1.\" $OpenBSD: access.2,v 1.23 2014/02/13 07:30:39 guenther 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: February 13 2014 $ 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.Fd #include <unistd.h> 42.Ft int 43.Fn access "const char *path" "int amode" 44.Fd #include <fcntl.h> 45.Fd #include <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 path name exceeded 140.Dv {PATH_MAX} 141characters. 142.It Bq Er ENOENT 143The named file does not exist. 144.It Bq Er ELOOP 145Too many symbolic links were encountered in translating the pathname. 146.It Bq Er EROFS 147Write access is requested for a file on a read-only file system. 148.It Bq Er ETXTBSY 149Write access is requested for a pure procedure (shared text) 150file presently being executed. 151.It Bq Er EACCES 152Permission bits of the file mode do not permit the requested access, 153or search permission is denied on a component of the path prefix. 154The owner of a file has permission checked with respect to the 155.Dq owner 156read, write, and execute mode bits, members of the file's group other 157than the owner have permission checked with respect to the 158.Dq group 159mode bits, and all others have permissions checked with respect to the 160.Dq other 161mode bits. 162.It Bq Er EPERM 163Write access has been requested and the named file has its immutable 164flag set (see 165.Xr chflags 2 ) . 166.It Bq Er EFAULT 167.Fa path 168points outside the process's allocated address space. 169.It Bq Er EIO 170An I/O error occurred while reading from or writing to the file system. 171.It Bq Er EINVAL 172An invalid value was specified for 173.Ar amode . 174.El 175.Pp 176Additionally, 177.Fn faccessat 178will fail if: 179.Bl -tag -width Er 180.It Bq Er EINVAL 181The value of the 182.Fa flag 183argument was neither zero nor 184.Dv AT_EACCESS . 185.It Bq Er EBADF 186The 187.Fa path 188argument specifies a relative path and the 189.Fa fd 190argument is neither 191.Dv AT_FDCWD 192nor a valid file descriptor. 193.It Bq Er ENOTDIR 194The 195.Fa path 196argument specifies a relative path and the 197.Fa fd 198argument is a valid file descriptor but it does not reference a directory. 199.It Bq Er EACCES 200The 201.Fa path 202argument specifies a relative path but search permission is denied 203for the directory which the 204.Fa fd 205file descriptor references. 206.El 207.Sh SEE ALSO 208.Xr chmod 2 , 209.Xr stat 2 210.Sh STANDARDS 211The 212.Fn access 213and 214.Fn faccessat 215functions conform to 216.St -p1003.1-2008 . 217.Sh HISTORY 218.Fn access 219first appeared as an internal kernel function in 220.At v1 221and was reimplemented in C before the release of 222.At v4 . 223It was first promoted to a system call in the Programmer's Workbench 224(PWB/UNIX), which was later ported to 225.At v7 226and 227.Bx 2 . 228.Pp 229The 230.Fn faccessat 231function appeared in 232.Ox 5.0 . 233.Sh AUTHORS 234.An Ken Thompson 235first implemented the 236.Fn access 237kernel function in C. 238.Sh CAVEATS 239.Fn access 240and 241.Fn faccessat 242should never be used for actual access control. 243Doing so can result in a time of check vs. time of use security hole. 244