X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/55e303ae13a4cf49d70f2294092726f2fffb9ef2..bca245acd4c03fd752d1a45f011ad495e60fe53d:/bsd/man/man2/chown.2 diff --git a/bsd/man/man2/chown.2 b/bsd/man/man2/chown.2 index 3ce057f3b..8d867fa41 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,46 @@ .\" .\" @(#)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 , +.Nm fchownat +.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 +.Fo fchown +.Fa "int fildes" +.Fa "uid_t owner" +.Fa "gid_t group" +.Fc .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 -.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 -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 +80,208 @@ but the change .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 -.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 +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 -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 +.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 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 . +The +.Fn fchownat +system call is expected to conform to POSIX.1-2008 . .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. +.Pp +The +.Fn fchownat +system call appeared in OS X 10.10