NAME

chmod - change the file modes

 SYNOPSIS

chmod [-R] mode file...

 DESCRIPTION

The chmod utility will change any or all of the file mode bits of the file named by each file operand in the way specified by the mode operand.

It is implementation-dependent whether and how the chmod utility affects any alternate or additional file access control mechanism (see file access permissions in the XBD specification, Glossary  ) being used for the specified file.

Only a process whose effective user ID matches the user ID of the file, or a process with the appropriate privileges, will be permitted to change the file mode bits of a file.

 OPTIONS

The chmod utility supports the XBD specification, Utility Syntax Guidelines  .

The following option is supported:

-R

Recursively change file mode bits. For each file operand that names a directory, chmod will change the file mode bits of the directory and all files in the file hierarchy below it.

 OPERANDS

The following operands are supported:

mode

Represents the change to be made to the file mode bits of each file named by one of the file operands; see the EXTENDED DESCRIPTION section.

file

A pathname of a file whose file mode bits are to be modified.

 STDIN

Not used.

 INPUT FILES

None.

 ENVIRONMENT VARIABLES

The following environment variables affect the execution of chmod:

LANG

Provide a default value for the internationalisation variables that are unset or null. If LANG is unset or null, the corresponding value from the implementation-dependent default locale will be used. If any of the internationalisation variables contains an invalid setting, the utility will behave as if none of the variables had been defined.

LC_ALL

If set to a non-empty string value, override the values of all the other internationalisation variables.

LC_CTYPE

Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- as opposed to multi-byte characters in arguments).

LC_MESSAGES

Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.

NLSPATH

Determine the location of message catalogues for the processing of LC_MESSAGES .

 ASYNCHRONOUS EVENTS

Default.

 STDOUT

Not used.

 STDERR

Used only for diagnostic messages.

 OUTPUT FILES

None.

 EXTENDED DESCRIPTION

The mode operand will be either a symbolic_mode expression or a non-negative octal integer. The symbolic_mode form is described by the grammar later in this section.

Each clause will specify an operation to be performed on the current file mode bits of each file. The operations will be performed on each file in the order in which the clauses are specified.

The who symbols u, g and o will specify the user , group and other parts of the file mode bits, respectively. A who consisting of the symbol a will be equivalent to ugo.

The perm symbols r, w and x represent the read , write and execute/search portions of file mode bits, respectively. The perm symbol s represent the set-user-ID-on-execution (when who contains or implies u) and set-group-ID-on-execution (when who contains or implies g) bits.

The perm symbol X represent the execute/search portion of the file mode bits if the file is a directory or if the current (unmodified) file mode bits have at least one of the execute bits (S_IXUSR, S_IXGRP or S_IXOTH) set. It will be ignored if the file is not a directory and none of the execute bits are set in the current file mode bits.

The permcopy symbols u, g and o represent the current permissions associated with the user, group and other parts of the file mode bits, respectively. For the remainder of this section, perm refers to the non-terminals perm and permcopy in the grammar.

If multiple actionlists are grouped with a single wholist in the grammar, each actionlist will be applied in the order specified with that wholist. The op symbols represent the operation performed, as follows:

+

If perm is not specified, the + operation will not change the file mode bits. If who is not specified, the file mode bits represented by perm for the owner, group and other permissions, except for those with corresponding bits in the file mode creation mask of the invoking process, will be set. Otherwise, the file mode bits represented by the specified who and perm values will be set.

-

If perm is not specified, the "-" operation will not change the file mode bits. If who is not specified, the file mode bits represented by perm for the owner, group and other permissions, except for those with corresponding bits in the file mode creation mask of the invoking process, will be cleared. Otherwise, the file mode bits represented by the specified who and perm values will be cleared.

=

Clear the file mode bits specified by the who value, or, if no who value is specified, all of the file mode bits specified in this specification. If perm is not specified, the = operation will make no further modifications to the file mode bits. If who is not specified, the file mode bits represented by perm for the owner, group and other permissions, except for those with corresponding bits in the file mode creation mask of the invoking process, will be set. Otherwise, the file mode bits represented by the specified who and perm values will be set.

When using the symbolic mode form on a regular file, it is implementation-dependent whether or not:

• Requests to set the set-user-ID-on-execution or set-group-ID-on-execution bit when all execute bits are currently clear and none are being set are ignored.

• Requests to clear all execute bits also clear the set-user-ID-on-execution and set-group-ID-on-execution bits.

