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 TypeMember Name Description

mode_tst_mode File mode. 

ino_tst_ino File’s inode number. 

dev_tst_dev ID of device containing the file. 

nlink_tst_nlink Number of links to the file. 

uid_tst_uid User ID of the file’s owner. 

gid_tst_gid Group ID of the file’s group. 

off_tst_size File size in bytes. 

time_tst_atime Time of last access. 

time_tst_mtime Time of last data modification. 

time_tst_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 ALSO

chmod(2P), chown(2P), creat(2P), dup(2P), fcntl(2P), open(2P), pipe(2P), stat(2)

4th Berkeley Distribution  —  August 1, 1992