chown(2)

chown, lchown, fchown -- change owner and group of a file

Synopsis

   #include <unistd.h>
   #include <sys/stat.h>
   
   int chown(const char path, uid_t owner, gid_t group);
   

   int lchown(const char path, uid_t owner, gid_t group);
   

   int fchown(int fildes, uid_t owner, gid_t 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 without the P_OWNER privilege, the set-user-ID and set-group-ID bits of the file mode, S_ISUID and S_ISGID respectively, are cleared (see chmod(2)).

The operating system has a configuration option, _POSIX_CHOWN_RESTRICTED (see getconf(1)), that restricts ownership changes for the chown, lchown, and fchown system calls.

When _POSIX_CHOWN_RESTRICTED is not in effect (the default), the effective user ID of the calling process must match the owner of the file or the process must have the P_OWNER privilege to change the ownership of a file.

When _POSIX_CHOWN_RESTRICTED is in effect, the chown, lchown, and fchown system calls 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. This restriction does not apply to calling processes with the P_OWNER privilege. (_POSIX_CHOWN_RESTRICTED is set or unset via the RSTCHOWN system tunable. See ``Filesystem parameters'' in Monitoring and tuning the system.)

Return values

On success, chown, fchown and lchown return 0 and mark for update the st_ctime field of the file. On failure, chown, fchown and lchown return -1, set errno to identify the error, and the owner and group of the file are unchanged.

In the following conditions, chown and lchown fail and set errno to:

EACCES: Search permission is denied on a component of the path prefix of path.
EACCES: Write permission on the named file is denied.
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 symbolic links were encountered in translating path.
ENAMETOOLONG: The length of the path argument exceeds {PATH_MAX}, or the length of a path component exceeds {NAME_MAX} while _POSIX_NO_TRUNC 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 of the calling process does not match the owner of the file and the calling process does not have the appropriate privilege (P_OWNER) for changing file ownership.
EROFS: The named file resides on a read-only file system.

In the following conditions, fchown fails and sets errno to:

EBADF: fildes is not an open file descriptor.
EINVAL: group or owner is out of range.
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.
EPERM: The effective user ID of the calling process does not match the owner of the file and the calling process does not have the appropriate privilege (P_OWNER) for changing file ownership.
EROFS: The named file referred to by fildes resides on a read-only file system.

References

chgrp(1), chmod(2), chown(1)