'\" et
.TH CHMOD "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\"
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.\"
.SH NAME
chmod
\(em change the file modes
.SH SYNOPSIS
.LP
.nf
chmod \fB[\fR-R\fB] \fImode file\fR...
.fi
.SH DESCRIPTION
The
.IR chmod
utility shall change any or all of the file mode bits of the file named
by each
.IR file
operand in the way specified by the
.IR mode
operand.
.P
It is implementation-defined whether and how the
.IR chmod
utility affects any alternate or additional file access control
mechanism (see the Base Definitions volume of POSIX.1\(hy2017,
.IR "Section 4.5" ", " "File Access Permissions")
being used for the specified file.
.P
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.
.P
Upon successfully changing the file mode bits of a file, the
.IR chmod
utility shall mark for update the last file status change timestamp
of the file.
.SH OPTIONS
The
.IR chmod
utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
.IR "Section 12.2" ", " "Utility Syntax Guidelines".
.P
The following option shall be supported:
.IP "\fB\-R\fP" 10
Recursively change file mode bits. For each
.IR file
operand that names a directory,
.IR chmod
shall change the file mode bits of the directory and all files in the
file hierarchy below it.
.SH OPERANDS
The following operands shall be supported:
.IP "\fImode\fR" 10
Represents the change to be made to the file mode bits of each
file named by one of the
.IR file
operands; see the EXTENDED DESCRIPTION section.
.IP "\fIfile\fR" 10
A pathname of a file whose file mode bits shall be modified.
.SH STDIN
Not used.
.SH "INPUT FILES"
None.
.SH "ENVIRONMENT VARIABLES"
The following environment variables shall affect the execution of
.IR chmod :
.IP "\fILANG\fP" 10
Provide a default value for the internationalization variables that are
unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
.IR "Section 8.2" ", " "Internationalization Variables"
for the precedence of internationalization variables used to determine
the values of locale categories.)
.IP "\fILC_ALL\fP" 10
If set to a non-empty string value, override the values of all the
other internationalization variables.
.IP "\fILC_CTYPE\fP" 10
Determine the locale for the interpretation of sequences of bytes of
text data as characters (for example, single-byte as opposed to
multi-byte characters in arguments).
.IP "\fILC_MESSAGES\fP" 10
.br
Determine the locale that should be used to affect the format and
contents of diagnostic messages written to standard error.
.IP "\fINLSPATH\fP" 10
Determine the location of message catalogs for the processing of
.IR LC_MESSAGES .
.SH "ASYNCHRONOUS EVENTS"
Default.
.SH STDOUT
Not used.
.SH STDERR
The standard error shall be used only for diagnostic messages.
.SH "OUTPUT FILES"
None.
.SH "EXTENDED DESCRIPTION"
The
.IR mode
operand shall be either a
.IR symbolic_mode
expression or a non-negative octal integer. The
.IR symbolic_mode
form is described by the grammar later in this section.
.P
Each
.BR clause
shall specify an operation to be performed on the current file mode
bits of each
.IR file .
The operations shall be performed on each
.IR file
in the order in which the
.BR clause s
are specified.
.P
The
.BR who
symbols
.BR u ,
.BR g ,
and
.BR o
shall specify the
.IR user ,
.IR group ,
and
.IR other
parts of the file mode bits, respectively. A
.BR who
consisting of the symbol
.BR a
shall be equivalent to
.BR ugo .
.P
The
.BR perm
symbols
.BR r ,
.BR w ,
and
.BR x
represent the
.IR read ,
.IR write ,
and
.IR execute /\c
.IR search
portions of file mode bits, respectively. The
.BR perm
symbol
.BR s
shall represent the
.IR "set-user-ID-on-execution"
(when
.BR who
contains or implies
.BR u )
and
.IR "set-group-ID-on-execution"
(when
.BR who
contains or implies
.BR g )
bits.
.P
The
.BR perm
symbol
.BR 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.
.P
The
.BR permcopy
symbols
.BR u ,
.BR g ,
and
.BR 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,
.BR perm
refers to the non-terminals
.BR perm
and
.BR permcopy
in the grammar.
.P
If multiple
.BR actionlist s
are grouped with a single
.BR wholist
in the grammar, each
.BR actionlist
shall be applied in the order specified with that
.BR wholist .
The
.IR op
symbols shall represent the operation performed, as follows:
.IP "\fR+\fP" 6
If
.BR perm
is not specified, the
.BR '\(pl' 
operation shall not change the file mode bits.
.RS 6 
.P
If
.BR who
is not specified, the file mode bits represented by
.BR 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.
.P
Otherwise, the file mode bits represented by the specified
.BR who
and
.BR perm
values shall be set.
.RE
.IP "\fR\-\fP" 6
If
.BR perm
is not specified, the
.BR '\-' 
operation shall not change the file mode bits.
.RS 6 
.P
If
.BR who
is not specified, the file mode bits represented by
.BR 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.
.P
Otherwise, the file mode bits represented by the specified
.BR who
and
.BR perm
values shall be cleared.
.RE
.IP "\fR=\fP" 6
Clear the file mode bits specified by the
.BR who
value, or, if no
.BR who
value is specified, all of the file mode bits specified in this volume of POSIX.1\(hy2017.
.RS 6 
.P
If
.BR perm
is not specified, the
.BR '=' 
operation shall make no further modifications to the file mode bits.
.P
If
.BR who
is not specified, the file mode bits represented by
.BR 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.
.P
Otherwise, the file mode bits represented by the specified
.BR who
and
.BR perm
values shall be set.
.RE
.P
When using the symbolic mode form on a regular file, it is
implementation-defined whether or not:
.IP " *" 4
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.
.IP " *" 4
Requests to clear all execute bits also clear the
set-user-ID-on-execution and set-group-ID-on-execution bits.
.IP " *" 4
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
.IR ls
.BR \-l
.IR file
writes an
.IR s
in the position indicating that the set-user-ID-on-execution or
set-group-ID-on-execution is set, the commands
.IR chmod
.BR u\-s
.IR file
or
.IR chmod
.BR g\-s
.IR file ,
respectively, shall not be ignored.
.P
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.
.P
If the
.BR who
symbol
.BR o
is used in conjunction with the
.BR perm
symbol
.BR s
with no other
.BR 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
.BR who
symbol
.BR o
in conjunction with the
.BR perm
symbol
.BR s .
.P
The
.BR perm
symbol
.BR t
shall specify the S_ISVTX bit. When used with a file of type
directory, it can be used with the
.BR who
symbol
.BR a ,
or with no
.BR who
symbol. It shall not be an error to specify a
.BR who
symbol of
.BR u ,
.BR g ,
or
.BR o
in conjunction with the
.BR perm
symbol
.BR t ,
but the meaning of these combinations is unspecified. The effect when
using the
.BR perm
symbol
.BR t
with any file type other than directory is unspecified.
.P
For an octal integer
.IR mode
operand, the file mode bits shall be set absolutely.
.P
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.
.TS
center tab(@) box;
cB cB | cB cB | cB cB | cB cB
nB l | nB l | nB l | nB l.
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
_
1000@S_ISVTX@0100@S_IXUSR@0010@S_IXGRP@0001@S_IXOTH
.TE
.P
When bits are set in the octal number other than those listed in the
table above, the behavior is unspecified.
.SS "Grammar for chmod"
.P
The grammar and lexical conventions in this section describe the syntax
for the
.IR symbolic_mode
operand. The general conventions for this style of grammar are
described in
.IR "Section 1.3" ", " "Grammar Conventions".
A valid
.IR symbolic_mode
can be represented as the non-terminal symbol
.IR symbolic_mode
in the grammar. This formal syntax shall take precedence over the
preceding text syntax description.
.P
The lexical processing is based entirely on single characters.
Implementations need not allow
<blank>
characters within the single argument being processed.
.sp
.RS 4
.nf

%start    symbolic_mode
%%
.P
symbolic_mode    : clause
                 | symbolic_mode \(aq,\(aq clause
                 ;
.P
clause           : actionlist
                 | wholist actionlist
                 ;
.P
wholist          : who
                 | wholist who
                 ;
.P
who              : \(aqu\(aq | \(aqg\(aq | \(aqo\(aq | \(aqa\(aq
                 ;
.P
actionlist       : action
                 | actionlist action
                 ;
.P
action           : op
                 | op permlist
                 | op permcopy
                 ;
.P
permcopy         : \(aqu\(aq | \(aqg\(aq | \(aqo\(aq
                 ;
.P
op               : \(aq+\(aq | \(aq-\(aq | \(aq=\(aq
                 ;
.P
permlist         : perm
                 | perm permlist
                 ;
.P
perm             : \(aqr\(aq | \(aqw\(aq | \(aqx\(aq | \(aqX\(aq | \(aqs\(aq | \(aqt\(aq  
                 ;
.fi
.P
.RE
.SH "EXIT STATUS"
The following exit values shall be returned:
.IP "\00" 6
The utility executed successfully and all requested changes were made.
.IP >0 6
An error occurred.
.SH "CONSEQUENCES OF ERRORS"
Default.
.LP
.IR "The following sections are informative."
.SH "APPLICATION USAGE"
Some implementations of the
.IR chmod
utility change the mode of a directory before the files in the
directory when performing a recursive (\c
.BR \-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 fails if the directory is
changed first; on the other hand, trying to re-enable permissions to a
restricted hierarchy fails if directories are changed last. Users
should not try to make a hierarchy inaccessible to themselves.
.P
Some implementations of
.IR chmod
never used the
.IR umask
of the process when changing modes; systems conformant with this volume of POSIX.1\(hy2017
do so when
.BR who
is not specified. Note the difference between:
.sp
.RS 4
.nf

chmod a-w file
.fi
.P
.RE
.P
which removes all write permissions, and:
.sp
.RS 4
.nf

chmod -- -w file
.fi
.P
.RE
.P
which removes write permissions that would be allowed if
.BR file
was created with the same
.IR umask .
.P
Conforming applications should never assume that they know how the
set-user-ID and set-group-ID bits on directories are interpreted.
.SH EXAMPLES
.ad l
.TS
center tab(@) box;
cB | cB
l | lw(3i).
Mode@Results
_
\fIa\fP+=@T{
Equivalent to
.IR a +,\c
.IR a =;
clears all file mode bits.
T}
\fIgo\fP+\-w@T{
Equivalent to
.IR go +,\c
.IR go \-\c
.IR w ;
clears group and other write bits.
T}
\fIg\fR=\fIo\fR\-\fIw\fR@T{
Equivalent to
.IR g =\c
.IR o ,\c
.IR g \-\c
.IR w ;
sets group bit to match other bits and then clears group write bit.
T}
\fIg\fR\-\fIr\fR+\fIw\fR@T{
Equivalent to
.IR g \-\c
.IR r ,\c
.IR g +\c
.IR w ;
clears group read bit and sets group write bit.
T}
\fIuo\fR=\fIg\fR@T{
Sets owner bits to match group bits and sets other bits to
match group bits.
T}
.TE
.ad b
.SH RATIONALE
The functionality of
.IR chmod
is described substantially through references to concepts defined in
the System Interfaces volume of POSIX.1\(hy2017. In this way, there is less duplication of effort required
for describing the interactions of permissions. However, the behavior
of this utility is not described in terms of the
\fIchmod\fR()
function from the System Interfaces volume of POSIX.1\(hy2017 because that specification requires certain
side-effects upon alternate file access control mechanisms that might
not be appropriate, depending on the implementation.
.P
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
.BR perm
symbol
.BR l
instead of the
.BR perm
symbols
.BR s
and
.BR 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\(hy2017 does not require mandatory locking (nor does
the System Interfaces volume of POSIX.1\(hy2017), but does allow it as an extension. However, this volume of POSIX.1\(hy2017 does
require that the
.IR ls
and
.IR chmod
utilities work consistently in this area. If
.IR ls
.BR \-l
.IR file
indicates that the set-group-ID bit is set,
.IR chmod
.BR g\-s
.IR file
must clear it (assuming appropriate privileges exist to change modes).
.P
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.
.P
The System Interfaces volume of POSIX.1\(hy2017 indicates that implementation-defined restrictions may cause
the S_ISUID and S_ISGID bits to be ignored. This volume of POSIX.1\(hy2017 allows the
.IR chmod
utility to choose to modify these bits before calling
\fIchmod\fR()
(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.
.P
The
.BR X
.BR perm
symbol was adopted from BSD-based systems because it provides commonly
desired functionality when doing recursive (\c
.BR \-R
option) modifications. Similar functionality is not provided by the
.IR find
utility. Historical BSD versions of
.IR chmod ,
however, only supported
.BR X
with
.IR op +;
it has been extended in this volume of POSIX.1\(hy2017 because it is also useful with
.IR op =.
(It has also been added for
.IR op \-
even though it duplicates
.BR x ,
in this case, because it is intuitive and easier to explain.)
.P
The grammar was extended with the
.IR permcopy
non-terminal to allow historical-practice forms of symbolic modes like
.BR o =\c
.BR u
.BR \-g
(that is, set the ``other'' permissions to the permissions of ``owner''
minus the permissions of ``group'').
.SH "FUTURE DIRECTIONS"
None.
.SH "SEE ALSO"
.IR "\fIls\fR\^",
.IR "\fIumask\fR\^"
.P
The Base Definitions volume of POSIX.1\(hy2017,
.IR "Section 4.5" ", " "File Access Permissions",
.IR "Chapter 8" ", " "Environment Variables",
.IR "Section 12.2" ", " "Utility Syntax Guidelines"
.P
The System Interfaces volume of POSIX.1\(hy2017,
.IR "\fIchmod\fR\^(\|)"
.\"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1-2017, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, 2018 Edition,
Copyright (C) 2018 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group.
In the event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .
.PP
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 .