From 3dc60799a1508babf4f6026cd7ac1a9b7ba0d773 Mon Sep 17 00:00:00 2001 From: jruoho Date: Mon, 17 May 2010 05:20:05 +0000 Subject: [PATCH] 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 | 247 +++++++++++++++++++++++++------------------- 1 file changed, 138 insertions(+), 109 deletions(-) diff --git a/lib/libc/sys/stat.2 b/lib/libc/sys/stat.2 index e010472a0344..a065dd9d74eb 100644 --- a/lib/libc/sys/stat.2 +++ b/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 -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 @@ 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 -.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 @@ be zero. .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 */ -.Ed +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 -For a list of access modes, see -.In sys/stat.h , -.Xr access 2 -and -.Xr chmod 2 . +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 The status information word .Fa st_flags has the following bits: -.Bd -literal -#define UF_NODUMP 0x00000001 /* do not dump file */ -#define UF_IMMUTABLE 0x00000002 /* file may not be changed */ -#define UF_APPEND 0x00000004 /* writes to file may only append */ -#define UF_OPAQUE 0x00000008 /* directory is opaque wrt. union */ -#define SF_ARCHIVED 0x00010000 /* file is archived */ -#define SF_IMMUTABLE 0x00020000 /* file may not be changed */ -#define SF_APPEND 0x00040000 /* writes to file may only append */ -.Ed +.Bl -column -offset indent \ +"struct timespec " "st_birthtimensec" +.It Sy Constant Ta Sy Description +.It Dv UF_NODUMP Ta do not dump a file +.It Dv UF_IMMUTABLE Ta file may not be changed +.It Dv UF_APPEND Ta writes to file may only append +.It Dv UF_OPAQUE Ta directory is opaque wrt. union +.It Dv SF_ARCHIVED Ta file is archived +.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