xnu-1228.9.59.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 3e5f148018cd18415918623a48d8951fc78e62fa..7179b362e8b1eca515576c125bdb3004fbdd6a8e 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,43 @@
 .\"
 .\"     @(#)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
+.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
 .Ft int

-.Fn chown "const char *path" "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 fchown "int fd" "uid_t owner" "gid_t group"
+.Fo lchown
+.Fa "const char *path"
+.Fa "uid_t owner"
+.Fa "gid_t group"
+.Fc

 .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 +77,133 @@ 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
+The
+.Fn chown
+system call

 clears the set-user-id and set-group-id bits
 on the file
 to prevent accidental or mischievous creation of
 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.
+set-user-id and set-group-id programs if not executed
+by the super-user.
+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

 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
 .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 .

 .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.