<!DOCTYPE html PUBLIC "‐//W3C//DTD XHTML 1.1//EN"
        "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">     <html
xmlns="http://www.w3.org/1999/xhtml"> <head>
    <link            rel="stylesheet"             type="text/css"
href="../../../style.css" title="style" />
    <link  rel="stylesheet"  type="text/css"  href="../style.css"
title="style" />
    <meta             http‐equiv="content‐type"              con‐
tent="text/html;charset=utf‐8" />

    <title>sys_stat.h.0p ‐ Linux manual page</title> </head>

<body>

<div        class="page‐top"><a       id="top_of_page"></a></div>
<!‐‐%%%TOP_BAR%%%‐‐> <!‐‐%%%PAGE_START%%%‐‐>

<table class="sec‐table"> <tr>
    <td>
        <p class="section‐dir"> <a href="#PROLOG">PROLOG</a> | <a
href="#NAME">NAME</a>  |  <a  href="#SYNOPSIS">SYNOPSIS</a>  | <a
href="#DESCRIPTION">DESCRIPTION</a> |  <a  href="#APPLICATION_US‐
AGE">APPLICATION&nbsp;USAGE</a>   |  <a  href="#RATIONALE">RATIO‐
NALE</a>   |   <a    href="#FUTURE_DIRECTIONS">FUTURE&nbsp;DIREC‐
TIONS</a>    |   <a   href="#SEE_ALSO">SEE&nbsp;ALSO</a>   |   <a
href="#COPYRIGHT">COPYRIGHT</a>
        </p>
    </td>
    <td class="search‐box">
        <div class="man‐search‐box">

            <form                method="get"                 ac‐
tion="http://www.google.com/search">
                <fieldset class="man‐search">
                    <input    type="text"    name="q"   size="10"
maxlength="255" value="" />
                    <input type="hidden"  name="sitesearch"  val‐
ue="man7.org/linux/man‐pages" />
                    <input  type="submit" name="sa" value="Search
online pages" />
                </fieldset>
            </form>

        </div>
    </td>
    <td> </td> </tr> </table>

<pre> <span class="headline">sys_stat.h(0P)            POSIX Pro‐
grammer’s  Manual            sys_stat.h(0P)</span>  </pre> <h2><a
id="PROLOG" href="#PROLOG"></a>PROLOG  &nbsp; &nbsp; &nbsp;  &nb‐
sp;        <a        href="#top_of_page"><span        class="top‐
link">top</span></a></h2><pre>
       This manual page is part of the POSIX Programmer’s Manual.
The Linux
       implementation of this interface may differ (consult the
       corresponding  Linux  manual page for details of Linux be‐
havior), or
       the interface may not be  implemented  on  Linux.   </pre>
<h2><a id="NAME" href="#NAME"></a>NAME  &nbsp; &nbsp; &nbsp; &nb‐
sp;        <a        href="#top_of_page"><span        class="top‐
link">top</span></a></h2><pre>
       sys/stat.h  —  data returned by the stat() function </pre>
<h2><a id="SYNOPSIS" href="#SYNOPSIS"></a>SYNOPSIS  &nbsp; &nbsp;
&nbsp;    &nbsp;    <a    href="#top_of_page"><span   class="top‐
link">top</span></a></h2><pre>
       #include &lt;sys/stat.h&gt; </pre> <h2><a id="DESCRIPTION"
href="#DESCRIPTION"></a>DESCRIPTION   &nbsp; &nbsp; &nbsp; &nbsp;
<a             href="#top_of_page"><span              class="top‐
link">top</span></a></h2><pre>
       The  <i>&lt;sys/stat.h&gt;</i>  header  shall  define  the
structure of the data
       returned  by  the  <i>fstat</i>(),   <i>lstat</i>(),   and
<i>stat</i>() functions.

       The  <i>&lt;sys/stat.h&gt;</i>  header  shall  define  the
<b>stat </b>structure, which shall
       include at least the following members:

           <b>dev_t st_dev             </b>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  charac‐
ter 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 sym‐
bolic 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 time‐
stamp.
           struct timespec st_ctim Last file status change  time‐
