stat.h.html

IEEE 1003.1-2003, Single Unix Specification v3

<p>Implementations may OR other implementation-defined bits into S_IRWXU, S_IRWXG, and S_IRWXO, but they shall not overlap any of
the other bits defined in this volume of IEEE&nbsp;Std&nbsp;1003.1-2001. The <i>file permission bits</i> are defined to be those
corresponding to the bitwise-inclusive OR of S_IRWXU, S_IRWXG, and S_IRWXO.</p>

<p>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.</p>

<dl compact>
<dt>S_ISBLK(<i>m</i>)</dt>

<dd>Test for a block special file.</dd>

<dt>S_ISCHR(<i>m</i>)</dt>

<dd>Test for a character special file.</dd>

<dt>S_ISDIR(<i>m</i>)</dt>

<dd>Test for a directory.</dd>

<dt>S_ISFIFO(<i>m</i>)</dt>

<dd>Test for a pipe or FIFO special file.</dd>

<dt>S_ISREG(<i>m</i>)</dt>

<dd>Test for a regular file.</dd>

<dt>S_ISLNK(<i>m</i>)</dt>

<dd>Test for a symbolic link.</dd>

<dt>S_ISSOCK(<i>m</i>)</dt>

<dd>Test for a socket.</dd>
</dl>

<p>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 <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.</p>

<dl compact>
<dt>S_TYPEISMQ(<i>buf</i>)</dt>

<dd>Test for a message queue.</dd>

<dt>S_TYPEISSEM(<i>buf</i>)</dt>

<dd>Test for a semaphore.</dd>

<dt>S_TYPEISSHM(<i>buf</i>)</dt>

<dd>Test for a shared memory object.</dd>
</dl>

<p><sup>[<a href="javascript:open_code('TYM')">TYM</a>]</sup> <img src="../../images/opt-start.gif" alt="[Option Start]" border=
"0"> 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.</p>

<dl compact>
<dt>S_TYPEISTMO(<i>buf</i>)</dt>

<dd>Test macro for a typed memory object.</dd>
</dl>

<img src="../../images/opt-end.gif" alt="[Option End]" border="0"> 

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

<pre>
<tt>int    chmod(const char *, mode_t);
int    fchmod(int, mode_t);
int    fstat(int, struct stat *);
int    lstat(const char *restrict, struct stat *restrict);
int    mkdir(const char *, mode_t);
int    mkfifo(const char *, mode_t);
<sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup><img src="../../images/opt-start.gif" alt="[Option Start]" border="0">
int    mknod(const char *, mode_t, dev_t);
<img src="../../images/opt-end.gif" alt="[Option End]" border="0">
int    stat(const char *restrict, struct stat *restrict);
mode_t umask(mode_t);
</tt>
</pre>
</blockquote>

<hr>
<div class="box"><em>The following sections are informative.</em></div>

<h4><a name="tag_13_62_04"></a>APPLICATION USAGE</h4>

<blockquote>
<p>Use of the macros is recommended for determining the type of a file.</p>
</blockquote>

<h4><a name="tag_13_62_05"></a>RATIONALE</h4>

<blockquote>
<p>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 alternative would be to require that these constants are
also defined by including <a href="../../basedefs/sys/types.h.html"><i>&lt;sys/types.h&gt;</i></a>.</p>

<p>The S_ISUID and S_ISGID bits may be cleared on any write, not just on <a href="../../functions/open.html"><i>open</i>()</a>, as
some historical implementations do.</p>

<p>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
IEEE&nbsp;Std&nbsp;1003.1-2001 unless the standard requires that they do, except in the case of documented extensions to the
standard.</p>

<p>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.</p>

<p>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.</p>

<p>The unit for the <i>st_blocks</i> member of the <b>stat</b> structure is not defined within IEEE&nbsp;Std&nbsp;1003.1-2001. In
some implementations it is 512 bytes. It may differ on a file system basis. There is no correlation between values of the
<i>st_blocks</i> and <i>st_blksize</i>, and the <i>f_bsize</i> (from <a href=
"../../basedefs/sys/statvfs.h.html"><i>&lt;sys/statvfs.h&gt;</i></a>) structure members.</p>

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

