xnu-2782.30.5.tar.gz

[apple/xnu.git] / bsd / man / man2 / chown.2

diff --git a/bsd/man/man2/chown.2 b/bsd/man/man2/chown.2
index 7179b362e8b1eca515576c125bdb3004fbdd6a8e..6734cf17dd586ecdb371f7d26342b60f117493e0 100644 (file)
--- a/bsd/man/man2/chown.2
+++ b/bsd/man/man2/chown.2
@@ -37,7 +37,8 @@
 .Sh NAME
 .Nm chown ,
 .Nm fchown ,
-.Nm lchown
+.Nm lchown ,
+.Nm fchownat
 .Nd change owner and group of a file
 .Sh SYNOPSIS
 .In unistd.h
@@ -59,6 +60,8 @@
 .Fa "uid_t owner"
 .Fa "gid_t group"
 .Fc
+.Ft int
+.Fn fchownat "int fd" "const char *path" "uid_t owner" "gid_t group" "int flag"
 .Sh DESCRIPTION
 The owner ID and group ID of the file
 named by
@@ -104,6 +107,49 @@ system call is similar to
 .Fn chown
 but does not follow symbolic links.
 .Pp
+The
+.Fn fchownat
+system call is equivalent to the
+.Fn chown
+and
+.Fn lchown
+except in the case where
+.Fa path
+specifies a relative path.
+In this case the file to be changed is determined relative to the directory
+associated with the file descriptor
+.Fa fd
+instead of the current working directory.
+.Pp
+Values for
+.Fa flag
+are constructed by a bitwise-inclusive OR of flags from the following
+list, defined in
+.In fcntl.h :
+.Bl -tag -width indent
+.It Dv AT_SYMLINK_NOFOLLOW
+If
+.Fa path
+names a symbolic link, ownership of the symbolic link is changed.
+.El
+.Pp
+If
+.Fn fchownat
+is passed the special value
+.Dv AT_FDCWD
+in the
+.Fa fd
+parameter, the current working directory is used and the behavior is identical
+to a call to
+.Fn chown
+or
+.Fn lchown
+respectively, depending on whether or not the
+.Dv AT_SYMLINK_NOFOLLOW
+bit is set in the
+.Fa flag
+argument.
+.Pp
 One of the owner or group id's
 may be left unchanged by specifying it as -1.
 .Sh RETURN VALUES
@@ -176,6 +222,36 @@ and the calling process does not have appropriate (i.e., root) privileges.
 .It Bq Er EROFS
 The named file resides on a read-only file system.
 .El
+.Pp
+In addition to the errors specified for
+.Fn chown
+and
+.Fn lchown ,
+the
+.Fn fchownat
+system call may fail if:
+.Bl -tag -width Er
+.It Bq 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 searching.
+.It Bq Er EINVAL
+The value of the
+.Fa flag
+argument is not valid.
+.It Bq 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 SEE ALSO
 .Xr chgrp 1 ,
 .Xr chmod 2 ,
@@ -186,6 +262,9 @@ The
 .Fn chown
 system call is expected to conform to
 .St -p1003.1-90 .
+The
+.Fn fchownat
+system call is expected to conform to POSIX.1-2008 .
 .Sh HISTORY
 The
 .Fn chown
@@ -207,3 +286,7 @@ The
 system call was added in
 .Fx 3.0
 to compensate for the loss of functionality.
+.Pp
+The
+.Fn fchownat
+system call appeared in OS X 10.10