stat(2)                                                         stat(2)

  stat()

  NAME

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

  SYNOPSIS

    #include 
    #include 

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

  DESCRIPTION

    The stat(2) and wcs_stat(2) functions are identical, as are the lstat(2)
    and wcs_lstat(2) functions, except that the wcs_stat(2) and wcs_lstat(2)
    functions accept wide characters in the path argument.

    The stat(2) and wcs_stat(2) functions obtain 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) or
    wcs_stat(2) returns information about the file the link references.

    The lstat(2) and wcs_lstat(2) functions are like stat(2), unless 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  will work
    with a symbolic link.

    The fstat(2) function 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  (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 , 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 ; 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), wcs_stat(2), and fstat(2) return 0.
    Otherwise they return -1 and set errno to indicate the error.

  ERRORS

    The stat(2), wcs_stat(2), lstat(2), and wcs_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.

    [ENOENT]
        The named file does not exist.

    [ENOMEM]
        Insufficient memory to allocate the stat structure.

    [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.

  SEE ALSO

    chmod(2)

    chown(2)

    group_from_gid(3)

    user_from_uid(3)

    utime(2)

  USAGE NOTES

    All of these functions are thread safe.

    All of these functions are async-signal safe.