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 lstat ,
 .Nm lstat64 ,
 .Nm stat ,

-.Nm stat64
+.Nm stat64 ,
+.Nm fstatat

 .Nd get file status
 .Sh SYNOPSIS
 .Fd #include <sys/stat.h>
 .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
 .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
 .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.
 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
 .Pp
 The
 .Fn fstat


@@ -118,6 +120,48 @@ known by the file descriptor
 .Fa fildes .
 .Pp
 The
 .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
 .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 
 .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:
 .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
 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 ,
 .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 .
 .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
 .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.
 .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