STAT(2P)STAT(2P)NAME
stat, fstat - (POSIX version) get file status
SYNOPSIS
#include <sys/types.h>
#include <sys/stat.h>
int stat(const char *path, struct stat *buf);
int fstat(int fd, struct stat *buf);
DESCRIPTION
The information in this specification applies only to POSIX
applications.
This is the POSIX specification for stat. For the BSD specification,
see stat(2).
The stat function obtains information about the file whose name is
given by path. Read, write or execute permission of the named file is
not required, but all directories listed in the pathname leading to the
file must be searchable.
The fstat function obtains the same information about an open file
referenced by the file descriptor fd.
The buf argument is a pointer to a stat structure, into which
information is placed concerning the file. The stat structure is
defined in the header <sys/stat.h> and includes the following members:
Member Type Member Name Description
mode_t st_mode File mode.
ino_t st_ino File's inode number.
dev_t st_dev ID of device containing the
file.
nlink_t st_nlink Number of links to the file.
uid_t st_uid User ID of the file's owner.
gid_t st_gid Group ID of the file's group.
off_t st_size File size in bytes.
time_t st_atime Time of last access.
time_t st_mtime Time of last data
modification.
time_t st_ctime Time of last file status
change.
The values of the time-related fields are given in seconds since the
Epoch.
The header <sys/stat.h> also defines the following macros which can be
used to test whether a file is of the specified type. The value m
supplied to the macros must be the the value of the st_mode member of a
stat structure. Each macro evaluates to a nonzero value if the test is
true, and zero if the test is false.
S_ISDIR(m) Test macro for a directory.
S_ISCHR(m) Test macro for a character special file.
S_ISBLK(m) Test macro for a block special file.
S_ISREG(m) Test macro for a regular file.
S_ISFIFO(m) Test macro for a FIFO.
Furthermore, <sys/stat.h> includes the following masks and bits which
can used to encode or decode the file modes portion of values of type
mode_t, such as the st_mode member of the stat structure.
S_IRWXU Read, write, execute (if a non-directory), or
search (if a directory) “owner” permissions mask.
S_IRUSR “Owner” read permission bit.
S_IWUSR “Owner” write permission bit.
S_IXUSR “Owner” execute (if a non-
directory) or search (if a
directory) permission bit.
S_IRWXG Read, write, execute (if a non-directory), or
search (if a directory) “group” permissions mask.
S_IRGRP “Group” read permission bit.
S_IWGRP “Group” write permission bit.
S_IXGRP “Group” execute (if a non-
directory) or search (if a
directory) permission bit.
S_IRWXO Read, write, execute (if a non-directory), or
search (if a directory) “other” permissions mask.
S_IROTH “Other” read permission bit.
S_IWOTH “Other” write permission bit.
S_IXOTH “Other” execute (if a non-
directory) or search (if a
directory) permission bit.
S_ISUID Set-user-id bit. The effective user ID of the
process is set to that of the file's owner when
the file is executed. On a regular file, this
bit is cleared on any write.
S_ISGID Set-group-id bit. The effective group ID of the
process is set to that of the file's group when
the file is executed. On a regular file, this
bit is cleared on any write.
The S_IRWXU mask is the bitwise inclusive OR of the S_IRUSR, S_IWUSR
and S_IXUSR bits.
The S_IRWXG mask is the bitwise inclusive OR of the S_IRGRP, S_IWGRP
and S_IXGRP bits.
The S_IRWXO mask is the bitwise inclusive OR of the S_IROTH, S_IWOTH
and S_IXOTH bits.
Both stat and fstat functions update any time-related fields of the
named file before writing into the stat structure.
RETURN VALUE
Upon successful completion a value of zero is returned. Otherwise, a
value of -1 is returned and errno is set to indicate the error.
ERRORS
If any of the following conditions occurs, stat returns -1 and sets
errno to the corresponding value:
[EACCES] Search permission is denied for a component of the path
prefix.
[EFAULT] Either path or buf points outside the process's
allocated address space.
[EINVAL] The pathname contains a character with the high-order
bit set.
[EIO] An I/O error occurred while reading from or writing to
the file system.
[ELOOP] Too many symbolic links were encountered in translating
the pathname.
[ENAMETOOLONG] A component of path exceeds {NAME_MAX} (see <limits.h>)
characters, or the entire pathname exceeds {PATH_MAX}
(see <limits.h>) characters.
[ENOENT] The named file does not exist.
[ENOENT] The path argument points to an empty string.
[ENOTDIR] A component of the path prefix is not a directory.
If any of the following conditions occurs, fstat returns -1 and sets
errno to the corresponding value:
[EBADF] The fd argument is not a valid open file descriptor.
[EFAULT] The buf argument points outside the process's allocated
address space.
[EIO] An I/O error occurred while reading from or writing to
the file system.
SEE ALSOchmod(2P), chown(2P), creat(2P), dup(2P), fcntl(2P), open(2P),
pipe(2P), stat(2)4th Berkeley Distribution August 1, 1992 STAT(2P)
