June 9, 2007 STAT 2

### NAME

stat, lstat, fstat - get file status

### LIBRARY

Standard C Library (libc, -lc)

### SYNOPSIS

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

### DESCRIPTION

The stat(``) 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 path name leading to the file must be searchable.

lstat(``) is like stat(``) except in the case where the named file is a symbolic link, in which case lstat(``) returns information about the link, while stat(``) returns information about the file the link references.

The fstat(``) function obtains the same information about an open file known 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. ``

    struct stat {
        dev_t     st_dev;     /* device containing the file */
        ino_t     st_ino;     /* file's serial number */
        mode_t    st_mode;    /* file's mode (protection and type) */
        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 */
        dev_t     st_rdev;    /* device type, for device special file */
    #if defined(_NETBSD_SOURCE)
        struct timespec st_atimespec;  /* time of last access */
        struct timespec st_mtimespec;  /* time of last data modification */
        struct timespec st_ctimespec;  /* time of last file status change */
    #else
        time_t    st_atime;            /* time of last access */
        long      st_atimensec;        /* nsec of last access */
        time_t    st_mtime;            /* time of last data modification */
        long      st_mtimensec;        /* nsec of last data modification */
        time_t    st_ctime;            /* time of last file status change */
        long      st_ctimensec;        /* nsec of last file status change */
    #endif
        off_t     st_size;    /* file size, in bytes */
        blkcnt_t  st_blocks;  /* blocks allocated for file */
        blksize_t st_blksize; /* optimal file sys I/O ops blocksize */
        uint32_t st_flags;   /* user defined flags for file */
        uint32_t st_gen;     /* file generation number */
    #if defined(_NETBSD_SOURCE)
        struct timespec st_birthtimespec;   /* time of inode creation */
    #else
        time_t    st_birthtime;             /* time of inode creation */
        long      st_birthtimensec;         /* nsec of inode creation */
    #endif
    };

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

st_atime
  Time when file data was last accessed. Changed by the mknod(2), utimes(2) and read(2) system calls.

st_mtime
  Time when file data was last modified. Changed by the mknod(2), utimes(2) and write(2) system calls.

st_ctime
  Time when file status was last changed (file metadata modification). Changed by the chflags(2), chmod(2), chown(2), link(2), mknod(2), rename(2), unlink(2), utimes(2) and write(2) system calls.

st_birthtime
  Time when the inode was created.

If ```_NETBSD_SOURCE` is defined, the time-related fields are defined as: ``

    #if defined(_NETBSD_SOURCE)
    #define st_atime                st_atimespec.tv_sec
    #define st_atimensec            st_atimespec.tv_nsec
    #define st_mtime                st_mtimespec.tv_sec
    #define st_mtimensec            st_mtimespec.tv_nsec
    #define st_ctime                st_ctimespec.tv_sec
    #define st_ctimensec            st_ctimespec.tv_nsec
    #define st_birthtime            st_birthtimespec.tv_sec
    #define st_birthtimensec        st_birthtimespec.tv_nsec
    #endif

The size-related fields of the ```struct` `stat` are as follows:

st_size
  The size of the file in bytes. A directory will be a multiple of the size of the dirent(5) structure. Some filesystems (notably ZFS) return the number of enties in the directory instead of the size in bytes.

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

st_blocks
  The actual number of blocks allocated for the file in 512-byte units. As short symbolic links are stored in the inode, this number may be zero.

The status information word ```st_mode` has the following bits: ``

    #define S_IFMT 0170000           /* type of file */
    #define        S_IFIFO  0010000  /* named pipe (fifo) */
    #define        S_IFCHR  0020000  /* character special */
    #define        S_IFDIR  0040000  /* directory */
    #define        S_IFBLK  0060000  /* block special */
    #define        S_IFREG  0100000  /* regular */
    #define        S_IFLNK  0120000  /* symbolic link */
    #define        S_IFSOCK 0140000  /* socket */
    #define        S_IFWHT  0160000  /* whiteout */
    #define S_ISUID 0004000  /* set user id on execution */
    #define S_ISGID 0002000  /* set group id on execution */
    #define S_ISVTX 0001000  /* save swapped text even after use */
    #define S_IRUSR 0000400  /* read permission, owner */
    #define S_IWUSR 0000200  /* write permission, owner */
    #define S_IXUSR 0000100  /* execute/search permission, owner */
    #define S_IRGRP 0000040  /* read permission, group */
    #define S_IWGRP 0000020  /* write permission, group */
    #define S_IXGRP 0000010  /* execute/search permission, group */
    #define S_IROTH 0000004  /* read permission, other */
    #define S_IWOTH 0000002  /* write permission, other */
    #define S_IXOTH 0000001  /* execute/search permission, other */

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

The status information word ```st_flags` has the following bits: ``

    #define UF_NODUMP       0x00000001 /* do not dump file */
    #define UF_IMMUTABLE    0x00000002 /* file may not be changed */
    #define UF_APPEND       0x00000004 /* writes to file may only append */
    #define UF_OPAQUE       0x00000008 /* directory is opaque wrt. union */
    #define SF_ARCHIVED     0x00010000 /* file is archived */
    #define SF_IMMUTABLE    0x00020000 /* file may not be changed */
    #define SF_APPEND       0x00040000 /* writes to file may only append */

For a description of the flags, see chflags(2).

### RETURN VALUES

Upon successful completion a value of 0 is returned. Otherwise, a value of -1 is returned and errno is set to indicate the error.

### COMPATIBILITY

Previous versions of the system used different types for the ```st_dev`, ```st_uid`, ```st_gid`, ```st_rdev`, ```st_size`, ```st_blksize` and ```st_blocks` fields.

### ERRORS

stat(``) and lstat(``) will fail if:

[```ENOTDIR`]
  A component of the path prefix is not a directory.

[```ENAMETOOLONG`]
  A component of a pathname exceeded ```{NAME_MAX}` characters, or an entire path name exceeded ```{PATH_MAX}` characters.

[```ENOENT`]
  The named file does not exist.

[```EACCES`]
  Search permission is denied for a component of the path prefix.

[```ELOOP`]
  Too many symbolic links were encountered in translating the pathname.

[```EFAULT`]
  ```sb` or name points to an invalid address.

[```ENXIO`]
  The named file is a character special or block special file, and the device associated with this special file does not exist.

[```EIO`]
  An I/O error occurred while reading from or writing to the file system.

[```EBADF`]
  A badly formed v-node was encountered. This can happen if a file system information node is incorrect.

fstat(``) will fail if:

[```EBADF`]
  ```fd` is not a valid open file descriptor.

[```EFAULT`]
  ```sb` points to an invalid address.

[```EIO`]
  An I/O error occurred while reading from or writing to the file system.

### SEE ALSO

chflags(2), chmod(2), chown(2), utimes(2), dir(5), symlink(7)

### STANDARDS

The stat(``) and fstat(``) functions conform to ISO/IEC 9945-1:1990 (``POSIX.1'') .

### HISTORY

A lstat(``) function call appeared in 4.2BSD.

### BUGS

Applying fstat(``) to a socket (and thus to a pipe) returns a zero'd buffer, except for the blocksize field, and a unique device and file serial number.