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.
This commit is contained in:
jruoho
parent
cbe8ce8cad
commit
3dc60799a1
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue