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 7ba416f38ee279b6d04b451a1e1311e1ab62b5c3..6734cf17dd586ecdb371f7d26342b60f117493e0 100644 (file)
--- a/bsd/man/man2/chown.2
+++ b/bsd/man/man2/chown.2
@@ -37,22 +37,37 @@
 .Sh NAME
 .Nm chown ,
 .Nm fchown ,
 .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
 .Ft int
 .Nd change owner and group of a file
 .Sh SYNOPSIS
 .In unistd.h
 .Ft int

-.Fn chown "const char *path" "uid_t owner" "gid_t group"
+.Fo chown
+.Fa "const char *path"
+.Fa "uid_t owner"
+.Fa "gid_t group"
+.Fc

 .Ft int
 .Ft int

-.Fn fchown "int fd" "uid_t owner" "gid_t group"
+.Fo fchown
+.Fa "int fildes"
+.Fa "uid_t owner"
+.Fa "gid_t group"
+.Fc

 .Ft int
 .Ft int

-.Fn lchown "const char *path" "uid_t owner" "gid_t group"
+.Fo lchown
+.Fa "const char *path"
+.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
 .Fa path
 or referenced by
 .Sh DESCRIPTION
 The owner ID and group ID of the file
 named by
 .Fa path
 or referenced by

-.Fa fd
+.Fa fildes

 is changed as specified by the arguments
 .Fa owner
 and
 is changed as specified by the arguments
 .Fa owner
 and


@@ -92,61 +107,150 @@ system call is similar to
 .Fn chown
 but does not follow symbolic links.
 .Pp
 .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
 .Rv -std
 .Sh ERRORS
 One of the owner or group id's
 may be left unchanged by specifying it as -1.
 .Sh RETURN VALUES
 .Rv -std
 .Sh ERRORS

+.Pp

 The
 .Fn chown
 and
 .Fn lchown
 The
 .Fn chown
 and
 .Fn lchown

-will fail and the file will be unchanged if:
+system calls will fail if:

 .Bl -tag -width Er
 .Bl -tag -width Er

-.It Bq Er ENOTDIR
-A component of the path prefix is not a directory.
-.It Bq Er ENAMETOOLONG
-A component of a pathname exceeded 255 characters,
-or an entire path name exceeded 1023 characters.
-.It Bq Er ENOENT
-The named file does not exist.
+.\" ==========

 .It Bq Er EACCES
 Search permission is denied for a component of the path prefix.
 .It Bq Er EACCES
 Search permission is denied for a component of the path prefix.

-.It Bq Er ELOOP
-Too many symbolic links were encountered in translating the pathname.
-.It Bq Er EPERM
-The effective user ID is not the super-user.
-.It Bq Er EROFS
-The named file resides on a read-only file system.

 .It Bq Er EFAULT
 The
 .Fa path
 argument
 points outside the process's allocated address space.
 .It Bq Er EFAULT
 The
 .Fa path
 argument
 points outside the process's allocated address space.

-.It Bq Er EIO
-An I/O error occurred while reading from or writing to the file system.
+.\" ==========
+.It Bq Er ELOOP
+Too many symbolic links are encountered in translating the pathname.
+This is taken to be indicative of a looping symbolic link.
+.\" ==========
+.It Bq Er ENAMETOOLONG
+A component of a pathname exceeded 255 characters,
+or an entire path name exceeded 1023 characters.
+.\" ==========
+.It Bq Er ENOENT
+A component of
+.Fa path
+does not exist.
+.\" ==========
+.It Bq Er ENOTDIR
+A component of the path prefix is not a directory.

 .El
 .Pp
 The
 .Fn fchown
 system call will fail if:
 .Bl -tag -width Er
 .El
 .Pp
 The
 .Fn fchown
 system call will fail if:
 .Bl -tag -width Er

+.\" ==========

 .It Bq Er EBADF
 The
 .It Bq Er EBADF
 The

-.Fa fd
+.Fa fildes

 argument
 does not refer to a valid descriptor.
 argument
 does not refer to a valid descriptor.

+.\" ==========

 .It Bq Er EINVAL
 The
 .It Bq Er EINVAL
 The

-.Fa fd
+.Fa fildes

 argument
 refers to a socket, not a file.
 argument
 refers to a socket, not a file.

+.El
+.Pp
+Any of these calls will fail if:
+.Bl -tag -width Er
+.\" ==========
+.It Bq Er EINTR
+Its execution is interrupted by a signal.
+.\" ==========
+.It Bq Er EIO
+An I/O error occurs while reading from or writing to the file system.
+.\" ==========

 .It Bq Er EPERM
 .It Bq Er EPERM

-The effective user ID is not the super-user.
+The effective user ID does not match the owner of the file
+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.
 .It Bq Er EROFS
 The named file resides on a read-only file system.

-.It Bq Er EIO
-An I/O error occurred while reading from or writing to the 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 ,
 .El
 .Sh SEE ALSO
 .Xr chgrp 1 ,


@@ -158,6 +262,9 @@ The
 .Fn chown
 system call is expected to conform to
 .St -p1003.1-90 .
 .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
 .Sh HISTORY
 The
 .Fn chown


@@ -179,3 +286,7 @@ The
 system call was added in
 .Fx 3.0
 to compensate for the loss of functionality.
 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