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

FreeBSD Manual Pages


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

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

     #include <unistd.h>

     access(const char *path, int amode);

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

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

     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

     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-

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

     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.

     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

     [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

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

     [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.

     chmod(2), stat(2)

     The access() and faccessat() functions conform to IEEE Std	1003.1-2008

     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.

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

     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


Want to link to this manual page? Use this URL:

home | help