[src/trunk]: src/lib/libc/sys Try to describe the struct stat instead of copy...

[jruoho <jruoho%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/5f56fc545b98
branches:  trunk
changeset: 754936:5f56fc545b98
user:      jruoho <jruoho%NetBSD.org@localhost>
date:      Mon May 17 05:20:05 2010 +0000

description:
Try to describe the struct stat instead of copy-pasting it from the header.
Use xrefs to avoid duplication of effort. Note the S_IS*() macros.

diffstat:

 lib/libc/sys/stat.2 |  247 +++++++++++++++++++++++++++++----------------------
 1 files changed, 138 insertions(+), 109 deletions(-)

diffs (truncated from 337 to 300 lines):

diff -r 6bb73bfe97a4 -r 5f56fc545b98 lib/libc/sys/stat.2
--- a/lib/libc/sys/stat.2       Mon May 17 03:09:06 2010 +0000
+++ b/lib/libc/sys/stat.2       Mon May 17 05:20:05 2010 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: stat.2,v 1.41 2010/04/03 15:48:52 jruoho Exp $
+.\"    $NetBSD: stat.2,v 1.42 2010/05/17 05:20:05 jruoho Exp $
 .\"
 .\" Copyright (c) 1980, 1991, 1993, 1994
 .\"    The Regents of the University of California.  All rights reserved.
@@ -29,7 +29,7 @@
 .\"
 .\"     @(#)stat.2     8.4 (Berkeley) 5/1/95
 .\"
-.Dd April 3, 2010
+.Dd April 17, 2010
 .Dt STAT 2
 .Os
 .Sh NAME
@@ -56,6 +56,7 @@
 permission of the named file is not required, but all directories
 listed in the path name leading to the file must be searchable.
 .Pp
+The function
 .Fn lstat
 is like
 .Fn stat
@@ -66,7 +67,6 @@
 while
 .Fn stat
 returns information about the file the link references.
-.Pp
 The
 .Fn fstat
 function obtains the same information about an open file
@@ -80,64 +80,57 @@
 structure
 as defined by
 .In sys/stat.h
-(shown below)
 and into which information is placed concerning the file.
-.Bd -literal
-struct stat {
-    dev_t     st_dev;     /* device containing the file */
-    ino_t     st_ino;     /* file's serial number */
-    mode_t    st_mode;    /* file's mode (protection and type) */
-    nlink_t   st_nlink;   /* number of hard links to the file */
-    uid_t     st_uid;     /* user-id of owner */
-    gid_t     st_gid;     /* group-id of owner */
-    dev_t     st_rdev;    /* device type, for device special file */
-#if defined(_NETBSD_SOURCE)
-    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 */
-#else
-    time_t    st_atime;            /* time of last access */
-    long      st_atimensec;        /* nsec of last access */
-    time_t    st_mtime;            /* time of last data modification */
-    long      st_mtimensec;        /* nsec of last data modification */
-    time_t    st_ctime;            /* time of last file status change */
-    long      st_ctimensec;        /* nsec of last file status change */
-#endif
-    off_t     st_size;    /* file size, in bytes */
-    blkcnt_t  st_blocks;  /* blocks allocated for file */
-    blksize_t st_blksize; /* optimal file sys I/O ops blocksize */
-    uint32_t st_flags;   /* user defined flags for file */
-    uint32_t st_gen;     /* file generation number */
-#if defined(_NETBSD_SOURCE)
-    struct timespec st_birthtimespec;  /* time of inode creation */
-#else
-    time_t    st_birthtime;             /* time of inode creation */
-    long      st_birthtimensec;         /* nsec of inode creation */
-#endif
-};
-.Ed
+.Ss The Standard Structure
+The following standards-compliant fields are defined in the structure:
+.Bl -column -offset indent \
+"nlink_t " "st_nlink " "Description"
+.It Sy Type Ta Sy Entry Ta Sy Description
+.It Vt dev_t Ta st_dev Ta device ID containing the file
+.It Vt ino_t Ta st_ino Ta serial number of the file
+.It Vt mode_t Ta st_mode Ta mode of the file
+.It Vt nlink_t Ta st_nlink Ta number of hard links to the file
+.It Vt uid_t Ta st_uid Ta user ID of the owner
+.It Vt gid_t Ta st_gid Ta group ID of the owner
+.It Vt dev_t Ta st_rdev Ta device type (character or block special)
+.It Vt off_t Ta st_size Ta size of the file in bytes
+.It Vt time_t Ta st_atime Ta time of last access
+.It Vt time_t Ta st_mtime Ta time of last data modification
+.It Vt time_t Ta st_ctime Ta  time of last file status change
+.It Vt blksize_t Ta st_blksize Ta preferred I/O block size (fs-specific)
+.It Vt blkcnt_t Ta st_block Ta blocks allocated for the file
+.El
 .Pp
-The time-related fields of
-.Fa struct stat
-are as follows:
-.Bl -tag -width XXXst_birthtime
-.It st_atime
+These are specified in the
+.St -p1003.1-2004
+standard.
+The
+.Va st_ino
+and
+.Va st_dev
+fields taken together to uniquely identify the file within the system.
+Most of the types are defined in
+.Xr types 3 .
+.Pp
+The time-related fields are:
+.Bl -tag -width st_blksize -offset indent
+.It Va st_atime
 Time when file data was last accessed.
 Changed by the
 .Xr mknod 2 ,
-.Xr utimes 2
+.Xr utimes 2 ,
 and
 .Xr read 2
 system calls.
-.It st_mtime
+.It Va st_mtime
 Time when file data was last modified.
 Changed by the
 .Xr mknod 2 ,
-.Xr utimes 2
+.Xr utimes 2 ,
 and
 .Xr write 2
 system calls.
-.It st_ctime
+.It Va st_ctime
 Time when file status was last changed (file metadata modification).
 Changed by the
 .Xr chflags 2 ,
@@ -147,44 +140,26 @@
 .Xr mknod 2 ,
 .Xr rename 2 ,
 .Xr unlink 2 ,
-.Xr utimes 2
+.Xr utimes 2 ,
 and
 .Xr write 2
 system calls.
-.It st_birthtime
-Time when the inode was created.
 .El
 .Pp
-If
-.Dv _NETBSD_SOURCE
-is defined, the time-related fields are defined as:
-.Bd -literal
-#if defined(_NETBSD_SOURCE)
-#define st_atime                st_atimespec.tv_sec
-#define st_atimensec            st_atimespec.tv_nsec
-#define st_mtime                st_mtimespec.tv_sec
-#define st_mtimensec            st_mtimespec.tv_nsec
-#define st_ctime                st_ctimespec.tv_sec
-#define st_ctimensec            st_ctimespec.tv_nsec
-#define st_birthtime            st_birthtimespec.tv_sec
-#define st_birthtimensec        st_birthtimespec.tv_nsec
-#endif
-.Ed
-.Pp
 The size-related fields of the
 .Fa struct stat
 are as follows:
-.Bl -tag -width XXXst_blksize
-.It st_size
+.Bl -tag -width st_blksize -offset indent
+.It Va st_size
 The size of the file in bytes.
 A directory will be a multiple of the size of the
 .Xr dirent 5
 structure.
 Some filesystems (notably ZFS) return the number of entries in the directory
 instead of the size in bytes.
-.It st_blksize
+.It Va st_blksize
 The optimal I/O block size for the file.
-.It st_blocks
+.It Va 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.
@@ -192,49 +167,102 @@
 .Pp
 The status information word
 .Fa st_mode
-has the following bits:
-.Bd -literal
-#define S_IFMT 0170000           /* type of file */
-#define        S_IFIFO  0010000  /* named pipe (fifo) */
-#define        S_IFCHR  0020000  /* character special */
-#define        S_IFDIR  0040000  /* directory */
-#define        S_IFBLK  0060000  /* block special */
-#define        S_IFREG  0100000  /* regular */
-#define        S_IFLNK  0120000  /* symbolic link */
-#define        S_IFSOCK 0140000  /* socket */
-#define        S_IFWHT  0160000  /* whiteout */
-#define S_ISUID 0004000  /* set user id on execution */
-#define S_ISGID 0002000  /* set group id on execution */
-#define S_ISVTX 0001000  /* save swapped text even after use */
-#define S_IRUSR 0000400  /* read permission, owner */
-#define S_IWUSR 0000200  /* write permission, owner */
-#define S_IXUSR 0000100  /* execute/search permission, owner */
-#define S_IRGRP 0000040  /* read permission, group */
-#define S_IWGRP 0000020  /* write permission, group */
-#define S_IXGRP 0000010  /* execute/search permission, group */
-#define S_IROTH 0000004  /* read permission, other */
-#define S_IWOTH 0000002  /* write permission, other */
-#define S_IXOTH 0000001  /* execute/search permission, other */
+contains bits that define the access mode (see
+.Xr chmod 2 )
+and the type (see
+.Xr dirent 3 )
+of the file.
+The following macros can be used to test
+whether a file is of the specified type.
+The value
+.Fa m
+supplied to the macros is the value of
+.Va st_mode .
+.Bl -tag -width "S_ISSOCK(m)" -offset indent
+.It Fn S_ISBLK "m"
+Test for a block special file.
+.It Fn S_ISCHR "m"
+Test for a character special file.
+.It Fn S_ISDIR "m"
+Test for a directory.
+.It Fn S_ISFIFO "m"
+Test for a pipe or FIFO special file.
+.It Fn S_ISREG "m"
+Test for a regular file.
+.It Fn S_ISLNK "m"
+Test for a symbolic link.
+.It Fn S_ISSOCK "m"
+Test for a socket.
+.El
+.Pp
+The macros evaluate to a non-zero value if the test
+is true or to the alue 0 if the test is false.
+.Ss NetBSD Extensions
+The following additional
+.Nx
+specific fields are present:
+.Bl -column -offset indent \
+"uint32_t" "st_birthtimensec" "Description"
+.It Sy Type Ta Sy Entry Ta Sy Description
+.It Vt long Ta st_atimensec Ta last access (nanoseconds)
+.It Vt long Ta st_mtimensec Ta last modification (nanoseconds)
+.It Vt long Ta st_ctimensec Ta last status change (nanoseconds)
+.It Vt time_t Ta st_birthtime Ta time of inode creation
+.It Vt long Ta st_birthtimensec Ta inode creation (nanoseconds)
+.It Vt uint32_t Ta st_flags Ta user defined flags for the file
+.It Vt uint32_t Ta st_gen Ta file generation number
+.\"
+.\" XXX: What is this?
+.\"
+.It Vt uint32_t Ta st_spare[2] Ta implementation detail
+.El
+.Pp
+However, if
+_NETBSD_SOURCE
+is furthermore defined, instead of the above,
+the following are present in the structure:
+.Bl -column -offset indent \
+"struct timespec " "st_birthtimensec" "Description"
+.It Sy Type Ta Sy Entry Ta Sy Description
+.It Vt struct timespec Ta st_atimespec Ta time of last access
+.It Vt struct timespec Ta st_mtimespec Ta time of last modification
+.It Vt struct timespec Ta st_birthtimespec Ta time of creation
+.It Vt uint32_t Ta st_flags Ta user defined flags
+.It Vt uint32_t Ta st_gen Ta file generation number
+.\"
+.\" XXX: What is this?
+.\"
+.It Vt uint32_t Ta st_spare[2] Ta implementation detail
+.El
+.Pp
+In this case the following macros are provided for convenience:
+.Bd -literal -offset indent
+#if defined(_NETBSD_SOURCE)
+  #define st_atime                st_atimespec.tv_sec
+  #define st_atimensec            st_atimespec.tv_nsec
+  #define st_mtime                st_mtimespec.tv_sec
+  #define st_mtimensec            st_mtimespec.tv_nsec
+  #define st_ctime                st_ctimespec.tv_sec
+  #define st_ctimensec            st_ctimespec.tv_nsec
+  #define st_birthtime            st_birthtimespec.tv_sec
+  #define st_birthtimensec        st_birthtimespec.tv_nsec
+#endif
 .Ed
 .Pp
-For a list of access modes, see
-.In sys/stat.h ,
-.Xr access 2
-and
-.Xr chmod 2 .