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.

lib/libc/sys/stat.2

@@ -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 @@ Read, write or execute
 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 @@ returns information about the link,
 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 @@ argument is a pointer to a
 structure
 as defined by
 .In sys/stat.h
-(shown below)
 and into which information is placed concerning the file.
-.Bd -literal
+.Ss The Standard Structure
-struct stat {
+The following standards-compliant fields are defined in the structure:
-    dev_t     st_dev;     /* device containing the file */
+.Bl -column -offset indent \
-    ino_t     st_ino;     /* file's serial number */
+"nlink_t " "st_nlink " "Description"
-    mode_t    st_mode;    /* file's mode (protection and type) */
+.It Sy Type Ta Sy Entry Ta Sy Description
-    nlink_t   st_nlink;   /* number of hard links to the file */
+.It Vt dev_t Ta st_dev Ta device ID containing the file
-    uid_t     st_uid;     /* user-id of owner */
+.It Vt ino_t Ta st_ino Ta serial number of the file
-    gid_t     st_gid;     /* group-id of owner */
+.It Vt mode_t Ta st_mode Ta mode of the file
-    dev_t     st_rdev;    /* device type, for device special file */
+.It Vt nlink_t Ta st_nlink Ta number of hard links to the file
-#if defined(_NETBSD_SOURCE)
+.It Vt uid_t Ta st_uid Ta user ID of the owner
-    struct timespec st_atimespec;  /* time of last access */
+.It Vt gid_t Ta st_gid Ta group ID of the owner
-    struct timespec st_mtimespec;  /* time of last data modification */
+.It Vt dev_t Ta st_rdev Ta device type (character or block special)
-    struct timespec st_ctimespec;  /* time of last file status change */
+.It Vt off_t Ta st_size Ta size of the file in bytes
-#else
+.It Vt time_t Ta st_atime Ta time of last access
-    time_t    st_atime;            /* time of last access */
+.It Vt time_t Ta st_mtime Ta time of last data modification
-    long      st_atimensec;        /* nsec of last access */
+.It Vt time_t Ta st_ctime Ta  time of last file status change
-    time_t    st_mtime;            /* time of last data modification */
+.It Vt blksize_t Ta st_blksize Ta preferred I/O block size (fs-specific)
-    long      st_mtimensec;        /* nsec of last data modification */
+.It Vt blkcnt_t Ta st_block Ta blocks allocated for the file
-    time_t    st_ctime;            /* time of last file status change */
+.El
-    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
 .Pp
-The time-related fields of
+These are specified in the
-.Fa struct stat
+.St -p1003.1-2004
-are as follows:
+standard.
-.Bl -tag -width XXXst_birthtime
+The
-.It st_atime
+.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 @@ Changed by the
 .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
+.Bl -tag -width st_blksize -offset indent
-.It st_size
+.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 @@ be zero.
 .Pp
 The status information word
 .Fa st_mode
-has the following bits:
+contains bits that define the access mode (see
-.Bd -literal
+.Xr chmod 2 )
-#define S_IFMT 0170000           /* type of file */
+and the type (see
-#define        S_IFIFO  0010000  /* named pipe (fifo) */
+.Xr dirent 3 )
-#define        S_IFCHR  0020000  /* character special */
+of the file.
-#define        S_IFDIR  0040000  /* directory */
+The following macros can be used to test
-#define        S_IFBLK  0060000  /* block special */
+whether a file is of the specified type.
-#define        S_IFREG  0100000  /* regular */
+The value
-#define        S_IFLNK  0120000  /* symbolic link */
+.Fa m
-#define        S_IFSOCK 0140000  /* socket */
+supplied to the macros is the value of
-#define        S_IFWHT  0160000  /* whiteout */
+.Va st_mode .
-#define S_ISUID 0004000  /* set user id on execution */
+.Bl -tag -width "S_ISSOCK(m)" -offset indent
-#define S_ISGID 0002000  /* set group id on execution */
+.It Fn S_ISBLK "m"
-#define S_ISVTX 0001000  /* save swapped text even after use */
+Test for a block special file.
-#define S_IRUSR 0000400  /* read permission, owner */
+.It Fn S_ISCHR "m"
-#define S_IWUSR 0000200  /* write permission, owner */
+Test for a character special file.
-#define S_IXUSR 0000100  /* execute/search permission, owner */
+.It Fn S_ISDIR "m"
-#define S_IRGRP 0000040  /* read permission, group */
+Test for a directory.
-#define S_IWGRP 0000020  /* write permission, group */
+.It Fn S_ISFIFO "m"
-#define S_IXGRP 0000010  /* execute/search permission, group */
+Test for a pipe or FIFO special file.
-#define S_IROTH 0000004  /* read permission, other */
+.It Fn S_ISREG "m"
-#define S_IWOTH 0000002  /* write permission, other */
+Test for a regular file.
-#define S_IXOTH 0000001  /* execute/search permission, other */
+.It Fn S_ISLNK "m"
-.Ed
+Test for a symbolic link.
+.It Fn S_ISSOCK "m"
+Test for a socket.
+.El
 .Pp
-For a list of access modes, see
+The macros evaluate to a non-zero value if the test
-.In sys/stat.h ,
+is true or to the alue 0 if the test is false.
-.Xr access 2
+.Ss NetBSD Extensions
-and
+The following additional
-.Xr chmod 2 .
+.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
 The status information word
 .Fa st_flags
 has the following bits:
-.Bd -literal
+.Bl -column -offset indent \
-#define UF_NODUMP	0x00000001 /* do not dump file */
+"struct timespec " "st_birthtimensec"
-#define UF_IMMUTABLE	0x00000002 /* file may not be changed */
+.It Sy Constant Ta Sy Description
-#define UF_APPEND	0x00000004 /* writes to file may only append */
+.It Dv UF_NODUMP Ta do not dump a file
-#define UF_OPAQUE	0x00000008 /* directory is opaque wrt. union */
+.It Dv UF_IMMUTABLE Ta file may not be changed
-#define SF_ARCHIVED	0x00010000 /* file is archived */
+.It Dv UF_APPEND Ta writes to file may only append
-#define SF_IMMUTABLE	0x00020000 /* file may not be changed */
+.It Dv UF_OPAQUE Ta directory is opaque wrt. union
-#define SF_APPEND	0x00040000 /* writes to file may only append */
+.It Dv SF_ARCHIVED Ta file is archived
-.Ed
+.It Dv SF_IMMUTABLE Ta file may not be changed
+.It Dv SF_APPEND Ta writes to file may only append
+.El
 .Pp
 For a description of the flags, see
 .Xr chflags 2 .
@@ -307,7 +335,8 @@ An I/O error occurred while reading from or writing to the file system.
 .Xr chmod 2 ,
 .Xr chown 2 ,
 .Xr utimes 2 ,
-.Xr dir 5 ,
+.Xr dirent 3 ,
+.Xr types 3 ,
 .Xr symlink 7
 .Sh STANDARDS
 The