ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/faccessx.htm

850 lines
21 KiB
HTML
Raw Normal View History

2024-04-02 14:02:31 +00:00
<!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>faccessx()--Determine File Accessibility for a Class of Users</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. -->
<!-- file cleaned -->
<!-- Change History: -->
<!-- 010314 JKUGEL: Creation based on access.htm, V5R2, DCR 98686 -->
<!-- 011022 JTROUS Changes from API Review 1, V5R2 -->
<!-- 011025 JKUGEL: Changes for ptr 9955545 -->
<!-- 020227 JTROUS Minor addition per Marcus Lundberg comment, v5r2-->
<!-- 020618 EMIG Updates for NFS threadsafety, V5R3 -->
<!-- 020514 JET: This file has undergone html cleanup -->
<!-- 020718 MFENLON: updated for QFileSvr.400 threadsafety, V5R3 -->
<!-- 040721 JTROUS: fix OS/400 reference, no change flag, V5R4 -->
<!-- 050323 JTROUS: fix enums, no change flag, V5R4 -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<!-- End Header Records --><!--Java sync-link-->
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<a name="Top_Of_Page"></a>
<h2>faccessx()--Determine File Accessibility for a Class of Users</h2>
<div class="box" style="width: 70%;">
<br>
&nbsp;&nbsp;Syntax<br>
<pre>
#include &lt;unistd.h&gt;
int faccessx(int <em>fildes</em>, int <em>amode</em>, int <em>who</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>faccessx()</strong> function determines whether a file can be
accessed by a specified class of users in a particular manner.</p>
<p>Adopted authority is not used.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong><em>fildes</em></strong></dt>
<dd>(Input) The file descriptor of the file that is having its accessibility
checked.<br>
<br>
</dd>
<dt><strong><em>amode</em></strong></dt>
<dd>(Input) A bitwise representation of the access permissions to be
checked.<br>
<br>
<p>The following symbols, which are defined in the
&lt;<strong>unistd.h</strong>&gt; header file, can be used in <em>
amode</em>:</p>
<dl compact>
<dt><em><samp>F_OK</samp></em></dt>
<dd>(<em>x'00'</em>) Tests whether the file exists</dd>
<dt><em><samp>R_OK</samp></em></dt>
<dd>(<samp>x'04'</samp>) Tests whether the file can be accessed for
reading</dd>
<dt><em><samp>W_OK</samp></em></dt>
<dd>(<em>x'02'</em>) Tests whether the file can be accessed for writing</dd>
<dt><em><samp>X_OK</samp></em></dt>
<dd>(<em>x'01'</em>) Tests whether the file can be accessed for execution</dd>
</dl>
<p>You can take the bitwise inclusive OR of any or all of the last three
symbols to test several access modes at once. If you are using F_OK to test for
the existence of the file, you cannot use OR with any of the other symbols. If
any other bits are set in <em>amode</em>, <strong>faccessx()</strong> returns
the [EINVAL] error.</p>
<br>
</dd>
<dt><strong><em>who</em></strong></dt>
<dd>(Input) The class of users whose authority is to be checked.
<p>The following symbols, which are defined in the
&lt;<strong>unistd.h</strong>&gt; header file, can be used in <em>who</em>:</p>
<dl compact>
<dt><em><samp>ACC_SELF</samp></em></dt>
<dd>(<em>x'00'</em>) Determines if specified access is permitted for the
current thread. The effective user and group IDs are used.
<p><strong>Note:</strong> If the real and effective user ID are the same and
the real and effective group ID are the same, the request is treated as
ACC_INVOKER. See the Usage Notes for more details.</p>
</dd>
<dt><em><samp>ACC_INVOKER</samp></em></dt>
<dd>(<em>x'01'</em>) Determines if specified access is permitted for the
current thread. The effective user and group IDs are used.</dd>
<dd><br>
<br>
</dd>
<dt><em><samp>ACC_OTHERS</samp></em></dt>
<dd>(<em>x'08'</em>) Determines if specified access is permitted for any user
other than the object owner. Only one of <em>R_OK</em>, <em>W_OK</em>, and <em>
X_OK</em> is permitted when <strong>who</strong> is <em>ACC_OTHERS</em>.
Privileged users (users with *ALLOBJ special authority) are not considered in
this check.</dd>
<dd><br>
<br>
</dd>
<dt><em><samp>ACC_ALL</samp></em></dt>
<dd>(<em>x'20'</em>) Determines if specified access is permitted for all users.
Only one of <em>R_OK</em>, <em>W_OK</em>, and <em>X_OK</em> is permitted when
<strong>who</strong> is <em>ACC_ALL</em>. Privileged users (users with *ALLOBJ
special authority) are not considered in this check.</dd>
</dl>
</dd>
</dl>
<br>
<h3>Authorities</h3>
<p>The following authorities are required if the <strong>who</strong> parameter
is <em>ACC_SELF</em> or <em>ACC_INVOKER</em>. If <em>ACC_SELF</em> is
specified, the effective UID and GID of the caller are used. If <em>
ACC_INVOKER</em> is used, the real UID and GID of the caller are used.</p>
<p><strong><a name="TBLFACCESSX">Authorization Required for
faccessx()</a></strong></p>
<table border width="100%" cellpadding="5">
<!-- 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%">Object when R_OK is specified</td>
<td align="left" valign="top" width="5%">*R</td>
<td align="left" valign="top" width="5%">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Object when W_OK is specified</td>
<td align="left" valign="top">*W</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Object when X_OK is specified</td>
<td align="left" valign="top">*X</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Object when R_OK | W_OK is
specified</td>
<td align="left" valign="top">*RW</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Object when R_OK | X_OK is
specified</td>
<td align="left" valign="top">*RX</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Object when W_OK | X_OK is
specified</td>
<td align="left" valign="top">*WX</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Object when R_OK | W_OK | X_OK is
specified</td>
<td align="left" valign="top">*RWX</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Object when F_OK is specified</td>
<td align="left" valign="top">None</td>
<td align="left" valign="top">None</td>
</tr>
</table>
<p>If the current thread has *ALLOBJ special authority, <strong>
faccessx()</strong> with <em>ACC_SELF</em> or <em>ACC_INVOKER</em> will
indicate success for R_OK, W_OK, or X_OK even if none of the permission bits
are set.</p>
<br>
<h3>Return Value</h3>
<dl compact>
<dt><em>0</em></dt>
<dd><strong>faccessx()</strong> was successful.</dd>
<dt><em>-1</em></dt>
<dd><strong>faccessx()</strong> was not successful (or the specified access is
not permitted for the class of users being checked). The <em>errno</em> global
variable is set to indicate the error.</dd>
</dl>
<br>
<h3>Error Conditions</h3>
<p>If <strong>faccessx()</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>The class of users specified by the <em>who</em> parameter does not have the
permission indicated by the <em>amode</em> parameter.</p>
<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#EINVAL">EINVAL</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</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#EINTR">EINTR</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#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#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#ETXTBSY">ETXTBSY</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</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>
<p>If interaction with a file server is required to access the object, <em>
errno</em> could indicate one of the following errors:</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#EADDRNOTAVAIL">EADDRNOTAVAIL</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ECONNABORTED">ECONNABORTED</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ECONNREFUSED">ECONNREFUSED</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ECONNRESET">ECONNRESET</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EHOSTDOWN">EHOSTDOWN</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EHOSTUNREACH">EHOSTUNREACH</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENETDOWN">ENETDOWN</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENETRESET">ENETRESET</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENETUNREACH">ENETUNREACH</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#ETIMEDOUT">ETIMEDOUT</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EUNATCH">EUNATCH</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 function:</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 both of the
following conditions occur:
<ul>
<li>Where multiple threads exist in the job.<br>
</li>
<li>The object this function is operating on resides in a file system that is
not threadsafe. Only the following file systems are threadsafe for this
function:
<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>ACC_SELF Mapped to ACC_INVOKER
<p>Some physical file systems do not support <em>ACC_SELF</em> for the <em>
who</em> parameter. However, <strong>faccessx()</strong> will change the <em>
who</em> parameter from <em>ACC_SELF</em> to <em>ACC_INVOKER</em> if the
caller's real and effective user ID are equal, and the caller's real and
effective group ID are equal.</p>
<br>
</li>
<li>Network File System Differences
<p>The Network File System will only support the value <em>ACC_INVOKER</em> for
the <em>who</em> parameter. If <strong>faccessx()</strong> is called on a file
in a mounted Network File System directory with a value for <em>who</em> other
than <em>ACC_INVOKER</em>, the call will return -1 and errno ENOTSUP. <strong>
Note:</strong> If the value for <em>who</em> has been mapped from <em>
ACC_SELF</em> to <em>ACC_INVOKER</em> as previously described, then ENOTSUP
will not be returned.</p>
<p>Local access to remote files through the Network File System may produce
unexpected results due to conditions at the server. Once a file is open,
subsequent requests to perform operations on the file can fail because file
attributes are checked at the server on each request. If permissions on the
file are made more restrictive at the server or the file is unlinked or made
unavailable by the server for another client, your operation on an open file
descriptor will fail when the local Network File System receives these updates.
The local Network File System also impacts operations that retrieve file
attributes. Recent changes at the server may not be available at your client
yet, and old values may be returned from operations. (Several options on the
Add Mounted File System (ADDMFS) command determine the time between refresh
operations of local data.)</p>
<br>
</li>
<li>QNTC File System Differences
<p>The QNTC File System will only support the value <em>ACC_INVOKER</em> for
the <em>who</em> parameter. If <strong>faccessx()</strong> is called on a file
in the QNTC File System with a value for <em>who</em> other than <em>
ACC_INVOKER</em>, the call will return -1 and errno ENOTSUP.</p>
<p><strong>
Note:</strong> If the value for <em>who</em> has been mapped from <em>
ACC_SELF</em> to <em>ACC_INVOKER</em> as previously described, then ENOTSUP
will not be returned.</p>
<br>
</li>
<li>QOPT File System Differences
<p>If the file descriptor refers to an object that exists on a volume formatted
in Universal Disk Format (UDF), the authorization that is checked for the
object follows the rules described in the previous table,
<a href="#TBLFACCESSX">Authorization Required for faccessx()</a>. If the
object exists on a volume formatted in some other media format, no
authorization checks are made on the object. The volume authorization list is
checked for the requested authority regardless of the volume media format.</p>
<br>
</li>
<li>QFileSvr.400 File System Differences<br>
<br>
<p>The QFileSvr.400 File System will only support the value <em>
ACC_INVOKER</em> for the <em>who</em> parameter. If <strong>faccessx()</strong>
is called on a file in the QFileSvr.400 File System with a value for <em>
who</em> other than <em>ACC_INVOKER</em>, the call will return -1 and errno
ENOTSUP. </p>
<p><strong>Note:</strong> If the value for <em>who</em> has been mapped
from <em>ACC_SELF</em> to <em>ACC_INVOKER</em> as previously described, then
ENOTSUP will not be returned.</p>
<br>
</li>
<li>QNetWare File System Differences<br>
<br>
<p>The QNetWare File System will only support the value <em>ACC_INVOKER</em>
for the <em>who</em> parameter. If <strong>faccessx()</strong> is called on a
file in the QNetWare File System with a value for <em>who</em> other than <em>
ACC_INVOKER</em>, the call will return -1 and errno ENOTSUP.</p>
<p> <strong>
Note:</strong> If the value for <em>who</em> has been mapped from <em>
ACC_SELF</em> to <em>ACC_INVOKER</em> as previously described, then ENOTSUP
will not be returned.</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="open.htm">open()</a>--Open File
</li>
<li><a href="access.htm">access()</a>--Determine File Accessibility
</li>
<li><a href="accessx.htm">accessx()</a>--Determine File Accessibility for a
Class of Users
</li>
<li><a href="accessxu.htm">QlgAccessx()</a>--Determine File Accessibility for a
Class of Users (using NLS-enabled path name)
</li>
<li><a href="accessu.htm">QlgAccess()</a>--Determine File Accessibility (using
NLS-enabled path name)
</li>
<li><a href="stat.htm">stat()</a>--Get File Information
</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 determines how a file is accessed:</p>
<pre>
#include &lt;stdio.h&gt;
#include &lt;unistd.h&gt;
#include &lt;fcntl.h&gt;
main() {
char path[]="/myfile";
int fd;
fd = open(path, O_RDONLY);
if (fd == -1)
{
printf("Error opening file.\n");
return;
}
if (faccessx(fd, R_OK, ACC_OTHERS) == 0)
printf("Someone besides the owner has read access to '%s'\n", path);
if (faccessx(fd, W_OK, ACC_OTHERS) == 0)
printf("Someone besides the owner has write access to '%s'\n", path);
if (faccessx(fd, X_OK, ACC_OTHERS) == 0)
printf("Someone besides the owner has search access to '%s'\n", path);
close(fd);
}
</pre>
<p><strong>Output:</strong></p>
<p>In this example <strong>faccessx()</strong> was called on a descriptor for
'/myfile'. The following would be the output if someone other than the owner
has *R authority, someone besides the owner has *W authority, and noone other
than the owner has *X authority.</p>
<br>
<pre>
Someone besides the owner has read access to '/'
Someone besides the owner has write access to '/'
</pre>
<br>
<hr>
API introduced: V5R2
<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>