sys_stat.h(3)              POSIX Programmer's Manual             sys_stat.h(3)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.

NNAAMMEE
       sys/stat.h -- data returned by the stat() function

SSYYNNOOPPSSIISS
       #include <sys/stat.h>

DDEESSCCRRIIPPTTIIOONN
       The _<_s_y_s_/_s_t_a_t_._h_> header shall define the structure of the data returned
       by the _f_s_t_a_t(), _l_s_t_a_t(), and _s_t_a_t() functions.

       The _<_s_y_s_/_s_t_a_t_._h_> header shall define the ssttaatt structure, which shall
       include at least the following members:


           dev_t st_dev            Device ID of device containing file.
           ino_t st_ino            File serial number.
           mode_t st_mode          Mode of file (see below).
           nlink_t st_nlink        Number of hard links to the file.
           uid_t st_uid            User ID of file.
           gid_t st_gid            Group ID of file.
           dev_t st_rdev           Device ID (if file is character or block special).
           off_t st_size           For regular files, the file size in bytes.
                                   For symbolic links, the length in bytes of the
                                   pathname contained in the symbolic link.
                                   For a shared memory object, the length in bytes.
                                   For a typed memory object, the length in bytes.
                                   For other file types, the use of this field is
                                   unspecified.
           struct timespec st_atim Last data access timestamp.
           struct timespec st_mtim Last data modification timestamp.
           struct timespec st_ctim Last file status change timestamp.
           blksize_t st_blksize    A file system-specific preferred I/O block size
                                   for this object. In some file system types, this
                                   may vary from file to file.
           blkcnt_t st_blocks      Number of blocks allocated for this object.

       The _s_t___i_n_o and _s_t___d_e_v fields taken together uniquely identify the file
       within the system.

       The _<_s_y_s_/_s_t_a_t_._h_> header shall define the bbllkkccnntt__tt, bbllkkssiizzee__tt, ddeevv__tt,
       iinnoo__tt, mmooddee__tt, nnlliinnkk__tt, uuiidd__tt, ggiidd__tt, ooffff__tt, and ttiimmee__tt types as
       described in _<_s_y_s_/_t_y_p_e_s_._h_>.

       The _<_s_y_s_/_s_t_a_t_._h_> header shall define the ttiimmeessppeecc structure as
       described in _<_t_i_m_e_._h_>.  Times shall be given in seconds since the
       Epoch.

       Which structure members have meaningful values depends on the type of
       file. For further information, see the descriptions of _f_s_t_a_t(),
       _l_s_t_a_t(), and _s_t_a_t() in the System Interfaces volume of POSIX.1-2017.

       For compatibility with earlier versions of this standard, the _s_t___a_t_i_m_e
       macro shall be defined with the value _s_t___a_t_i_m_._t_v___s_e_c.  Similarly,
       _s_t___c_t_i_m_e and _s_t___m_t_i_m_e shall be defined as macros with the values
       _s_t___c_t_i_m_._t_v___s_e_c and _s_t___m_t_i_m_._t_v___s_e_c, respectively.

       The _<_s_y_s_/_s_t_a_t_._h_> header shall define the following symbolic constants
       for the file types encoded in type mmooddee__tt.  The values shall be
       suitable for use in ##iiff preprocessing directives:

       S_IFMT      Type of file.

                   S_IFBLK     Block special.

                   S_IFCHR     Character special.

                   S_IFIFO     FIFO special.

                   S_IFREG     Regular.

                   S_IFDIR     Directory.

                   S_IFLNK     Symbolic link.

                   S_IFSOCK    Socket.

       The _<_s_y_s_/_s_t_a_t_._h_> header shall define the following symbolic constants
       for the file mode bits encoded in type mmooddee__tt, with the indicated
       numeric values. These macros shall expand to an expression which has a
       type that allows them to be used, either singly or OR'ed together, as
       the third argument to _o_p_e_n() without the need for a mmooddee__tt cast. The
       values shall be suitable for use in ##iiff preprocessing directives.

       +--------+---------------+----------------------------------------------+
       | NNaammee   | NNuummeerriicc VVaalluuee |                 DDeessccrriippttiioonn                  |
       +--------+---------------+----------------------------------------------+
       |S_IRWXU |      0700     | Read, write, execute/search by owner.        |
       |S_IRUSR |      0400     | Read permission, owner.                      |
       |S_IWUSR |      0200     | Write permission, owner.                     |
       |S_IXUSR |      0100     | Execute/search permission, owner.            |
       +--------+---------------+----------------------------------------------+
       |S_IRWXG |       070     | Read, write, execute/search by group.        |
       |S_IRGRP |       040     | Read permission, group.                      |
       |S_IWGRP |       020     | Write permission, group.                     |
       |S_IXGRP |       010     | Execute/search permission, group.            |
       +--------+---------------+----------------------------------------------+
       |S_IRWXO |        07     | Read, write, execute/search by others.       |
       |S_IROTH |        04     | Read permission, others.                     |
       |S_IWOTH |        02     | Write permission, others.                    |
       |S_IXOTH |        01     | Execute/search permission, others.           |
       +--------+---------------+----------------------------------------------+
       |S_ISUID |     04000     | Set-user-ID on execution.                    |
       |S_ISGID |     02000     | Set-group-ID on execution.                   |
       |S_ISVTX |     01000     | On directories, restricted deletion flag.    |
       +--------+---------------+----------------------------------------------+
       The following macros shall be provided to test whether a file is of the
       specified type. The value _m supplied to the macros is the value of
       _s_t___m_o_d_e from a ssttaatt structure. The macro shall evaluate to a non-zero
       value if the test is true; 0 if the test is false.

       S_ISBLK(_m)    Test for a block special file.

       S_ISCHR(_m)    Test for a character special file.

       S_ISDIR(_m)    Test for a directory.

       S_ISFIFO(_m)   Test for a pipe or FIFO special file.

       S_ISREG(_m)    Test for a regular file.

       S_ISLNK(_m)    Test for a symbolic link.

       S_ISSOCK(_m)   Test for a socket.

       The implementation may implement message queues, semaphores, or shared
       memory objects as distinct file types. The following macros shall be
       provided to test whether a file is of the specified type. The value of
       the _b_u_f argument supplied to the macros is a pointer to a ssttaatt
       structure. The macro shall evaluate to a non-zero value if the
       specified object is implemented as a distinct file type and the
       specified file type is contained in the ssttaatt structure referenced by
       _b_u_f.  Otherwise, the macro shall evaluate to zero.

       S_TYPEISMQ(_b_u_f)
                     Test for a message queue.

       S_TYPEISSEM(_b_u_f)
                     Test for a semaphore.

       S_TYPEISSHM(_b_u_f)
                     Test for a shared memory object.

       The implementation may implement typed memory objects as distinct file
       types, and the following macro shall test whether a file is of the
       specified type. The value of the _b_u_f argument supplied to the macros is
       a pointer to a ssttaatt structure. The macro shall evaluate to a non-zero
       value if the specified object is implemented as a distinct file type
       and the specified file type is contained in the ssttaatt structure
       referenced by _b_u_f.  Otherwise, the macro shall evaluate to zero.

       S_TYPEISTMO(_b_u_f)
                     Test macro for a typed memory object.

       The _<_s_y_s_/_s_t_a_t_._h_> header shall define the following symbolic constants
       as distinct integer values outside of the range [0,999999999], for use
       with the _f_u_t_i_m_e_n_s() and _u_t_i_m_e_n_s_a_t() functions: UTIME_NOW UTIME_OMIT

       The following shall be declared as functions and may also be defined as
       macros. Function prototypes shall be provided.


           int    chmod(const char *, mode_t);
           int    fchmod(int, mode_t);
           int    fchmodat(int, const char *, mode_t, int);
           int    fstat(int, struct stat *);
           int    fstatat(int, const char *restrict, struct stat *restrict, int);
           int    futimens(int, const struct timespec [2]);
           int    lstat(const char *restrict, struct stat *restrict);
           int    mkdir(const char *, mode_t);
           int    mkdirat(int, const char *, mode_t);
           int    mkfifo(const char *, mode_t);
           int    mkfifoat(int, const char *, mode_t);
           int    mknod(const char *, mode_t, dev_t);
           int    mknodat(int, const char *, mode_t, dev_t);
           int    stat(const char *restrict, struct stat *restrict);
           mode_t umask(mode_t);
           int    utimensat(int, const char *, const struct timespec [2], int);

       Inclusion of the _<_s_y_s_/_s_t_a_t_._h_> header may make visible all symbols from
       the _<_t_i_m_e_._h_> header.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       Use of the macros is recommended for determining the type of a file.

