NAME
stat, fstat, lstat - get file status
SYNOPSIS
#include <sys/stat.h>
#include <unistd.h>
int stat(const char *file_name, struct stat *buf));
int fstat(int filedes, struct stat *buf));
int lstat(const char *file_name, struct stat *buf));
DESCRIPTION
These functions return information about the specified file.
You do not need any access rights to the file to get this
information but you need search rights to all directories
named in the path leading to the file.
stat stats the file pointed to by file_name and fills in
buf.
lstat is identical to stat, only the link itself is stated,
not the file that is obtained by tracing the links.
fstat is identical to stat, only the open file pointed to by
filedes (as returned by open(2)) is stated in place of
file_name.
They all return a stat structure, which contains the follow-
ing fields:
struct stat
{
dev_t st_dev; /* device */
ino_t st_ino; /* inode */
mode_t st_mode; /* protection */
nlink_t st_nlink; /* number of hard links */
uid_t st_uid; /* user ID of owner */
gid_t st_gid; /* group ID of owner */
dev_t st_rdev; /* device type (if inode device) */
off_t st_size; /* total size, in bytes */
unsigned long st_blksize; /* blocksize for filesystem I/O */
unsigned long st_blocks; /* number of blocks allocated */
time_t st_atime; /* time of last access */
time_t st_mtime; /* time of last modification */
time_t st_ctime; /* time of last change */
};
Note that st_blocks may not always be in terms of blocks of
size st_blksize, and that st_blksize may instead provide a
notion of the "preferred" blocksize for efficient file sys-
tem I/O.
Not all of the Linux filesystems implement all of the time
fields. Traditionally, st_atime is changed by mknod(2),
utime(2), read(2),
Traditionally, st_mtime is changed by mknod(2), utime(2),
and write(2). The st_mtime is not changed for changes in
owner, group, hard link count, or mode.
Traditionally, st_ctime is changed by writing or by setting
inode information (i.e., owner, group, link count, mode,
etc.).
The following POSIX macros are defined to check the file
type:
S_ISLNK(m) is it a symbolic link?
S_ISREG(m) regular file?
S_ISDIR(m) directory?
S_ISCHR(m) character device?
S_ISBLK(m) block device?
S_ISFIFO(m) fifo?
S_ISSOCK(m) socket?
The following flags are defined for the st_mode field:
S_IFMT 00170000 bitmask for the file type bitfields
(not POSIX)
S_IFSOCK 0140000 socket (not POSIX)
S_IFLNK 0120000 symbolic link (not POSIX)
S_IFREG 0100000 regular file (not POSIX)
S_IFBLK 0060000 block device (not POSIX)
S_IFDIR 0040000 directory (not POSIX)
S_IFCHR 0020000 character device (not POSIX)
S_IFIFO 0010000 fifo (not POSIX)
S_ISUID 0004000 set UID bit
S_ISGID 0002000 set GID bit
S_ISVTX 0001000 sticky bit (not POSIX)
S_IRWXU 00700 user (file owner) has read, write and
execute permission
S_IRUSR 00400 user has read permission (same as
S_IREAD, which is not POSIX)
S_IWUSR 00200 user has write permission (same as
S_IWRITE, which is not POSIX)
S_IXUSR 00100 user has execute permission (same as
S_IEXEC, which is not POSIX)
S_IRWXG 00070 group has read, write and execute per-
mission
S_IRGRP 00040 group has read permission
S_IWGRP 00020 group has write permission
S_IXGRP 00010 group has execute permission
S_IRWXO 00007 others have read, write and execute per-
mission
S_IROTH 00004 others have read permission
S_IWOTH 00002 others have write permisson
S_IXOTH 00001 others have execute permission
RETURN VALUE
On success, zero is returned. On error, -1 is returned, and
errno is set appropriately.
ERRORS
EBADF
filedes is bad.
ENOENT
A component of the path file_name does not exist, or
the path is an empty string.
ENOTDIR
A component of the path is not a directory.
ELOOP
Too many symbolic links encountered while traversing
the path.
EFAULT
Bad address.
EACCES
Permission denied.
ENOMEM
Out of memory (i.e. kernel memory).
ENAMETOOLONG
File name too long.
CONFORMING TO
The stat and fstat calls conform to SVr4, SVID, POSIX,
X/OPEN, BSD 4.3. The lstat call conforms to 4.3BSD and
SVr4. SVr4 documents additional fstat error conditions
EINTR, ENOLINK, and EOVERFLOW. SVr4 documents additional
stat and lstat error conditions EACCES, EINTR, EMULTIHOP,
ENOLINK, and EOVERFLOW.
SEE ALSO
chmod(2), chown(2), readlink(2), utime (2)