X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/593a1d5fd87cdf5b46dd5fcb84467b432cea0f91..4bd07ac2140668789aa3ee8ec4dde4a3e0a3bba5:/bsd/man/man2/stat.2?ds=sidebyside diff --git a/bsd/man/man2/stat.2 b/bsd/man/man2/stat.2 index 53704ece8..7282de5a9 100644 --- a/bsd/man/man2/stat.2 +++ b/bsd/man/man2/stat.2 @@ -33,13 +33,17 @@ .\" .\" @(#)stat.2 8.3 (Berkeley) 4/19/94 .\" -.Dd April 19, 1994 +.Dd May 15, 2008 .Dt STAT 2 .Os BSD 4 .Sh NAME .Nm fstat , +.Nm fstat64 , .Nm lstat , -.Nm stat +.Nm lstat64 , +.Nm stat , +.Nm stat64 , +.Nm fstatat .Nd get file status .Sh SYNOPSIS .Fd #include @@ -58,10 +62,31 @@ .Fa "const char *restrict path" .Fa "struct stat *restrict buf" .Fc +.Ft int +.Fn fstatat "int fd" "const char *path" "struct stat *buf" "int flag" +.Sh TRANSITIIONAL SYNOPSIS (NOW DEPRECATED) +.Ft int +.br +.Fo fstat64 +.Fa "int fildes" +.Fa "struct stat64 *buf" +.Fc ; +.sp +.Ft int +.br +.Fo lstat64 +.Fa "const char *restrict path" +.Fa "struct stat64 *restrict buf" +.Fc ; +.sp +.Ft int +.br +.Fo stat64 +.Fa "const char *restrict path" +.Fa "struct stat64 *restrict buf" +.Fc ; .Sh DESCRIPTION -The -.Fn stat -family of functions obtain information about a file. The +The .Fn stat function obtains information about the file pointed to by .Fa path . @@ -69,21 +94,19 @@ 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 -.Fn Lstat +The +.Fn lstat +function is like .Fn stat -except in the case where the named file is a symbolic link, -in which case +except in the case where the named file is a symbolic link; .Fn lstat returns information about the link, while .Fn stat returns information about the file the link references. -Unlike other filesystem objects, -symbolic links do not have an owner, group, access mode, times, etc. -Instead, these attributes are taken from the directory that -contains the link. -The only attributes returned from an +The attributes cannot be relied on in case of symbolic links. +In this case, the only attributes returned from an .Fn lstat that refer to the symbolic link itself are the file type (S_IFLNK), size, blocks, and link count (always 1). @@ -95,6 +118,48 @@ known by the file descriptor .Fa fildes . .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 buf argument is a pointer to a .Fa stat @@ -102,8 +167,38 @@ structure as defined by .Aq Pa sys/stat.h and into which information is placed concerning the file. +When the macro +.Dv _DARWIN_FEATURE_64_BIT_INODE +is not defined (see below for more information about this macro), the +.Fa stat +structure is defined as: +.Bd -literal +struct stat { /* when _DARWIN_FEATURE_64_BIT_INODE is NOT defined */ + dev_t st_dev; /* device inode resides on */ + ino_t st_ino; /* inode's number */ + mode_t st_mode; /* inode protection mode */ + 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 special file inode */ + 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 */ + off_t st_size; /* file size, in bytes */ + quad_t st_blocks; /* blocks allocated for file */ + u_long st_blksize;/* optimal file sys I/O ops blocksize */ + u_long st_flags; /* user defined flags for file */ + u_long st_gen; /* file generation number */ +}; +.Ed +.Pp +However, when the macro +.Dv _DARWIN_FEATURE_64_BIT_INODE +is defined, the +.Fa stat +structure will now be defined as: .Bd -literal -struct stat { +struct stat { /* when _DARWIN_FEATURE_64_BIT_INODE is defined */ dev_t st_dev; /* ID of device containing file */ mode_t st_mode; /* Mode of file (see below) */ nlink_t st_nlink; /* Number of hard links */ @@ -123,8 +218,6 @@ struct stat { int32_t st_lspare; /* RESERVED: DO NOT USE! */ int64_t st_qspare[2]; /* RESERVED: DO NOT USE! */ }; - - .Ed .Pp The time-related fields of @@ -161,10 +254,9 @@ and .Xr write 2 system calls. .It st_birthtime -Time of file creation. Only set once when the file is created. -On filesystems where birthtime is not available, this field holds the -.Fa ctime -instead. +Time of file creation. Only set once when the file is created. This field is +only available in the 64 bit inode variants. On filesystems where birthtime is +not available, this field is set to 0 (i.e. epoch). .El .Pp The size-related fields of the structures are as follows: @@ -210,6 +302,141 @@ field, see .Aq Pa sys/stat.h and .Xr chflags 2 . +.Sh _DARWIN_FEATURE_64_BIT_INODE +In order to accommodate advanced capabilities of newer file systems, the +.Fa struct stat , +.Fa struct statfs , +and +.Fa struct dirent +data structures were updated in Mac OSX 10.5. +.Pp +The most obvious change is the increased size of +.Fa ino_t +from 32 bits to 64 bits. As a consequence, storing an ino_t in an int is +no longer safe, and file formats storing ino_t as 32-bit values may need to +be updated. There are other changes as well, such as the widening of +.Fa f_fstypename , +.Fa f_mntonname , +and +.Fa f_mntfromname +in +.Fa struct statfs . +Please refer to +.Xr stat 2 +and +.Xr dir 5 +for more detail on the specific changes to the other affected data structures. +.Pp +On platforms that existed before these updates were available, ABI +compatibility is achieved by providing two implementations for related +functions: one using the legacy data structures and one using the updated +data structures. Variants which make use of the newer structures have their +symbols suffixed with $INODE64. These $INODE64 suffixes are automatically +appended by the compiler tool-chain and should not be used directly. +.Pp +Platforms that were released after these updates only have the newer variants +available to them. These platforms have the macro +.Dv _DARWIN_FEATURE_ONLY_64_BIT_INODE +defined. +.Pp +The +.Dv _DARWIN_FEATURE_64_BIT_INODE +macro should not be set directly. Instead, developers should make use of the +.Dv _DARWIN_NO_64_BIT_INODE +or +.Dv _DARWIN_USE_64_BIT_INODE +macros when the default variant is not desired. The following table details +the effects of defining these macros for different deployment targets. +.Pp +.TS +center; +c s s s +l | c s s +c | c c c +c | c c c +l | c c c. +T{ +.Dv _DARWIN_FEATURE_ONLY_64_BIT_INODE Sy not defined +T} += + Deployment Target +user defines: < 10.5 10.5 > 10.5 +_ +T{ +.Em (none) +T} 32-bit 32-bit 64-bit +T{ +.Dv _DARWIN_NO_64_BIT_INODE +T} 32-bit 32-bit 32-bit +T{ +.Dv _DARWIN_USE_64_BIT_INODE +T} 32-bit 64-bit 64-bit +_ +.T& +c s s s +c s s s +c | l s s +c | c c c +l | c c c. + +T{ +.Dv _DARWIN_FEATURE_ONLY_64_BIT_INODE Sy defined +T} += +user defines: Any Deployment Target +_ +T{ +.Em (none) +T} 64-bit-only +T{ +.Dv _DARWIN_NO_64_BIT_INODE +T} T{ +.Em (error) +T} +T{ +.Dv _DARWIN_USE_64_BIT_INODE +T} 64-bit-only +_ +.TE +.Pp +.Bl -tag -width 64-bit-only -offset indent +.It 32-bit +32-bit inode values are enabled, and the legacy structures involving the +.Vt ino_t +type are in use. +The macro +.Dv _DARWIN_FEATURE_64_BIT_INODE +is not defined. +.It 64-bit +64-bit inode values are enabled, and the expanded structures involving the +.Vt ino_t +type are in use. +The macro +.Dv _DARWIN_FEATURE_64_BIT_INODE +is defined, and loader symbols will contain the +.Li $INODE64 +suffix. +.It 64-bit-only +Like 64-bit, except loader symbols do not have the +.Li $INODE64 +suffix. +.It Em (error) +A compile time error is generated. +.El +.Pp +Due to the increased benefits of the larger structure, it is highly +recommended that developers not define +.Dv _DARWIN_NO_64_BIT_INODE +and make use of +.Dv _DARWIN_USE_64_BIT_INODE +when targeting Mac OSX 10.5. +.Pp +In addition to the $INODE64 suffixed symbols, variants suffixed with 64 are +also available for related functions. These functions were provided as a way +for developers to use the updated structures in code that also made use of +the legacy structures. The enlarged stat structures were also prefixed with +64 to distinguish them from their legacy variants. These functions have been +deprecated and should be avoided. .Sh RETURN VALUES Upon successful completion a value of 0 is returned. Otherwise, a value of -1 is returned and @@ -296,16 +523,75 @@ or the file serial number cannot be represented correctly in the structure pointed to by .Fa buf . .El +.Pp +In addition to the errors returned by the +.Fn stat +and +.Fn lstat , +.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 CAVEATS The file generation number, .Fa st_gen , is only available to the super-user. +.br +The fields in the stat structure currently marked +.Fa st_spare1 , +.Fa st_spare2 , +and +.Fa st_spare3 +are present in preparation for inode time stamps expanding +to 64 bits. This, however, can break certain programs that +depend on the time stamps being contiguous (in calls to +.Xr utimes 2 ) . +.Sh TRANSITIONAL DESCRIPTION (NOW DEPRECATED) +The +.Fa fstat64 , +.Fa lstat64 +and +.Fa stat64 +routines are equivalent to their corresponding non-64-suffixed routine, +when 64-bit inodes are in effect. +They were added before there was support for the symbol variants, and so are +now deprecated. +Instead of using these, set the +.Dv _DARWIN_USE_64_BIT_INODE +macro before including header files to force 64-bit inode support. +.Pp +The +.Fa stat64 +structure used by these deprecated routines is the same as the +.Fa stat +structure when 64-bit inodes are in effect (see above). .Sh SEE ALSO .Xr chflags 2 , .Xr chmod 2 , .Xr chown 2 , .Xr utimes 2 , .Xr compat 5 , +.Xr statfs 2 , .Xr symlink 7 .Sh BUGS Applying @@ -321,8 +607,21 @@ and .Fn fstat function calls are expected to conform to .St -p1003.1-88 . +The +.Fn fstatat +system call is expected to conform to POSIX.1-2008 . .Sh HISTORY An .Fn lstat function call appeared in .Bx 4.2 . +The +.Fn stat64 , +.Fn fstat64 , +and +.Fn lstat64 +system calls first appeared in Mac OS X 10.5 (Leopard) and are now deprecated +in favor of the corresponding symbol variants. +The +.Fn fstatat +system call appeared in OS X 10.10