Provided by: manpages-posix-dev_2.16-1_all 
NAME
chown - change owner and group of a file
SYNOPSIS
#include <unistd.h>
int chown(const char *path, uid_t owner, gid_t group);
DESCRIPTION
The chown() function shall change the user and group ownership of a file.
The path argument points to a pathname naming a file. The user ID and group ID of the
named file shall be set to the numeric values contained in owner and group, respectively.
Only processes with an effective user ID equal to the user ID of the file or with
appropriate privileges may change the ownership of a file. If _POSIX_CHOWN_RESTRICTED is
in effect for path:
* Changing the user ID is restricted to processes with appropriate privileges.
* Changing the group ID is permitted to a process with an effective user ID equal to the
user ID of the file, but without appropriate privileges, if and only if owner is equal
to the file's user ID or ( uid_t)-1 and group is equal either to the calling process'
effective group ID or to one of its supplementary group IDs.
If the specified file is a regular file, one or more of the S_IXUSR, S_IXGRP, or S_IXOTH
bits of the file mode are set, and the process does not have appropriate privileges, the
set-user-ID (S_ISUID) and set-group-ID (S_ISGID) bits of the file mode shall be cleared
upon successful return from chown(). If the specified file is a regular file, one or more
of the S_IXUSR, S_IXGRP, or S_IXOTH bits of the file mode are set, and the process has
appropriate privileges, it is implementation-defined whether the set-user-ID and set-
group-ID bits are altered. If the chown() function is successfully invoked on a file that
is not a regular file and one or more of the S_IXUSR, S_IXGRP, or S_IXOTH bits of the file
mode are set, the set-user-ID and set-group-ID bits may be cleared.
If owner or group is specified as ( uid_t)-1 or ( gid_t)-1, respectively, the
corresponding ID of the file shall not be changed. If both owner and group are -1, the
times need not be updated.
Upon successful completion, chown() shall mark for update the st_ctime field of the file.
RETURN VALUE
Upon successful completion, 0 shall be returned; otherwise, -1 shall be returned and errno
set to indicate the error. If -1 is returned, no changes are made in the user ID and group
ID of the file.
ERRORS
The chown() function shall fail if:
EACCES Search permission is denied on a component of the path prefix.
ELOOP A loop exists in symbolic links encountered during resolution of the path argument.
ENAMETOOLONG
The length of the path argument exceeds {PATH_MAX} or a pathname component is
longer than {NAME_MAX}.
ENOTDIR
A component of the path prefix is not a directory.
ENOENT A component of path does not name an existing file or path is an empty string.
EPERM The effective user ID does not match the owner of the file, or the calling process
does not have appropriate privileges and _POSIX_CHOWN_RESTRICTED indicates that
such privilege is required.
EROFS The named file resides on a read-only file system.
The chown() function may fail if:
EIO An I/O error occurred while reading or writing to the file system.
EINTR The chown() function was interrupted by a signal which was caught.
EINVAL The owner or group ID supplied is not a value supported by the implementation.
ELOOP More than {SYMLOOP_MAX} symbolic links were encountered during resolution of the
path argument.
ENAMETOOLONG
As a result of encountering a symbolic link in resolution of the path argument, the
length of the substituted pathname string exceeded {PATH_MAX}.
The following sections are informative.
EXAMPLES
None.
APPLICATION USAGE
Although chown() can be used on some implementations by the file owner to change the owner
and group to any desired values, the only portable use of this function is to change the
group of a file to the effective GID of the calling process or to a member of its group
set.
RATIONALE
System III and System V allow a user to give away files; that is, the owner of a file may
change its user ID to anything. This is a serious problem for implementations that are
intended to meet government security regulations. Version 7 and 4.3 BSD permit only the
superuser to change the user ID of a file. Some government agencies (usually not ones
concerned directly with security) find this limitation too confining. This volume of
IEEE Std 1003.1-2001 uses may to permit secure implementations while not disallowing
System V.
System III and System V allow the owner of a file to change the group ID to anything.
Version 7 permits only the superuser to change the group ID of a file. 4.3 BSD permits the
owner to change the group ID of a file to its effective group ID or to any of the groups
in the list of supplementary group IDs, but to no others.
The POSIX.1-1990 standard requires that the chown() function invoked by a non-appropriate
privileged process clear the S_ISGID and the S_ISUID bits for regular files, and permits
them to be cleared for other types of files. This is so that changes in accessibility do
not accidentally cause files to become security holes. Unfortunately, requiring these
bits to be cleared on non-executable data files also clears the mandatory file locking bit
(shared with S_ISGID), which is an extension on many implementations (it first appeared in
System V). These bits should only be required to be cleared on regular files that have one
or more of their execute bits set.
FUTURE DIRECTIONS
None.
SEE ALSO
chmod() , pathconf() , the Base Definitions volume of IEEE Std 1003.1-2001, <sys/types.h>,
<unistd.h>
COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form from IEEE Std
1003.1, 2003 Edition, Standard for Information Technology -- Portable Operating System
Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003 by
the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and The Open Group
Standard, the original IEEE and The Open Group Standard is the referee document. The
original Standard can be obtained online at http://www.opengroup.org/unix/online.html .