X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/55e303ae13a4cf49d70f2294092726f2fffb9ef2..593a1d5fd87cdf5b46dd5fcb84467b432cea0f91:/bsd/man/man2/chown.2 diff --git a/bsd/man/man2/chown.2 b/bsd/man/man2/chown.2 index 3ce057f3b..7179b362e 100644 --- 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. .\" @@ -34,29 +31,43 @@ .\" .\" @(#)chown.2 8.4 (Berkeley) 4/19/94 .\" -.Dd January 25, 1997 +.Dd April 19, 1994 .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 -.Fd #include -.Fd #include +.In unistd.h +.Ft int +.Fo chown +.Fa "const char *path" +.Fa "uid_t owner" +.Fa "gid_t group" +.Fc .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 -.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 -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 -.Fa fd +.Fa fildes is changed as specified by the arguments .Fa owner -and +and .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 -.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 -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 -.Fn Fchown +The +.Fn fchown +system call 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 -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 -.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 -.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 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 -.Fa Path +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 -.Fn Fchown -will fail if: +The +.Fn fchown +system call will fail if: .Bl -tag -width Er +.\" ========== .It Bq Er EBADF -.Fa fd +The +.Fa fildes +argument does not refer to a valid descriptor. +.\" ========== .It Bq Er EINVAL -.Fa fd +The +.Fa fildes +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 -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 EIO -An I/O error occurred while reading from or writing to the file system. .El .Sh SEE ALSO -.Xr chown 8 , .Xr chgrp 1 , .Xr chmod 2 , -.Xr flock 2 +.Xr flock 2 , +.Xr chown 8 .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 +.Fn chown +function appeared in +.At v7 . +The .Fn fchown -function call appeared in +system call appeared in .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 . +The +.Fn lchown +system call was added in +.Fx 3.0 +to compensate for the loss of functionality.