diff options
Diffstat (limited to 'static/netbsd/man2/stat.2')
| -rw-r--r-- | static/netbsd/man2/stat.2 | 424 |
1 files changed, 424 insertions, 0 deletions
diff --git a/static/netbsd/man2/stat.2 b/static/netbsd/man2/stat.2 new file mode 100644 index 00000000..92718869 --- /dev/null +++ b/static/netbsd/man2/stat.2 @@ -0,0 +1,424 @@ +.\" $NetBSD: stat.2,v 1.60 2023/10/15 20:37:04 jschauma Exp $ +.\" +.\" Copyright (c) 1980, 1991, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)stat.2 8.4 (Berkeley) 5/1/95 +.\" +.Dd October 15, 2023 +.Dt STAT 2 +.Os +.Sh NAME +.Nm stat , +.Nm lstat , +.Nm fstat , +.Nm fstatat +.Nd get file status +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/stat.h +.Ft int +.Fn stat "const char *path" "struct stat *sb" +.Ft int +.Fn lstat "const char *path" "struct stat *sb" +.Ft int +.Fn fstat "int fd" "struct stat *sb" +.In sys/stat.h +.In fcntl.h +.Ft int +.Fn fstatat "int fd" "const char *path" "struct stat *sb" "int flag" +.Sh DESCRIPTION +The +.Fn stat +function obtains information about the file pointed to by +.Fa path . +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 +except in the case where the named file is a symbolic link, +in which case +.Fn lstat +returns information about the link, +while +.Fn stat +returns information about the file the link references. +The +.Fn fstat +function obtains the same information about an open file +known by the file descriptor +.Fa fd . +.Pp +.Fn fstatat +works the same way as +.Fn stat +(or +.Fn lstat +if +.Dv AT_SYMLINK_NOFOLLOW +is set in +.Fa flag ) +except if +.Fa path +is relative. +In that case, it is looked up from a directory whose file +descriptor was passed as +.Fa fd . +Search permission is required on this directory. +.\" (These alternatives await a decision about the semantics of O_SEARCH) +.\" Search permission is required on this directory +.\" except if +.\" .Fa fd +.\" was opened with the +.\" .Dv O_SEARCH +.\" flag. +.\" - or - +.\" This file descriptor must have been opened with the +.\" .Dv O_SEARCH +.\" flag. +.Fa fd +can be set to +.Dv AT_FDCWD +in order to specify the current directory. +.Pp +The +.Fa sb +argument is a pointer to a +.Fa stat +structure +as defined by +.In sys/stat.h +and into which information is placed concerning the file. +.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 (inode number) +.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_blocks Ta blocks allocated for the file +.El +.Pp +These are specified in the +.St -p1003.1-2004 +standard. +The +.Va st_ino +and +.Va st_dev +fields taken together 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 , +and +.Xr read 2 +system calls. +.It Va st_mtime +Time when file data was last modified. +Changed by the +.Xr mknod 2 , +.Xr utimes 2 , +and +.Xr write 2 +system calls. +.It Va st_ctime +Time when file status was last changed (file metadata modification). +Changed by the +.Xr chflags 2 , +.Xr chmod 2 , +.Xr chown 2 , +.Xr link 2 , +.Xr mknod 2 , +.Xr rename 2 , +.Xr unlink 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 st_blksize -offset indent +.It Va st_size +The size of the file in bytes. +The meaning of the size reported for a directory is file system +dependent. +Some file systems (e.g. FFS) return the total size used for the +directory metadata, possibly including free slots; others (notably +ZFS) return the number of entries in the directory. +Some may also return other things or always report zero. +.It Va st_blksize +The optimal I/O block size for the file. +.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. +.El +.Pp +The status information word +.Fa st_mode +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_ISLNK "m" +Test for a symbolic link. +.It Fn S_ISREG "m" +Test for a regular file. +.It Fn S_ISSOCK "m" +Test for a socket. +.It Fn S_ISWHT "m" +Test for a whiteout file. +.El +.Pp +The macros evaluate to a non-zero value if the test +is true or to the value 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: +.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 . +.Sh RETURN VALUES +.Rv -std stat lstat fstat fstatat +.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 , +.Fn lstat +and +.Fn fstatat +will fail if: +.Bl -tag -width Er +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er EBADF +A badly formed vnode was encountered. +This can happen if a file system information node is incorrect. +.It Bq Er EFAULT +.Fa sb +or +.Fa path +points to an invalid address. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded +.Brq Dv NAME_MAX +characters, or an entire path name exceeded +.Brq Dv PATH_MAX +characters. +.It Bq Er ENOENT +The named file does not exist. +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENXIO +The named file is a character special or block +special file, and the device associated with this special file +does not exist. +.El +.Pp +In addition, +.Fn fstatat +will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +.Fa path +does not specify an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a valid file descriptor open for reading or searching. +.It Bq Er ENOTDIR +.Fa path +is not an absolute path and +.Fa fd +is a file descriptor associated with a non-directory file. +.El +.Pp +.Fn fstat +will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +.Fa fd +is not a valid open file descriptor. +.It Bq Er EFAULT +.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 SEE ALSO +.Xr chflags 2 , +.Xr chmod 2 , +.Xr chown 2 , +.Xr utimes 2 , +.Xr dirent 3 , +.Xr types 3 , +.Xr symlink 7 +.Sh STANDARDS +.Fn stat , +.Fn lstat , +and +.Fn fstat +conform to +.St -p1003.1-2004 . +.Fn fstatat +conforms to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn stat +and +.Fn fstat +function calls appeared in +.At v1 . +A +.Fn lstat +function call appeared in +.Bx 4.2 . +.Sh BUGS +Applying +.Fn fstat +to a socket (and thus to a pipe) +returns a zero'd buffer, +except for the blocksize field, +and a unique device and file serial number. |