mirror of https://github.com/mkerrisk/man-pages
494 lines
17 KiB
Groff
494 lines
17 KiB
Groff
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "CHMOD" 1P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" chmod
|
|
.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 \- 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 .
|