bsd/man/man2/access.2

   1 .\"     $NetBSD: access.2,v 1.7 1995/02/27 12:31:44 cgd Exp $
   2 .\"
   3 .\" Copyright (c) 1980, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)access.2    8.2 (Berkeley) 4/1/94
  35 .\"
  36 .Dd April 1, 1994
  37 .Dt ACCESS 2
  38 .Os BSD 4
  39 .Sh NAME
  40 .Nm access ,
  41 .Nm faccessat
  42 .Nd check access permissions of a file or pathname
  43 .Sh SYNOPSIS
  44 .Fd #include <unistd.h>
  45 .Ft int
  46 .Fo access
  47 .Fa "const char *path"
  48 .Fa "int amode"
  49 .Fc
  50 .Ft int
  51 .Fn faccessat "int fd" "const char *path" "int mode" "int flag"
  52 .Sh DESCRIPTION
  53 The
  54 .Fn access
  55 function checks the accessibility of the
  56 file named by
  57 .Fa path
  58 for the access permissions indicated by
  59 .Fa amode .
  60 The value of
  61 .Fa amode
  62 is the bitwise inclusive OR of the access permissions to be
  63 checked
  64 .Pf ( Dv R_OK
  65 for read permission,
  66 .Dv W_OK
  67 for write permission and
  68 .Dv X_OK
  69 for execute/search permission) or the existence test,
  70 .Dv F_OK .
  71 All components of the pathname
  72 .Fa path
  73 are checked for access permissions (including
  74 .Dv F_OK ) .
  75 .Pp
  76 The real user ID is used in place of the effective user ID
  77 and the real group access list
  78 (including the real group ID) are
  79 used in place of the effective ID for verifying permission.
  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 If
 122 .Fa path
 123 cannot be found
 124 or if any of the desired access modes would not be granted,
 125 then a -1 value is returned and the global integer variable
 126 .Va errno
 127 is set to indicate the error.
 128 Otherwise, a 0 value is returned.
 129 .Sh ERRORS
 130 Access to the file is denied if:
 131 .Bl -tag -width Er
 132 .\" ==========
 133 .It Bq Er EACCES
 134 Permission bits of the file mode do not permit the requested access,
 135 or search permission is denied on a component of the path prefix.
 136 .Pp
 137 The owner of a file has permission checked
 138 with respect to the ``owner'' read, write, and execute mode bits,
 139 members of the file's group other than the owner have permission checked
 140 with respect to the ``group'' mode bits,
 141 and all others have permissions checked
 142 with respect to the ``other'' mode bits.
 143 .\"
 144 .\" ==========
 145 .It Bq Er EFAULT
 146 .Fa Path
 147 points outside the process's allocated address space.
 148 .It Bq Er EINVAL
 149 An invalid value was specified for
 150 .Ar amode .
 151 .\" ==========
 152 .It Bq Er EIO
 153 An I/O error occurred while reading from or writing to the file system.
 154 .\" ==========
 155 .It Bq Er ELOOP
 156 Too many symbolic links were encountered in translating the pathname.
 157 .\" ==========
 158 .It Bq Er ENAMETOOLONG
 159 A component of a pathname exceeded
 160 .Dv {NAME_MAX}
 161 characters, or an entire path name exceeded
 162 .Dv {PATH_MAX}
 163 characters.
 164 .\" ==========
 165 .It Bq Er ENOENT
 166 The named file does not exist.
 167 .\" ==========
 168 .It Bq Er ENOTDIR
 169 A component of the path prefix is not a directory.
 170 .\" ==========
 171 .It Bq Er EROFS
 172 Write access is requested for a file on a read-only file system.
 173 .\" ==========
 174 .It Bq Er ETXTBSY
 175 Write access is requested for a pure procedure (shared text)
 176 file that is presently being executed.
 177 .El
 178 .Pp
 179 Also, the
 180 .Fn faccessat
 181 system call may fail if:
 182 .Bl -tag -width Er
 183 .It Bq Er EBADF
 184 The
 185 .Fa path
 186 argument does not specify an absolute path and the
 187 .Fa fd
 188 argument is
 189 neither
 190 .Dv AT_FDCWD
 191 nor a valid file descriptor.
 192 .It Bq Er EINVAL
 193 The value of the
 194 .Fa flag
 195 argument is not valid.
 196 .It Bq Er ENOTDIR
 197 The
 198 .Fa path
 199 argument is not an absolute path and
 200 .Fa fd
 201 is neither
 202 .Dv AT_FDCWD
 203 nor a file descriptor associated with a directory.
 204 .El
 205 .Sh SEE ALSO
 206 .Xr chmod 2 ,
 207 .Xr stat 2
 208 .Sh STANDARDS
 209 The
 210 .Fn access
 211 function conforms to
 212 .St -p1003.1-90 .
 213 The
 214 .Fn faccessat
 215 system call is expected to conform to POSIX.1-2008 .
 216 .Sh CAVEAT
 217 .Fn access
 218 is a potential security hole and
 219 should never be used.