chown(2) SYSTEM CALLS chown(2)
NAME
chown, lchown, fchown - change owner and group of a file
SYNOPSIS
#include <unistd.h>
#include <sys/stat.h>
int chown(const char *path, uidt owner, gidt group);
int lchown(const char *path, uidt owner, gidt group);
int fchown(int fildes, uidt owner, gidt group);
DESCRIPTION
The owner ID and group ID of the file specified by path or
referenced by the descriptor fildes, are set to owner and
group respectively. If owner or group is specified as -1,
the corresponding ID of the file is not changed.
The function lchown sets the owner ID and group ID of the
named file just as chown does, except in the case where the
named file is a symbolic link. In this case lchown changes
the ownership of the symbolic link file itself, while chown
changes the ownership of the file or directory to which the
symbolic link refers.
If chown, lchown, or fchown is invoked by a process other
than super-user, the set-user-ID and set-group-ID bits of
the file mode, SISUID and SISGID respectively, are cleared
[see chmod(2)].
The operating system has a configuration option,
{POSIXCHOWNRESTRICTED}, to restrict ownership changes for
the chown, lchown, and fchown system calls. When
{POSIXCHOWNRESTRICTED} is not in effect, the effective
user ID of the process must match the owner of the file or
the process must be the super-user to change the ownership
of a file. When {POSIXCHOWNRESTRICTED} is in effect, the
chown, lchown, and fchown system calls, for users other than
super-user, prevent the owner of the file from changing the
owner ID of the file and restrict the change of the group of
the file to the list of supplementary group IDs.
Upon successful completion, chown, fchown and lchown mark
for update the stctime field of the file.
chown and lchown fail and the owner and group of the named
file remain unchanged if one or more of the following are
true:
EACCES Search permission is denied on a com-
ponent of the path prefix of path.
1
chown(2) SYSTEM CALLS chown(2)
EFAULT path points outside the allocated
address space of the process.
EINTR A signal was caught during the chown or
lchown system calls.
EINVAL group or owner is out of range.
EIO An I/O error occurred while reading from
or writing to the file system.
ELOOP Too many symbolic links were encountered
in translating path.
EMULTIHOP Components of path require hopping to
multiple remote machines and file system
type does not allow it. Too many sym-
bolic links were encountered in
translating path.
ENAMETOOLONG The length of the path argument exceeds
{PATHMAX}, or the length of a path com-
ponent exceeds {NAMEMAX} while
POSIXNOTRUNC is in effect.
ENOLINK path points to a remote machine and the
link to that machine is no longer
active.
ENOTDIR A component of the path prefix of path
is not a directory.
ENOENT Either a component of the path prefix or
the file referred to by path does not
exist or is a null pathname.
EPERM The effective user ID does not match the
owner of the file or the process is not
the super-user and
{POSIXCHOWNRESTRICTED} indicates that
such privilege is required.
EROFS The named file resides on a read-only
file system.
fchown fails and the owner and group of the named file
remain unchanged if one or more of the following are true:
EBADF fildes is not an open file descriptor.
EINVAL group or owner is out of range.
2
chown(2) SYSTEM CALLS chown(2)
EPERM The effective user ID does not match the
owner of the file or the process is not
the super-user and
{POSIXCHOWNRESTRICTED} indicates that
such privilege is required.
EROFS The named file referred to by fildes
resides on a read-only file system.
EINTR A signal was caught during execution of
the system call.
EIO An I/O error occurred while reading from
or writing to the file system.
ENOLINK fildes points to a remote machine and
the link to that machine is no longer
active.
SEE ALSO
chmod(2).
chown(1), chgrp(1) in the User's Reference Manual.
DIAGNOSTICS
Upon successful completion, a value of 0 is returned. Oth-
erwise, a value of -1 is returned and errno is set to indi-
cate the error.
3