chmod [-R] mode file...
It is implementation-defined whether and how the chmod utility affects any alternate or additional file access control mechanism (see the Base Definitions volume of POSIX.1-2017, Section 4.5, File Access Permissions) being used for the specified file.
Only a process whose effective user ID matches the user ID of the file, or a process with appropriate privileges, shall be permitted to change the file mode bits of a file.
Upon successfully changing the file mode bits of a file, the chmod utility shall mark for update the last file status change timestamp of the file.
The following option shall be supported:
Each clause shall specify an operation to be performed on the current file mode bits of each file. The operations shall be performed on each file in the order in which the clauses are specified.
The who symbols u, g, and o shall specify the user, group, and other parts of the file mode bits, respectively. A who consisting of the symbol a shall 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 shall 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 shall 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 shall 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 shall 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 shall be applied in the order specified with that wholist. The op symbols shall represent the operation performed, as follows:
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, shall be set.
Otherwise, the file mode bits represented by the specified who and perm values shall be set.
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, shall be cleared.
Otherwise, the file mode bits represented by the specified who and perm values shall be cleared.
If perm is not specified, the '=' operation shall 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, shall be set.
Otherwise, the file mode bits represented by the specified who and perm values shall be set.
When using the symbolic mode form on a regular file, it is implementation-defined whether or not:
When using the symbolic mode form on other file types, it is implementation-defined whether or not requests to set or clear the set-user-ID-on-execution or set-group-ID-on-execution bits are honored.
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 shall not be modified. It shall not be an error to specify the who symbol o in conjunction with the perm symbol s.
The perm symbol t shall specify the S_ISVTX bit. When used with a file of type directory, it can be used with the who symbol a, or with no who symbol. It shall not be an error to specify a who symbol of u, g, or o in conjunction with the perm symbol t, but the meaning of these combinations is unspecified. The effect when using the perm symbol t with any file type other than directory is unspecified.
For an octal integer mode operand, the file mode bits shall be set absolutely.
For each bit set in the octal number, the corresponding file permission bit shown in the following table shall be set; all other file permission bits shall 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 shall be set; if these bits are not set in the octal number, they are cleared. For other file types, it is implementation-defined whether or not requests to set or clear the set-user-ID-on-execution or set-group-ID-on-execution bits are honored.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
When bits are set in the octal number other than those listed in the table above, the behavior is unspecified.
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 Section 1.3, Grammar Conventions. A valid symbolic_mode can be represented as the non-terminal symbol symbolic_mode in the grammar. This formal syntax shall take precedence over the preceding text syntax description.
The lexical processing is based entirely on single characters. Implementations need not allow <blank> characters within the single argument being processed.
%start symbolic_mode
%%
symbolic_mode : clause
| symbolic_mode ',' clause
;
clause : 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' | 't'
;
The following sections are informative.
Some implementations of chmod never used the umask of the process when changing modes; systems conformant with this volume of POSIX.1-2017 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.
Conforming applications should never assume that they know how the set-user-ID and set-group-ID bits on directories are interpreted.
| ||||||||||||||
Implementations that support mandatory file and record locking as specified by the 1984 /usr/group standard historically used the combination of set-group-ID bit set and group execute bit clear to indicate mandatory locking. This condition is usually set or cleared with the symbolic mode perm symbol l instead of the perm symbols s and x so that the mandatory locking mode is not changed without explicit indication that that was what the user intended. Therefore, the details on how the implementation treats these conditions must be defined in the documentation. This volume of POSIX.1-2017 does not require mandatory locking (nor does the System Interfaces volume of POSIX.1-2017), but does allow it as an extension. However, this volume of POSIX.1-2017 does require that the ls and chmod utilities work consistently in this area. If ls -l file indicates that the set-group-ID bit is set, chmod g-s file must clear it (assuming appropriate privileges exist to change modes).
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. This problem is avoided here by specifying only 0 and >0 as exit values.
The System Interfaces volume of POSIX.1-2017 indicates that implementation-defined restrictions may cause the S_ISUID and S_ISGID bits to be ignored. This volume of POSIX.1-2017 allows the chmod utility to choose to modify these bits before calling chmod() (or some function providing equivalent capabilities) for non-regular files. Among other things, this allows implementations that use the set-user-ID and set-group-ID bits on directories to enable extended features to handle these extensions in an intelligent manner.
The X perm symbol was adopted from BSD-based systems because it provides commonly desired functionality when doing recursive (-R option) modifications. Similar functionality is not provided by the find utility. Historical BSD versions of chmod, however, only supported X with op+; it has been extended in this volume of POSIX.1-2017 because it is also useful with op=. (It has also been added for op- even though it duplicates x, in this case, because it is intuitive and easier to explain.)
The grammar was extended with the permcopy non-terminal to allow historical-practice forms of symbolic modes like o=u -g (that is, set the ``other'' permissions to the permissions of ``owner'' minus the permissions of ``group'').
The Base Definitions volume of POSIX.1-2017, Section 4.5, File Access Permissions, Chapter 8, Environment Variables, Section 12.2, Utility Syntax Guidelines
The System Interfaces volume of POSIX.1-2017, chmod()
Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .