diff --git a/man2/chown.2 b/man2/chown.2 index b7410cf76..96cf0eef0 100644 --- a/man2/chown.2 +++ b/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 +.\" and Copyright (c) 2006, 2007, 2008, 2014 Michael Kerrisk .\" .\" %%%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 .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 " "/* Definition of AT_* constants */" +.B #include +.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)