stamp.
           blksize_t  st_blksize     A  file system‐specific pre‐
ferred 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 <i>st_ino</i> and <i>st_dev</i> fields taken  together
uniquely identify the
       file within the system.

       The  <i>&lt;sys/stat.h&gt;</i>  header  shall  define  the
<b>blkcnt_t</b>, <b>blksize_t</b>, <b>dev_t</b>,
       <b>ino_t</b>, <b>mode_t</b>, <b>nlink_t</b>, <b>uid_t</b>,
<b>gid_t</b>, <b>off_t</b>, and <b>time_t </b>types as
       described in <i>&lt;sys/types.h&gt;</i>.

       The  <i>&lt;sys/stat.h&gt;</i>  header  shall  define  the
<b>timespec </b>structure as
       described in <i>&lt;time.h&gt;</i>.  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
<i>fstat</i>(),
       <i>lstat</i>(), and <i>stat</i>() in the System Interfaces
volume of POSIX.1‐2008.

       For compatibility with earlier versions of this  standard,
the
       <i>st_atime</i>  macro  shall  be  defined  with the value
<i>st_atim.tv_sec</i>.
       Similarly, <i>st_ctime</i> and  <i>st_mtime</i>  shall  be
defined as macros with the
       values  <i>st_ctim.tv_sec</i>  and  <i>st_mtim.tv_sec</i>,
respectively.

       The <i>&lt;sys/stat.h&gt;</i> header shall define the fol‐
lowing symbolic constants
       for  the  file  types  encoded in type <b>mode_t</b>.  The
values shall be
       suitable for use in <b>#if </b>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 <i>&lt;sys/stat.h&gt;</i> header shall define the fol‐
lowing symbolic constants
       for the file mode bits encoded in type <b>mode_t</b>, 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 <i>open</i>()  without  the  need
for a <b>mode_t </b>cast.
       The values shall be suitable for use in <b>#if </b>prepro‐
cessing directives.

      ┌────────┬───────────────┬──────────────────────────────────────────────┐
      │     <b>Name       </b>│     <b>Numeric     Value    </b>│
<b>Description                  </b>│
      ├────────┼───────────────┼──────────────────────────────────────────────┤
      │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,  own‐
er.            │
      ├────────┼───────────────┼──────────────────────────────────────────────┤
      │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,  oth‐
ers.           │
      ├────────┼───────────────┼──────────────────────────────────────────────┤
      │S_ISUID  │      04000      │  Set‐user‐ID  on   execution.
│
      │S_ISGID  │      02000      │  Set‐group‐ID  on  execution.
│
      │S_ISVTX │     01000     │ On directories, restricted dele‐
tion flag.    │
      └────────┴───────────────┴──────────────────────────────────────────────┘
       The following macros shall be provided to test  whether  a
file is of
       the  specified  type.  The  value <i>m</i> supplied to the
macros is the value
       of <i>st_mode</i> from a <b>stat </b>structure. The  macro
shall evaluate to a non‐
       zero value if the test is true; 0 if the test is false.

       S_ISBLK(<i>m</i>)    Test for a block special file.

       S_ISCHR(<i>m</i>)    Test for a character special file.

       S_ISDIR(<i>m</i>)    Test for a directory.

       S_ISFIFO(<i>m</i>)   Test for a pipe or FIFO special file.

       S_ISREG(<i>m</i>)    Test for a regular file.

       S_ISLNK(<i>m</i>)    Test for a symbolic link.

       S_ISSOCK(<i>m</i>)   Test for a socket.

       The  implementation  may  implement  message queues, sema‐
phores, or
       shared memory objects as distinct file types. The  follow‐
ing macros
       shall  be provided to test whether a file is of the speci‐
fied type.
       The value of  the  <i>buf</i>  argument  supplied  to  the
macros is a pointer to
       a  <b>stat  </b>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 <b>stat </b>struc‐
ture referenced by
       <i>buf</i>.  Otherwise, the macro shall evaluate to zero.

       S_TYPEISMQ(<i>buf</i>)
                     Test for a message queue.

       S_TYPEISSEM(<i>buf</i>)
                     Test for a semaphore.

       S_TYPEISSHM(<i>buf</i>)
                     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  <i>buf</i>  argument
