CHOWN
Section: POSIX Programmer's Manual (3P)
Updated: 2017
Page Index
PROLOG
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.
NAME
chown, fchownat
--- change owner and group of a file
SYNOPSIS
#include <unistd.h>
int chown(const char *path, uid_t owner, gid_t group);
#include <fcntl.h>
int fchownat(int fd, const char *path, uid_t owner, gid_t group,
int flag);
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.
Upon successful completion,
chown()
shall mark for update the last file status change timestamp of the
file, except that if
owner
is (uid_t)-1
and
group
is (gid_t)-1,
the file status change timestamp need not be marked for update.
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 access mode of
the open file description associated with the file descriptor is not
O_SEARCH, the function shall check whether directory searches are
permitted using the current permissions of the directory underlying
the file descriptor. If the access mode is 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.
RETURN VALUE
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.
ERRORS
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
-
The access mode of the open file description associated with
fd
is not 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.
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 POSIX.1-2017 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.
FUTURE DIRECTIONS
None.
SEE ALSO
chmod(),
fpathconf(),
lchown()
The Base Definitions volume of POSIX.1-2017,
<fcntl.h>,
<sys_types.h>,
<unistd.h>
COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1-2017, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, 2018 Edition,
Copyright (C) 2018 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 .
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 .