415 lines
16 KiB
HTML
415 lines
16 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title><sys/stat.h></title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../../jscript/dotcode.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="<sys/stat.h>"></a> <a name="tag_13_62"></a><!-- <sys/stat.h> -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_13_62_01"></a>NAME</h4>
|
|
|
|
<blockquote>sys/stat.h - data returned by the stat() function</blockquote>
|
|
|
|
<h4><a name="tag_13_62_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<p><tt>#include <sys/stat.h></tt></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_13_62_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i><sys/stat.h></i> header shall define the structure of the data returned by the functions <a href=
|
|
"../../functions/fstat.html"><i>fstat</i>()</a>, <a href="../../functions/lstat.html"><i>lstat</i>()</a>, and <a href=
|
|
"../../functions/stat.html"><i>stat</i>()</a>.</p>
|
|
|
|
<p>The <b>stat</b> structure shall contain at least the following members:</p>
|
|
|
|
<pre>
|
|
<tt>dev_t st_dev </tt> Device ID of device containing file. <tt>
|
|
ino_t st_ino </tt> File serial number. <tt>
|
|
mode_t st_mode </tt> Mode of file (see below). <tt>
|
|
nlink_t st_nlink </tt> Number of hard links to the file. <tt>
|
|
uid_t st_uid </tt> User ID of file. <tt>
|
|
gid_t st_gid </tt> Group ID of file. <tt>
|
|
<sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup><img src="../../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
dev_t st_rdev </tt> Device ID (if file is character or block special). <tt>
|
|
<img src="../../images/opt-end.gif" alt="[Option End]" border="0">
|
|
off_t st_size </tt> For regular files, the file size in bytes. <tt>
|
|
</tt> For symbolic links, the length in bytes of the <tt>
|
|
</tt> pathname contained in the symbolic link. <tt>
|
|
<sup>[<a href="javascript:open_code('SHM')">SHM</a>]</sup><img src="../../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
</tt> For a shared memory object, the length in bytes. <tt>
|
|
<img src="../../images/opt-end.gif" alt="[Option End]" border="0">
|
|
<sup>[<a href="javascript:open_code('TYM')">TYM</a>]</sup><img src="../../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
</tt> For a typed memory object, the length in bytes. <tt>
|
|
<img src="../../images/opt-end.gif" alt="[Option End]" border="0">
|
|
</tt> For other file types, the use of this field is <tt>
|
|
</tt> unspecified. <tt>
|
|
time_t st_atime </tt> Time of last access. <tt>
|
|
time_t st_mtime </tt> Time of last data modification. <tt>
|
|
time_t st_ctime </tt> Time of last status change. <tt>
|
|
<sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup><img src="../../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
blksize_t st_blksize</tt> A file system-specific preferred I/O block size for <tt>
|
|
</tt> this object. In some file system types, this may <tt>
|
|
</tt> vary from file to file. <tt>
|
|
blkcnt_t st_blocks </tt> Number of blocks allocated for this object. <tt>
|
|
<img src="../../images/opt-end.gif" alt="[Option End]" border="0">
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>The <i>st_ino</i> and <i>st_dev</i> fields taken together uniquely identify the file within the system. 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 shall be defined as described in <a href="../sys/types.h.html#tag_13_67"><i><sys/types.h></i></a> . Times
|
|
shall be given in seconds since the Epoch.</p>
|
|
|
|
<p>Unless otherwise specified, the structure members <i>st_mode</i>, <i>st_ino</i>, <i>st_dev</i>, <i>st_uid</i>, <i>st_gid</i>,
|
|
<i>st_atime</i>, <i>st_ctime</i>, and <i>st_mtime</i> shall have meaningful values for all file types defined in
|
|
IEEE Std 1003.1-2001.</p>
|
|
|
|
<p>For symbolic links, the <i>st_mode</i> member shall contain meaningful information, which can be used with the file type macros
|
|
described below, that take a <i>mode</i> argument. The <i>st_size</i> member shall contain the length, in bytes, of the pathname
|
|
contained in the symbolic link. File mode bits and the contents of the remaining members of the <b>stat</b> structure are
|
|
unspecified. The value returned in the <i>st_size</i> field shall be the length of the contents of the symbolic link, and shall not
|
|
count a trailing null if one is present.</p>
|
|
|
|
<p>The following symbolic names for the values of type <b>mode_t</b> shall also be defined.</p>
|
|
|
|
<p>File type:</p>
|
|
|
|
<dl compact>
|
|
<dt>S_IFMT</dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../../images/opt-start.gif" alt="[Option Start]" border=
|
|
"0"> Type of file.
|
|
|
|
<dl compact>
|
|
<dt>S_IFBLK</dt>
|
|
|
|
<dd>Block special.</dd>
|
|
|
|
<dt>S_IFCHR</dt>
|
|
|
|
<dd>Character special.</dd>
|
|
|
|
<dt>S_IFIFO</dt>
|
|
|
|
<dd>FIFO special.</dd>
|
|
|
|
<dt>S_IFREG</dt>
|
|
|
|
<dd>Regular.</dd>
|
|
|
|
<dt>S_IFDIR</dt>
|
|
|
|
<dd>Directory.</dd>
|
|
|
|
<dt>S_IFLNK</dt>
|
|
|
|
<dd>Symbolic link.</dd>
|
|
|
|
<dt>S_IFSOCK</dt>
|
|
|
|
<dd>Socket. <img src="../../images/opt-end.gif" alt="[Option End]" border="0"></dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
|
|
<p>File mode bits:</p>
|
|
|
|
<dl compact>
|
|
<dt>S_IRWXU</dt>
|
|
|
|
<dd>Read, write, execute/search by owner.
|
|
|
|
<dl compact>
|
|
<dt>S_IRUSR</dt>
|
|
|
|
<dd>Read permission, owner.</dd>
|
|
|
|
<dt>S_IWUSR</dt>
|
|
|
|
<dd>Write permission, owner.</dd>
|
|
|
|
<dt>S_IXUSR</dt>
|
|
|
|
<dd>Execute/search permission, owner.</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt>S_IRWXG</dt>
|
|
|
|
<dd>Read, write, execute/search by group.
|
|
|
|
<dl compact>
|
|
<dt>S_IRGRP</dt>
|
|
|
|
<dd>Read permission, group.</dd>
|
|
|
|
<dt>S_IWGRP</dt>
|
|
|
|
<dd>Write permission, group.</dd>
|
|
|
|
<dt>S_IXGRP</dt>
|
|
|
|
<dd>Execute/search permission, group.</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt>S_IRWXO</dt>
|
|
|
|
<dd>Read, write, execute/search by others.
|
|
|
|
<dl compact>
|
|
<dt>S_IROTH</dt>
|
|
|
|
<dd>Read permission, others.</dd>
|
|
|
|
<dt>S_IWOTH</dt>
|
|
|
|
<dd>Write permission, others.</dd>
|
|
|
|
<dt>S_IXOTH</dt>
|
|
|
|
<dd>Execute/search permission, others.</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt>S_ISUID</dt>
|
|
|
|
<dd>Set-user-ID on execution.</dd>
|
|
|
|
<dt>S_ISGID</dt>
|
|
|
|
<dd>Set-group-ID on execution.</dd>
|
|
|
|
<dt>S_ISVTX</dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../../images/opt-start.gif" alt="[Option Start]" border=
|
|
"0"> On directories, restricted deletion flag. <img src="../../images/opt-end.gif" alt="[Option End]" border="0"></dd>
|
|
</dl>
|
|
|
|
<p>The bits defined by S_IRUSR, S_IWUSR, S_IXUSR, S_IRGRP, S_IWGRP, S_IXGRP, S_IROTH, S_IWOTH, S_IXOTH, S_ISUID, S_ISGID, <sup>[<a
|
|
href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../../images/opt-start.gif" alt="[Option Start]" border="0"> and
|
|
S_ISVTX <img src="../../images/opt-end.gif" alt="[Option End]" border="0"> shall be unique.</p>
|
|
|
|
<p>S_IRWXU is the bitwise-inclusive OR of S_IRUSR, S_IWUSR, and S_IXUSR.</p>
|
|
|
|
<p>S_IRWXG is the bitwise-inclusive OR of S_IRGRP, S_IWGRP, and S_IXGRP.</p>
|
|
|
|
<p>S_IRWXO is the bitwise-inclusive OR of S_IROTH, S_IWOTH, and S_IXOTH.</p>
|
|
|
|
<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 Std 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><sys/stat.h></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><sys/types.h></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 Std 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>
|
|
</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 Std 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/types.h.html#tag_13_67"><i><sys/types.h></i></a> , the System Interfaces volume of
|
|
IEEE Std 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 Std 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>
|
|
</blockquote>
|
|
|
|
<div class="box"><em>End of informative text.</em></div>
|
|
|
|
<hr>
|
|
<hr size="2" noshade>
|
|
<center><font size="2"><!--footer start-->
|
|
UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® 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>
|
|
|