Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ACCESS(2)		  FreeBSD System Calls Manual		     ACCESS(2)

NAME
     access, faccessat -- check	access permissions of a	file or	pathname

SYNOPSIS
     #include <unistd.h>

     int
     access(const char *path, int amode);

     #include <fcntl.h>
     #include <unistd.h>

     int
     faccessat(int fd, const char *path, int amode, int	flag);

DESCRIPTION
     The access() function checks the accessibility of the file	named by path
     for the access permissions	indicated by amode.  The amode argument	is ei-
     ther the bitwise OR of one	or more	of the access permissions to be
     checked (R_OK for read permission,	W_OK for write permission, and X_OK
     for execute/search	permission) or the existence test, F_OK.  All compo-
     nents of the pathname path	are checked for	access permissions (including
     F_OK).

     The real user ID is used in place of the effective	user ID	and the	real
     group access list (including the real group ID) is	used in	place of the
     effective ID for verifying	permission.

     If	the invoking process has superuser privileges, access()	will always
     indicate success for R_OK and W_OK, regardless of the actual file permis-
     sion bits.	 Likewise, for X_OK, if	the file has any of the	execute	bits
     set and path is not a directory, access() will indicate success.

     The faccessat() function is equivalent to access()	except that where path
     specifies a relative path,	the file whose accessibility is	checked	is de-
     termined relative to the directory	associated with	file descriptor	fd in-
     stead of the current working directory.

     If	faccessat() is passed the special value	AT_FDCWD (defined in
     <fcntl.h>)	in the fd parameter, the current working directory is used.
     If	flag is	also zero, the behavior	is identical to	a call to access().

     The flag argument is the bitwise OR of zero or more of the	following val-
     ues:

	   AT_EACCESS  The checks for accessibility are	performed using	the
		       effective user and group	IDs instead of the real	user
		       and group IDs.

RETURN VALUES
     If	path cannot be found or	if any of the desired access modes would not
     be	granted, then a	-1 value is returned; otherwise	a 0 value is returned.

ERRORS
     Access to the file	is denied if:

     [ENOTDIR]		A component of the path	prefix is not a	directory.

     [ENAMETOOLONG]	A component of a pathname exceeded NAME_MAX charac-
			ters, or an entire pathname (including the terminating
			NUL) exceeded PATH_MAX bytes.

     [ENOENT]		The named file does not	exist.

     [ELOOP]		Too many symbolic links	were encountered in translat-
			ing the	pathname.

     [EROFS]		Write access is	requested for a	file on	a read-only
			file system.

     [ETXTBSY]		Write access is	requested for a	pure procedure (shared
			text) file presently being executed.

     [EACCES]		Permission bits	of the file mode do not	permit the re-
			quested	access,	or search permission is	denied on a
			component of the path prefix.  The owner of a file has
			permission checked with	respect	to the "owner" read,
			write, and execute mode	bits, members of the file's
			group other than the owner have	permission checked
			with respect to	the "group" mode bits, and all others
			have permissions checked with respect to the "other"
			mode bits.

     [EPERM]		Write access has been requested	and the	named file has
			its immutable flag set (see chflags(2)).

     [EFAULT]		path points outside the	process's allocated address
			space.

     [EIO]		An I/O error occurred while reading from or writing to
			the file system.

     [EINVAL]		An invalid value was specified for amode.

     Additionally, faccessat() will fail if:

     [EINVAL]		The value of the flag argument was neither zero	nor
			AT_EACCESS.

     [EBADF]		The path argument specifies a relative path and	the fd
			argument is neither AT_FDCWD nor a valid file descrip-
			tor.

     [ENOTDIR]		The path argument specifies a relative path and	the fd
			argument is a valid file descriptor but	it does	not
			reference a directory.

     [EACCES]		The path argument specifies a relative path but	search
			permission is denied for the directory which the fd
			file descriptor	references.

SEE ALSO
     chmod(2), stat(2)

STANDARDS
     The access() and faccessat() functions conform to IEEE Std	1003.1-2008
     ("POSIX.1").

HISTORY
     access() first appeared as	an internal kernel function in Version 1 AT&T
     UNIX and was reimplemented	in C before the	release	of Version 4 AT&T
     UNIX.  It was first promoted to a system call in the Programmer's Work-
     bench (PWB/UNIX), which was later ported to Version 7 AT&T	UNIX and 2BSD.

     The faccessat() function appeared in OpenBSD 5.0.

AUTHORS
     Ken Thompson first	implemented the	access() kernel	function in C.

CAVEATS
     access() and faccessat() should never be used for actual access control.
     Doing so can result in a time of check vs.	time of	use security hole.

FreeBSD	13.0		       January 19, 2015			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO | STANDARDS | HISTORY | AUTHORS | CAVEATS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=access&sektion=2&manpath=OpenBSD+6.9>

home | help