-.\" $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.
.\"
.\"
.\" @(#)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 <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
-.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
.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
projects / apple / xnu.git / blobdiff