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. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)access.2 8.2 (Berkeley) 4/1/94 33.\" $FreeBSD: src/lib/libc/sys/access.2,v 1.7.2.5 2002/10/12 22:02:53 rwatson Exp $ 34.\" $DragonFly: src/lib/libc/sys/access.2,v 1.2 2003/06/17 04:26:47 dillon Exp $ 35.\" 36.Dd August 23, 2009 37.Dt ACCESS 2 38.Os 39.Sh NAME 40.Nm access , 41.Nm faccessat 42.Nd check access permissions of a file or pathname 43.Sh LIBRARY 44.Lb libc 45.Sh SYNOPSIS 46.In unistd.h 47.Ft int 48.Fn access "const char *path" "int mode" 49.Ft int 50.Fn faccessat "int fd" "const char *path" "int mode" "int flags" 51.Sh DESCRIPTION 52The 53.Fn access 54function checks the accessibility of the 55file named by 56.Fa path 57for the access permissions indicated by 58.Fa mode . 59The value of 60.Fa mode 61is the bitwise inclusive OR of the access permissions to be 62checked 63.Pf ( Dv R_OK 64for read permission, 65.Dv W_OK 66for write permission and 67.Dv X_OK 68for execute/search permission) or the existence test, 69.Dv F_OK . 70All components of the pathname 71.Fa path 72are checked for access permissions (including 73.Dv F_OK ) . 74.Pp 75The real user ID is used in place of the effective user ID 76and the real group access list 77(including the real group ID) are 78used in place of the effective ID for verifying permission. 79.Pp 80Even if a process has appropriate privileges and indicates success for 81.Dv X_OK , 82the file may not actually have execute permission bits set. 83Likewise for 84.Dv R_OK 85and 86.Dv W_OK . 87.Pp 88The 89.Fn faccessat 90function 91operates as the 92.Fn access 93function but uses either the effective and group IDs or real ones depending on 94the value of 95.Fa flags . 96.Pp 97The values for the 98.Fa flags 99are constructed by a bitwise-inclusive OR of flags from the following list, 100defined in 101.In fcntl.h : 102.Bl -tag -width indent 103.It Dv AT_EACCESS 104Use effective user and group IDs. 105.El 106.Pp 107If 108.Fa path 109specifies a relative path the file to access is determined relative to the 110directory associated with the file descriptor 111.Fa fd 112instead of the current working directory. 113If 114.Fa fd 115is the special value 116.Dv AT_FDCWD 117the current working directory is used and the behavior is identical to a call to 118.Fn access . 119.Sh RETURN VALUES 120If 121.Fa path 122cannot be found or if any of the desired access modes would 123not be granted, then a -1 value is returned; otherwise 124a 0 value is returned. 125.Sh ERRORS 126The 127.Fn access 128and 129.Fn faccessat 130functions can fail with: 131.Bl -tag -width Er 132.It Bq Er ENOTDIR 133A component of the path prefix is not a directory. 134.It Bq Er ENAMETOOLONG 135A component of a pathname exceeded 255 characters, 136or an entire path name exceeded 1023 characters. 137.It Bq Er ENOENT 138The named file does not exist. 139.It Bq Er ELOOP 140Too many symbolic links were encountered in translating the pathname. 141.It Bq Er EROFS 142Write access is requested for a file on a read-only file system. 143.It Bq Er ETXTBSY 144Write access is requested for a pure procedure (shared text) 145file presently being executed. 146.It Bq Er EACCES 147Permission bits of the file mode do not permit the requested 148access, or search permission is denied on a component of the 149path prefix. The owner of a file has permission checked with 150respect to the ``owner'' read, write, and execute mode bits, 151members of the file's group other than the owner have permission 152checked with respect to the ``group'' mode bits, and all 153others have permissions checked with respect to the ``other'' 154mode bits. 155.It Bq Er EFAULT 156.Fa Path 157points outside the process's allocated address space. 158.It Bq Er EIO 159An I/O error occurred while reading from or writing to the file system. 160.El 161.Pp 162In addition the 163.Fn faccessat 164function can fail with: 165.Bl -tag -width Er 166.It Bq Er EBADF 167.Fa fd 168is not a valid file descriptor. 169.It Bq Er ENOTDIR 170.Fa path 171is relative and 172.Fa fd 173does not point to a directory. 174.It Bq Er EINVAL 175.Fa flags 176contains unsupported flags. 177.El 178.Sh SEE ALSO 179.Xr chmod 2 , 180.Xr stat 2 181.Sh STANDARDS 182The 183.Fn access 184function call is expected to conform to 185.St -p1003.1-90 . 186.Pp 187The 188.Fn faccessat 189function call is expected to conform to 190.St -p1003.1-2008 . 191.Sh CAVEAT 192.Fn Access 193is a potential security hole due to race conditions and 194should never be used. 195Setuid and setgid applications should either use the 196.Fn faccessat 197function or restore the effective uid or gid 198and perform actions directly rather than use 199.Fn access 200to simulate access checks for the real user of group id. 201.Sh HISTORY 202An 203.Fn access 204function call appeared in 205.At v7 . 206.Pp 207The 208.Fn faccessat 209system call appeared in 210.Dx 2.3 . 211