bring stat(2) up to date w.r.t. sys/stat.h

SCCS-vsn: lib/libc/sys/stat.2 8.2

diff --git a/usr/src/lib/libc/sys/stat.2 b/usr/src/lib/libc/sys/stat.2
index e52620c..93bd684 100644 (file)
--- a/usr/src/lib/libc/sys/stat.2
+++ b/usr/src/lib/libc/sys/stat.2
@@ -3,7 +3,7 @@
 .\"
 .\" %sccs.include.redist.man%
 .\"
-.\"     @(#)stat.2     8.1 (Berkeley) %G%
+.\"     @(#)stat.2     8.2 (Berkeley) %G%
 .\"
 .Dd 
 .Dt STAT 2
@@ -17,11 +17,11 @@
 .Fd #include <sys/types.h>
 .Fd #include <sys/stat.h>
 .Ft int
-.Fn stat "const char *path" "struct stat *buf"
+.Fn stat "const char *path" "struct stat *sb"
 .Ft int
-.Fn lstat "const char *path" "struct stat *buf"
+.Fn lstat "const char *path" "struct stat *sb"
 .Ft int
-.Fn fstat "int fd" "struct stat *buf"
+.Fn fstat "int fd" "struct stat *sb"
 .Sh DESCRIPTION
 The
 .Fn stat
@@ -54,14 +54,11 @@ The
 .Fn fstat
 obtains the same information about an open file
 known by the file descriptor
-.Fa fd ,
-such as would
-be obtained by an
-.Xr open
-call.
+.Fa fd .
 .Pp
-.Fa Buf
-is a pointer to a
+The
+.Fa sb
+argument is a pointer to a
 .Fn stat
 structure
 as defined by
@@ -77,15 +74,12 @@ struct stat {
     uid_t    st_uid;    /* user-id of owner */
     gid_t    st_gid;    /* group-id of owner */
     dev_t    st_rdev;   /* device type, for special file inode */
+    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 */
     off_t    st_size;   /* file size, in bytes */
-    time_t   st_atime;  /* time of last access */
-    long     st_spare1;
-    time_t   st_mtime;  /* time of last data modification */
-    long     st_spare2;
-    time_t   st_ctime;  /* time of last file status change */
-    long     st_spare3;
-    long     st_blksize;/* optimal file sys I/O ops blocksize */
-    long     st_blocks; /* blocks allocated for file */
+    quad_t   st_blocks; /* blocks allocated for file */
+    u_long   st_blksize;/* optimal file sys I/O ops blocksize */
     u_long   st_flags;  /* user defined flags for file */
     u_long   st_gen;    /* file generation number */
 };
@@ -94,38 +88,53 @@ struct stat {
 The time-related fields of
 .Fa struct stat
 are as follows:
-.Bl -tag -width st_blocks
+.Bl -tag -width XXXst_mtime
 .It st_atime
-Time when file data last accessed.  Changed by the following system
-calls:
+Time when file data last accessed.
+Changed by the
 .Xr mknod 2 ,
-.Xr utimes 2 ,
+.Xr utimes 2
 and
-.Xr read 2 .
+.Xr read 2
+system calls.
 .It st_mtime
 Time when file data last modified.
-Changed by the following system calls:
+Changed by the
 .Xr mknod 2 ,
-.Xr utimes 2 ,
-.Xr write 2 .
+.Xr utimes 2
+and
+.Xr write 2
+system calls.
 .It st_ctime
 Time when file status was last changed (inode data modification).
-Changed by the following system calls:
-.Xr chmod 2
+Changed by the
+.Xr chmod 2 ,
 .Xr chown 2 ,
 .Xr link 2 ,
 .Xr mknod 2 ,
 .Xr rename 2 ,
 .Xr unlink 2 ,
-.Xr utimes 2 ,
-.Xr write 2 .
+.Xr utimes 2
+and
+.Xr write 2
+system calls.
+.El
+.Pp
+The size-related fields of the
+.Fa struct stat
+are as follows:
+.Bl -tag -width XXXst_blksize
+.It st_blksize
+The optimal I/O block size for the file.
 .It st_blocks
 The actual number of blocks allocated for the file in 512-byte units.
+As short symbolic links are stored in the inode, this number may
+be zero.
 .El
 .Pp
 The status information word
 .Fa st_mode
-has bits:
+has the following bits:
 .Bd -literal
 #define S_IFMT 0170000           /* type of file */
 #define        S_IFIFO  0010000  /* named pipe (fifo) */
@@ -153,6 +162,17 @@ Upon successful completion a value of 0 is returned.
 Otherwise, a value of -1 is returned and
 .Va errno
 is set to indicate the error.
+.Sh COMPATIBILITY
+Previous versions of the system used different types for the
+.Li st_dev ,
+.Li st_uid ,
+.Li st_gid ,
+.Li st_rdev ,
+.Li st_size ,
+.Li st_blksize
+and
+.Li st_blocks
+fields.
 .Sh ERRORS
 .Fn Stat
 and
@@ -173,7 +193,7 @@ Search permission is denied for a component of the path prefix.
 .It Bq Er ELOOP
 Too many symbolic links were encountered in translating the pathname.
 .It Bq Er EFAULT
-.Fa Buf
+.Fa Sb
 or
 .Em name
 points to an invalid address.
@@ -188,13 +208,13 @@ will fail if:
 .Fa fd
 is not a valid open file descriptor.
 .It Bq Er EFAULT
-.Fa Buf
+.Fa Sb
 points to an invalid address.
 .It Bq Er EIO
 An I/O error occurred while reading from or writing to the file system.
 .El
 .Sh CAVEAT
-The fields in the stat structure currently marked 
+The fields in the stat structure currently marked
 .Fa st_spare1 ,
 .Fa st_spare2 ,
 and