283 lines
10 KiB
HTML
283 lines
10 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>chmod</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="chmod"></a> <a name="tag_03_70"></a><!-- chmod -->
|
|
<!--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_03_70_01"></a>NAME</h4>
|
|
|
|
<blockquote>chmod - change mode of a file</blockquote>
|
|
|
|
<h4><a name="tag_03_70_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<p><code><tt>#include <<a href="../basedefs/sys/stat.h.html">sys/stat.h</a>><br>
|
|
<br>
|
|
int chmod(const char *</tt><i>path</i><tt>, mode_t</tt> <i>mode</i><tt>);<br>
|
|
</tt></code></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_70_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>chmod</i>() function shall change 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"> S_ISVTX, <img src="../images/opt-end.gif" alt="[Option End]"
|
|
border="0"> and the file permission bits of the file named by the pathname pointed to by the <i>path</i> argument to the
|
|
corresponding bits in the <i>mode</i> argument. The application shall ensure that the effective user ID of the process matches the
|
|
owner of the file or the process has appropriate privileges in order to do this.</p>
|
|
|
|
<p>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"> S_ISVTX, <img src="../images/opt-end.gif" alt="[Option End]" border="0"> and the file permission
|
|
bits are described in <a href="../basedefs/sys/stat.h.html"><i><sys/stat.h></i></a>.</p>
|
|
|
|
<p>If the calling process does not have appropriate privileges, and if the group ID of the file does not match the effective group
|
|
ID or one of the supplementary group IDs and if the file is a regular file, bit S_ISGID (set-group-ID on execution) in the file's
|
|
mode shall be cleared upon successful return from <i>chmod</i>().</p>
|
|
|
|
<p>Additional implementation-defined restrictions may cause the S_ISUID and S_ISGID bits in <i>mode</i> to be ignored.</p>
|
|
|
|
<p>The effect on file descriptors for files open at the time of a call to <i>chmod</i>() is implementation-defined.</p>
|
|
|
|
<p>Upon successful completion, <i>chmod</i>() shall mark for update the <i>st_ctime</i> field of the file.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_70_04"></a>RETURN VALUE</h4>
|
|
|
|
<blockquote>
|
|
<p>Upon successful completion, 0 shall be returned; otherwise, -1 shall be returned and <i>errno</i> set to indicate the error. If
|
|
-1 is returned, no change to the file mode occurs.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_70_05"></a>ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>chmod</i>() function shall fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EACCES]</dt>
|
|
|
|
<dd>Search permission is denied on a component of the path prefix.</dd>
|
|
|
|
<dt>[ELOOP]</dt>
|
|
|
|
<dd>A loop exists in symbolic links encountered during resolution of the <i>path</i> argument.</dd>
|
|
|
|
<dt>[ENAMETOOLONG]</dt>
|
|
|
|
<dd>
|
|
The length of the <i>path</i> argument exceeds {PATH_MAX} or a pathname component is longer than {NAME_MAX}.</dd>
|
|
|
|
<dt>[ENOTDIR]</dt>
|
|
|
|
<dd>A component of the path prefix is not a directory.</dd>
|
|
|
|
<dt>[ENOENT]</dt>
|
|
|
|
<dd>A component of <i>path</i> does not name an existing file or <i>path</i> is an empty string.</dd>
|
|
|
|
<dt>[EPERM]</dt>
|
|
|
|
<dd>The effective user ID does not match the owner of the file and the process does not have appropriate privileges.</dd>
|
|
|
|
<dt>[EROFS]</dt>
|
|
|
|
<dd>The named file resides on a read-only file system.</dd>
|
|
</dl>
|
|
|
|
<p>The <i>chmod</i>() function may fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EINTR]</dt>
|
|
|
|
<dd>A signal was caught during execution of the function.</dd>
|
|
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd>The value of the <i>mode</i> argument is invalid.</dd>
|
|
|
|
<dt>[ELOOP]</dt>
|
|
|
|
<dd>More than {SYMLOOP_MAX} symbolic links were encountered during resolution of the <i>path</i> argument.</dd>
|
|
|
|
<dt>[ENAMETOOLONG]</dt>
|
|
|
|
<dd>
|
|
As a result of encountering a symbolic link in resolution of the <i>path</i> argument, the length of the substituted pathname
|
|
strings exceeded {PATH_MAX}.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_03_70_06"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<h5><a name="tag_03_70_06_01"></a>Setting Read Permissions for User, Group, and Others</h5>
|
|
|
|
<p>The following example sets read permissions for the owner, group, and others.</p>
|
|
|
|
<pre>
|
|
<tt>#include <sys/stat.h>
|
|
<br>
|
|
const char *path;
|
|
...
|
|
chmod(path, S_IRUSR|S_IRGRP|S_IROTH);
|
|
</tt>
|
|
</pre>
|
|
|
|
<h5><a name="tag_03_70_06_02"></a>Setting Read, Write, and Execute Permissions for the Owner Only</h5>
|
|
|
|
<p>The following example sets read, write, and execute permissions for the owner, and no permissions for group and others.</p>
|
|
|
|
<pre>
|
|
<tt>#include <sys/stat.h>
|
|
<br>
|
|
const char *path;
|
|
...
|
|
chmod(path, S_IRWXU);
|
|
</tt>
|
|
</pre>
|
|
|
|
<h5><a name="tag_03_70_06_03"></a>Setting Different Permissions for Owner, Group, and Other</h5>
|
|
|
|
<p>The following example sets owner permissions for CHANGEFILE to read, write, and execute, group permissions to read and execute,
|
|
and other permissions to read.</p>
|
|
|
|
<pre>
|
|
<tt>#include <sys/stat.h>
|
|
<br>
|
|
#define CHANGEFILE "/etc/myfile"
|
|
...
|
|
chmod(CHANGEFILE, S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH);
|
|
</tt>
|
|
</pre>
|
|
|
|
<h5><a name="tag_03_70_06_04"></a>Setting and Checking File Permissions</h5>
|
|
|
|
<p>The following example sets the file permission bits for a file named <b>/home/cnd/mod1</b>, then calls the <a href=
|
|
"../functions/stat.html"><i>stat</i>()</a> function to verify the permissions.</p>
|
|
|
|
<pre>
|
|
<tt>#include <sys/types.h>
|
|
#include <sys/stat.h>
|
|
<br>
|
|
int status;
|
|
struct stat buffer
|
|
...
|
|
chmod("home/cnd/mod1", S_IRWXU|S_IRWXG|S_IROTH|S_IWOTH);
|
|
status = stat("home/cnd/mod1", &buffer;);
|
|
</tt>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_70_07"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>In order to ensure that the S_ISUID and S_ISGID bits are set, an application requiring this should use <a href=
|
|
"../functions/stat.html"><i>stat</i>()</a> after a successful <i>chmod</i>() to verify this.</p>
|
|
|
|
<p>Any file descriptors currently open by any process on the file could possibly become invalid if the mode of the file is changed
|
|
to a value which would deny access to that process. One situation where this could occur is on a stateless file system. This
|
|
behavior will not occur in a conforming environment.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_70_08"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>This volume of IEEE Std 1003.1-2001 specifies that the S_ISGID bit is cleared by <i>chmod</i>() on a regular file
|
|
under certain conditions. This is specified on the assumption that regular files may be executed, and the system should prevent
|
|
users from making executable <a href="../functions/setgid.html"><i>setgid</i>()</a> files perform with privileges that the caller
|
|
does not have. On implementations that support execution of other file types, the S_ISGID bit should be cleared for those file
|
|
types under the same circumstances.</p>
|
|
|
|
<p>Implementations that use the S_ISUID bit to indicate some other function (for example, mandatory record locking) on
|
|
non-executable files need not clear this bit on writing. They should clear the bit for executable files and any other cases where
|
|
the bit grants special powers to processes that change the file contents. Similar comments apply to the S_ISGID bit.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_70_09"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_70_10"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="chown.html"><i>chown</i>()</a> , <a href="mkdir.html"><i>mkdir</i>()</a> , <a href="mkfifo.html"><i>mkfifo</i>()</a> ,
|
|
<a href="open.html"><i>open</i>()</a> , <a href="stat.html"><i>stat</i>()</a> , <a href="statvfs.html"><i>statvfs</i>()</a> , the
|
|
Base Definitions volume of IEEE Std 1003.1-2001, <a href="../basedefs/sys/stat.h.html"><i><sys/stat.h></i></a>, <a
|
|
href="../basedefs/sys/types.h.html"><i><sys/types.h></i></a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_70_11"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 1. Derived from Issue 1 of the SVID.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_70_12"></a>Issue 6</h4>
|
|
|
|
<blockquote>
|
|
<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>The requirement to include <a href="../basedefs/sys/types.h.html"><i><sys/types.h></i></a> has been removed. Although <a
|
|
href="../basedefs/sys/types.h.html"><i><sys/types.h></i></a> was required for conforming implementations of previous POSIX
|
|
specifications, it was not required for UNIX applications.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The [EINVAL] and [EINTR] optional error conditions are added.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>A second [ENAMETOOLONG] is added as an optional error condition.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>The following changes were made to align with the IEEE P1003.1a draft standard:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>The [ELOOP] optional error condition is added.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>The DESCRIPTION is updated to avoid use of the term "must" for application requirements.</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>
|
|
|