path: root/man1p/chmod.1p

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "CHMOD" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" chmod 
.SH NAME
chmod \- change the file modes
.SH SYNOPSIS
.LP
\fBchmod\fP \fB[\fP\fB-R\fP\fB]\fP \fImode file\fP \fB...\fP
.SH DESCRIPTION
.LP
The \fIchmod\fP utility shall change any or all of the file mode bits
of the file named by each \fIfile\fP operand in the way
specified by the \fImode\fP operand.
.LP
It is implementation-defined whether and how the \fIchmod\fP utility
affects any alternate or additional file access control
mechanism (see the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
Section 4.4, File Access Permissions) being used for the specified
file.
.LP
Only a process whose effective user ID matches the user ID of the
file, or a process with the appropriate privileges, shall be
permitted to change the file mode bits of a file.
.SH OPTIONS
.LP
The \fIchmod\fP utility shall conform to the Base Definitions volume
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
.LP
The following option shall be supported:
.TP 7
\fB-R\fP
Recursively change file mode bits. For each \fIfile\fP operand that
names a directory, \fIchmod\fP shall change the file mode
bits of the directory and all files in the file hierarchy below it.
.sp
.SH OPERANDS
.LP
The following operands shall be supported:
.TP 7
\fImode\fP
Represents the change to be made to the file mode bits of each file
named by one of the \fIfile\fP operands; see the EXTENDED
DESCRIPTION section.
.TP 7
\fIfile\fP
A pathname of a file whose file mode bits shall be modified.
.sp
.SH STDIN
.LP
Not used.
.SH INPUT FILES
.LP
None.
.SH ENVIRONMENT VARIABLES
.LP
The following environment variables shall affect the execution of
\fIchmod\fP:
.TP 7
\fILANG\fP
Provide a default value for the internationalization variables that
are unset or null. (See the Base Definitions volume of
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
for
the precedence of internationalization variables used to determine
the values of locale categories.)
.TP 7
\fILC_ALL\fP
If set to a non-empty string value, override the values of all the
other internationalization variables.
.TP 7
\fILC_CTYPE\fP
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).
.TP 7
\fILC_MESSAGES\fP
Determine the locale that should be used to affect the format and
contents of diagnostic messages written to standard
error.
.TP 7
\fINLSPATH\fP
Determine the location of message catalogs for the processing of \fILC_MESSAGES
\&.\fP 
.sp
.SH ASYNCHRONOUS EVENTS
.LP
Default.
.SH STDOUT
.LP
Not used.
.SH STDERR
.LP
The standard error shall be used only for diagnostic messages.
.SH OUTPUT FILES
.LP
None.
.SH EXTENDED DESCRIPTION
.LP
The \fImode\fP operand shall be either a \fIsymbolic_mode\fP expression
or a non-negative octal integer. The
\fIsymbolic_mode\fP form is described by the grammar later in this
section.
.LP
Each \fBclause\fP shall specify an operation to be performed on the
current file mode bits of each \fIfile\fP. The operations
shall be performed on each \fIfile\fP in the order in which the \fBclause\fPs
are specified.
.LP
The \fBwho\fP symbols \fBu\fP, \fBg\fP, and \fBo\fP shall specify
the \fIuser\fP, \fIgroup\fP, and \fIother\fP parts of
the file mode bits, respectively. A \fBwho\fP consisting of the symbol
\fBa\fP shall be equivalent to \fBugo\fP.
.LP
The \fBperm\fP symbols \fBr\fP, \fBw\fP, and \fBx\fP represent the
\fIread\fP, \fIwrite\fP, and \fIexecute\fP/
\fIsearch\fP portions of file mode bits, respectively. The \fBperm\fP
symbol \fBs\fP shall represent the
\fIset-user-ID-on-execution\fP (when \fBwho\fP contains or implies
\fBu\fP) and \fIset-group-ID-on-execution\fP (when
\fBwho\fP contains or implies \fBg\fP) bits.
.LP
The \fBperm\fP symbol \fBX\fP 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.
.LP
The \fBpermcopy\fP symbols \fBu\fP, \fBg\fP, and \fBo\fP 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, \fBperm\fP refers to the
non-terminals \fBperm\fP and \fBpermcopy\fP in the grammar.
.LP
If multiple \fBactionlist\fPs are grouped with a single \fBwholist\fP
in the grammar, each \fBactionlist\fP shall be applied
in the order specified with that \fBwholist\fP. The \fIop\fP symbols
shall represent the operation performed, as follows:
.TP 7
\fB+\fP
If \fBperm\fP is not specified, the \fB'+'\fP operation shall not
change the file mode bits. 
.LP
If \fBwho\fP is not specified, the file mode bits represented by \fBperm\fP
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.
.LP
Otherwise, the file mode bits represented by the specified \fBwho\fP
and \fBperm\fP values shall be set.
.TP 7
\fB-\fP
If \fBperm\fP is not specified, the \fB'-'\fP operation shall not
change the file mode bits. 
.LP
If \fBwho\fP is not specified, the file mode bits represented by \fBperm\fP
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.
.LP
Otherwise, the file mode bits represented by the specified \fBwho\fP
and \fBperm\fP values shall be cleared.
.TP 7
\fB=\fP
Clear the file mode bits specified by the \fBwho\fP value, or, if
no \fBwho\fP value is specified, all of the file mode bits
specified in this volume of IEEE\ Std\ 1003.1-2001. 
.LP
If \fBperm\fP is not specified, the \fB'='\fP operation shall make
no further modifications to the file mode bits.
.LP
If \fBwho\fP is not specified, the file mode bits represented by \fBperm\fP
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.
.LP
Otherwise, the file mode bits represented by the specified \fBwho\fP
and \fBperm\fP values shall be set.
.sp
.LP
When using the symbolic mode form on a regular file, it is implementation-defined
whether or not:
.IP " *" 3
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.
.LP
.IP " *" 3
Requests to clear all execute bits also clear the set-user-ID-on-execution
and set-group-ID-on-execution bits.
.LP
.IP " *" 3
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 \fIls\fP \fB-l\fP \fIfile\fP writes
an \fIs\fP in the
position indicating that the set-user-ID-on-execution or set-group-ID-on-execution
is set, the commands \fIchmod\fP \fBu-s\fP
\fIfile\fP or \fIchmod\fP \fBg-s\fP \fIfile\fP, respectively, shall
not be ignored.
.LP
.LP
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.
.LP
If the \fBwho\fP symbol \fBo\fP is used in conjunction with the \fBperm\fP
symbol \fBs\fP with no other \fBwho\fP 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 \fBwho\fP symbol \fBo\fP in conjunction with the \fBperm\fP
symbol \fBs\fP.
.LP
The \fBperm\fP symbol \fBt\fP shall specify the S_ISVTX bit. When
used with a file of type directory, it can be used with the
\fBwho\fP symbol \fBa\fP, or with no \fBwho\fP symbol. It shall not
be an error to specify a \fBwho\fP symbol of \fBu\fP,
\fBg\fP, or \fBo\fP in conjunction with the \fBperm\fP symbol \fBt\fP,
but the meaning of these combinations is unspecified.
The effect when using the \fBperm\fP symbol \fBt\fP with any file
type other than directory is unspecified. 
.LP
For an octal integer \fImode\fP operand, the file mode bits shall
be set absolutely.
.LP
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 C
center; l1 l1 l1 l1 l1 l1 l1 l.
\fBOctal\fP	\fBMode Bit\fP	\fBOctal\fP	\fBMode Bit\fP	\fBOctal\fP	\fBMode Bit\fP	\fBOctal\fP	\fBMode Bit\fP
\fB4000\fP	S_ISUID	\fB0400\fP	S_IRUSR	\fB0040\fP	S_IRGRP	\fB0004\fP	S_IROTH
\fB2000\fP	S_ISGID	\fB0200\fP	S_IWUSR	\fB0020\fP	S_IWGRP	\fB0002\fP	S_IWOTH
\fB1000\fP	S_ISVTX	\fB0100\fP	S_IXUSR	\fB0010\fP	S_IXGRP	\fB0001\fP	S_IXOTH
.TE
.LP
When bits are set in the octal number other than those listed in the
table above, the behavior is unspecified.
.SS Grammar for chmod
.LP
The grammar and lexical conventions in this section describe the syntax
for the \fIsymbolic_mode\fP operand. The general
conventions for this style of grammar are described in \fIGrammar
Conventions\fP . A valid
\fIsymbolic_mode\fP can be represented as the non-terminal symbol
\fIsymbolic_mode\fP in the grammar. This formal syntax shall
take precedence over the preceding text syntax description.
.LP
The lexical processing is based entirely on single characters. Implementations
need not allow <blank>s within the single
argument being processed.
.sp
.RS
.nf