supplied to the
       macros  is a pointer to a <b>stat </b>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
<b>stat</b>
       structure referenced by <i>buf</i>.  Otherwise, the  macro
shall evaluate to
       zero.

       S_TYPEISTMO(<i>buf</i>)
                     Test macro for a typed memory object.

       The <i>&lt;sys/stat.h&gt;</i> header shall define the fol‐
lowing symbolic constants
       as  distinct  integer  values   outside   of   the   range
[0,999999999], for
       use  with  the  <i>futimens</i>()  and  <i>utimensat</i>()
functions: UTIME_NOW
       UTIME_OMIT

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

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

       <i>The  following  sections  are  informative.</i>  </pre>
<h2><a  id="APPLICATION_USAGE"  href="#APPLICATION_USAGE"></a>AP‐
PLICATION    USAGE     &nbsp;    &nbsp;    &nbsp;    &nbsp;    <a
href="#top_of_page"><span                             class="top‐
link">top</span></a></h2><pre>
       Use of the macros is recommended for determining the  type
of   a   file.    </pre>   <h2><a   id="RATIONALE"  href="#RATIO‐
NALE"></a>RATIONALE    &nbsp;    &nbsp;    &nbsp;    &nbsp;    <a
href="#top_of_page"><span                             class="top‐
link">top</span></a></h2><pre>
       A   conforming   C‐language   application   must   include
<i>&lt;sys/stat.h&gt;</i> for
       functions  that  have  arguments  or return values of type
<b>mode_t</b>, so
       that symbolic values for that type can be used. An  alter‐
native would
       be to require that these constants are also defined by in‐
cluding
       <i>&lt;sys/types.h&gt;</i>.

       The S_ISUID and S_ISGID bits may be cleared on any  write,
not just on
       <i>open</i>(), as some historical implementations do.

       System  calls  that  update  the  time entry fields in the
<b>stat </b>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‐2008 unless the  stan‐
dard 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
<i>stat</i>() must always
       return an <i>st_mtim.tv_nsec</i> that  is  a  multiple  of
1000. Some older
       implementations   returned   higher‐resolution  timestamps
while the <i>inode</i>
       information was cached, and then  spontaneously  truncated
the <i>tv_nsec</i>
       fields  when  they were stored to and retrieved from disk,
but this
       behavior does not conform.

       Note that <i>st_dev</i> 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 <i>st_ino</i> and <i>st_dev</i> fields.

       The unit for the <i>st_blocks</i> member  of  the  <b>stat
</b>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 correla‐
tion between
       values  of the <i>st_blocks</i> and <i>st_blksize</i>, and
the <i>f_bsize</i> (from
       <i>&lt;sys/statvfs.h&gt;</i>) structure members.

       Traditionally, some implementations defined the multiplier
for
       <i>st_blocks</i> in <i>&lt;sys/param.h&gt;</i> as the sym‐
bol DEV_BSIZE.

       Some earlier versions of this  standard  did  not  specify
values for the
       file mode bit macros. The expectation was that some imple‐
mentors
       might choose to use a different encoding  for  these  bits
than the
       traditional  one, and that new applications would use sym‐
bolic 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.
</pre>    <h2><a    id="FUTURE_DIRECTIONS"   href="#FUTURE_DIREC‐
TIONS"></a>FUTURE DIRECTIONS   &nbsp;  &nbsp;  &nbsp;  &nbsp;  <a
href="#top_of_page"><span                             class="top‐
link">top</span></a></h2><pre>
       No new S_IFMT symbolic names for the file type  values  of
<b>mode_t </b>will
       be  defined  by  POSIX.1‐2008;  if  new file types are re‐
quired, they will
       only be testable  through  <i>S_ISxx</i>()  or  <i>S_TYPE‐
ISxxx</i>()   macros   instead.    </pre>   <h2><a  id="SEE_ALSO"
href="#SEE_ALSO"></a>SEE ALSO  &nbsp;  &nbsp;  &nbsp;  &nbsp;  <a
href="#top_of_page"><span                             class="top‐
link">top</span></a></h2><pre>
       <a
