illumos-gate Cdiff usr/src/man/man2/access.2

Print this page

markup tweaks per mandoc author
fcntl.h only needed for faccessat
copyright
document standards for access, faccess


*** 1,6 ****
! '\" 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
--- 1,6 ----
! .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
  .\" 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
*** 8,336 ****
  .\" 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 <unistd.h>
! #include <sys/fcntl.h>
! 
! \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<fcntl.h>\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<fcntl.h>\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)
--- 8,294 ----
  .\" 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]
! .Dd "Jul 24, 2014"
! .Dt ACCESS 2
! .Os
! .Sh NAME
! .Nm access ,
! .Nm faccessat
! .Nd determine accessibility of a file
! .Sh SYNOPSIS
! .In unistd.h
! .Ft int
! .Fo access
! .Fa "const char *path"
! .Fa "int amode"
! .Fc
! .
! .In unistd.h
! .In fcntl.h
! .Ft int
! .Fo faccessat
! .Fa "int fd"
! .Fa "const char *path"
! .Fa "int amode"
! .Fa "int flag"
! .Fc
! .Sh DESCRIPTION
! The
! .Fn access
! function checks the file named by the pathname pointed to by
! the
! .Fa path
! argument for accessibility according to the bit pattern
! contained in
! .Fa amode ,
! using the real user ID in place of the
! effective user ID and the real group IDR 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.
! .Lp
! The value of
! .Fa amode
! is either the bitwise inclusive
! .Sy OR
! of the access
! permissions to be checked
! .Po
! .Dv R_OK ,
! .Dv W_OK ,
! .Dv X_OK
! .Pc
! or the existence
! test,
! .Dv F_OK .
! .Lp
! These constants are defined in
! .In unistd.h
! as follows:
! .Bl -tag -offset indent -width Dv
! .It Dv R_OK
  Test for read permission.
! .It Dv W_OK
  Test for write permission.
! .It Dv X_OK
  Test for execute or search permission.
! .It Dv F_OK
  Check existence of file
! .El
! .Lp
! See
! .Xr Intro 2
! for additional information about "File Access Permission".
! .Lp
  If any access permissions are to be checked, each will be checked individually,
! as described in
! .Xr Intro 2 .
! If the process has appropriate privileges, an
! implementation may indicate success for
! .Dv X_OK
! even if none of the execute file permission bits are set.
! .Lp
! The
! .Fn faccessat
! function is equivalent to the
! .Fn access
! function,
! except in the case where
! .Fa path
! 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
! .Fa fd
! instead of the current working directory.
! .Lp
! If
! .Fn faccessat
! is passed in the
! .Fa fd
! parameter the special value
! .Dv AT_FDCWD ,
! defined in
! .In fcntl.h ,
! the current working directory is
! used and the behavior is identical to a call to
! .Fn access .
! .Lp
! Values for
! .Fa flag
! are constructed by a bitwise-inclusive OR of flags from
! the following list, defined in
! .In fcntl.h :
! .Bl -tag -offset indent -width Dv
! .It Dv AT_EACCESS
  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
! .Fn access .
! .El
! .Sh RETURN VALUES
! If the requested access is permitted,
! .Fn access
! and
! .Fn faccessat
! succeed and return 0. Otherwise, \(mi1 is returned
! and
! .Va errno
! is set to indicate the error.
! .Sh ERRORS
! The
! .Fn access
! and
! .Fn faccessat
! functions will fail if:
! .Bl -tag -width Er
! .It Er EACCES
  Permission bits of the file mode do not permit the requested access, or search
  permission is denied on a component of the path prefix.
! .
! .It Er EFAULT
! The
! .Fa path
! argument points to an illegal address.
! .
! .It Er EINTR
! A signal was caught during the
! .Fn access
! function.
! .
! .It Er ELOOP
! Too many symbolic links were encountered in resolving
! .Fa path ,
! or loop exists in symbolic links encountered during resolution of the
! .Fa path
  argument.
! .
! .It Er ENAMETOOLONG
! The length of the
! .Fa path
! argument exceeds
! .Brq Dv PATH_MAX ,
! or a pathname
! component is longer than
! .Brq Dv NAME_MAX
! while
! .Dv _POSIX_NO_TRUNC
! is in effect.
! .
! .It Er ENOENT
! A component of
! .Fa path
! does not name an existing file or
! .Fa path
! is an empty string.
! .
! .It Er ENOLINK
! The
! .Fa path
! argument points to a remote machine and the link to that machine
  is no longer active.
! .
! .It Er ENOTDIR
  A component of the path prefix is not a directory.
! .
! .It Er ENXIO
! The
! .Fa path
! argument points to a character or block device special file and
  the corresponding device has been retired by the fault management framework.
! .
! .It Er EROFS
  Write access is requested for a file on a read-only file system.
! .
! .El
! .Lp
! The
! .Fn faccessat
! function will fail if:
! .Bl -tag -width Er
! .It Er EBADF
! The
! .Fa path
! argument does not specify an absolute path and the
! .Fa fd
! argument is neither
! .Dv AT_FDCWD
! nor a valid file descriptor open for reading or searching.
! .El
! .Lp
! The
! .Fn access
! and
! .Fn faccessat
! functions may fail if:
! .Bl -tag -width Er
! .
! .It Er EINVAL
! The value of the
! .Fa amode
! argument is invalid.
! .
! .It Er ENAMETOOLONG
  Pathname resolution of a symbolic link produced an intermediate result whose
! length exceeds
! .Brq Dv PATH_MAX .
! .
! .It Er ETXTBSY
  Write access is requested for a pure procedure (shared text) file that is being
  executed.
! .El
! .Lp
! The
! .Fn faccessat
! function may fail if:
! .Bl -tag -width Er
! .
! .It Er BEINVAL
! The value of the
! .Fa flag
! argument is not valid.
! .
! .It Er ENOTDIR
! The
! .Fa path
! argument is not an absolute path and
! .Fa fd
! is neither
! .Dv AT_FDCWD
! nor a file descriptor associated with a directory.
! .El
! .Sh USAGE
! Additional values of
! .Fa amode
! other than the set defined in the description
  might be valid, for example, if a system has extended access controls.
! .Lp
! The purpose of the
! .Fn faccessat
! 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
! .Fn access ,
! resulting in unspecified
  behavior. By opening a file descriptor for the target directory and using the
! .Fn faccessat
! function, it can be guaranteed that the file tested for
  accessibility is located relative to the desired directory.
! .Sh INTERFACE STABILITY
! .Sy Standard .
! .Sh MT-LEVEL
! .Sy Async-Signal-Safe .
! .Sh SEE ALSO
! .Xr Intro 2 ,
! .Xr chmod 2 ,
! .Xr stat 2 ,
! .Xr standards 5
! .Sh STANDARDS
! The
! .Fn access
! function is defined in
! .St -p1003.1 .
! The
! .Fn faccessat
! function was introduced in
! .St -p1003.1-2008 .