xnu-6153.121.1.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 3ce057f3b4d8a20876c09f41baba443d070d1edd..8d867fa41be4c8a0046e50ae45639bedbad079f9 100644 (file)
--- a/bsd/man/man2/chown.2
+++ b/bsd/man/man2/chown.2
@@ -1,6 +1,3 @@
-.\"    $OpenBSD: chown.2,v 1.3 1997/01/26 05:10:33 downsj Exp $
-.\"    $NetBSD: chown.2,v 1.10 1995/10/12 15:40:47 jtc Exp $
-.\"

 .\" Copyright (c) 1980, 1991, 1993, 1994
 .\"    The Regents of the University of California.  All rights reserved.
 .\"
 .\" Copyright (c) 1980, 1991, 1993, 1994
 .\"    The Regents of the University of California.  All rights reserved.
 .\"


@@ -34,29 +31,46 @@
 .\"
 .\"     @(#)chown.2    8.4 (Berkeley) 4/19/94
 .\"
 .\"
 .\"     @(#)chown.2    8.4 (Berkeley) 4/19/94
 .\"

-.Dd January 25, 1997
+.Dd April 19, 1994

 .Dt CHOWN 2
 .Os
 .Sh NAME
 .Nm chown ,
 .Dt CHOWN 2
 .Os
 .Sh NAME
 .Nm chown ,

-.Nm fchown
-.Nd change owner and group of a file or link
+.Nm fchown ,
+.Nm lchown ,
+.Nm fchownat
+.Nd change owner and group of a file

 .Sh SYNOPSIS
 .Sh SYNOPSIS

-.Fd #include <sys/types.h>
-.Fd #include <unistd.h>
+.In unistd.h
+.Ft int
+.Fo chown
+.Fa "const char *path"
+.Fa "uid_t owner"
+.Fa "gid_t group"
+.Fc
+.Ft int
+.Fo fchown
+.Fa "int fildes"
+.Fa "uid_t owner"
+.Fa "gid_t group"
+.Fc

 .Ft int
 .Ft int

-.Fn chown "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
 .Ft int

-.Fn fchown "int fd" "uid_t owner" "gid_t group"
+.Fn fchownat "int fd" "const char *path" "uid_t owner" "gid_t group" "int flag"

 .Sh DESCRIPTION
 .Sh DESCRIPTION

-The owner ID and group ID of the file (or link)
+The owner ID and group ID of the file

 named by
 .Fa path
 or referenced by
 named by
 .Fa path
 or referenced by

-.Fa fd
+.Fa fildes

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

-and 
+and

 .Fa group .
 The owner of a file may change the
 .Fa group
 .Fa group .
 The owner of a file may change the
 .Fa group


@@ -66,88 +80,208 @@ but the change
 .Fa owner
 capability is restricted to the super-user.
 .Pp
 .Fa owner
 capability is restricted to the super-user.
 .Pp

-.Fn Chown
-clears the set-user-id and set-group-id bits
-on the file
-to prevent accidental or mischievous creation of
-set-user-id and set-group-id programs.
+The
+.Fn chown
+system call clears the set-user-id and set-group-id bits on the file.
+The
+.Fn chown
+system call
+follows symbolic links to operate on the target of the link
+rather than the link itself.

 .Pp
 .Pp

-.Fn Fchown
+The
+.Fn fchown
+system call

 is particularly useful when used in conjunction
 with the file locking primitives (see
 .Xr flock 2 ) .
 .Pp
 is particularly useful when used in conjunction
 with the file locking primitives (see
 .Xr flock 2 ) .
 .Pp

+The
+.Fn lchown
+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
 One of the owner or group id's
 may be left unchanged by specifying it as -1.
 .Sh RETURN VALUES

-Zero is returned if the operation was successful;
--1 is returned if an error occurs, with a more specific
-error code being placed in the global variable
-.Va errno .
+.Rv -std

 .Sh ERRORS
 .Sh ERRORS

-.Fn Chown
-will fail and the file or link will be unchanged if:
+.Pp
+The
+.Fn chown
+and
+.Fn lchown
+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 
-.Dv {NAME_MAX}
-characters, or an entire path name exceeded 
-.Dv {PATH_MAX}
-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
 .It Bq Er EFAULT

-.Fa Path
+The
+.Fa path
+argument

 points outside the process's allocated address space.
 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
 .El
 .Pp

-.Fn Fchown
-will fail if:
+The
+.Fn fchown
+system call will fail if:

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

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

 .It Bq Er EBADF
 .It Bq Er EBADF

-.Fa fd
+The
+.Fa fildes
+argument

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

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

 .It Bq Er EINVAL
 .It Bq Er EINVAL

-.Fa fd
+The
+.Fa fildes
+argument

 refers to a socket, not a file.
 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
 .El
 .Sh SEE ALSO

-.Xr chown 8 ,

 .Xr chgrp 1 ,
 .Xr chmod 2 ,
 .Xr chgrp 1 ,
 .Xr chmod 2 ,

-.Xr flock 2
+.Xr flock 2 ,
+.Xr chown 8

 .Sh STANDARDS
 The
 .Fn chown
 .Sh STANDARDS
 The
 .Fn chown

-function is expected to conform to 
-.St -p1003.1-88 .
+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
 .Sh HISTORY
 The

+.Fn chown
+function appeared in
+.At v7 .
+The

 .Fn fchown
 .Fn fchown

-function call appeared in
+system call appeared in

 .Bx 4.2 .
 .Pp
 The
 .Fn chown
 and
 .Fn fchown
 .Bx 4.2 .
 .Pp
 The
 .Fn chown
 and
 .Fn fchown

-functions were changed to follow symbolic links in
+system calls were changed to follow symbolic links in

 .Bx 4.4 .
 .Bx 4.4 .

+The
+.Fn lchown
+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