RRAATTIIOONNAALLEE
       A conforming C-language application must include _<_s_y_s_/_s_t_a_t_._h_> for
       functions that have arguments or return values of type mmooddee__tt, so that
       symbolic values for that type can be used. An alternative would be to
       require that these constants are also defined by including
       _<_s_y_s_/_t_y_p_e_s_._h_>.

       The S_ISUID and S_ISGID bits may be cleared on any write, not just on
       _o_p_e_n(), as some historical implementations do.

       System calls that update the time entry fields in the ssttaatt structure
       must be documented by the implementors. POSIX-conforming systems should
       not update the time entry fields for functions listed in the System
       Interfaces volume of POSIX.1-2017 unless the standard requires that
       they do, except in the case of documented extensions to the standard.

       Upon assignment, file timestamps are immediately converted to the
       resolution of the file system by truncation (i.e., the recorded time
       can be older than the actual time). For example, if the file system
       resolution is 1 microsecond, then a conforming _s_t_a_t() must always
       return an _s_t___m_t_i_m_._t_v___n_s_e_c that is a multiple of 1000. Some older
       implementations returned higher-resolution timestamps while the _i_n_o_d_e
       information was cached, and then spontaneously truncated the _t_v___n_s_e_c
       fields when they were stored to and retrieved from disk, but this
       behavior does not conform.

       Note that _s_t___d_e_v must be unique within a Local Area Network (LAN) in a
       ``system'' made up of multiple computers' file systems connected by a
       LAN.

       Networked implementations of a POSIX-conforming system must guarantee
       that all files visible within the file tree (including parts of the
       tree that may be remotely mounted from other machines on the network)
       on each individual processor are uniquely identified by the combination
       of the _s_t___i_n_o and _s_t___d_e_v fields.

       The unit for the _s_t___b_l_o_c_k_s member of the ssttaatt structure is not defined
       within POSIX.1-2008. In some implementations it is 512 bytes. It may
       differ on a file system basis. There is no correlation between values
       of the _s_t___b_l_o_c_k_s and _s_t___b_l_k_s_i_z_e, and the _f___b_s_i_z_e (from _<_s_y_s_/_s_t_a_t_v_f_s_._h_>)
       structure members.

       Traditionally, some implementations defined the multiplier for
       _s_t___b_l_o_c_k_s in _<_s_y_s_/_p_a_r_a_m_._h_> as the symbol DEV_BSIZE.

       Some earlier versions of this standard did not specify values for the
       file mode bit macros. The expectation was that some implementors might
       choose to use a different encoding for these bits than the traditional
       one, and that new applications would use symbolic file modes instead of
       numeric. This version of the standard specifies the traditional
       encoding, in recognition that nearly 20 years after the first
       publication of this standard numeric file modes are still in widespread
       use by application developers, and that all conforming implementations
       still use the traditional encoding.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       No new S_IFMT symbolic names for the file type values of mmooddee__tt will be
       defined by POSIX.1-2008; if new file types are required, they will only
       be testable through _S___I_S_x_x() or _S___T_Y_P_E_I_S_x_x_x() macros instead.

SSEEEE AALLSSOO
       <<ssyyss__ssttaattvvffss..hh>>, <<ssyyss__ttyyppeess..hh>>, <<ttiimmee..hh>>

       The System Interfaces volume of POSIX.1-2017, _c_h_m_o_d(), _f_c_h_m_o_d(),
       _f_s_t_a_t(), _f_s_t_a_t_a_t(), _f_u_t_i_m_e_n_s(), _m_k_d_i_r(), _m_k_f_i_f_o(), _m_k_n_o_d(), _u_m_a_s_k()

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1-2017, Standard for Information Technology --
       Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the
       Institute of Electrical and Electronics Engineers, Inc and The Open
       Group.  In the event of any discrepancy between this version and the
       original IEEE and The Open Group Standard, the original IEEE and The
       Open Group Standard is the referee document. The original Standard can
       be obtained online at http://www.opengroup.org/unix/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2017                        sys_stat.h(3)
