.Dt STAT 2
.Os BSD 4
.Sh NAME
-.Nm stat ,
+.Nm fstat ,
.Nm lstat ,
-.Nm fstat
+.Nm stat
.Nd get file status
.Sh SYNOPSIS
-.Fd #include <sys/types.h>
.Fd #include <sys/stat.h>
.Ft int
-.Fn stat "const char *path" "struct stat *sb"
+.Fo fstat
+.Fa "int fildes"
+.Fa "struct stat *buf"
+.Fc
.Ft int
-.Fn lstat "const char *path" "struct stat *sb"
+.Fo lstat
+.Fa "const char *restrict path"
+.Fa "struct stat *restrict buf"
+.Fc
.Ft int
-.Fn fstat "int fd" "struct stat *sb"
+.Fo stat
+.Fa "const char *restrict path"
+.Fa "struct stat *restrict buf"
+.Fc
.Sh DESCRIPTION
The
.Fn stat
+family of functions obtain information about a file. The
+.Fn stat
function obtains information about the file pointed to by
.Fa path .
Read, write or execute
.Fn fstat
obtains the same information about an open file
known by the file descriptor
-.Fa fd .
+.Fa fildes .
.Pp
The
-.Fa sb
+.Fa buf
argument is a pointer to a
-.Fn stat
-structure
+.Fa stat
+structure
as defined by
.Aq Pa sys/stat.h
-(shown below)
and into which information is placed concerning the file.
.Bd -literal
struct stat {
- 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 or 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 */
+ 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 */
+ ino_t st_ino; /* File serial number */
+ uid_t st_uid; /* User ID of the file */
+ gid_t st_gid; /* Group ID of the file */
+ dev_t st_rdev; /* Device ID */
+ struct timespec st_atimespec; /* time of last access */
+ struct timespec st_mtimespec; /* time of last data modification */
+ struct timespec st_ctimespec; /* time of last status change */
+ struct timespec st_birthtimespec; /* time of file creation(birth) */
+ off_t st_size; /* file size, in bytes */
+ blkcnt_t st_blocks; /* blocks allocated for file */
+ blksize_t st_blksize; /* optimal blocksize for I/O */
+ uint32_t st_flags; /* user defined flags for file */
+ uint32_t st_gen; /* file generation number */
+ int32_t st_lspare; /* RESERVED: DO NOT USE! */
+ int64_t st_qspare[2]; /* RESERVED: DO NOT USE! */
};
+
+
.Ed
.Pp
The time-related fields of
.Fa struct stat
are as follows:
-.Bl -tag -width XXXst_mtime
+.Bl -tag -width XXXst_birthtime
.It st_atime
Time when file data last accessed.
Changed by the
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.
.El
.Pp
-The size-related fields of the
-.Fa struct stat
-are as follows:
+The size-related fields of the structures are as follows:
.Bl -tag -width XXXst_blksize
.It st_blksize
The optimal I/O block size for the file.
.Xr access 2
and
.Xr chmod 2 .
+.Pp
+For a list of the file flags in the
+.Fa st_flags
+field, see
+.Aq Pa sys/stat.h
+and
+.Xr chflags 2 .
.Sh RETURN VALUES
Upon successful completion a value of 0 is returned.
Otherwise, a value of -1 is returned and
.Li st_blocks
fields.
.Sh ERRORS
-.Fn Stat
-and
+.Bl -tag -width Er
+The
+.Fn fstat
+system call will fail if:
+.\" ===========
+.It Bq Er EBADF
+.Fa fildes
+is not a valid open file descriptor.
+.\" ===========
+.It Bq Er EFAULT
+.Fa Sb
+points to an invalid address.
+.\" ===========
+.It Bq Er EIO
+An I/O error occurs while reading from or writing to the file system.
+.El
+.Pp
+The
.Fn lstat
-will fail if:
+and
+.Fn stat
+system calls will fail if:
.Bl -tag -width Er
-.It Bq Er ENOTDIR
-A component of the path prefix is not a directory.
-.It Bq Er ENAMETOOLONG
-A component of a pathname exceeded
-.Dv {NAME_MAX}
-characters, or an entire path name exceeded
-.Dv {PATH_MAX}
-characters.
-.It Bq Er ENOENT
-The named file does not exist.
+.\" ===========
.It Bq Er EACCES
Search permission is denied for a component of the path prefix.
-.It Bq Er ELOOP
-Too many symbolic links were encountered in translating the pathname.
+.\" ===========
.It Bq Er EFAULT
.Fa Sb
or
.Em name
points to an invalid address.
+.\" ===========
.It Bq Er EIO
-An I/O error occurred while reading from or writing to the file system.
+An I/O error occurs while reading from or writing to the file system.
+.\" ===========
+.It Bq Er ELOOP
+Too many symbolic links are encountered in translating the pathname.
+This is taken to be indicative of a looping symbolic link.
+.\" ===========
+.It Bq Er ENAMETOOLONG
+A component of a pathname exceeds
+.Dv {NAME_MAX}
+characters, or an entire path name exceeds
+.Dv {PATH_MAX}
+characters.
+.\" ===========
+.It Bq Er ENOENT
+The named file does not exist.
+.\" ===========
+.It Bq Er ENOTDIR
+A component of the path prefix is not a directory.
.El
.Pp
+The
+.Fn fstat ,
+.Fn lstat ,
+and
+.Fn stat
+system calls will fail if:
.Bl -tag -width Er
-.Fn Fstat
-will fail if:
-.It Bq Er EBADF
-.Fa fd
-is not a valid open file descriptor.
-.It Bq Er EFAULT
-.Fa Sb
-points to an invalid address.
-.It Bq Er EIO
-An I/O error occurred while reading from or writing to the file system.
+.\" ===========
+.It Bq Er EOVERFLOW
+The file size in bytes
+or the number of blocks allocated to the file
+or the file serial number cannot be represented correctly
+in the structure pointed to by
+.Fa buf .
.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 SEE ALSO
+.Xr chflags 2 ,
.Xr chmod 2 ,
.Xr chown 2 ,
-.Xr utimes 2
+.Xr utimes 2 ,
+.Xr compat 5 ,
.Xr symlink 7
.Sh BUGS
Applying
projects / apple / xnu.git / blobdiff