chown

Changes the owner and group of a file.

Syntax

   #include <sys/types.h>

   #include <unistd.h>

   int chown (const char *pathname, uid_t owner, 

    gid_t group);

Parameters

pathname: A pointer to a string containing the pathname of a file whose user ID and group ID are to be modified. The pathname must be terminated by a null character.
owner: The new owner (user ID) of the file.
group: The new group ID of the file.

Return Values

0: Success.
-1: An error occurred. The file's owner and group ID are not changed, and errnois set to indicate the error condition.

Description

The chown()function changes the user ID (UID) of the specified file to owner and the group ID (GID) of the file to group.

In order to change the UID of a file, the user associated with the calling process must be one of the following:

The file's account manager (a user whose GID matches the GID of the file and who has the MPE/iX account manager (AM) user capability). In this case, owner must specify a UID belonging to a user assigned to the account manager's own account, and group must specify the account manager's own effective GID.
A system manager (a user who has the MPE/iX system manager (SM) user capability). In this case, owner can specify any UID existing in the user database.

In order to change the GID of a file, the user associated with the calling process must be one of the following:

The file owner (a user whose effective UID matches the UID of the file). In this case, owner must specify the file's UID and group must specify the file owner's own GID.
A user with appropriate privileges, defined to be one of the following:
- The file's account manager (a user whose GID matches the GID of the file and who has the MPE/iX account manager (AM) user capability). In this case, owner must specify the UID of a user assigned to the account manager's own account, and group must specify the account manager's own effective GID.
- A system manager (a user who has the MPE/iX system manager (SM) user capability). In this case, group can specify any GID existing in the group database.

Upon successful completion, chown() marks for update the st_ctime time field of the file.

Implementation Considerations

Refer to the EIMPL and EFAULT error descriptions below.

The S_ISUID and S_ISGID bits are not supported.

The {_POSIX_CHOWN_RESTRICTED} constant is always in effect for pathname.

You cannot modify the GID of the root directory, MPE/iX accounts, or MPE/iX groups.

An object's owner, its account manager(s), and system managers have different abilities to assign UID and GID values. A system manager (user with MPE/iX SM capability) can specify any positive UID or GID value defined in the user or group databases. An account manager (user with MPE/iX AM capability) can specify the UID of any user belonging to the account manager's account, but can only specify the GID associated with the account manager's own effective GID. File owners lacking SM or AM capability cannot change a file's UID, but can change a file or directory's GID to their own effective GID.

Changing an object's file owner ID (UID) or file group ID (GID) changes access control for that file or directory. File owners of files and directories can also change the access permissions granted to the object. Changing an object's UID or GID also changes the file owner or file group referenced by $OWNER and $GROUP entries in the ACD associated with the file or directory.

An ACD is automatically assigned to a file if the file lacks an ACD and the group parameter specifies a different GID than the GID associated with the MPE/iX account in which the file resides. The new ACD grants all access to the file owner and RACD access to all others.

Errors

If an error occurs, errno is set to one of the following values:

`EACCES`	CAUSE	The calling process does not have search permission to a component of the pathname.
	ACTION	Make sure that the calling process has search permission to all component directories in the pathname.
`EFAULT`	CAUSE	The system detected a NULL or bad address in attempting to use the `pathname` parameter, or the pathname was not terminated by a null character.
	ACTION	Make sure that the pointer is correctly initialized.
`EIMPL`	CAUSE	One of the following: An attempt was made to change the UID or GID of the root directory, an MPE/iX account, an MPE/iX group, an output spool file, or a system-defined file. The pathname begins with two slash characters (//).
	ACTION	One of the following: Do not attempt to change the UID or GID of the root directory, an MPE/iX account, an MPE/iX group, an output spool file, or a system-defined file. Do not begin pathname with two slash characters (//).
`ENAMETOOLONG`	CAUSE	One of the following: The length of the pathname exceeds the `{PATH_MAX}` limit (defined in the file `<limits.h>`). A component of the pathname is longer than `{NAME_MAX}` (defined in `<limits.h>`), and `{_POSIX_NO_TRUNC}` is in effect for that directory.
	ACTION	Make sure that both the component's length and the full pathname length do not exceed the `{NAME_MAX}` or `{PATH_MAX}` limits.
`ENOENT`	CAUSE	The specified file does not exist, or `pathname` points to an empty string.
	ACTION	Specify an existing filename.
`ENOTDIR`	CAUSE	A component of the pathname is not a directory.
	ACTION	Specify a valid pathname.
`EINVAL`	CAUSE	The `owner` parameter or `group` parameter specified an invalid or unsupported value.
	ACTION	Specify a valid and supported value.
`EPERM`	CAUSE	One of the following: The calling process does not have the MPE/iX process handling (PH) capability. The calling process has outstanding switches to CM code, has set critical mode, has outstanding NOWAITIO, or is holding an operating system internal resource, or the calling process is in a Procedure Exit handler.
	ACTION	One of the following: Link the program file with the MPE/iX PH capability. Do not execute `execl()` when the calling process has outstanding switches to CM code, has set critical mode, has outstanding NOWAITIO, or is holding an operating system internal resource, or in a Procedure Exit handler.

chown

Technical documentation

» Table of Contents

» Index