Update to reflect renaming of the st_[acm]timespec members to st_[acm]tim

per the POSIX 1003.1-2008 spec.  Also, tweak the information about what
system calls hit which timestamps

ok jmc@

1 files changed, 61 insertions, 22 deletions

diff --git a/lib/libc/sys/stat.2 b/lib/libc/sys/stat.2
index 294e6e316d8..ab1750f0e62 100644
--- a/lib/libc/sys/stat.2
+++ b/lib/libc/sys/stat.2
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: stat.2,v 1.24 2007/11/05 14:52:46 jmc Exp $
+.\"	$OpenBSD: stat.2,v 1.25 2009/01/29 22:15:14 guenther Exp $
 .\"
 .\" Copyright (c) 1980, 1991, 1993, 1994
 .\"	The Regents of the University of California.  All rights reserved.
@@ -29,7 +29,7 @@
 .\"
 .\"     @(#)stat.2	8.3 (Berkeley) 4/19/94
 .\"
-.Dd $Mdocdate: November 5 2007 $
+.Dd $Mdocdate: January 29 2009 $
 .Dt STAT 2
 .Os
 .Sh NAME
@@ -97,9 +97,9 @@ struct stat {
     uid_t      st_uid;    /* user ID of the file's owner */
     gid_t      st_gid;    /* group ID of the file's group */
     dev_t      st_rdev;   /* device type */
-    struct timespec st_atimespec;  /* time of last access */
-    struct timespec st_mtimespec;  /* time of last data modification */
-    struct timespec st_ctimespec;  /* time of last file status change */
+    struct timespec st_atim;  /* time of last access */
+    struct timespec st_mtim;  /* time of last data modification */
+    struct timespec st_ctim;  /* time of last file status change */
     off_t      st_size;   /* file size, in bytes */
     int64_t    st_blocks; /* blocks allocated for file */
     u_int32_t  st_blksize;/* optimal blocksize for I/O */
@@ -110,31 +110,42 @@ struct stat {
 .Pp
 The time-related fields of
 .Li struct stat
-are as follows:
-.Bl -tag -width XXXst_mtime
-.It Fa st_atime
+are represented in
+.Li struct timespec
+format, which has nanosecond precision.
+However, the actual precision is generally limited by the file
+system holding the file.
+The fields are as follows:
+.Bl -tag -width XXXst_mtim
+.It Fa st_atim
 Time when file data was last accessed.
-Changed by the
-.Xr mknod 2 ,
-.Xr utimes 2 ,
+Set when the file system object was created and updated by the
+.Xr utimes 2
 and
 .Xr read 2
 system calls.
-.It Fa st_mtime
+.It Fa st_mtim
 Time when file data was last modified.
 Changed by the
-.Xr mknod 2 ,
+.Xr truncate 2 ,
 .Xr utimes 2 ,
 and
 .Xr write 2
 system calls.
+For directories, changed by any system call that alters which files are
+in the directory, such as the
+.Xr unlink 2 ,
+.Xr rename 2 ,
+.Xr mkdir 2 ,
+and
+.Xr symlink
+system calls.
 .It Fa st_ctime
 Time when file status was last changed (inode data modification).
 Changed by the
 .Xr chmod 2 ,
 .Xr chown 2 ,
 .Xr link 2 ,
-.Xr mknod 2 ,
 .Xr rename 2 ,
 .Xr unlink 2 ,
 .Xr utimes 2 ,
@@ -143,6 +154,35 @@ and
 system calls.
 .El
 .Pp
+In addition, all the time fields are set to the current time when
+a file system object is first created by the
+.Xr mkdir 2 ,
+.Xr mkfifo 2 ,
+.Xr mknod 2 ,
+.Xr open 2 ,
+and
+.Xr symlink 2
+system calls.
+.Pp
+For compatibility with previous standards,
+.Fa st_atime ,
+.Fa st_mtime ,
+and
+.Fa st_ctime
+macros are provided that expand to the
+.Fa tv_secs
+member of their respective
+.Li struct timespec
+member.
+Deprecated macros are also provided for some transitional names:
+.Fa st_atimensec ,
+.Fa st_mtimensec ,
+.Fa st_ctimensec , 
+.Fa st_atimespec ,
+.Fa st_mtimespec ,
+and
+.Fa st_ctimespec
+.Pp
 The size-related fields of the
 .Li struct stat
 are as follows:
@@ -285,15 +325,14 @@ The file generation number,
 .Fa st_gen ,
 is only available to the superuser.
 .Pp
-The fields in the stat structure currently marked
-.Fa st_spare1 ,
-.Fa st_spare2 ,
-and
-.Fa st_spare3
-are present in preparation for inode time stamps expanding to 64 bits.
-This, however, can break certain programs that
-depend on the time stamps being contiguous (in calls to
+Certain programs written when the timestamps were just of type
+.Li time_t
+assumed that the members were consecutive (and could therefore
+be placed directly to
 .Xr utimes 2 ) .
+The transition to timestamps of type
+.Li struct timespec
+broke them irrevocably.
 .Sh BUGS
 Applying
 .Fn fstat