<html lang="en">
<head>
<title>Testing File Access - The GNU C Library</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="The GNU C Library">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="File-Attributes.html#File-Attributes" title="File Attributes">
<link rel="prev" href="Setting-Permissions.html#Setting-Permissions" title="Setting Permissions">
<link rel="next" href="File-Times.html#File-Times" title="File Times">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
This file documents the GNU C library.

This is Edition 0.12, last updated 2007-10-27,
of `The GNU C Library Reference Manual', for version
2.8 (Sourcery G++ Lite 2011.03-41).

Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002,
2003, 2007, 2008, 2010 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``Free Software Needs Free Documentation''
and ``GNU Lesser General Public License'', the Front-Cover texts being
``A GNU Manual'', and with the Back-Cover Texts as in (a) below.  A
copy of the license is included in the section entitled "GNU Free
Documentation License".

(a) The FSF's Back-Cover Text is: ``You have the freedom to
copy and modify this GNU manual.  Buying copies from the FSF
supports it in developing GNU and promoting software freedom.''-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
--></style>
<link rel="stylesheet" type="text/css" href="../cs.css">
</head>
<body>
<div class="node">
<a name="Testing-File-Access"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="File-Times.html#File-Times">File Times</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="Setting-Permissions.html#Setting-Permissions">Setting Permissions</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="File-Attributes.html#File-Attributes">File Attributes</a>
<hr>
</div>

<h4 class="subsection">14.9.8 Testing Permission to Access a File</h4>

<p><a name="index-testing-access-permission-1571"></a><a name="index-access_002c-testing-for-1572"></a><a name="index-setuid-programs-and-file-access-1573"></a>
In some situations it is desirable to allow programs to access files or
devices even if this is not possible with the permissions granted to the
user.  One possible solution is to set the setuid-bit of the program
file.  If such a program is started the <em>effective</em> user ID of the
process is changed to that of the owner of the program file.  So to
allow write access to files like <samp><span class="file">/etc/passwd</span></samp>, which normally can
be written only by the super-user, the modifying program will have to be
owned by <code>root</code> and the setuid-bit must be set.

   <p>But beside the files the program is intended to change the user should
not be allowed to access any file to which s/he would not have access
anyway.  The program therefore must explicitly check whether <em>the
user</em> would have the necessary access to a file, before it reads or
writes the file.

   <p>To do this, use the function <code>access</code>, which checks for access
permission based on the process's <em>real</em> user ID rather than the
effective user ID.  (The setuid feature does not alter the real user ID,
so it reflects the user who actually ran the program.)

   <p>There is another way you could check this access, which is easy to
describe, but very hard to use.  This is to examine the file mode bits
and mimic the system's own access computation.  This method is
undesirable because many systems have additional access control
features; your program cannot portably mimic them, and you would not
want to try to keep track of the diverse features that different systems
have.  Using <code>access</code> is simple and automatically does whatever is
appropriate for the system you are using.

   <p><code>access</code> is <em>only</em> only appropriate to use in setuid programs. 
A non-setuid program will always use the effective ID rather than the
real ID.

   <p><a name="index-unistd_002eh-1574"></a>The symbols in this section are declared in <samp><span class="file">unistd.h</span></samp>.

<!-- unistd.h -->
<!-- POSIX.1 -->
<div class="defun">
&mdash; Function: int <b>access</b> (<var>const char *filename, int how</var>)<var><a name="index-access-1575"></a></var><br>
<blockquote><p>The <code>access</code> function checks to see whether the file named by
<var>filename</var> can be accessed in the way specified by the <var>how</var>
argument.  The <var>how</var> argument either can be the bitwise OR of the
flags <code>R_OK</code>, <code>W_OK</code>, <code>X_OK</code>, or the existence test
<code>F_OK</code>.

        <p>This function uses the <em>real</em> user and group IDs of the calling
process, rather than the <em>effective</em> IDs, to check for access
permission.  As a result, if you use the function from a <code>setuid</code>
or <code>setgid</code> program (see <a href="How-Change-Persona.html#How-Change-Persona">How Change Persona</a>), it gives
information relative to the user who actually ran the program.

        <p>The return value is <code>0</code> if the access is permitted, and <code>-1</code>
otherwise.  (In other words, treated as a predicate function,
<code>access</code> returns true if the requested access is <em>denied</em>.)

        <p>In addition to the usual file name errors (see <a href="File-Name-Errors.html#File-Name-Errors">File Name Errors</a>), the following <code>errno</code> error conditions are defined for
this function:

          <dl>
<dt><code>EACCES</code><dd>The access specified by <var>how</var> is denied.

          <br><dt><code>ENOENT</code><dd>The file doesn't exist.

          <br><dt><code>EROFS</code><dd>Write permission was requested for a file on a read-only file system. 
</dl>
        </p></blockquote></div>

   <p>These macros are defined in the header file <samp><span class="file">unistd.h</span></samp> for use
as the <var>how</var> argument to the <code>access</code> function.  The values
are integer constants. 
<a name="index-unistd_002eh-1576"></a>
<!-- unistd.h -->
<!-- POSIX.1 -->

<div class="defun">
&mdash; Macro: int <b>R_OK</b><var><a name="index-R_005fOK-1577"></a></var><br>
<blockquote><p>Flag meaning test for read permission. 
</p></blockquote></div>

<!-- unistd.h -->
<!-- POSIX.1 -->
<div class="defun">
&mdash; Macro: int <b>W_OK</b><var><a name="index-W_005fOK-1578"></a></var><br>
<blockquote><p>Flag meaning test for write permission. 
</p></blockquote></div>

<!-- unistd.h -->
<!-- POSIX.1 -->
<div class="defun">
&mdash; Macro: int <b>X_OK</b><var><a name="index-X_005fOK-1579"></a></var><br>
<blockquote><p>Flag meaning test for execute/search permission. 
</p></blockquote></div>

<!-- unistd.h -->
<!-- POSIX.1 -->
<div class="defun">
&mdash; Macro: int <b>F_OK</b><var><a name="index-F_005fOK-1580"></a></var><br>
<blockquote><p>Flag meaning test for existence of the file. 
</p></blockquote></div>

   </body></html>