1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
|
chmod(P) chmod(P)
NAME
chmod - change the file modes
SYNOPSIS
chmod [-R] mode file ...
DESCRIPTION
The chmod utility shall 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-defined whether and how the chmod
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 Permis-
sions) 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 privi-
leges, shall be permitted to change the file mode bits
of a file.
OPTIONS
The chmod utility shall conform to the Base Definitions
volume of IEEE Std 1003.1-2001, Section 12.2, Utility
Syntax Guidelines.
The following option shall be supported:
-R Recursively change file mode bits. For each file
operand that names a directory, chmod shall
change the file mode bits of the directory and
all files in the file hierarchy below it.
OPERANDS
The following operands shall be supported:
mode Represents the change to be made to the file mode
bits of each file named by one of the file oper-
ands; see the EXTENDED DESCRIPTION section.
file A pathname of a file whose file mode bits shall
be modified.
STDIN
Not used.
INPUT FILES
None.
ENVIRONMENT VARIABLES
The following environment variables shall affect the
execution of chmod:
LANG Provide a default value for the internationaliza-
tion 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 cate-
gories.)
LC_ALL If set to a non-empty string value, override the
values of all the other internationalization
variables.
LC_CTYPE
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).
LC_MESSAGES
Determine the locale that should be used to
affect the format and contents of diagnostic mes-
sages written to standard error.
NLSPATH
Determine the location of message catalogs for
the processing of LC_MESSAGES .
ASYNCHRONOUS EVENTS
Default.
STDOUT
Not used.
STDERR
The standard error shall be used only for diagnostic
messages.
OUTPUT FILES
None.
EXTENDED DESCRIPTION
The mode operand shall be either a symbolic_mode expres-
sion or a non-negative octal integer. The symbolic_mode
form is described by the grammar later in this section.
Each clause shall specify an operation to be performed
on the current file mode bits of each file. The opera-
tions 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, respec-
tively. A who consisting of the symbol a shall be equiv-
alent to ugo.
The perm symbols r, w, and x represent the read, write,
and execute/ search portions of file mode bits, respec-
tively. 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-termi-
nals 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 perm is not specified, the '+' operation shall
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, shall be
set.
Otherwise, the file mode bits represented by the speci-
fied who and perm values shall be set.
- If perm is not specified, the '-' operation shall
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, shall be
cleared.
Otherwise, the file mode bits represented by the speci-
fied who and perm values shall 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 volume of
IEEE Std 1003.1-2001.
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 speci-
fied who and perm values shall be set.
When using the symbolic mode form on a regular file, it
is implementation-defined 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-exe-
cution 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 posi-
tion 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,
shall not be ignored.
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 con-
junction 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.
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
When bits are set in the octal number other than those
listed in the table above, the behavior 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 Grammar Conventions . A valid symbolic_mode
can be represented as the non-terminal symbol sym-
bolic_mode in the grammar. This formal syntax shall take
precedence over the preceding text syntax description.
The lexical processing is based entirely on single char-
acters. Implementations need not allow <blank>s 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'
;
EXIT STATUS
The following exit values shall be returned:
0 The utility executed successfully and all
requested changes were made.
>0 An error occurred.
CONSEQUENCES OF ERRORS
Default.
The following sections are informative.
APPLICATION USAGE
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 direc-
tory. 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 them-
selves.
Some implementations of chmod never used the process'
umask when changing modes; systems conformant with this
volume of IEEE Std 1003.1-2001 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 direc-
tories are interpreted.
EXAMPLES
Mode Results
a+= Equivalent to a+, a=; clears all file mode bits.
go+-w Equivalent to go+, go- w; clears group and other write bits.
g=o-w Equivalent to g= o, g- w; sets group bit to match other bits and then clears group write bit.
g-r+w Equivalent to g- r, g+ w; clears group read bit and sets group write bit.
uo=g Sets owner bits to match group bits and sets other bits to match group bits.
RATIONALE
The functionality of chmod 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 chmod() 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.
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 sym-
bols 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
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 exten-
sion. However, this volume of IEEE Std 1003.1-2001 does
require that the ls and chmod utilities work consis-
tently 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 prac-
tice 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 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 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. His-
torical BSD versions of chmod, however, only supported X
with op+; it has been extended in this volume of
IEEE Std 1003.1-2001 because it is also useful with op=.
(It has also been added for op- even though it dupli-
cates x, in this case, because it is intuitive and eas-
ier 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").
FUTURE DIRECTIONS
None.
SEE ALSO
ls , umask , the System Interfaces volume of
IEEE Std 1003.1-2001, chmod()
COPYRIGHT
Portions of this text are reprinted and reproduced in
electronic form from IEEE Std 1003.1, 2003 Edition,
Standard for Information Technology -- Portable Operat-
ing System Interface (POSIX), The Open Group Base Speci-
fications Issue 6, Copyright (C) 2001-2003 by the Insti-
tute 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.open-
group.org/unix/online.html .
POSIX 2003 chmod(P)
|
