CHOWN(1) General Commands Manual CHOWN(1)

chown — change file ownership

chown [-R] owner [:group] file ...

The chown utility shall set the user ID of the file named by each file operand to the user ID specified by the owner operand. For each file operand, it shall perform actions equivalent to the POSIX. 1 {8} chown function, called with the following arguments:

  1. The file operand shall be used as the path argument.
  2. The user ID indicated by the owner portion of the first operand shall be used as the owner argument.
  3. If the group portion of the first operand is given, the group ID indicated by it shall be used as the group argument; otherwise, the group ID of the file shall be used as the group argument.

The chown utility shall conform to the utility argument syntax guidelines described in 2.10.2. The following option shall be supported by the implementation:

Recursively change file user IDs, and if the group operand is specified, group IDs. For each file operand that names a directory, chown changes the user and group ID of the directory and all files in the file hierarchy below it.

The following operands shall be supported by the implementation: owner[:group] A user ID and optional group ID to be assigned to file. The owner portion of this operand shall be a user name from the user database or a numeric user ID. Either specifies a user ID to be given to each file named by one of the file operands. If a numeric owner operand exists in the user database as a user name, the user ID number associated with that user name is used as the user ID. Similarly, if the group portion of this operand is present, it shall be a group name from the group database or a numeric group ID. Either specifies a group ID to be given to each file. If a numeric

group operand exists in the group database as a group name, the group ID number associated with that group name shall be used as the group ID.

file

A pathname of a file whose user ID is to be modified.

None.

None.

The following environment variables shall affect the execution of chown:

This variable shall determine the locale to use for the locale categories when both LC_ALL and the corresponding environment variable (beginning with LC_ ) do not specify a locale. See 2.6.

This variable shall determine the locale to be used to override any values for locale categories specified by the settings of LANG or any environment variables beginning with LC_.

This variable shall determine the locale for the interpretation of sequences of bytes of text data as characters (e.g., single- versus multibyte characters in arguments).

This variable shall determine the language in which messages should be written.

Default.

None.

Used only for diagnostic messages.

None.

None.

The chown utility shall exit with one of the following values:

The utility executed successfully and all requested changes were made.

An error occurred.

If, when invoked with the −R option, chown attempts but fails to change the user ID and/or, if the group operand is specified, group ID, of a particular file in a specified file hierarchy, it shall continue to process the remaining files in the hierarchy. If chown cannot read or search a directory within a hierarchy, it shall continue to process the other parts of the hierarchy that are accessible.

The System V and BSD versions use different exit status codes. Some implementations used the exit status as a count of the number of errors that occurred; this practice is unworkable since it can overflow the range of valid exit status values. These are masked by specifying only 0 and >0 as exit values. The functionality of chown is described substantially through references to functions in POSIX. 1 {8}. In this way, there is no duplication of effort required for describing the interactions of permissions, multiple groups, etc. For implementations on which symbolic links are supported, actual use of the chown function to implement this utility might not be the appropriate, depending on the implementation.

The bc(1) BSD method of specifying both owner and group was included in this standard because:

  1. There are cases where the desired end condition could not be achieved using the chgrp and chown (that only changed the user ID) utilities. [If the current owner is not a member of the desired group and the desired owner is not a member of the current group, the chown function could fail unless both owner and group are changed at the same time.]
  2. Even if they could be changed independently, in cases where both are being changed, there is a 100 percent performance penalty caused by being forced to invoke both utilities.

The BSD syntax user[.group] was changed to user[:group] in POSIX. 2 because the period is a valid character in login names (as specified by POSIX. 1 {8}, login names consist of characters in the portable filename character set). The colon character was chosen as the replacement for the period character because it would never be allowed as a character in a user name or group name on traditional implementations. The −R option is considered by some observers as an undesirable departure from the traditional system tools approach; since a tool, find, already exists to recurse over directories, there was felt to be no good reason to require other tools to have to duplicate that functionality. However, the −R option was deemed an important user convenience, is far more efficient than forking a separate process for each element of the directory hierarchy, and is in widespread historical use.

September 1991 posix.fail