<h4><a name="tag_13_62_06"></a>FUTURE DIRECTIONS</h4>

<blockquote>
<p>No new S_IFMT symbolic names for the file type values of <b>mode_t</b> will be defined by IEEE&nbsp;Std&nbsp;1003.1-2001; if new
file types are required, they will only be testable through <i>S_ISxx</i>() or <i>S_TYPEISxxx</i>() macros instead.</p>
</blockquote>

<h4><a name="tag_13_62_07"></a>SEE ALSO</h4>

<blockquote>
<p><a href="../sys/statvfs.h.html#tag_13_63"><i>&lt;sys/statvfs.h&gt;</i></a> , <a href=
"../sys/types.h.html#tag_13_67"><i>&lt;sys/types.h&gt;</i></a> , the System Interfaces volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a
href="../../functions/chmod.html"><i>chmod</i>()</a>, <a href="../../functions/fchmod.html"><i>fchmod</i>()</a>, <a href=
"../../functions/fstat.html"><i>fstat</i>()</a>, <a href="../../functions/lstat.html"><i>lstat</i>()</a>, <a href=
"../../functions/mkdir.html"><i>mkdir</i>()</a>, <a href="../../functions/mkfifo.html"><i>mkfifo</i>()</a>, <a href=
"../../functions/mknod.html"><i>mknod</i>()</a>, <a href="../../functions/stat.html"><i>stat</i>()</a>, <a href=
"../../functions/umask.html"><i>umask</i>()</a></p>
</blockquote>

<h4><a name="tag_13_62_08"></a>CHANGE HISTORY</h4>

<blockquote>
<p>First released in Issue 1. Derived from Issue 1 of the SVID.</p>
</blockquote>

<h4><a name="tag_13_62_09"></a>Issue 5</h4>

<blockquote>
<p>The DESCRIPTION is updated for alignment with the POSIX Realtime Extension.</p>

<p>The type of <i>st_blksize</i> is changed from <b>long</b> to <b>blksize_t</b>; the type of <i>st_blocks</i> is changed from
<b>long</b> to <b>blkcnt_t</b>.</p>
</blockquote>

<h4><a name="tag_13_62_10"></a>Issue 6</h4>

<blockquote>
<p>The S_TYPEISMQ(), S_TYPEISSEM(), and S_TYPEISSHM() macros are unconditionally mandated.</p>

<p>The Open Group Corrigendum U035/4 is applied. In the DESCRIPTION, the types <b>blksize_t</b> and <b>blkcnt_t</b> have been
described.</p>

<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p>

<ul>
<li>
<p>The <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
are mandated.</p>
</li>
</ul>

<p>S_IFSOCK and S_ISSOCK are added for sockets.</p>

<p>The description of <b>stat</b> structure members is changed to reflect contents when file type is a symbolic link.</p>

<p>The test macro S_TYPEISTMO is added for alignment with IEEE&nbsp;Std&nbsp;1003.1j-2000.</p>

<p>The <b>restrict</b> keyword is added to the prototypes for <a href="../../functions/lstat.html"><i>lstat</i>()</a> and <a href=
"../../functions/stat.html"><i>stat</i>()</a>.</p>

<p>The <a href="../../functions/lstat.html"><i>lstat</i>()</a> function is made mandatory.</p>

<p>IEEE&nbsp;Std 1003.1-2001/Cor&nbsp;1-2002, item XBD/TC1/D6/17 is applied, adding text regarding the <i>st_blocks</i> member of
the <b>stat</b> structure to the RATIONALE.</p>
</blockquote>

<div class="box"><em>End of informative text.</em></div>

<hr>
<hr size="2" noshade>
<center><font size="2"><!--footer start-->
UNIX &reg; is a registered Trademark of The Open Group.<br>
POSIX &reg; is a registered Trademark of The IEEE.<br>
[ <a href="../../mindex.html">Main Index</a> | <a href="../../basedefs/contents.html">XBD</a> | <a href=
"../../utilities/contents.html">XCU</a> | <a href="../../functions/contents.html">XSH</a> | <a href=
"../../xrat/contents.html">XRAT</a> ]</font></center>

<!--footer end-->
<hr size="2" noshade>
</body>
</html>