href="../man0/sys_statvfs.h.0p.html">sys_statvfs.h(0p)</a>,    <a
href="../man0/sys_types.h.0p.html">sys_types.h(0p)</a>,        <a
href="../man0/time.h.0p.html">time.h(0p)</a>

       The   System   Interfaces   volume   of  POSIX.1‐2008,  <a
href="../man3/chmod.3p.html">chmod(3p)</a>, <a href="../man3/fch‐
mod.3p.html">fchmod(3p)</a>,
       <a      href="../man3/fstat.3p.html">fstat(3p)</a>,     <a
href="../man3/fstatat.3p.html">fstatat(3p)</a>,                <a
href="../man3/futimens.3p.html">futimens(3p)</a>,              <a
href="../man3/mkdir.3p.html">mkdir(3p)</a>, <a  href="../man3/mk‐
fifo.3p.html">mkfifo(3p)</a>,
       <a      href="../man3/mknod.3p.html">mknod(3p)</a>,     <a
href="../man3/umask.3p.html">umask(3p)</a>     </pre>      <h2><a
id="COPYRIGHT"   href="#COPYRIGHT"></a>COPYRIGHT   &nbsp;  &nbsp;
&nbsp;   &nbsp;    <a    href="#top_of_page"><span    class="top‐
link">top</span></a></h2><pre>
       Portions  of  this  text  are  reprinted and reproduced in
electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for  Informa‐
tion
       Technology ‐‐ Portable Operating System Interface (POSIX),
The Open
       Group Base Specifications Issue 7, Copyright (C)  2013  by
the
       Institute of Electrical and Electronics Engineers, Inc and
The Open
       Group.  (This is POSIX.1‐2008 with the 2013 Technical Cor‐
rigendum 1
       applied.)  In  the  event  of any discrepancy between this
version and
       the original IEEE and The Open Group Standard, the  origi‐
nal IEEE and
       The Open Group Standard is the referee document. The orig‐
inal
       Standard    can    be    obtained     online     at     <a
href="http://www.unix.org/online.html">http://www.unix.org/on‐
line.html</a> .

       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
       <a      href="https://www.kernel.org/doc/man‐pages/report‐
ing_bugs.html">https://www.kernel.org/doc/man‐pages/report‐
ing_bugs.html</a> .

<span  class="footline">IEEE/The  Open Group                 2013
sys_stat.h(0P)</span> </pre>

<hr class="end‐man‐text" />

<hr class="start‐footer" />

<div class="footer">

<table class="colophon‐table">
    <tr>
    <td class="pub‐info">
        <p>
            HTML rendering created 2019‐08‐02
            by  <a  href="http://man7.org/mtk/index.html">Michael
Kerrisk</a>,
            author of
            <a  href="http://man7.org/tlpi/"><em>The  Linux  Pro‐
gramming Interface</em></a>,
            maintainer of the
            <a href="https://www.kernel.org/doc/man‐pages/">Linux
<em>man‐pages</em> project</a>.
        </p>
        <p>
            For details of in‐depth
            <strong>Linux/UNIX  system programming training cour‐
ses</strong>
            that I teach,  look  <a  href="http://man7.org/train‐
ing/">here</a>.
        </p>
        <p>
            Hosting    by    <a   href="http://www.jambit.com/in‐
dex_en.html">jambit GmbH</a>.
        </p>
        <p>
            <a href="http://validator.w3.org/check?uri=referer">
            <img src="http://www.w3.org/Icons/valid‐xhtml11"
                alt="Valid XHTML 1.1" height="31" width="88" />
            </a>
        </p>
    </td>
    <td class="colophon‐divider">
    </td>
    <td class="tlpi‐cover">
        <a                      href="http://man7.org/tlpi/"><img
src="http://man7.org/tlpi/cover/TLPI‐front‐cover‐vsmall.png"
alt="Cover of TLPI" /></a>
    </td>
    </tr> </table>

</div>

<hr class="end‐footer" />

</body> </html>