|
PROLOG | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT |
CHOWN(3P) POSIX Programmer's Manual CHOWN(3P)
This manual page is part of the POSIX Programmer's Manual. The Linux
implementation of this interface may differ (consult the
corresponding Linux manual page for details of Linux behavior), or
the interface may not be implemented on Linux.
chown, fchownat — change owner and group of a file relative to
directory file descriptor
#include <unistd.h>
int chown(const char *path, uid_t owner, gid_t group);
int fchownat(int fd, const char *path, uid_t owner, gid_t group,
int flag);
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 last
file status change timestamp of the file.
The fchownat() function shall be equivalent to the chown() and
lchown() functions except in the case where path specifies a relative
path. In this case the file to be changed is determined relative to
the directory associated with the file descriptor fd instead of the
current working directory. If the file descriptor was opened without
O_SEARCH, the function shall check whether directory searches are
permitted using the current permissions of the directory underlying
the file descriptor. If the file descriptor was opened with O_SEARCH,
the function shall not perform the check.
Values for flag are constructed by a bitwise-inclusive OR of flags
from the following list, defined in <fcntl.h>:
AT_SYMLINK_NOFOLLOW
If path names a symbolic link, ownership of the symbolic link
is changed.
If fchownat() is passed the special value AT_FDCWD in the fd
parameter, the current working directory shall be used and the
behavior shall be identical to a call to chown() or lchown()
respectively, depending on whether or not the AT_SYMLINK_NOFOLLOW bit
is set in the flag argument.
Upon successful completion, these functions shall return 0.
Otherwise, these functions shall return −1 and set errno to indicate
the error. If −1 is returned, no changes are made in the user ID and
group ID of the file.
These functions 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 a component of a pathname is longer than
{NAME_MAX}.
ENOENT A component of path does not name an existing file or path is
an empty string.
ENOTDIR
A component of the path prefix names an existing file that is
neither a directory nor a symbolic link to a directory, or the
path argument contains at least one non-<slash> character and
ends with one or more trailing <slash> characters and the last
pathname component names an existing file that is neither a
directory nor a symbolic link to a directory.
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 fchownat() function shall fail if:
EACCES fd was not opened with O_SEARCH and the permissions of the
directory underlying fd do not permit directory searches.
EBADF The path argument does not specify an absolute path and the fd
argument is neither AT_FDCWD nor a valid file descriptor open
for reading or searching.
ENOTDIR
The path argument is not an absolute path and fd is a file
descriptor associated with a non-directory file.
These functions 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
The length of a pathname exceeds {PATH_MAX}, or pathname
resolution of a symbolic link produced an intermediate result
with a length that exceeds {PATH_MAX}.
The fchownat() function may fail if:
EINVAL The value of the flag argument is not valid.
The following sections are informative.
None.
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.
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 POSIX.1‐2008 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.
The purpose of the fchownat() function is to enable changing
ownership of files in directories other than the current working
directory without exposure to race conditions. Any part of the path
of a file could be changed in parallel to a call to chown() or
lchown(), resulting in unspecified behavior. By opening a file
descriptor for the target directory and using the fchownat() function
it can be guaranteed that the changed file is located relative to the
desired directory.
None.
chmod(3p), fpathconf(3p), lchown(3p)
The Base Definitions volume of POSIX.1‐2008, fcntl.h(0p),
sys_types.h(0p), unistd.h(0p)
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2013 Edition, Standard for Information
Technology -- Portable Operating System Interface (POSIX), The Open
Group Base Specifications Issue 7, Copyright (C) 2013 by the
Institute of Electrical and Electronics Engineers, Inc and The Open
Group. (This is POSIX.1-2008 with the 2013 Technical Corrigendum 1
applied.) 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.unix.org/online.html .
Any typographical or formatting errors that appear in this page are
most likely to have been introduced during the conversion of the
source files to man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .
IEEE/The Open Group 2013 CHOWN(3P)
Pages that refer to this page: unistd.h(0p), chgrp(1p), chown(1p), pax(1p), chmod(3p), fchmod(3p), fchown(3p), fchownat(3p), fpathconf(3p), fstatvfs(3p), lchown(3p)