\fB%start    symbolic_mode
%%
.sp

symbolic_mode    : clause
                 | symbolic_mode ',' clause
                 ;
.sp

clause           : actionlist
                 | wholist actionlist
                 ;
.sp

wholist          : who
                 | wholist who
                 ;
.sp

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

actionlist       : action
                 | actionlist action
                 ;
.sp

action           : op
                 | op permlist
                 | op permcopy
                 ;
.sp

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

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

permlist         : perm
                 | perm permlist
                 ;
.sp


perm             : 'r' | 'w' | 'x' | 'X' | 's' | 't'  
                 ;
\fP
.fi
.RE
.SH EXIT STATUS
.LP
The following exit values shall be returned:
.TP 7
\ 0
The utility executed successfully and all requested changes were made.
.TP 7
>0
An error occurred.
.sp
.SH CONSEQUENCES OF ERRORS
.LP
Default.
.LP
\fIThe following sections are informative.\fP
.SH APPLICATION USAGE
.LP
Some implementations of the \fIchmod\fP utility change the mode of
a directory before the files in the directory when
performing a recursive ( \fB-R\fP 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.
.LP
Some implementations of \fIchmod\fP never used the process' \fIumask\fP
when changing
modes; systems conformant with this volume of IEEE\ Std\ 1003.1-2001
do so when \fBwho\fP is not specified. Note the
difference between:
.sp
.RS
.nf

\fBchmod a-w file
\fP
.fi
.RE
.LP
which removes all write permissions, and:
.sp
.RS
.nf

\fBchmod -- -w file
\fP
.fi
.RE
.LP
which removes write permissions that would be allowed if \fBfile\fP
was created with the same \fIumask\fP.
.LP
Conforming applications should never assume that they know how the
set-user-ID and set-group-ID bits on directories are
interpreted.
.SH EXAMPLES
.TS C
center; l lw(40).
\fBMode\fP	T{
.na
\fBResults\fP
.ad
T}
\fIa\fP+=	T{
.na
Equivalent to \fIa\fP+, \fIa\fP=; clears all file mode bits.
.ad
T}
\fIgo\fP+-w	T{
.na
Equivalent to \fIgo\fP+, \fIgo\fP- \fIw\fP; clears group and other write bits.
.ad
T}
\fIg\fP=\fIo\fP-\fIw\fP	T{
.na
Equivalent to \fIg\fP= \fIo\fP, \fIg\fP- \fIw\fP; sets group bit to match other bits and then clears group write bit.
.ad
T}
\fIg\fP-\fIr\fP+\fIw\fP	T{
.na
Equivalent to \fIg\fP- \fIr\fP, \fIg\fP+ \fIw\fP; clears group read bit and sets group write bit.
.ad
T}
\fIuo\fP=\fIg\fP	T{
.na
Sets owner bits to match group bits and sets other bits to match group bits.
.ad
T}
.TE
.SH RATIONALE
.LP
The functionality of \fIchmod\fP is described substantially through
references to concepts defined in the System Interfaces
volume of IEEE\ Std\ 1003.1-2001. 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\fP() function from the System Interfaces
volume of IEEE\ Std\ 1003.1-2001 because
that specification requires certain side effects upon alternate file
access control mechanisms that might not be appropriate,
depending on the implementation.
.LP
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 \fBperm\fP symbol \fBl\fP instead of
the \fBperm\fP symbols \fBs\fP and \fBx\fP 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 IEEE\ Std\ 1003.1-2001
does not require mandatory locking (nor does the System Interfaces
volume of IEEE\ Std\ 1003.1-2001), but does allow it as
an extension. However, this volume of IEEE\ Std\ 1003.1-2001 does
require that the \fIls\fP and \fIchmod\fP utilities work consistently
in this area. If \fIls\fP \fB-l\fP \fIfile\fP indicates that the set-group-ID
bit is set, \fIchmod\fP \fBg-s\fP
\fIfile\fP must clear it (assuming appropriate privileges exist to
change modes).
.LP
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.
.LP
The System Interfaces volume of IEEE\ Std\ 1003.1-2001 indicates that
implementation-defined restrictions may cause the
S_ISUID and S_ISGID bits to be ignored. This volume of IEEE\ Std\ 1003.1-2001
allows the \fIchmod\fP utility to choose to
modify these bits before calling \fIchmod\fP() (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.
.LP
The \fBX\fP \fBperm\fP symbol was adopted from BSD-based systems because
it provides commonly desired functionality when doing
recursive ( \fB-R\fP option) modifications. Similar functionality
is not provided by the \fIfind\fP utility. Historical BSD versions
of \fIchmod\fP, however, only supported \fBX\fP with
\fIop\fP+; it has been extended in this volume of IEEE\ Std\ 1003.1-2001
because it is also useful with \fIop\fP=. (It
has also been added for \fIop\fP- even though it duplicates \fBx\fP,
in this case, because it is intuitive and easier to
explain.)
.LP
The grammar was extended with the \fIpermcopy\fP non-terminal to allow
historical-practice forms of symbolic modes like
\fBo\fP= \fBu\fP \fB-g\fP (that is, set the "other" permissions to
the permissions of "owner" minus the permissions of
"group").
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIls\fP , \fIumask\fP , the System Interfaces volume of
IEEE\ Std\ 1003.1-2001, \fIchmod\fP()
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 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 .