xnu-3248.20.55.tar.gz

[apple/xnu.git] / bsd / man / man2 / stat.2

diff --git a/bsd/man/man2/stat.2 b/bsd/man/man2/stat.2
index 02de79c7274bb52821adf44001629684be263719..7282de5a91b76f2c131cf970d42c87cab042ff70 100644 (file)
--- a/bsd/man/man2/stat.2
+++ b/bsd/man/man2/stat.2
@@ -42,7 +42,8 @@
 .Nm lstat ,
 .Nm lstat64 ,
 .Nm stat ,
-.Nm stat64
+.Nm stat64 ,
+.Nm fstatat
 .Nd get file status
 .Sh SYNOPSIS
 .Fd #include <sys/stat.h>
@@ -61,6 +62,8 @@
 .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
@@ -102,10 +105,7 @@ returns information about the link,
 while
 .Fn stat
 returns information about the file the link references.
-Unlike other filesystem objects,
-symbolic links may not have an owner, group, access mode, times, etc.
-Instead, these attributes may be taken from the directory that
-contains the link.
+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),
@@ -118,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
@@ -214,9 +256,7 @@ system calls.
 .It st_birthtime
 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 holds the
-.Fa ctime
-instead.
+not available, this field is set to 0 (i.e. epoch).
 .El
 .Pp
 The size-related fields of the structures are as follows:
@@ -483,6 +523,35 @@ 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 ,
@@ -538,6 +607,9 @@ 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
@@ -550,3 +622,6 @@ 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