chown, fchown, lchown, chownx, fchownx, chownxat, or fchownat Subroutine

Edit online

Purpose

Changes file ownership.

Library

Standard C Library (libc.a)

Syntax

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

int chown ( Path, Owner, Group ) const char *Path; uid_t Owner; gid_t Group;

int fchown ( FileDescriptor, Owner, Group )

int FileDescriptor; uid_t Owner; gid_t Group;

int lchown ( Path, Owner, Group )

const char *fname uid_t uid gid_tgid

#include <sys/types.h>

#include <sys/chownx.h>

int chownx ( Path, Owner, Group, Flags )

char *Path; uid_t Owner; gid_t Group; int Flags;

int fchownx ( FileDescriptor, Owner, Group, Flags )

int FileDescriptor; uid_t Owner; gid_t Group; int Flags;

int chownxat ( DirFileDescriptor, Path, Owner, Group, Flags)

int DirFileDescriptor;

char * Path;

uid_t Owner;

gid_t Group;

int Flags;

int fchownat (DirFileDescriptor, Path, Owner, Group, Flag)

int DirFileDescriptor;

char*Path;

uid_t Owner;

gid_t Group;

int Flag;

Description

The chown, chownx, fchown, fchownx, chownxat, fchownat, and lchown subroutines set the file owner and group IDs of the specified file system object. Root user authority is required to change the owner of a file.

A function lchown function sets the owner ID and group ID of the named file similarity to chown function except in the case where the named file is a symbolic link. In this case lchown function changes the ownership of the symbolic link file itself, while chown function changes the ownership of the file or directory to which the symbolic link refers.

The chownxat subroutine is equivalent to the chownx subroutine and the fchownat subroutine is equivalent to the chown or the lchown subroutine if the Path parameter specifies an absolute path or if the DirFileDescriptor parameter is set to AT_FDCWD. The file to be changed is determined by the relative path to the directory that is associated with the DirFileDescriptor parameter instead of the current working directory. If the directory is opened without the O_SEARCH open flag, the subroutine checks to determine whether directory searches are permitted by using the current permissions of the directory. If the directory is opened with the O_SEARCH open flag, the subroutine does not perform the check.

Parameters

Item	Description
FileDescriptor	Specifies the file descriptor of an open file.
Flags	Specifies whether the file owner ID or group ID should be changed. This parameter is constructed by logically ORing the following values: T_OWNER_AS_IS Ignores the value specified by the Owner parameter and leaves the owner ID of the file unaltered. T_GROUP_AS_IS Ignores the value specified by the Group parameter and leaves the group ID of the file unaltered.
Flag	Specifies a bit field. If the AT_SYMLINK_NOFOLLOW bit is set and the Path specifies a symbolic link, then the owner and group of the symbolic link is changed.
Group	Specifies the new group of the file. For the chown, fchown, fchownat, and lchown commands, if this value is -1, the group is not changed. (A value of -1 indicates only that the group is not changed; it does not indicate a group that is not valid. An owner or group ID cannot be invalid.) For the chownx, chownxat, and fchownx commands, the subroutines change the Group to -1 if -1 is supplied for Group and T_GROUP_AS_IS is not set.
Owner	Specifies the new owner of the file. For the chown, fchown, fchownat, and lchown commands, if this value is -1, the group is not changed. (A value of -1 indicates only that the group is not changed; it does not indicate a group that is not valid. An owner or group ID cannot be invalid.) For the chownx, chownxat, and fchownx commands, the subroutines change the Owner to -1 if -1 is supplied for Owner and T_OWNER_AS_IS is not set.
Path	Specifies the path name of the file. For chownxat and fchownat, if the DirFileDescriptor is specified and Path is relative, then the DirFileDescriptor specifies the effective current working directory for the Path.
DirFileDescriptor	Specifies the file descriptor of an open directory, which is used as the effective current working directory for the Path parameter. If the DirFileDescriptor parameter equals AT_FDCWD, the DirFileDescriptor parameter is ignored and the Path argument specifies the complete file.

Return Values

Upon successful completion, the chown, chownx, fchown, fchownx, chownxat, fchownat, and lchown subroutines return a value of 0. If the chown, chownx, fchown, fchownx, chownxat, fchownat, or lchown subroutine is unsuccessful, a value of -1 is returned and the errno global variable is set to indicate the error.

Error Codes

The chown, fchownat, chownx, chownxat, or lchown subroutine is unsuccessful and the owner and group of a file remain unchanged if one of the following is true:

Item	Description
EACCES	Search permission is denied on a component of the Path parameter.
EDQUOT	The new group for the file system object cannot be set because the group's quota of disk blocks or i-nodes has been exhausted on the file system.
EFAULT	The Path parameter points to a location outside of the allocated address space of the process.
EINVAL	The owner or group ID supplied is not valid.
ELOOP	Too many symbolic links were encountered in translating the Path parameter.
ENAMETOOLONG	A component of the Path parameter exceeded 255 characters, or the entire Path parameter exceeded 1023 characters.
ENOENT	A symbolic link was named, but the file to which it refers does not exist; or a component of the Path parameter does not exist; or the process has the disallow truncation attribute set; or the Path parameter is null.
ENOTDIR	A component of the path prefix is not a directory.
EPERM	The effective user ID does not match the owner of the file, and the calling process does not have the appropriate privileges.
EROFS	The named file resides on a read-only file system.
ESTALE	The root or current directory of the process is located in a virtual file system that has been unmounted.

The fchown or fchownx subroutine is unsuccessful and the file owner and group remain unchanged if one of the following is true:

Item	Description
EBADF	The named file resides on a read-only file system.
EDQUOT	The new group for the file system object cannot be set because the group's quota of disk blocks or i-nodes has been exhausted on the file system.
EIO	An I/O error occurred during the operation.

The chownxat or the fchownat subroutine is unsuccessful and the file owner and group remain unchanged if one of the following is true:

Item	Description
EBADF	The Path parameter does not specify an absolute path and the DirFileDescriptor argument is neither AT_FDCWD nor a valid file descriptor.
EINVAL	The value of the Flag parameter is not valid.
ENOTDIR	The Path parameter is not an absolute path and DirFileDescriptor is a file descriptor but is not associated with a directory.

Security

Access Control: The invoker must have search permission for all components of the Path parameter.