'\" te .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. .\" Copyright 1989 AT&T .\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at http://www.opengroup.org/bookstore/. .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text .\" are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical .\" and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. .\" This notice shall appear on any product containing this material. .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] .TH ACCESS 2 "Jun 16, 2009" .SH NAME access, faccessat \- determine accessibility of a file .SH SYNOPSIS .LP .nf #include #include \fBint\fR \fBaccess\fR(\fBconst char *\fR\fIpath\fR, \fBint\fR \fIamode\fR); .fi .LP .nf \fBint\fR \fBfaccessat\fR(\fBint\fR \fIfd\fR, \fBconst char *\fR\fIpath\fR, \fBint\fR \fIamode\fR, \fBint\fR \fIflag\fR); .fi .SH DESCRIPTION .sp .LP The \fBaccess()\fR function checks the file named by the pathname pointed to by the \fIpath\fR argument for accessibility according to the bit pattern contained in \fIamode\fR, using the real user \fBID\fR in place of the effective user \fBID\fR and the real group \fBID\fR in place of the effective group ID. This allows a setuid process to verify that the user running it would have had permission to access this file. .sp .LP The value of \fIamode\fR is either the bitwise inclusive \fBOR\fR of the access permissions to be checked (\fBR_OK\fR, \fBW_OK\fR, \fBX_OK\fR) or the existence test, \fBF_OK\fR. .sp .LP These constants are defined in <\fBunistd.h\fR> as follows: .sp .ne 2 .na \fB\fBR_OK\fR\fR .ad .RS 8n Test for read permission. .RE .sp .ne 2 .na \fB\fBW_OK\fR\fR .ad .RS 8n Test for write permission. .RE .sp .ne 2 .na \fB\fBX_OK\fR\fR .ad .RS 8n Test for execute or search permission. .RE .sp .ne 2 .na \fB\fBF_OK\fR\fR .ad .RS 8n Check existence of file .RE .sp .LP See \fBIntro\fR(2) for additional information about "File Access Permission". .sp .LP If any access permissions are to be checked, each will be checked individually, as described in \fBIntro\fR(2). If the process has appropriate privileges, an implementation may indicate success for \fBX_OK\fR even if none of the execute file permission bits are set. .sp .LP The \fBfaccessat()\fR function is equivalent to the \fBaccess()\fR function, except in the case where \fIpath\fR specifies a relative path. In this case the file whose accessibility is to be determined is located relative to the directory associated with the file descriptor \fIfd\fR instead of the current working directory. .sp .LP If \fBfaccessat()\fR is passed in the \fIfd\fR parameter the special value \fBAT_FDCWD\fR, defined in \fB\fR, the current working directory is used and the behavior is identical to a call to \fBaccess()\fR. .sp .LP Values for \fIflag\fR are constructed by a bitwise-inclusive OR of flags from the following list, defined in \fB\fR: .sp .ne 2 .na \fB\fBAT_EACCESS\fR\fR .ad .RS 14n The checks for accessibility are performed using the effective user and group IDs instead of the real user and group ID as required in a call to \fBaccess()\fR. .RE .SH RETURN VALUES .sp .LP If the requested access is permitted, \fBaccess()\fR and \fBfaccessat()\fRsucceed and return \fB0\fR. Otherwise, \fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the error. .SH ERRORS .sp .LP The \fBaccess()\fR and \fBfaccessat()\fR functions will fail if: .sp .ne 2 .na \fB\fBEACCES\fR\fR .ad .RS 16n Permission bits of the file mode do not permit the requested access, or search permission is denied on a component of the path prefix. .RE .sp .ne 2 .na \fB\fBEFAULT\fR\fR .ad .RS 16n The \fIpath\fR argument points to an illegal address. .RE .sp .ne 2 .na \fB\fBEINTR\fR\fR .ad .RS 16n A signal was caught during the \fBaccess()\fR function. .RE .sp .ne 2 .na \fB\fBELOOP\fR\fR .ad .RS 16n Too many symbolic links were encountered in resolving \fIpath\fR, or loop exists in symbolic links encountered during resolution of the \fIpath\fR argument. .RE .sp .ne 2 .na \fB\fBENAMETOOLONG\fR\fR .ad .RS 16n The length of the \fIpath\fR argument exceeds {\fBPATH_MAX\fR}, or a pathname component is longer than {\fBNAME_MAX\fR} while \fB_POSIX_NO_TRUNC\fR is in effect. .RE .sp .ne 2 .na \fB\fBENOENT\fR\fR .ad .RS 16n A component of \fIpath\fR does not name an existing file or \fIpath\fR is an empty string. .RE .sp .ne 2 .na \fB\fBENOLINK\fR\fR .ad .RS 16n The \fIpath\fR argument points to a remote machine and the link to that machine is no longer active. .RE .sp .ne 2 .na \fB\fBENOTDIR\fR\fR .ad .RS 16n A component of the path prefix is not a directory. .RE .sp .ne 2 .na \fB\fBENXIO\fR\fR .ad .RS 16n The \fIpath\fR argument points to a character or block device special file and the corresponding device has been retired by the fault management framework. .RE .sp .ne 2 .na \fB\fBEROFS\fR\fR .ad .RS 16n Write access is requested for a file on a read-only file system. .RE .sp .LP The \fBfaccessat()\fR function will fail if: .sp .ne 2 .na \fB\fBEBADF\fR\fR .ad .RS 9n The \fIpath\fR argument does not specify an absolute path and the \fIfd\fR argument is neither \fBAT_FDCWD\fR nor a valid file descriptor open for reading or searching. .RE .sp .LP The \fBaccess()\fR and \fBfaccessat()\fR functions may fail if: .sp .ne 2 .na \fB\fBEINVAL\fR\fR .ad .RS 16n The value of the \fIamode\fR argument is invalid. .RE .sp .ne 2 .na \fB\fBENAMETOOLONG\fR\fR .ad .RS 16n Pathname resolution of a symbolic link produced an intermediate result whose length exceeds {\fBPATH_MAX\fR}. .RE .sp .ne 2 .na \fB\fBETXTBSY\fR\fR .ad .RS 16n Write access is requested for a pure procedure (shared text) file that is being executed. .RE .sp .LP The \fBfaccessat()\fR function may fail if: .sp .ne 2 .na \fB\fBEINVAL\fR\fR .ad .RS 11n The value of the \fIflag\fR argument is not valid. .RE .sp .ne 2 .na \fB\fBENOTDIR\fR\fR .ad .RS 11n The \fIpath\fR argument is not an absolute path and \fIfd\fR is neither \fBAT_FDCWD\fR nor a file descriptor associated with a directory. .RE .SH USAGE .sp .LP Additional values of \fIamode\fR other than the set defined in the description might be valid, for example, if a system has extended access controls. .sp .LP The purpose of the \fBfaccessat()\fR function is to enable the checking of the accessibility of files in directories other than the current working directory without exposure to race conditions. Any part of the path of a file could be changed in parallel to a call to \fBaccess()\fR, resulting in unspecified behavior. By opening a file descriptor for the target directory and using the \fBfaccessat()\fR function, it can be guaranteed that the file tested for accessibility is located relative to the desired directory. .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .sp .TS box; c | c l | l . ATTRIBUTE TYPE ATTRIBUTE VALUE _ Interface Stability Committed _ MT-Level Async-Signal-Safe _ Standard See below. .TE .sp .LP For \fBaccess()\fR, see \fBstandards\fR(5). .SH SEE ALSO .sp .LP \fBIntro\fR(2), \fBchmod\fR(2), \fBstat\fR(2), \fBattributes\fR(5), \fBstandards\fR(5)