xnu-4903.270.47.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..e6ed48bf0b2dc1e19d4b945adb14a372b53f064e 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,14 +105,13 @@ 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.
-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).
+For symbolic links, the st_mode member contains meaningful information
+when used with the file type macros, and the st_size member contains
+the length of the pathname contained in the symbolic link. File mode
+bits and the contents of the remaining members of the stat structure
+are unspecified. The value returned in the st_size member is the
+length of the contents of the symbolic link, and does not count any
+trailing null.
 .Pp
 The
 .Fn fstat
@@ -118,6 +120,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 +258,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 +525,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 +609,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 +624,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