chown.2: Merge text of fchownat(2)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man2/chown.2

@@ -1,6 +1,6 @@
 .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
 .\" and Copyright (c) 1998 Andries Brouwer (aeb@cwi.nl)
-.\" and Copyright (c) 2007, 2008 Michael Kerrisk <mtk.manpages@gmail.com>
+.\" and Copyright (c) 2006, 2007, 2008, 2014 Michael Kerrisk <mtk.manpages@gmail.com>
 .\"
 .\" %%%LICENSE_START(VERBATIM)
 .\" Permission is granted to make and distribute verbatim copies of this
@@ -35,10 +35,11 @@
 .\"     (bsdgroups versus sysvgroups, and the effect of the parent
 .\"     directory's set-group-ID permission bit).
 .\"
-.TH CHOWN 2 2014-01-05 "Linux" "Linux Programmer's Manual"
+.TH CHOWN 2 2014-02-21 "Linux" "Linux Programmer's Manual"
 .SH NAME
-chown, fchown, lchown \- change ownership of a file
+chown, fchown, lchown, fchownat \- change ownership of a file
 .SH SYNOPSIS
+.nf
 .B #include <unistd.h>
 .sp
 .BI "int chown(const char *" path ", uid_t " owner ", gid_t " group );
@@ -47,6 +48,14 @@ chown, fchown, lchown \- change ownership of a file
 .br
 .BI "int lchown(const char *" path ", uid_t " owner ", gid_t " group );
 .sp
+.BR "#include <fcntl.h>           " "/* Definition of AT_* constants */"
+.B #include <unistd.h>
+.sp
+.BI "int fchownat(int " dirfd ", const char *" pathname ,
+.BI "             uid_t " owner ", gid_t " group ", int " flags );
+.fi
+.sp
+.sp
 .in -4n
 Feature Test Macro Requirements for glibc (see
 .BR feature_test_macros (7)):
@@ -62,6 +71,18 @@ _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
 .br
 || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L
 .RE
+.sp
+.BR fchownat ():
+.PD 0
+.ad l
+.RS 4
+.TP 4
+Since glibc 2.10:
+_XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
+.TP
+Before glibc 2.10:
+_ATFILE_SOURCE
+.RE
 .ad
 .PD
 .SH DESCRIPTION
@@ -116,6 +137,80 @@ bit is not set) the
 .B S_ISGID
 bit indicates mandatory locking, and is not cleared by a
 .BR chown ().
+.SS fchownat()
+The
+.BR fchownat ()
+system call operates in exactly the same way as
+.BR chown (2),
+except for the differences described here.
+
+If the pathname given in
+.I pathname
+is relative, then it is interpreted relative to the directory
+referred to by the file descriptor
+.I dirfd
+(rather than relative to the current working directory of
+the calling process, as is done by
+.BR chown (2)
+for a relative pathname).
+
+If
+.I pathname
+is relative and
+.I dirfd
+is the special value
+.BR AT_FDCWD ,
+then
+.I pathname
+is interpreted relative to the current working
+directory of the calling process (like
+.BR chown (2)).
+
+If
+.I pathname
+is absolute, then
+.I dirfd
+is ignored.
+
+The
+.I flags
+argument is a bit mask created by ORing together
+0 or more of the following values;
+.TP
+.BR AT_EMPTY_PATH " (since Linux 2.6.39)"
+.\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
+If
+.I pathname
+is an empty string, operate on the file referred to by
+.IR dirfd
+(which may have been obtained using the
+.BR open (2)
+.B O_PATH
+flag).
+In this case,
+.I dirfd
+can refer to any type of file, not just a directory.
+This flag is Linux-specific; define
+.B _GNU_SOURCE
+.\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
+to obtain its definition.
+
+.TP
+.B AT_SYMLINK_NOFOLLOW
+If
+.I pathname
+is a symbolic link, do not dereference it:
+instead operate on the link itself, like
+.BR lchown (2).
+(By default,
+.BR fchownat ()
+dereferences symbolic links, like
+.BR chown (2).)
+.PP
+See
+.BR openat (2)
+for an explanation of the need for
+.BR fchownat ().
 .SH RETURN VALUE
 On success, zero is returned.
 On error, \-1 is returned, and
@@ -178,7 +273,35 @@ See above.
 .TP
 .B EROFS
 See above.
+.PP
+The same errors that occur for
+.BR chown (2)
+can also occur for
+.BR fchownat ().
+The following additional errors can occur for
+.BR fchownat ():
+.TP
+.B EBADF
+.I dirfd
+is not a valid file descriptor.
+.TP
+.B EINVAL
+Invalid flag specified in
+.IR flags .
+.TP
+.B ENOTDIR
+.I pathname
+is relative and
+.I dirfd
+is a file descriptor referring to a file other than a directory.
+.SH VERSIONS
+.BR fchownat ()
+was added to Linux in kernel 2.6.16;
+library support was added to glibc in version 2.4.
 .SH CONFORMING TO
+.BR chown (),
+.BR fchown (),
+.BR lchown ():
 4.4BSD, SVr4, POSIX.1-2001.
 
 The 4.4BSD version can be
@@ -189,6 +312,10 @@ used only by the superuser (that is, ordinary users cannot give away files).
 .\" fchown():
 .\" SVr4 documents additional EINVAL, EIO, EINTR, and ENOLINK
 .\" error conditions.
+
+.BR fchownat ():
+POSIX.1-2008.
+A similar system call exists on Solaris.
 .SH NOTES
 The original Linux
 .BR chown (),
@@ -335,7 +462,6 @@ main(int argc, char *argv[])
 .fi
 .SH SEE ALSO
 .BR chmod (2),
-.BR fchownat (2),
 .BR flock (2),
 .BR path_resolution (7),
 .BR symlink (7)