1.\" $OpenBSD: access.2,v 1.27 2023/09/28 01:51:00 jsg Exp $ 2.\" $NetBSD: access.2,v 1.7 1995/02/27 12:31:44 cgd Exp $ 3.\" 4.\" Copyright (c) 1980, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)access.2 8.2 (Berkeley) 4/1/94 32.\" 33.Dd $Mdocdate: September 28 2023 $ 34.Dt ACCESS 2 35.Os 36.Sh NAME 37.Nm access , 38.Nm faccessat 39.Nd check access permissions of a file or pathname 40.Sh SYNOPSIS 41.In unistd.h 42.Ft int 43.Fn access "const char *path" "int amode" 44.In fcntl.h 45.In unistd.h 46.Ft int 47.Fn faccessat "int fd" "const char *path" "int amode" "int flag" 48.Sh DESCRIPTION 49The 50.Fn access 51function checks the accessibility of the file named by 52.Fa path 53for the access permissions indicated by 54.Fa amode . 55The 56.Fa amode 57argument is either the bitwise OR of one or more of the access permissions 58to be checked 59.Pf ( Dv R_OK 60for read permission, 61.Dv W_OK 62for write permission, and 63.Dv X_OK 64for execute/search permission) or the existence test, 65.Dv F_OK . 66All components of the pathname 67.Fa path 68are checked for access permissions (including 69.Dv F_OK ) . 70.Pp 71The real user ID is used in place of the effective user ID 72and the real group access list 73(including the real group ID) is 74used in place of the effective ID for verifying permission. 75.Pp 76If the invoking process has superuser privileges, 77.Fn access 78will always indicate success for 79.Dv R_OK 80and 81.Dv W_OK , 82regardless of the actual file permission bits. 83Likewise, for 84.Dv X_OK , 85if the file has any of the execute bits set and 86.Fa path 87is not a directory, 88.Fn access 89will indicate success. 90.Pp 91The 92.Fn faccessat 93function is equivalent to 94.Fn access 95except that where 96.Fa path 97specifies a relative path, 98the file whose accessibility is checked is determined relative to 99the directory associated with file descriptor 100.Fa fd 101instead of the current working directory. 102.Pp 103If 104.Fn faccessat 105is passed the special value 106.Dv AT_FDCWD 107(defined in 108.In fcntl.h ) 109in the 110.Fa fd 111parameter, the current working directory is used. 112If 113.Fa flag 114is also zero, the behavior is identical to a call to 115.Fn access . 116.Pp 117The 118.Fa flag 119argument is the bitwise OR of zero or more of the following values: 120.Pp 121.Bl -tag -width AT_EACCESS -offset indent -compact 122.It Dv AT_EACCESS 123The checks for accessibility are performed using the effective user 124and group IDs instead of the real user and group IDs. 125.El 126.Sh RETURN VALUES 127If 128.Fa path 129cannot be found or if any of the desired access modes would not be granted, 130then a \-1 value is returned; otherwise a 0 value is returned. 131.Sh ERRORS 132Access to the file is denied if: 133.Bl -tag -width Er 134.It Bq Er ENOTDIR 135A component of the path prefix is not a directory. 136.It Bq Er ENAMETOOLONG 137A component of a pathname exceeded 138.Dv NAME_MAX 139characters, or an entire pathname (including the terminating NUL) 140exceeded 141.Dv PATH_MAX 142bytes. 143.It Bq Er ENOENT 144The named file does not exist. 145.It Bq Er ELOOP 146Too many symbolic links were encountered in translating the pathname. 147.It Bq Er EROFS 148Write access is requested for a file on a read-only file system. 149.It Bq Er ETXTBSY 150Write access is requested for a pure procedure (shared text) 151file presently being executed. 152.It Bq Er EACCES 153Permission bits of the file mode do not permit the requested access, 154or search permission is denied on a component of the path prefix. 155The owner of a file has permission checked with respect to the 156.Dq owner 157read, write, and execute mode bits, members of the file's group other 158than the owner have permission checked with respect to the 159.Dq group 160mode bits, and all others have permissions checked with respect to the 161.Dq other 162mode bits. 163.It Bq Er EPERM 164Write access has been requested and the named file has its immutable 165flag set (see 166.Xr chflags 2 ) . 167.It Bq Er EFAULT 168.Fa path 169points outside the process's allocated address space. 170.It Bq Er EIO 171An I/O error occurred while reading from or writing to the file system. 172.It Bq Er EINVAL 173An invalid value was specified for 174.Fa amode . 175.El 176.Pp 177Additionally, 178.Fn faccessat 179will fail if: 180.Bl -tag -width Er 181.It Bq Er EINVAL 182The value of the 183.Fa flag 184argument was neither zero nor 185.Dv AT_EACCESS . 186.It Bq Er EBADF 187The 188.Fa path 189argument specifies a relative path and the 190.Fa fd 191argument is neither 192.Dv AT_FDCWD 193nor a valid file descriptor. 194.It Bq Er ENOTDIR 195The 196.Fa path 197argument specifies a relative path and the 198.Fa fd 199argument is a valid file descriptor but it does not reference a directory. 200.It Bq Er EACCES 201The 202.Fa path 203argument specifies a relative path but search permission is denied 204for the directory which the 205.Fa fd 206file descriptor references. 207.El 208.Sh SEE ALSO 209.Xr chmod 2 , 210.Xr stat 2 211.Sh STANDARDS 212The 213.Fn access 214and 215.Fn faccessat 216functions conform to 217.St -p1003.1-2008 . 218.Sh HISTORY 219.Fn access 220first appeared as an internal kernel function in 221.At v1 . 222It became a system call, 223first appearing outside of Bell Labs in the 224.Dq 50 changes 225tape for 226.At v6 . 227The first official release with the system call was PWB/UNIX 1.0. 228It was also included in 229.Bx 2 . 230.Pp 231The 232.Fn faccessat 233function appeared in 234.Ox 5.0 . 235.Sh CAVEATS 236.Fn access 237and 238.Fn faccessat 239should never be used for actual access control. 240Doing so can result in a time of check vs. time of use security hole. 241