From a7ae4e787ac9fe78516832417df9c1740c8b5f4e Mon Sep 17 00:00:00 2001
From: Michael Kerrisk <mtk.manpages@gmail.com>
Date: Tue, 2 May 2006 00:04:28 +0000
Subject: [PATCH] New page for faccessat(2)

---
 man2/faccessat.2 | 141 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 141 insertions(+)
 create mode 100644 man2/faccessat.2

diff --git a/man2/faccessat.2 b/man2/faccessat.2
new file mode 100644
index 000000000..980250d5d
--- /dev/null
+++ b/man2/faccessat.2
@@ -0,0 +1,141 @@
+.\" Hey Emacs! This file is -*- nroff -*- source.
+.\"
+.\" This manpage is Copyright (C) 2006, Michael Kerrisk
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.\" 
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date.  The author(s) assume no
+.\" responsibility for errors or omissions, or for damages resulting from
+.\" the use of the information contained herein.  The author(s) may not
+.\" have taken the same level of care in the production of this manual,
+.\" which is licensed free of charge, as they might when working
+.\" professionally.
+.\" 
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.\"
+.\"
+.TH FACCESSAT 2 2006-05-05 "Linux 2.6.16" "Linux Programmer's Manual"
+.SH NAME
+faccessat \- change permissions of a file relative to a directory \
+file descriptor
+.SH SYNOPSIS
+.nf
+.B #include <unistd.h>
+.sp
+.BI "int faccessat(int " dirfd ", const char *" path ", int " \
+mode ", int " flags );
+.fi
+.SH DESCRIPTION
+The
+.BR faccessat ()
+system call operates in exactly the same way as
+.BR access (2),
+except for the differences described in this manual page.
+
+If the pathname given in 
+.I path
+is relative, then it is interpreted relative to the directory
+referred to by the file descriptor
+.IR dirfd 
+(rather than relative to the current working directory of 
+the calling process, as is done by
+.BR access (2)
+for a relative pathname).
+
+If the pathname given in 
+.I path
+is relative and 
+.I dirfd
+is the special value
+.BR AT_FDCWD ,
+then
+.I path
+is interpreted relative to the current working 
+directory of the calling process (like
+.BR access (2)).
+
+If the pathname given in
+.IR path
+is absolute, then 
+.I dirfd 
+is ignored.
+
+.I flags
+is constructed by ORing together zero or more of the following values:
+.TP
+.B AT_EACESS
+Perform access checks using the effective user and group IDs.  
+By default, 
+.BR faccessat ()
+uses the effective IDs (like
+.BR access (2)).
+.TP
+.B AT_SYMLINK_NOFOLLOW
+If 
+.I path 
+is a symbolic link, do not dereference it: 
+instead return information about the link itself.
+.SH "RETURN VALUE"
+On success,
+.BR faccessat () 
+returns 0.  
+On error, \-1 is returned and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+The same errors that occur for
+.BR access (2)
+can also occur for
+.BR faccessat ().
+The following additional errors can occur for 
+.BR faccessat ():
+.TP
+.B EBADF
+.I dirfd
+is not a valid file descriptor.
+.TP
+.B EINVAL
+Invalid flag specified in
+.IR flags .
+.TP
+.B ENOTDIR
+.I path
+is a relative path and
+.I dirfd
+is a file descriptor referring to a file other than a directory.
+.SH NOTES
+See
+.BR openat (2)
+for an explanation of the need for
+.BR faccessat ().
+.SH "CONFORMING TO"
+This system call is non-standard but is proposed
+for inclusion in a future revision of POSIX.1.
+.SH GLIBC NOTES
+The
+.B AT_EACCESS
+and
+.B AT_SYMLINK_NOFOLLOW
+flags are actually implemented within the glibc wrapper function for 
+.BR faccessat ().
+If either of these flags are specified, then the wrapper function employs 
+.BR fstatat (2)
+to determine access permissions.
+.SH VERSIONS
+.BR faccessat ()
+was added to Linux in kernel 2.6.16.
+.SH "SEE ALSO"
+.BR access (2),
+.BR openat (2),
+.BR path_resolution (2)
+.\" FIXME . Should have SEE ALSO in both directions for eaccess.3, when
+.\"         that page is eventually written.