.\"
.\" @(#)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 <sys/stat.h>
.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 .
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).
.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
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 */
int32_t st_lspare; /* RESERVED: DO NOT USE! */
int64_t st_qspare[2]; /* RESERVED: DO NOT USE! */
};
-
-
.Ed
.Pp
The time-related fields of
.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:
.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
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
.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
projects / apple / xnu.git / blobdiff