STAT

NAME

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

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

ERRORS

[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

Index

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

ERRORS

SEE ALSO