• Requests to clear the set-user-ID-on-execution or set-group-ID-on-execution bits when all execute bits are currently clear are ignored. However, if the command ls -l file writes an s in the position indicating that the set-user-ID-on-execution or set-group-ID-on-execution is set, the commands chmod u-s file or chmod g-s file, respectively, will not be ignored.

When using the symbolic mode form on other file types, it is implementation-dependent whether or not requests to set or clear the set-user-ID-on-execution or set-group-ID-on-execution bits are honoured.

If the who symbol o is used in conjunction with the perm symbol s with no other who symbols being specified, the set-user-ID-on-execution and set-group-ID-on-execution bits will not be modified. It will not be an error to specify the who symbol o in conjunction with the perm symbol s.

For an octal integer mode operand, the file mode bits will be set absolutely.

For each bit set in the octal number, the corresponding file permission bit shown in the following table will be set; all other file permission bits will be cleared. For regular files, for each bit set in the octal number corresponding to the set-user-ID-on-execution or the set-group-ID-on-execution bits shown in the following table will be set; if these bits are not set in the octal number, they will be cleared. For other file types, it is implementation-dependent whether or not requests to set or clear the set-user-ID-on-execution or set-group-ID-on-execution bits are honoured.

Octal
Mode bit
Octal
Mode bit
Octal
Mode bit
Octal
Mode bit
4000
S_ISUID
0400
S_IRUSR
0040
S_IRGRP
0004
S_IROTH
2000
S_ISGID
0200
S_IWUSR
0020
S_IWGRP
0002
S_IWOTH
 
 
0100
S_IXUSR
0010
S_IXGRP
0001
S_IXOTH

When bits are set in the octal number other than those listed in the table above, the behaviour is unspecified.

 Grammar for chmod

The grammar and lexical conventions in this section describe the syntax for the symbolic_mode operand. The general conventions for this style of grammar are described in . A valid symbolic_mode can be represented as the non-terminal symbol symbolic_mode in the grammar. This formal syntax takes precedence over the preceding text syntax description.

The lexical processing will be based entirely on single characters. Implementations need not allow blank characters within the single argument being processed.

%start             symbolic_mode
%%

symbolic_mode    : section
                 | symbolic_mode ',' section
                 ;

section          : actionlist
                 | wholist actionlist
                 ;

wholist          : who
                 | wholist who
                 ;

who              : 'u' | 'g' | 'o' | 'a'
                 ;

actionlist       : action
                 | actionlist action
                 ;

action           : op
                 | op permlist
                 | op permcopy
                 ;

permcopy         : 'u' | 'g' | 'o'
                 ;

op               : '+' | '-' | '='
                 ;

permlist         : perm
                 | perm permlist
                 ;

perm             : 'r' | 'w' | 'x' | 'X' | 's'
                 ;

 EXIT STATUS

The following exit values are returned:

0

The utility executed successfully and all requested changes were made.

>0

An error occurred.

 CONSEQUENCES OF ERRORS

If, when invoked with the -R option, chmod attempts but fails to change the mode of a particular file in a specified file hierarchy, it will continue to process the remaining files in the hierarchy, affecting the final exit status. If chmod cannot read or search a directory within a hierarchy, it will continue to process the other parts of the hierarchy that are accessible.

 APPLICATION USAGE

The references to octal modes are supported because, although they are obsolescent in the ISO/IEC 9945-2:1993 standard, XSI-conformant systems have committed to maintaining them for portable applications until further notice.

Some implementations of the chmod utility change the mode of a directory before the files in the directory when performing a recursive (-R option) change; others change the directory mode after the files in the directory. If an application tries to remove read or search permission for a file hierarchy, the removal attempt will fail if the directory is changed first; on the other hand, trying to re-enable permissions to a restricted hierarchy will fail if directories are changed last. Users should not try to make a hierarchy inaccessible to themselves.

Some implementations of chmod never used the process' umask when changing modes; systems conformant with this specification do so when who is not specified. Note the difference between:

chmod a-w file

which removes all write permissions, and:

chmod -- -w file

which removes write permissions that would be allowed if file was created with the same umask.

Portable applications should never assume that they know how the set-user-ID and set-group-ID bits on directories will be interpreted.

 EXAMPLES

Mode
Results
a+=
 Equivalent to clears all file mode bits. 
go+-w
 Equivalent to clears group and other write bits. 
g=o-w
 Equivalent to sets group bit to match other bits and then clears group write bit. 
g-r+w
 Equivalent to clears group read bit and sets group write bit. 
=g
Sets owner bits to match group bits and sets other bits to match group bits

 FUTURE DIRECTIONS

None.

 SEE ALSO

ls, umask, the XSH specification description of chmod().