On Wed, 5 Dec 2018, Alan Somers wrote:
Log:
stat(2): clarify which syscalls modify file timestamps
The list of syscalls that modify st_atim, st_mtim, and st_ctim was quite out
of date and probably not accurate to begin with. Update it, and make it
clear that the list is open-ended.
These fields shouldn't exist. They are misimplemented compatibility cruft.
They didn't exist in FreeBSD-4. They were correctly implemented
compatibility cruft then. The POSIX fields are still only time_t's with
names st_atime, etc., but these fields are timespecs with necessarily
different names. In FreeBSD-4, they were named st_atimespec, etc. unless
POSIX_SOURCE is defined, which before about 2007 POSIX required struct
timespec to not be defined, so the fields were declared as 2 scalars
st_atime and st_atimensec, etc. Padding of the scalars caused ABI problems
which I fixed in FreeBSD-5 using bit-fields. Now the support for POSIX
before about 2007 is broken by declaring struct timespec undonditionally
and using it for st_atim, etc. API compatibility with old versions of
FreeBSD is broken by renaming st_atimespec to st_atim, etc.
All versions that use timespecs use macro hacks of dubious standard
conformance to convert from timespecs to POSIX time_t's. All names starting
with st_ are reserved if <sys/stat.h> is included. This is what makes it
conforming for the implementation to use st_atim, etc. It is less clear
if the macros conform because it would be non-conforming for a an application
to #undef st_atim or depend on st_atim not being a macro.
Modified: head/lib/libc/sys/stat.2
==============================================================================
--- head/lib/libc/sys/stat.2 Wed Dec 5 17:13:33 2018 (r341597)
+++ head/lib/libc/sys/stat.2 Wed Dec 5 17:28:40 2018 (r341598)
...
@@ -193,45 +193,53 @@ are:
.Bl -tag -width ".Va st_birthtim"
.It Va st_atim
Time when file data was last accessed.
-Changed by the
-.Xr mknod 2 ,
Not changed by mknod, but set by it. Still set by it.
-.Xr utimes 2 ,
Not really changed if the change is null, where a null change may be the
result of rounding to a representable value. Permissions are still required
for making null changes. Similarly for most operations.
+Changed implicitly by syscalls such as
.Xr read 2
and
-.Xr readv 2
-system calls.
+.Xr readv 2 ,
Not changed by reads if the file system is mounted -noatime and the file
system supports this (you can't tell if the file system supports this
by examining its MNT_NOATIME flag). Not changed if granularity makes the
change null.
+and explicitly by
+.Xr utimes 2 .
The lists would be even longer if they mentioned utime, lutimes, futimes,
futimesat, futimens and futimnsat.
.It Va st_mtim
Time when file data was last modified.
-Changed by the
+Changed implicitly by syscalls such as
+.Xr truncate 2 ,
+.Xr write 2 ,
+and
+.Xr writev 2 ,
+and explicitly by
+.Xr utimes 2 .
+Also, any syscall which modifies directory content changes the
+.Va st_mtim
+for the affected directory.
+For instance,
+.Xr creat 2 ,
Usually spelled open with O_CREAT.
.Xr mkdir 2 ,
creat, open with O_CREAT, link, symlink, mkdir and all of the removed mk's
also set all times.
-.Xr mkfifo 2 ,
-.Xr mknod 2 ,
-.Xr utimes 2 ,
-.Xr write 2
+.Xr rename 2 ,
+.Xr link 2 ,
rename to a different directory changes 2 sets of directory times.
link is unsorted in this and another list.
...
+.Xr link 2 ,
and
-.Xr writev 2
-system calls.
+.Xr unlink 2 .
.It Va st_birthtim
Time when the inode was created.
.El
st_birthim should be named st_btime.
st_birthtim is set by all creation operations. It is changed by changing
st_mtim to a value before the current st_birthtim. This is done at the vfs
level, so it should work for all file systems that support birthtimes.
Changing st_birthtime forwards is not supported by any syscall. There
are already about 10 times too many syscalls for setting times, but
none of them supports setting birthtimes or ctimes. I use a sysctl
hack to set ctimes, as needed to back up and restore them, but don't
do anything special for birthtimes.
Bruce
_______________________________________________
svn-src-all@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/svn-src-all
To unsubscribe, send any mail to "svn-src-all-unsubscr...@freebsd.org"
