chown(2) chown(2)
NAME
chown, lchown, fchown - change owner and group of a file
SYNOPSIS
#include <unistd.h>
#include <sys/types.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 (uidt)-1 or (gidt)-1 respectively,
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 sym-
bolic 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
superuser, 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 effec-
tive user ID of the process must match the owner of the file or the pro-
cess must be the superuser to change the ownership of a file. When
POSIXCHOWNRESTRICTED is in effect, the chown(), lchown(), and fchown()
system calls, for users other than superuser, 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.
ERRORS
The following error code descriptions are function-specific. You will
find a general description in introprm2(2) or in errno(5).
chown() and lchown() fail and the owner and group of the named file
remain unchanged if one or more of the following apply:
EACCES Search permission is denied on a component of the path
prefix of path.
Page 1 Reliant UNIX 5.44 Printed 11/98
chown(2) chown(2)
EFAULT path points outside the allocated address space of the
process.
EINTR A signal was caught during the chown() or lchown() sys-
tem 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.
ENAMETOOLONG The length of the path argument exceeds PATHMAX or the
length of a path component exceeds NAMEMAX.
ENAMETOOLONG Pathname resolution of a symbolic link produced an
intermediate result whose length exceeds PATHMAX.
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 direc-
tory.
ENOENT Either a component of the path prefix or the file
referred to by path does not exist or is a null path-
name.
EPERM The effective user ID does not match the owner of the
file or the calling process does not have the appropri-
ate permissions.
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 apply:
EBADF fildes is not an open file descriptor.
EINVAL group or owner is out of range.
EPERM The effective user ID does not match the owner of the
file or the process is not the superuser and
POSIXCHOWNRESTRICTED indicates that such privilege is
required.
Page 2 Reliant UNIX 5.44 Printed 11/98
chown(2) chown(2)
EROFS The named file referred to by fildes resides on a read-
only file system.
EINTR A signal was caught during the chown() or lchown() sys-
tem calls.
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.
RESULT
Upon successful completion, a value of 0 is returned. Otherwise, a
value of -1 is returned and errno is set to indicate the error. If -1
is returned, no changes are made in the user ID and group ID of the
file.
APPLICATION USAGE
Because POSIXCHOWNRESTRICTED is always defined with a value other
than -1 on XSI-compliant systems, the error EPERM is always returned
if the effective user ID does not match the owner of the file, or the
calling process does not have appropriate privileges.
On implementations which support symbolic links as directory entries
rather than files, lchown() may fail.
SEE ALSO
chgrp(1), chown(1), chmod(2), symlink(2), unistd(4), types(5).
Page 3 Reliant UNIX 5.44 Printed 11/98