chown()

NAME

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

SYNOPSIS

#include <unistd.h>


int chown (const char *path, uid_t owner, gid_t group)
int fchown (int fildes, uid_t owner, gid_t group)
int lchown (const char *path, uid_t owner, gid_t group)

DESCRIPTION

These calls change the owner identifier (ID) and group ID of a file. A process must have the appropriate permissions on a file to change ownership.

The owner ID and group ID of the file named by path or referenced by fildes is changed as specified by the arguments owner and group. The owner of a file may change the group to a group of which he or she is a member.

The chown(2) and lchown(2) utilities behave nearly identically, except if the file path is a symbolic link: in that case, chown(2) will change the ownership on the file referenced by the symbolic link, and lchown(2) will change the ownership on the symbolic link file itself.

All three calls clear the set-user-id and set-group-id bits on the file to prevent accidental or mischievous creation of set-user-id and set-group-id programs.

One of the owner or group IDs may be left unchanged by specifying it as -1.

Note that with Windows, it is not usually possible to give away ownership of a file. It is possible, however, to take ownership of a file, if the effective user ID of the process has the Windows Take Ownership permission for the file. Any user with the Windows privileges SE_BACKUP and SE_RESTORE may give away ownership of a file. (Normally this is only users with Administrator or Backup Operator privileges.)

RETURN VALUES

The chown(2), lchown(2), and fchown(2) functions return zero if the operation was successful; they return -1 if an error occurs, placing a more specific error code in the global variable errno.

ERRORS

The chown(2) and lchown(2) will fail and the file will be unchanged if:

[EACCES]: Search permission is denied for a component of the path prefix.
[EINVAL]: The pathname contains a character with the high-order bit set, or the operation is not valid on this type of file, or the owner or group ID is not valid.
[EIO]: An I/O error occurred while reading from or writing to the file system.
[ELOOP]: Too many symbolic links were encountered in translating the pathname.
[ENAMETOOLONG]: A component of a pathname exceeded {NAME_MAX} characters, or an entire pathname exceeded {PATH_MAX} characters.
[ENOENT]: The named file does not exist.
[ENOTDIR]: A component of the path prefix is not a directory.
[EPERM]: The effective user ID does not have the permissions required.
[EROFS]: The named file resides on a read-only file system.
[EFAULT]: Path points outside the process's allocated address space.

The fchown(2) function will fail and the file will be unchanged if:

[EBADF]: The fildes doesn't describe an open file.
[EINTR]: The call was interrupted by a signal.
[EINVAL]: The owner or group ID is not valid, or the operation is not valid on this type of file.
[EIO]: An I/O error occurred.
[EPERM]: The effective user ID does not have the permissions required.
[EROFS]: The file indicated by fildes resides on a read-only file system.

The lchown(2) call can also fail for these reasons:

[EINTR]: The execution of the function was interrupted by a signal.
[EIO]: An I/O error occurred.
[EOPNOTSUPP]: The path names a symbolic link and the implementation does not support setting the owner or group of a symbolic link. (This error should not occur on an system.)
[EROFS]: The file indicated by fildes resides on a read-only file system.