lib/libc/sys/access.2

   1 .\" Copyright (c) 1980, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)access.2    8.2 (Berkeley) 4/1/94
  33 .\" $FreeBSD$
  34 .\"
  35 .Dd September 21, 2001
  36 .Dt ACCESS 2
  37 .Os
  38 .Sh NAME
  39 .Nm access , eaccess
  40 .Nd check accessibility of a file
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In unistd.h
  45 .Ft int
  46 .Fn access "const char *path" "int mode"
  47 .Ft int
  48 .Fn eaccess "const char *path" "int mode"
  49 .Sh DESCRIPTION
  50 The
  51 .Fn access
  52 and
  53 .Fn eaccess
  54 functions check the accessibility of the
  55 file named by
  56 the
  57 .Fa path
  58 argument
  59 for the access permissions indicated by
  60 the
  61 .Fa mode
  62 argument.
  63 The value of
  64 .Fa mode
  65 is either the bitwise-inclusive OR of the access permissions to be
  66 checked
  67 .Dv ( R_OK
  68 for read permission,
  69 .Dv W_OK
  70 for write permission, and
  71 .Dv X_OK
  72 for execute/search permission),
  73 or the existence test
  74 .Pq Dv F_OK .
  75 .Pp
  76 For additional information, see the
  77 .Sx "File Access Permission"
  78 section of
  79 .Xr intro 2 .
  80 .Pp
  81 The
  82 .Fn eaccess
  83 call uses
  84 the effective user ID and the group access list
  85 to authorize the request;
  86 the
  87 .Fn access
  88 call uses
  89 the real user ID in place of the effective user ID,
  90 the real group ID in place of the effective group ID,
  91 and the rest of the group access list.
  92 .Pp
  93 Even if a process's real or effective user has appropriate privileges
  94 and indicates success for
  95 .Dv X_OK ,
  96 the file may not actually have execute permission bits set.
  97 Likewise for
  98 .Dv R_OK
  99 and
 100 .Dv W_OK .
 101 .Sh RETURN VALUES
 102 .Rv -std
 103 .Sh ERRORS
 104 Access to the file is denied if:
 105 .Bl -tag -width Er
 106 .It Bq Er ENOTDIR
 107 A component of the path prefix is not a directory.
 108 .It Bq Er ENAMETOOLONG
 109 A component of a pathname exceeded 255 characters,
 110 or an entire path name exceeded 1023 characters.
 111 .It Bq Er ENOENT
 112 The named file does not exist.
 113 .It Bq Er ELOOP
 114 Too many symbolic links were encountered in translating the pathname.
 115 .It Bq Er EROFS
 116 Write access is requested for a file on a read-only file system.
 117 .It Bq Er ETXTBSY
 118 Write access is requested for a pure procedure (shared text)
 119 file presently being executed.
 120 .It Bq Er EACCES
 121 Permission bits of the file mode do not permit the requested
 122 access, or search permission is denied on a component of the
 123 path prefix.
 124 .It Bq Er EFAULT
 125 .Fa path
 126 points outside the process's allocated address space.
 127 .It Bq Er EIO
 128 An I/O error occurred while reading from or writing to the file system.
 129 .El
 130 .Sh SECURITY CONSIDERATIONS
 131 The
 132 .Fn access
 133 call
 134 is a potential security hole due to race conditions and
 135 should never be used.
 136 Set-user-ID and set-group-ID applications should restore the
 137 effective user or group ID,
 138 and perform actions directly rather than use
 139 .Fn access
 140 to simulate access checks for the real user or group ID.
 141 The
 142 .Fn eaccess
 143 call
 144 likewise may be subject to races if used inappropriately.
 145 .Sh SEE ALSO
 146 .Xr chmod 2 ,
 147 .Xr intro 2 ,
 148 .Xr stat 2
 149 .Sh STANDARDS
 150 The
 151 .Fn access
 152 function call is expected to conform to
 153 .St -p1003.1-90 .
 154 .Sh HISTORY
 155 An
 156 .Fn access
 157 function call appeared in
 158 .At v7 .