diff options
Diffstat (limited to 'lib/libc/sys/stat.2')
| -rw-r--r-- | lib/libc/sys/stat.2 | 437 |
1 files changed, 437 insertions, 0 deletions
diff --git a/lib/libc/sys/stat.2 b/lib/libc/sys/stat.2 new file mode 100644 index 0000000..b6c03ab --- /dev/null +++ b/lib/libc/sys/stat.2 @@ -0,0 +1,437 @@ +.\" 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. +.\" 4. 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 +.\" $FreeBSD$ +.\" +.Dd November 17, 2011 +.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/types.h +.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" +.Ft int +.Fn fstatat "int fd" "const char *path" "struct stat *buf" "int flag" +.Sh DESCRIPTION +The +.Fn stat +system call 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 +.Fn lstat +system call 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. +.Pp +The +.Fn fstat +system call obtains the same information about an open file +known by the file descriptor +.Fa fd . +.Pp +The +.Fn fstatat +system call is equivalent to +.Fn stat +and +.Fn lstat +except in the case where the +.Fa path +specifies a relative path. +In this case the status is retrieved from a file relative to +the directory associated with the file descriptor +.Fa fd +instead of the current working directory. +.Pp +The values for the +.Fa flag +are constructed by a bitwise-inclusive OR of flags from the following list, +defined in +.In fcntl.h : +.Bl -tag -width indent +.It Dv AT_SYMLINK_NOFOLLOW +If +.Fa path +names a symbolic link, the status of the symbolic link is returned. +.El +.Pp +If +.Fn fstatat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is +identical to a call to +.Fn stat +or +.Fn lstat +respectively, depending on whether or not the +.Dv AT_SYMLINK_NOFOLLOW +bit is set in +.Fa flag . +.Pp +The +.Fa sb +argument is a pointer to a +.Vt stat +structure +as defined by +.In sys/stat.h +and into which information is placed concerning the file. +.Pp +The fields of +.Vt "struct stat" +related to the file system are as follows: +.Bl -tag -width ".Va st_nlink" +.It Va st_dev +The numeric ID of the device containing the file. +.It Va st_ino +The file's inode number. +.It Va st_nlink +The number of hard links to the file. +.El +.Pp +The +.Va st_dev +and +.Va st_ino +fields together identify the file uniquely within the system. +.Pp +The time-related fields of +.Vt "struct stat" +are as follows: +.Bl -tag -width ".Va st_birthtim" +.It Va st_atim +Time when file data last accessed. +Changed by the +.Xr mknod 2 , +.Xr utimes 2 , +.Xr read 2 +and +.Xr readv 2 +system calls. +.It Va st_mtim +Time when file data last modified. +Changed by the +.Xr mkdir 2 , +.Xr mkfifo 2 , +.Xr mknod 2 , +.Xr utimes 2 , +.Xr write 2 +and +.Xr writev 2 +system calls. +.It Va st_ctim +Time when file status was last changed (inode data modification). +Changed by the +.Xr chflags 2 , +.Xr chmod 2 , +.Xr chown 2 , +.Xr creat 2 , +.Xr link 2 , +.Xr mkdir 2 , +.Xr mkfifo 2 , +.Xr mknod 2 , +.Xr rename 2 , +.Xr rmdir 2 , +.Xr symlink 2 , +.Xr truncate 2 , +.Xr unlink 2 , +.Xr utimes 2 , +.Xr write 2 +and +.Xr writev 2 +system calls. +.It Va st_birthtim +Time when the inode was created. +.El +.Pp +The following time-related macros are defined for compatibility: +.Bd -literal +#define st_atime st_atim.tv_sec +#define st_mtime st_mtim.tv_sec +#define st_ctime st_ctim.tv_sec +#ifndef _POSIX_SOURCE +#define st_birthtime st_birthtim.tv_sec +#endif + +#ifndef _POSIX_SOURCE +#define st_atimespec st_atim +#define st_mtimespec st_mtim +#define st_ctimespec st_ctim +#define st_birthtimespec st_birthtim +#endif +.Ed +.Pp +The size-related fields of the +.Vt "struct stat" +are as follows: +.Bl -tag -width ".Va st_blksize" +.It Va st_size +The file size in bytes. +.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 access-related fields of +.Vt "struct stat" +are as follows: +.Bl -tag -width ".Va st_mode" +.It Va st_uid +The user ID of the file's owner. +.It Va st_gid +The group ID of the file. +.It Va st_mode +Status of the file (see below). +.El +.Pp +The status information word +.Fa st_mode +has the following bits: +.Bd -literal +#define S_IFMT 0170000 /* type of file mask */ +#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_IRWXU 0000700 /* RWX mask for owner */ +#define S_IRUSR 0000400 /* read permission, owner */ +#define S_IWUSR 0000200 /* write permission, owner */ +#define S_IXUSR 0000100 /* execute/search permission, owner */ +#define S_IRWXG 0000070 /* RWX mask for group */ +#define S_IRGRP 0000040 /* read permission, group */ +#define S_IWGRP 0000020 /* write permission, group */ +#define S_IXGRP 0000010 /* execute/search permission, group */ +#define S_IRWXO 0000007 /* RWX mask for other */ +#define S_IROTH 0000004 /* read permission, other */ +#define S_IWOTH 0000002 /* write permission, other */ +#define S_IXOTH 0000001 /* execute/search permission, other */ +.Ed +.Pp +For a list of access modes, see +.In sys/stat.h , +.Xr access 2 +and +.Xr chmod 2 . +The following macros are available to test whether a +.Va st_mode +value passed in the +.Fa m +argument corresponds to a file of the specified type: +.Bl -tag -width ".Fn S_ISFIFO m" +.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. +.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. +.Sh RETURN VALUES +.Rv -std +.Sh COMPATIBILITY +Previous versions of the system used different types for the +.Va st_dev , +.Va st_uid , +.Va st_gid , +.Va st_rdev , +.Va st_size , +.Va st_blksize +and +.Va st_blocks +fields. +.Sh ERRORS +The +.Fn stat +and +.Fn lstat +system calls 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 EFAULT +The +.Fa sb +or +.Fa path +argument +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 255 characters, +or an entire path name exceeded 1023 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 EOVERFLOW +The file size in bytes cannot be +represented correctly in the structure pointed to by +.Fa sb . +.El +.Pp +The +.Fn fstat +system call will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument +is not a valid open file descriptor. +.It Bq Er EFAULT +The +.Fa sb +argument +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 EOVERFLOW +The file size in bytes cannot be +represented correctly in the structure pointed to by +.Fa sb . +.El +.Pp +In addition to the errors returned by the +.Fn lstat , +the +.Fn fstatat +may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er EINVAL +The value of the +.Fa flag +argument is not valid. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El +.Sh SEE ALSO +.Xr access 2 , +.Xr chmod 2 , +.Xr chown 2 , +.Xr fhstat 2 , +.Xr statfs 2 , +.Xr utimes 2 , +.Xr sticky 7 , +.Xr symlink 7 +.Sh STANDARDS +The +.Fn stat +and +.Fn fstat +system calls are expected to conform to +.St -p1003.1-90 . +The +.Fn fstatat +system call follows The Open Group Extended API Set 2 specification. +.Sh HISTORY +The +.Fn stat +and +.Fn fstat +system calls appeared in +.At v7 . +The +.Fn lstat +system call appeared in +.Bx 4.2 . +The +.Fn fstatat +system call appeared in +.Fx 8.0 . +.Sh BUGS +Applying +.Fn fstat +to a socket (and thus to a pipe) +returns a zeroed buffer, +except for the blocksize field, +and a unique device and inode number. |
