chown(S-osr5)

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

Syntax

cc . . . -lc

#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 other than root, the set-user-ID and set-group-ID bits of the file mode, S_ISUID and S_ISGID respectively, are cleared (see chmod(S-osr5)).

When {_POSIX_CHOWN_RESTRICTED} is not in effect, the effective user ID of the calling process must match the owner of the file or the process must have the effective user ID of root.

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 processes having the effective user ID of root.

{_POSIX_CHOWN_RESTRICTED} will be in effect if either the user does not have the chown kernel authorization (as set up by the system administrator in the Account Manager or the usermod(ADM) command) or if the kernel configurable CHOWN_RES is set.

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.

Diagnostics

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 filesystem.
[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 privileges 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.
[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.
[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.

Files

/lib/libc.a: linking library

Standards conformance

chown is conformant with:

AT&T SVID Issue 3;
X/Open Portability Guide, Issue 3, 1989 ;
IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C Language] (ISO/IEC 9945-1) ;
and NIST FIPS 151-1 .

fchown and lchown are conformant with:

AT&T SVID Issue 3;