NAME

chown - change owner and group of a file

 SYNOPSIS

#include <sys/types.h>
#include <unistd.h>

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

 DESCRIPTION

The path argument points to a pathname naming a file. The user ID and group ID of the named file are set to the numeric values contained in owner and group respectively.

On XSI-conformant systems {_POSIX_CHOWN_RESTRICTED} is always defined, therefore:

• 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 path argument refers to a regular file, the set-user-ID (S_ISUID) and set-group-ID (S_ISGID) bits of the file mode are cleared upon successful return from chown(), unless the call is made by a process with appropriate privileges, in which case it is implementation-dependent whether these bits are altered. If chown() is successfully invoked on a file that is not a regular file, these bits may be cleared. These bits are defined in <sys/stat.h>.

If owner or group is specified as (uid_t)-1 or (gid_t)-1 respectively, the corresponding ID of the file is unchanged.

Upon successful completion, chown() will mark for update the st_ctime field of the file.

 RETURN VALUE

Upon successful completion, 0 is returned. Otherwise, -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.

 ERRORS

The chown() function will fail if:

[EACCES]

Search permission is denied on a component of the path prefix.

[ELOOP]

Too many symbolic links were encountered in resolving path.

[ENAMETOOLONG]

The length of the path argument exceeds {PATH_MAX} or a pathname component is longer than {NAME_MAX}.

[ENOTDIR]

A component of the path prefix is not a directory.

[ENOENT]

A component of path does not name an existing file or path is an empty string.

[EPERM]

The effective user ID does not match the owner of the file, or the calling process does not have appropriate privileges.

[EROFS]

The named file resides on a read-only file system.

The chown() function 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.

[ENAMETOOLONG]

Pathname resolution of a symbolic link produced an intermediate result whose length exceeds {PATH_MAX}.

 EXAMPLES

None.

 APPLICATION USAGE

Because {_POSIX_CHOWN_RESTRICTED} is always defined with a value other than -1 on XSI-conformant 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.

 FUTURE DIRECTIONS

None.

 SEE ALSO

chmod(), <sys/types.h>, <unistd.h>.

DERIVATION

Derived from Issue 1 of the SVID.