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 May 21, 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.El 158.Pp 159Even if a process's real or effective user has appropriate privileges 160and indicates success for 161.Dv X_OK , 162the file may not actually have execute permission bits set. 163Likewise for 164.Dv R_OK 165and 166.Dv W_OK . 167.Sh RETURN VALUES 168.Rv -std 169.Sh ERRORS 170The 171.Fn access , 172.Fn eaccess , 173and 174.Fn faccessat 175system calls may fail if: 176.Bl -tag -width Er 177.It Bq Er EINVAL 178The value of the 179.Fa mode 180argument is invalid. 181.It Bq Er ENOTDIR 182A component of the path prefix is not a directory. 183.It Bq Er ENAMETOOLONG 184A component of a pathname exceeded 255 characters, 185or an entire path name exceeded 1023 characters. 186.It Bq Er ENOENT 187The named file does not exist. 188.It Bq Er ELOOP 189Too many symbolic links were encountered in translating the pathname. 190.It Bq Er EROFS 191Write access is requested for a file on a read-only file system. 192.It Bq Er ETXTBSY 193Write access is requested for a pure procedure (shared text) 194file presently being executed. 195.It Bq Er EACCES 196Permission bits of the file mode do not permit the requested 197access, or search permission is denied on a component of the 198path prefix. 199.It Bq Er EFAULT 200The 201.Fa path 202argument 203points outside the process's allocated address space. 204.It Bq Er EIO 205An I/O error occurred while reading from or writing to the file system. 206.It Bq Er EINTEGRITY 207Corrupted data was detected while reading from the file system. 208.El 209.Pp 210Also, the 211.Fn faccessat 212system call may fail if: 213.Bl -tag -width Er 214.It Bq Er EBADF 215The 216.Fa path 217argument does not specify an absolute path and the 218.Fa fd 219argument is 220neither 221.Dv AT_FDCWD 222nor a valid file descriptor. 223.It Bq Er EINVAL 224The value of the 225.Fa flag 226argument is not valid. 227.It Bq Er ENOTDIR 228The 229.Fa path 230argument is not an absolute path and 231.Fa fd 232is neither 233.Dv AT_FDCWD 234nor a file descriptor associated with a directory. 235.It Bq Er ENOTCAPABLE 236.Fa path 237is an absolute path, 238or contained a ".." component leading to a 239directory outside of the directory hierarchy specified by 240.Fa fd , 241and the process is in capability mode. 242.El 243.Sh SEE ALSO 244.Xr chmod 2 , 245.Xr intro 2 , 246.Xr stat 2 247.Sh STANDARDS 248The 249.Fn access 250system call is expected to conform to 251.St -p1003.1-90 . 252The 253.Fn faccessat 254system call follows The Open Group Extended API Set 2 specification. 255.Sh HISTORY 256The 257.Fn access 258function appeared in 259.At v7 . 260The 261.Fn faccessat 262system call appeared in 263.Fx 8.0 . 264.Sh SECURITY CONSIDERATIONS 265The 266.Fn access , 267.Fn eaccess , 268and 269.Fn faccessat 270system calls are subject to time-of-check-to-time-of-use races and 271should not be relied upon for file permission enforcement purposes. 272Instead, applications should perform the desired action using the 273requesting user's credentials. 274