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