233 lines
7.8 KiB
HTML
233 lines
7.8 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>access</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
|
|
<basefont size="3"> <a name="access"></a> <a name="tag_03_10"></a><!-- access -->
|
|
<!--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_10_01"></a>NAME</h4>
|
|
|
|
<blockquote>access - determine accessibility of a file</blockquote>
|
|
|
|
<h4><a name="tag_03_10_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<p><code><tt>#include <<a href="../basedefs/unistd.h.html">unistd.h</a>><br>
|
|
<br>
|
|
int access(const char *</tt><i>path</i><tt>, int</tt> <i>amode</i><tt>);<br>
|
|
</tt></code></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_10_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>access</i>() function shall check the file named by the pathname pointed to by the <i>path</i> argument for accessibility
|
|
according to the bit pattern contained in <i>amode</i>, using the real user ID in place of the effective user ID and the real group
|
|
ID in place of the effective group ID.</p>
|
|
|
|
<p>The value of <i>amode</i> is either the bitwise-inclusive OR of the access permissions to be checked (R_OK, W_OK, X_OK) or the
|
|
existence test (F_OK).</p>
|
|
|
|
<p>If any access permissions are checked, each shall be checked individually, as described in the Base Definitions volume of
|
|
IEEE Std 1003.1-2001, <a href="../basedefs/xbd_chap03.html">Chapter 3, Definitions</a>. If the process has appropriate
|
|
privileges, an implementation may indicate success for X_OK even if none of the execute file permission bits are set.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_10_04"></a>RETURN VALUE</h4>
|
|
|
|
<blockquote>
|
|
<p>If the requested access is permitted, <i>access</i>() succeeds and shall return 0; otherwise, -1 shall be returned and
|
|
<i>errno</i> shall be set to indicate the error.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_10_05"></a>ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>access</i>() function shall fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EACCES]</dt>
|
|
|
|
<dd>Permission bits of the file mode do not permit the requested access, or 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>[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>[ENOTDIR]</dt>
|
|
|
|
<dd>A component of the path prefix is not a directory.</dd>
|
|
|
|
<dt>[EROFS]</dt>
|
|
|
|
<dd>Write access is requested for a file on a read-only file system.</dd>
|
|
</dl>
|
|
|
|
<p>The <i>access</i>() function may fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd>The value of the <i>amode</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
|
|
string exceeded {PATH_MAX}.</dd>
|
|
|
|
<dt>[ETXTBSY]</dt>
|
|
|
|
<dd>Write access is requested for a pure procedure (shared text) file that is being executed.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_03_10_06"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<h5><a name="tag_03_10_06_01"></a>Testing for the Existence of a File</h5>
|
|
|
|
<p>The following example tests whether a file named <b>myfile</b> exists in the <b>/tmp</b> directory.</p>
|
|
|
|
<pre>
|
|
<tt>#include <unistd.h>
|
|
...
|
|
int result;
|
|
const char *filename = "/tmp/myfile";
|
|
<br>
|
|
result = access (filename, F_OK);
|
|
</tt>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_10_07"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>Additional values of <i>amode</i> other than the set defined in the description may be valid; for example, if a system has
|
|
extended access controls.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_10_08"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>In early proposals, some inadequacies in the <i>access</i>() function led to the creation of an <i>eaccess</i>() function
|
|
because:</p>
|
|
|
|
<ol>
|
|
<li>
|
|
<p>Historical implementations of <i>access</i>() do not test file access correctly when the process' real user ID is superuser. In
|
|
particular, they always return zero when testing execute permissions without regard to whether the file is executable.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The superuser has complete access to all files on a system. As a consequence, programs started by the superuser and switched to
|
|
the effective user ID with lesser privileges cannot use <i>access</i>() to test their file access permissions.</p>
|
|
</li>
|
|
</ol>
|
|
|
|
<p>However, the historical model of <i>eaccess</i>() does not resolve problem (1), so this volume of IEEE Std 1003.1-2001
|
|
now allows <i>access</i>() to behave in the desired way because several implementations have corrected the problem. It was also
|
|
argued that problem (2) is more easily solved by using <a href="../functions/open.html"><i>open</i>()</a>, <a href=
|
|
"../functions/chdir.html"><i>chdir</i>()</a>, or one of the <i><a href="../functions/exec.html">exec</a></i> functions as
|
|
appropriate and responding to the error, rather than creating a new function that would not be as reliable. Therefore,
|
|
<i>eaccess</i>() is not included in this volume of IEEE Std 1003.1-2001.</p>
|
|
|
|
<p>The sentence concerning appropriate privileges and execute permission bits reflects the two possibilities implemented by
|
|
historical implementations when checking superuser access for X_OK.</p>
|
|
|
|
<p>New implementations are discouraged from returning X_OK unless at least one execution permission bit is set.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_10_09"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_10_10"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="chmod.html"><i>chmod</i>()</a> , <a href="stat.html"><i>stat</i>()</a> , the Base Definitions volume of
|
|
IEEE Std 1003.1-2001, <a href="../basedefs/unistd.h.html"><i><unistd.h></i></a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_10_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_10_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 [ELOOP] mandatory error condition is added.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>A second [ENAMETOOLONG] is added as an optional error condition.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The [ETXTBSY] optional error condition is added.</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>
|
|
</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>
|
|
|