friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
8826eae394
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/chown.htm

882 lines
21 KiB
HTML
Raw Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
<title>chown()--Change Owner and Group of File</title>
<!-- Begin Header Records ========================================== -->
<!-- All rights reserved. Licensed Materials Property of IBM -->
<!-- US Government Users Restricted Rights -->
<!-- Use, duplication or disclosure restricted by -->
<!-- GSA ADP Schedule Contract with IBM Corp. -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- Unix2 SCRIPT J converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!-- 010320 JTROUS Include Journal ERRNOs, should have in V5R1 -->
<!-- 011022 JTROUS Changes from API Review 1, V5R2 -->
<!-- 020618 EMIG Updates for NFS threadsafety, V5R3 -->
<!-- 020501 JET This file has undergone error condition cleanup -->
<!-- 020719 MFENLON: updated for QFileSvr.400 threadsafety, V5R3 -->
<!-- 040615 JTROUS : Add restriction per CPS item, V5R4 -->
<!-- 050321 JTROUS: fix enums, no change flag, V5R4 -->
<!-- End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<!--Java sync-link--><!-- Java sync-link -->
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<a name="Top_Of_Page"></a>
<h2>chown()--Change Owner and Group of File</h2>
<div class="box" style="width: 70%;">
<br>
&nbsp;&nbsp;Syntax<br>
<pre>
#include &lt;unistd.h&gt;
int chown(const char <em>*path</em>, uid_t <em>owner</em>, gid_t <em>group</em>);
</pre>
&nbsp;&nbsp;Service Program Name: QP0LLIB1<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Conditional; see <a href="#USAGE_NOTES">Usage Notes</a>.<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The <strong>chown()</strong> function changes the owner and primary group of a file.
If the named file is a symbolic link, <strong>chown()</strong> resolves the
symbolic link. The permissions of the previous owner or primary group to the
object are revoked.</p>
<p>If the file is checked out by another user (someone other than the user
profile of the current job), <strong>chown()</strong> fails with the [EBUSY]
error.</p>
<p>When <strong>chown()</strong> completes successfully, it updates the change
time of the file.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong><em>path</em></strong></dt>
<dd>
<p>(Input) A pointer to the null-terminated path name of the file whose owner
and group are being changed.</p>
<p>This parameter is assumed to be represented in the CCSID (coded character
set identifier) currently in effect for the job. If the CCSID of the job is
65535, this parameter is assumed to be represented in the default CCSID of the
job.</p>
<p>See <a href="chownu.htm">QlgChown()--Change Owner and Group of File</a> for
a description and an example of supplying the <em>path</em> in any CCSID.</p>
<br>
</dd>
<dt><strong><em>owner</em></strong></dt>
<dd>
<p>(Input) The user ID (UID) of the new owner of the file.</p>
</dd>
<dt><strong><em>group</em></strong></dt>
<dd>
<p>(Input) The group ID (GID) of the new primary group for the file.</p>
<p><img src="delta.gif" alt="Start of change">
The new primary group user cannot be the owner of the object.
<img src="deltaend.gif" alt="End of change"></p>
</dd>
</dl>
<p><strong>Note:</strong> Changing the owner or the primary group causes the
S_ISUID (set-user-ID) and S_ISGID (set-group-ID) bits of the file mode to be
cleared, unless the caller has all object (*ALLOBJ) special authority. If the caller does
have *ALLOBJ special authority, the bits are not changed. This does not apply
to directories or FIFO special files. See the <a href="chmod.htm">chmod()</a>
documentation.</p>
<br>
<h3>Authorities</h3>
<p><strong>Note:</strong> Adopted authority is not used.</p>
<p><strong><a name="TBLACHOWN">Authorization Required for chown() (excluding
QSYS.LIB, independent ASP QSYS.LIB, and QDLS)</a></strong></p>
<table border width="100%">
<!-- cols="60 20 20" -->
<tr>
<th align="left" valign="bottom">Object Referred to</th>
<th align="left" valign="bottom">Authority Required</th>
<th align="left" valign="bottom">errno</th>
</tr>
<tr>
<td align="left" valign="top" width="90%">Each directory in the path name
preceding the object</td>
<td align="center" valign="top" width="5%">*X</td>
<td align="left" valign="top" width="5%">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Object, when changing the owner</td>
<td align="center" valign="top">Owner and *OBJEXIST<br>
(also see <strong>Note 1</strong>)</td>
<td align="left" valign="top">EPERM</td>
</tr>
<tr>
<td align="left" valign="top">Object, when changing the primary group</td>
<td align="center" valign="top">See <strong>Note 2</strong></td>
<td align="left" valign="top">EPERM</td>
</tr>
<tr>
<td align="left" valign="top">Previous owner's user profile, when changing the
owner</td>
<td align="center" valign="top">*DLT</td>
<td align="left" valign="top">EPERM</td>
</tr>
<tr>
<td align="left" valign="top">New owner's user profile, when changing the
owner</td>
<td align="center" valign="top">*ADD</td>
<td align="left" valign="top">EPERM</td>
</tr>
<tr>
<td align="left" valign="top">User profile of previous primary group, when
changing the primary group</td>
<td align="center" valign="top">*DLT</td>
<td align="left" valign="top">EPERM</td>
</tr>
<tr>
<td align="left" valign="top">New primary group's user profile, when changing
the primary group</td>
<td align="center" valign="top">*ADD</td>
<td align="left" valign="top">EPERM</td>
</tr>
<tr>
<td align="left" valign="top" colspan="3"><strong>Note:</strong>
<ol type="1">
<li>You do not need the listed authority if you have *ALLOBJ special
authority.</li>
<li>At least one of the following must be true:
<ol type="a">
<li>You have *ALLOBJ special authority.</li>
<li>You are the owner <u>and</u> either of the following:
<ul>
<li>The new primary group is the primary group of the job.</li>
<li>The new primary group is one of the supplementary groups of the job.</li>
</ul>
</li>
</ol>
</li>
</ol>
</td>
</tr>
</table>
<br>
<p><strong><a name="TBLACHOWN2">Authorization Required for chown() in the
QSYS.LIB and independent ASP QSYS.LIB File Systems</a></strong></p>
<table border width="100%">
<!-- cols="60 20 20" -->
<tr>
<th align="left" valign="bottom">Object Referred to</th>
<th align="left" valign="bottom">Authority Required</th>
<th align="left" valign="bottom">errno</th>
</tr>
<tr>
<td align="left" valign="top" width="90%">Each directory in the path name
preceding the object</td>
<td align="center" valign="top" width="5%">*X<br>
See <strong>Note 1</strong></td>
<td align="left" valign="top" width="5%">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Object when changing the owner</td>
<td align="center" valign="top">See <strong>Note 2</strong>(a)</td>
<td align="left" valign="top">EPERM</td>
</tr>
<tr>
<td align="left" valign="top">Object when changing the primary group</td>
<td align="center" valign="top">See <strong>Note 2</strong>(b)</td>
<td align="left" valign="top">EPERM</td>
</tr>
<tr>
<td align="left" valign="top" colspan="3"><strong>Note:</strong>
<ol type="1">
<li>For *FILE objects (such as DDM file, diskette file, print file, and save
file), *RX authority is required to the parent directory of the object, rather
than just *X authority.</li>
<li>The required authorization varies for each object type. For details of the
following commands, see the <a href="../books/sc415302.pdf">iSeries Security
Reference</a> <img src="wbpdf.gif" alt="Link to PDF"> book.
<ol type="a">
<li>CHGOWN</li>
<li>CHGPGP</li>
</ol>
</li>
</ol>
</td>
</tr>
</table>
<br>
<p><strong><a name="TBLACHOWN3">Authorization Required for chown() in the QDLS
File System</a></strong></p>
<table border width="100%">
<!-- cols="60 20 20" -->
<tr>
<th align="left" valign="bottom">Object Referred to</th>
<th align="left" valign="bottom">Authority Required</th>
<th align="left" valign="bottom">errno</th>
</tr>
<tr>
<td align="left" valign="top" width="90%">Each directory in the path name
preceding the object</td>
<td align="center" valign="top" width="5%">*X</td>
<td align="left" valign="top" width="5%">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Object</td>
<td align="center" valign="top">*ALLOBJ Special<br>
Authority or Owner</td>
<td align="left" valign="top">EPERM</td>
</tr>
<tr>
<td align="left" valign="top">Previous owner's user profile, when changing the
owner</td>
<td align="center" valign="top">*DLT</td>
<td align="left" valign="top">EPERM</td>
</tr>
<tr>
<td align="left" valign="top">New owner's user profile, when changing the
owner</td>
<td align="center" valign="top">*ADD</td>
<td align="left" valign="top">EPERM</td>
</tr>
<tr>
<td align="left" valign="top">Previous primary group's user profile, when
changing the primary group</td>
<td align="center" valign="top">*DLT</td>
<td align="left" valign="top">EPERM</td>
</tr>
<tr>
<td align="left" valign="top">New primary group's user profile, when changing
the primary group</td>
<td align="center" valign="top">*ADD</td>
<td align="left" valign="top">EPERM</td>
</tr>
</table>
<br>
<p><strong><a name="TBLACHOWN4">Authorization Required for chown() in the QOPT
File System</a></strong></p>
<table border width="100%">
<!-- cols="60 20 20" -->
<tr>
<th align="left" valign="bottom">Object Referred to</th>
<th align="left" valign="bottom">Authority Required</th>
<th align="left" valign="bottom">errno</th>
</tr>
<tr>
<td align="left" valign="top" width="90%">Volume authorization list</td>
<td align="center" valign="top" width="5%">*CHANGE</td>
<td align="left" valign="top" width="5%">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Each directory in the path name preceding the
object.</td>
<td align="center" valign="top">*X</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Object</td>
<td align="center" valign="top">*ALLOBJ Special<br>
Authority or Owner</td>
<td align="left" valign="top">EPERM</td>
</tr>
</table>
<br>
<br>
<h3>Return Value</h3>
<dl compact>
<dt><em>0</em></dt>
<dd><strong>chown()</strong> was successful.</dd>
<dt><em>-1</em></dt>
<dd><strong>chown()</strong> was not successful. The <em>errno</em> global
variable is set to indicate the error.</dd>
</dl>
<br>
<h3>Error Conditions</h3>
<p>If <strong>chown()</strong> is not successful, <em>errno</em> usually
indicates one of the following errors. Under some conditions, <em>errno</em>
could indicate an error other than those listed here.</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<th align="left" valign="bottom">Error condition</th>
<th align="left" valign="bottom">Additional information</th>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EACCES">EACCES</a>]</em></td>
<td align="left" valign="top">
<p>If you are accessing a remote file through the Network File System, update
operations to file permissions at the server are not reflected at the client
until updates to data that is stored locally by the Network File System take
place. (Several options on the Add Mounted File System (ADDMFS) command
determine the time between refresh operations of local data.) Access to a
remote file may also fail due to different mappings of user IDs (UID) or group
IDs (GID) on the local and remote systems.</p>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EAGAIN">EAGAIN</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EBADFID">EBADFID</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EBADNAME">EBADNAME</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EBUSY">EBUSY</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ECONVERT">ECONVERT</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EDAMAGE">EDAMAGE</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EFAULT">EFAULT</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EFILECVT">EFILECVT</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EINTR">EINTR</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EINVAL">EINVAL</a>]</em></td>
<td align="left" valign="top">
<p>The <em>owner</em> or <em>group</em> is not a valid user ID (UID) or group ID
(GID). The <em>owner</em> is the current primary group of the object.</p>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EIO">EIO</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EJRNDAMAGE">EJRNDAMAGE</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EJRNENTTOOLONG">EJRNENTTOOLONG</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EJRNINACTIVE">EJRNINACTIVE</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EJRNRCVSPC">EJRNRCVSPC</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ELOOP">ELOOP</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENAMETOOLONG">ENAMETOOLONG</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENEWJRN">ENEWJRN</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENEWJRNRCV">ENEWJRNRCV</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOENT">ENOENT</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOSPC">ENOSPC</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOTAVAIL">ENOTAVAIL</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOTDIR">ENOTDIR</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOTSAFE">ENOTSAFE</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOTSUP">ENOTSUP</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EPERM">EPERM</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EROOBJ">EROOBJ</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ESTALE">ESTALE</a>]</em></td>
<td align="left" valign="top">
<p>If you are accessing a remote file through the Network File System, the file
may have been deleted at the server.</p>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EUNKNOWN">EUNKNOWN</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
</table>
<br>
<br>
<h3>Error Messages</h3>
<p>The following messages may be sent from this API:</p>
<table width="100%">
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td width="15%" valign="top">CPE3418 E</td>
<td width="85%" valign="top">Possible APAR condition or hardware failure.</td>
</tr>
<tr>
<td valign="top">CPFA0D4 E</td>
<td valign="top">File system error occurred. Error number &amp;1.</td>
</tr>
<tr>
<td valign="top">CPF3CF2 E</td>
<td valign="top">Error(s) occurred during running of &amp;1 API.</td>
</tr>
<tr>
<td valign="top">CPF9872 E</td>
<td valign="top">Program or service program &amp;1 in library &amp;2 ended.
Reason code &amp;3.</td>
</tr>
</table>
<br>
<br>
<h3><a name="usage_notes">Usage Notes</a></h3>
<ol type="1">
<li>This function will fail with error code [ENOTSAFE] when all the following
conditions are true:
<ul>
<li>Where multiple threads exist in the job.<br>
</li>
<li>The object on which this function is operating resides in a file system
that is not threadsafe. Only the following file systems are threadsafe for this
function:<br>
<br>
<ul>
<li>"Root" (/)</li>
<li>QOpenSys</li>
<li>User-defined</li>
<li>QNTC</li>
<li>QSYS.LIB</li>
<li>Independent ASP QSYS.LIB</li>
<li>QOPT</li>
<li>Network File System</li>
<li>QFileSvr.400</li>
</ul>
</li>
</ul>
<br>
</li>
<li>QSYS.LIB and Independent ASP QSYS.LIB File System Differences
<p><strong>chown()</strong> is not supported for member (.MBR) objects.</p>
<br>
</li>
<li>QDLS File System Differences
<p>The owner and primary group of the /QDLS directory (root folder) cannot be
changed. If an attempt is made to change the owner and primary group, error
ENOTSUP error is returned.</p>
<br>
</li>
<li>QOPT File System Differences
<p>Changing the owner and primary group is allowed only for an object that
exists on a volume formatted in Universal Disk Format (UDF). For all other
media formats, ENOTSUP will be returned.</p>
<p>QOPT file system objects that have owners will not be recognized by the Work
with Objects by Owner (WRKOBJOWN) CL command. Likewise, QOPT objects that have
a primary group will not be recognized by the Work Objects by Primary Group) CL
command.</p>
<br>
</li>
<li>QFileSvr.400 File System Differences
<p>The QFileSvr.400 file system does not support <strong>chown()</strong>.</p>
<br>
</li>
<li>QNetWare File System Differences
<p>The QNetWare file system does not support primary group. The GID must be
zero.</p>
<br>
</li>
<li>QNTC File System Differences
<p>The owner of files and directories cannot be changed. All files and
directories in QNTC are owned by the QDFTOWN user profile.</p>
</li>
</ol>
<br>
<h3>Related Information</h3>
<ul>
<li>The &lt;<strong>unistd.h</strong>&gt; file (see <a href="unix13.htm">Header
Files for UNIX-Type Functions</a>)
</li>
<li>The &lt;<strong>limits.h</strong>&gt; file (see <a href="unix13.htm">Header
Files for UNIX-Type Functions</a>)
</li>
<li><a href="chmod.htm">chmod()</a>--Change File Authorizations
</li>
<li><a href="fchown.htm">fchown()</a>--Change Owner and Group of File by
Descriptor
</li>
<li><a href="fstat.htm">fstat()</a>--Get File Information by Descriptor
</li>
<li><a href="lstat.htm">lstat()</a>--Get File or Link Information
</li>
<li><a href="stat.htm">stat()</a>--Get File Information
</li>
<li><a href="chownu.htm">QlgChown()</a>--Change Owner and Group of File</li>
</ul>
<br>
<h3>Example</h3>
<p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a>
for information pertaining to code examples.</p>
<p>The following example changes the owner and group of a file:</p>
<pre>
#include &lt;stdio.h&gt;
#include &lt;unistd.h&gt;
#include &lt;sys/stat.h&gt;
#include &lt;sys/types.h&gt;
main() {
char fn[]="temp.file";
int file_descriptor;
struct stat info;
if ((file_descriptor = creat(fn, S_IRWXU)) == -1)
perror("creat() error");
else {
close(file_descriptor);
stat(fn, &amp;info);
printf("original owner was %d and group was %d\n", info.st_uid,
info.st_gid);
if (chown(fn, 152, 0) != 0)
perror("chown() error");
else {
stat(fn, &amp;info);
printf("after chown(), owner is %d and group is %d\n",
info.st_uid, info.st_gid);
}
unlink(fn);
}
}
</pre>
<p><strong>Output:</strong></p>
<pre>
original owner was 137 and group was 0
after chown(), owner is 152 and group is 0
</pre>
<br>
<hr>
API introduced: V3R1
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"unix.htm">UNIX-Type APIs</a> | <a href="aplist.htm">APIs by category</a></td>
</tr>
</table>
</center>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink