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. 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.\" 30.Dd March 30, 2021 31.Dt ACCESS 2 32.Os 33.Sh NAME 34.Nm access , 35.Nm eaccess , 36.Nm faccessat 37.Nd check accessibility of a file 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.In unistd.h 42.Ft int 43.Fn access "const char *path" "int mode" 44.Ft int 45.Fn eaccess "const char *path" "int mode" 46.Ft int 47.Fn faccessat "int fd" "const char *path" "int mode" "int flag" 48.Sh DESCRIPTION 49The 50.Fn access 51and 52.Fn eaccess 53system calls check the accessibility of the 54file named by 55the 56.Fa path 57argument 58for the access permissions indicated by 59the 60.Fa mode 61argument. 62The value of 63.Fa mode 64is either the bitwise-inclusive OR of the access permissions to be 65checked 66.Dv ( R_OK 67for read permission, 68.Dv W_OK 69for write permission, and 70.Dv X_OK 71for execute/search permission), 72or the existence test 73.Pq Dv F_OK . 74.Pp 75For additional information, see the 76.Sx "File Access Permission" 77section of 78.Xr intro 2 . 79.Pp 80The 81.Fn eaccess 82system call uses 83the effective user ID and the group access list 84to authorize the request; 85the 86.Fn access 87system call uses 88the real user ID in place of the effective user ID, 89the real group ID in place of the effective group ID, 90and the rest of the group access list. 91.Pp 92The 93.Fn faccessat 94system call is equivalent to 95.Fn access 96except in the case where 97.Fa path 98specifies a relative path. 99In this case the file whose accessibility is to be determined is 100located relative to the directory associated with the file descriptor 101.Fa fd 102instead of the current working directory. 103If 104.Fn faccessat 105is passed the special value 106.Dv AT_FDCWD 107in the 108.Fa fd 109parameter, the current working directory is used and the behavior is 110identical to a call to 111.Fn access . 112Values for 113.Fa flag 114are constructed by a bitwise-inclusive OR of flags from the following 115list, defined in 116.In fcntl.h : 117.Bl -tag -width indent 118.It Dv AT_EACCESS 119The checks for accessibility are performed using the effective user and group 120IDs instead of the real user and group ID as required in a call to 121.Fn access . 122.It Dv AT_RESOLVE_BENEATH 123Only walk paths below the directory specified by the 124.Ar fd 125descriptor. 126See the description of the 127.Dv O_RESOLVE_BENEATH 128flag in the 129.Xr open 2 130manual page. 131.It Dv AT_EMPTY_PATH 132If the 133.Fa path 134argument is an empty string, operate on the file or directory 135referenced by the descriptor 136.Fa fd . 137If 138.Fa fd 139is equal to 140.Dv AT_FDCWD , 141operate on the current working directory. 142.El 143.Pp 144Even if a process's real or effective user has appropriate privileges 145and indicates success for 146.Dv X_OK , 147the file may not actually have execute permission bits set. 148Likewise for 149.Dv R_OK 150and 151.Dv W_OK . 152.Sh RETURN VALUES 153.Rv -std 154.Sh ERRORS 155.Fn access , 156.Fn eaccess , 157or 158.Fn faccessat 159will fail if: 160.Bl -tag -width Er 161.It Bq Er EINVAL 162The value of the 163.Fa mode 164argument is invalid. 165.It Bq Er ENOTDIR 166A component of the path prefix is not a directory. 167.It Bq Er ENAMETOOLONG 168A component of a pathname exceeded 255 characters, 169or an entire path name exceeded 1023 characters. 170.It Bq Er ENOENT 171The named file does not exist. 172.It Bq Er ELOOP 173Too many symbolic links were encountered in translating the pathname. 174.It Bq Er EROFS 175Write access is requested for a file on a read-only file system. 176.It Bq Er ETXTBSY 177Write access is requested for a pure procedure (shared text) 178file presently being executed. 179.It Bq Er EACCES 180Permission bits of the file mode do not permit the requested 181access, or search permission is denied on a component of the 182path prefix. 183.It Bq Er EFAULT 184The 185.Fa path 186argument 187points outside the process's allocated address space. 188.It Bq Er EIO 189An I/O error occurred while reading from or writing to the file system. 190.It Bq Er EINTEGRITY 191Corrupted data was detected while reading from the file system. 192.El 193.Pp 194Also, the 195.Fn faccessat 196system call may fail if: 197.Bl -tag -width Er 198.It Bq Er EBADF 199The 200.Fa path 201argument does not specify an absolute path and the 202.Fa fd 203argument is 204neither 205.Dv AT_FDCWD 206nor a valid file descriptor. 207.It Bq Er EINVAL 208The value of the 209.Fa flag 210argument is not valid. 211.It Bq Er ENOTDIR 212The 213.Fa path 214argument is not an absolute path and 215.Fa fd 216is neither 217.Dv AT_FDCWD 218nor a file descriptor associated with a directory. 219.It Bq Er ENOTCAPABLE 220.Fa path 221is an absolute path, 222or contained a ".." component leading to a 223directory outside of the directory hierarchy specified by 224.Fa fd , 225and the process is in capability mode. 226.El 227.Sh SEE ALSO 228.Xr chmod 2 , 229.Xr intro 2 , 230.Xr stat 2 231.Sh STANDARDS 232The 233.Fn access 234system call is expected to conform to 235.St -p1003.1-90 . 236The 237.Fn faccessat 238system call follows The Open Group Extended API Set 2 specification. 239.Sh HISTORY 240The 241.Fn access 242function appeared in 243.At v7 . 244The 245.Fn faccessat 246system call appeared in 247.Fx 8.0 . 248.Sh SECURITY CONSIDERATIONS 249The 250.Fn access 251system call 252is a potential security hole due to race conditions and 253should never be used. 254Set-user-ID and set-group-ID applications should restore the 255effective user or group ID, 256and perform actions directly rather than use 257.Fn access 258to simulate access checks for the real user or group ID. 259The 260.Fn eaccess 261system call 262likewise may be subject to races if used inappropriately. 263.Pp 264.Fn access 265remains useful for providing clues to users as to whether operations 266make sense for particular filesystem objects (e.g. 'delete' menu 267item only highlighted in a writable folder ... avoiding interpretation 268of the st_mode bits that the application might not understand -- 269e.g. in the case of AFS). 270It also allows a cheaper file existence test than 271.Xr stat 2 . 272