stat()

NAME

stat(), lstat(), fstat() - get file status

SYNOPSIS

#include <sys/types.h>
#include <sys/stat.h>


int stat (const char *path, struct stat *sb)
int lstat (const char *path, struct stat *sb)
int fstat (int fd, struct stat *sb)

The stat(2) function obtains information about the file pointed to 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. If path is a symbolic link, stat(2) returns information about the file the link references.

The lstat(2) function is like stat(2), except if the file named by path is a symbolic link. In this case, lstat(2) returns information about the link file itself. The function stores the length of the pathname in the link file in the st_size member (without the trailing null). The file type information macros defined in <sys/stat.h> will work with a symbolic link.

The fstat(2) obtains the same information about an open file identified by the file descriptor fd.

The sb argument is a pointer to a stat structure as defined by <sys/stat.h> (shown below) and into which information is placed concerning the file.

Type	Field	Description
mode_t	st_mode	protection mode
ino_t	st_ino	file serial number
dev_t	st_dev	device file resides on
dev_t	st_rdev	type of device file resides on
nlink_t	st_nlink	number of hard links to the file
uid_t	st_uid	user-ID of owner
gid_t	st_gid	group-ID of owner
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
long	st_blksize	optimal file system I/O ops blocksize
long	st_blocks	number of blocks allocated for the file
int	st_attrs	MS-DOS file attributes
int	st_info	Interix-specific flags
long	st_reserved[18]	reserved for future use

The time-related fields of struct stat are as follows:

st_atime: Time when file data last accessed. Changed by the utime(2) and read(2) calls.
st_mtime: Time when file data last modified. Changed by the utime(2) and write(2) calls.
st_ctime: Time when file status was last changed (file serial data modification). Changed by the chmod(2), chown(2), link(2), rename(2), unlink(2), utime(2) and write(2) calls.

The size-related fields of the struct stat are:

st_blksize: The optimal I/O block size for the file.

The status information word st_mode has the following bits:

Symbol	Meaning
S_IFMT	Type of file
S_IFIFO	named pipe (fifo)
S_IFCHR	character special
S_IFDIR	directory
S_IFBLK	block special
S_IFREG	regular
S_IFLNK	symbolic link
S_IFSOCK	file is socket
S_ISUID	set user ID on execution
S_ISGID	set group ID on execution
S_IRWXU	read, write, execute/search by owner
S_IRUSR	read permission, owner
S_IWUSR	write permission, owner
S_IXUSR	execute/search permission, owner
S_IRWXG	read, write, execute/search by group
S_IRGRP	read permission, group
S_IWGRP	write permission, group
S_IXGRP	execute/search permission, group
S_IRWXO	read, write, execute/search by others
S_IROTH	read permission, file other
S_IWOTH	write permission, file other
S_IXOTH	execute/search permission, file other

For a list of access modes, see <sys/stat.h>, access(2) and chmod(2).

For a FIFO file, the st_size field contains its PIPE_BUF value.

The st_attrs field can have the following bits set:

S_READONLY
S_HIDDEN
S_SYSTEM
S_DIRECTORY
S_ARCHIVE
S_TEMPORARY
S_COMPRESSED
S_OFFLINE

The st_info field has only one flag: When st_info is set to S_INO_RELIABLE, st_ino can be trusted.

Determining File Type

To determine the type of a file, several macros are defined in <sys/stat.h>; these all take the value of the st_mode from the stat structure as their argument:

S_ISDIR(m)	True if directory file, false otherwise
S_ISCHR(m)	True if character special file, false otherwise
S_ISBLK(m)	True if block special file, false otherwise
S_ISREG(m)	True if regular file, false otherwise
S_ISFIFO(m)	True if pipe or FIFO special file, false otherwise
S_ISSOCK(m)	True if a socket, false otherwise

RETURN VALUES

Upon successful completion, stat(2) and fstat(2) return 0. Otherwise they return -1 and set errno to indicate the error.

ERRORS

The stat(2) and lstat(2) calls will fail if:

[EACCES]: Search permission is denied for a component of the path prefix.
[EFAULT]: Sb or name points to an invalid address.
[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.
[EINVAL]: The pathname contains a character with the high-order bit set, or the process attempted to stat(2) a file on a device that does not support the call.
[ENAMETOOLONG]: A component of a pathname exceeded characters, or an entire pathname exceeded characters.
[ENOMEM]: Insufficient memory to allocate the stat structure.

The stat(2) and lstat(2) calls will fail if:

[ENOENT]: The named file does not exist.
[ENOTDIR]: A component of the path prefix is not a directory.

The fstat(2) call will fail if:

[EBADF]: fd is not a valid open file descriptor.
[EIO]: An I/O error occurred while reading from or writing to the file system.

NOTE

If the Win32 Read-Only attribute is set on a file, stat(2) reports that the file is unwriteable, no matter what the permissions are. To turn off the Win32 Read-Only attribute, you can use chmod(2) to enable a write permission; chmod(2) will unset the Read-Only attribute.