STAT(2)

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
stat, fstat, and lstat return a stat structure, which is declared as follows:

    struct stat
    {
        dev_t         st_dev;      /* device */
        ino_t         st_ino;      /* inode */
        umode_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 */
    };

Not all of the Linux filesystems implement all of the time fields. Traditionally, st_atime is changed by mknod(2), utime(2), read(2), write(2), and truncate(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 flags are defined for the st_mode field:

    S_IFMT
        0170000 type of file

    S_IFSOCK
        0140000 socket

    S_IFLNK
        0120000 symbolic link

    S_IFREG
        0100000 regular file

    S_IFBLK
        0060000 block device

    S_IFDIR
        0040000 directory

    S_IFCHR
        0020000 character device

    S_IFIFO
        0010000 fifo

    S_ISUID
        04000 set user ID on execution

    S_ISGID
        02000 set group ID on execution

    S_ISVTX
        01000 sticky bit

    S_IRUSR (S_IREAD)
        00400 read by owner

    S_IWUSR (S_IWRITE)
        00200 write by owner

    S_IXUSR (S_IEXEC)
        00100 execute/search by owner

    S_IRGRP
        00040 read by group

    S_IWGRP
        00020 write by group

    S_IXGRP
        00010 execute/search by group

    S_IROTH
        00004 read by others

    S_IWOTH
        00002 write by others

    S_IXOTH
        00001 execute/search by others

And the following macros are defined to utilize those fields:

#define S_ISLNK(m)	(((m) & S_IFMT) == S_IFLNK)
#define S_ISREG(m)	(((m) & S_IFMT) == S_IFREG)
#define S_ISDIR(m)	(((m) & S_IFMT) == S_IFDIR)
#define S_ISCHR(m)	(((m) & S_IFMT) == S_IFCHR)
#define S_ISBLK(m)	(((m) & S_IFMT) == S_IFBLK)
#define S_ISFIFO(m)	(((m) & S_IFMT) == S_IFIFO)
#define S_ISSOCK(m)	(((m) & S_IFMT) == S_IFSOCK)

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 is stated in place of file_name.

RETURN VALUE
On success, zero is returned. On error, -1 is returned, and errno is set appropriately.

ERRORS

EBADF
    filedes is bad.

ENOENT
    File does not exist.

CONFORMING TO
SVID (not lstat()), AT&T (not lstat()), POSIX (not lstat()), X/OPEN (not lstat()), BSD 4.3

SEE ALSO
chmod(2), chown(2), readlink(2), utime(2)