bsd/man/man2/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 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)access.2    8.2 (Berkeley) 4/1/94
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd September 15, 2014
  32 .Dt ACCESS 2
  33 .Os
  34 .Sh NAME
  35 .Nm access ,
  36 .Nm faccessat
  37 .Nd check accessibility of a file
  38 .Sh SYNOPSIS
  39 .In unistd.h
  40 .Ft int
  41 .Fn access "const char *path" "int mode"
  42 .Ft int
  43 .Fn faccessat "int fd" "const char *path" "int mode" "int flag"
  44 .Sh DESCRIPTION
  45 The
  46 .Fn access
  47 system call checks the accessibility of the
  48 file named by
  49 the
  50 .Fa path
  51 argument
  52 for the access permissions indicated by
  53 the
  54 .Fa mode
  55 argument.
  56 The value of
  57 .Fa mode
  58 is either the bitwise-inclusive OR of the access permissions to be
  59 checked
  60 .Dv ( R_OK
  61 for read permission,
  62 .Dv W_OK
  63 for write permission, and
  64 .Dv X_OK
  65 for execute/search permission),
  66 or the existence test
  67 .Pq Dv F_OK .
  68 .Pp
  69 For additional information, see the
  70 .Sx "File Access Permission"
  71 section of
  72 .Xr intro 2 .
  73 .Pp
  74 The
  75 .Fn access
  76 system call uses
  77 the real user ID in place of the effective user ID,
  78 the real group ID in place of the effective group ID,
  79 and the rest of the group access list.
  80 .Pp
  81 The
  82 .Fn faccessat
  83 system call is equivalent to
  84 .Fn access
  85 except in the case where
  86 .Fa path
  87 specifies a relative path.
  88 In this case the file whose accessibility is to be determined is
  89 located relative to the directory associated with the file descriptor
  90 .Fa fd
  91 instead of the current working directory.
  92 If
  93 .Fn faccessat
  94 is passed the special value
  95 .Dv AT_FDCWD
  96 in the
  97 .Fa fd
  98 parameter, the current working directory is used and the behavior is
  99 identical to a call to
 100 .Fn access .
 101 Values for
 102 .Fa flag
 103 are constructed by a bitwise-inclusive OR of flags from the following
 104 list, defined in
 105 .In fcntl.h :
 106 .Bl -tag -width indent
 107 .It Dv AT_EACCESS
 108 The checks for accessibility are performed using the effective user and group
 109 IDs instead of the real user and group ID as required in a call to
 110 .Fn access .
 111 .El
 112 .Pp
 113 Even if a process has appropriate privileges and indicates success for
 114 .Dv X_OK ,
 115 the file may not actually have execute permission bits set.
 116 Likewise for
 117 .Dv R_OK
 118 and
 119 .Dv W_OK .
 120 .Sh RETURN VALUES
 121 .Rv -std
 122 .Sh ERRORS
 123 .Fn access
 124 or
 125 .Fn faccessat
 126 will fail if:
 127 .Bl -tag -width Er
 128 .It Bq Er EINVAL
 129 The value of the
 130 .Fa mode
 131 argument is invalid.
 132 .It Bq Er ENOTDIR
 133 A component of the path prefix is not a directory.
 134 .It Bq Er ENAMETOOLONG
 135 A component of a pathname exceeded
 136 .Dv {NAME_MAX}
 137 characters, or an entire path name exceeded
 138 .Dv {PATH_MAX}
 139 characters.
 140 .It Bq Er ENOENT
 141 The named file does not exist.
 142 .It Bq Er ELOOP
 143 Too many symbolic links were encountered in translating the pathname.
 144 .It Bq Er EROFS
 145 Write access is requested for a file on a read-only file system.
 146 .It Bq Er ETXTBSY
 147 Write access is requested for a pure procedure (shared text)
 148 file presently being executed.
 149 .It Bq Er EACCES
 150 Permission bits of the file mode do not permit the requested
 151 access, or search permission is denied on a component of the
 152 path prefix.
 153 .It Bq Er EFAULT
 154 The
 155 .Fa path
 156 argument
 157 points outside the process's allocated address space.
 158 .It Bq Er EIO
 159 An I/O error occurred while reading from or writing to the file system.
 160 .El
 161 .Pp
 162 Also, the
 163 .Fn faccessat
 164 system call may fail if:
 165 .Bl -tag -width Er
 166 .It Bq Er EBADF
 167 The
 168 .Fa path
 169 argument does not specify an absolute path and the
 170 .Fa fd
 171 argument is
 172 neither
 173 .Dv AT_FDCWD
 174 nor a valid file descriptor.
 175 .It Bq Er EINVAL
 176 The value of the
 177 .Fa flag
 178 argument is not valid.
 179 .It Bq Er ENOTDIR
 180 The
 181 .Fa path
 182 argument is not an absolute path and
 183 .Fa fd
 184 is neither
 185 .Dv AT_FDCWD
 186 nor a file descriptor associated with a directory.
 187 .El
 188 .Sh SEE ALSO
 189 .Xr chmod 2 ,
 190 .Xr intro 2 ,
 191 .Xr stat 2
 192 .Sh STANDARDS
 193 The
 194 .Fn access
 195 system call is expected to conform to
 196 .St -p1003.1-90 .
 197 The
 198 .Fn faccessat
 199 system call is expected to conform to POSIX.1-2008 .
 200 .Sh HISTORY
 201 The
 202 .Fn access
 203 function appeared in
 204 .At v7 .
 205 .Sh SECURITY CONSIDERATIONS
 206 The result of
 207 .Fn access
 208 should not be used to make an actual access control decision, since its
 209 response, even if correct at the moment it is formed, may be outdated at the
 210 time you act on it.
 211 .Fn access
 212 results should only be used to pre-flight, such as when configuring user
 213 interface elements or for optimization purposes.  The actual access control
 214 decision should be made by attempting to execute the relevant system call while
 215 holding the applicable credentials, and properly handling any resulting errors;
 216 and this must be done even though
 217 .Fn access
 218 may have predicted success.
 219 .Pp
 220 Additionally, set-user-ID and set-group-ID applications should restore the
 221 effective user or group ID,
 222 and perform actions directly rather than use
 223 .Fn access
 224 to simulate access checks for the real user or group ID.