1CHMOD(1P) POSIX Programmer's Manual CHMOD(1P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 chmod - change the file modes
13
15 chmod [-R] mode file ...
16
18 The chmod utility shall change any or all of the file mode bits of the
19 file named by each file operand in the way specified by the mode oper‐
20 and.
21 It is implementation-defined whether and how the chmod utility affects
23 any alternate or additional file access control mechanism (see the Base
24 Definitions volume of IEEE Std 1003.1-2001, Section 4.4, File Access
25 Permissions) being used for the specified file.
26 Only a process whose effective user ID matches the user ID of the file,
28 or a process with the appropriate privileges, shall be permitted to
29 change the file mode bits of a file.
30
32 The chmod utility shall conform to the Base Definitions volume of
33 IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
34 The following option shall be supported:
36 -R Recursively change file mode bits. For each file operand that
38 names a directory, chmod shall change the file mode bits of the
39 directory and all files in the file hierarchy below it.
40
43 The following operands shall be supported:
44 mode Represents the change to be made to the file mode bits of each
46 file named by one of the file operands; see the EXTENDED
47 DESCRIPTION section.
48 file A pathname of a file whose file mode bits shall be modified.
50
53 Not used.
54
56 None.
57
59 The following environment variables shall affect the execution of
60 chmod:
61 LANG Provide a default value for the internationalization variables
63 that are unset or null. (See the Base Definitions volume of
64 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
65 ables for the precedence of internationalization variables used
66 to determine the values of locale categories.)
67 LC_ALL If set to a non-empty string value, override the values of all
69 the other internationalization variables.
70 LC_CTYPE
72 Determine the locale for the interpretation of sequences of
73 bytes of text data as characters (for example, single-byte as
74 opposed to multi-byte characters in arguments).
75 LC_MESSAGES
77 Determine the locale that should be used to affect the format
78 and contents of diagnostic messages written to standard error.
79 NLSPATH
81 Determine the location of message catalogs for the processing of
82 LC_MESSAGES .
83
86 Default.
87
89 Not used.
90
92 The standard error shall be used only for diagnostic messages.
93
95 None.
96
98 The mode operand shall be either a symbolic_mode expression or a non-
99 negative octal integer. The symbolic_mode form is described by the
100 grammar later in this section.
101 Each clause shall specify an operation to be performed on the current
103 file mode bits of each file. The operations shall be performed on each
104 file in the order in which the clauses are specified.
105 The who symbols u, g, and o shall specify the user, group, and other
107 parts of the file mode bits, respectively. A who consisting of the sym‐
108 bol a shall be equivalent to ugo.
109 The perm symbols r, w, and x represent the read, write, and execute/
111 search portions of file mode bits, respectively. The perm symbol s
112 shall represent the set-user-ID-on-execution (when who contains or
113 implies u) and set-group-ID-on-execution (when who contains or implies
114 g) bits.
115 The perm symbol X shall represent the execute/search portion of the
117 file mode bits if the file is a directory or if the current (unmodi‐
118 fied) file mode bits have at least one of the execute bits (S_IXUSR,
119 S_IXGRP, or S_IXOTH) set. It shall be ignored if the file is not a
120 directory and none of the execute bits are set in the current file mode
121 bits.
122 The permcopy symbols u, g, and o shall represent the current permis‐
124 sions associated with the user, group, and other parts of the file mode
125 bits, respectively. For the remainder of this section, perm refers to
126 the non-terminals perm and permcopy in the grammar.
127 If multiple actionlists are grouped with a single wholist in the gram‐
129 mar, each actionlist shall be applied in the order specified with that
130 wholist. The op symbols shall represent the operation performed, as
131 follows:
132 + If perm is not specified, the '+' operation shall not change the
134 file mode bits.
135 If who is not specified, the file mode bits represented by perm for the
137 owner, group, and other permissions, except for those with correspond‐
138 ing bits in the file mode creation mask of the invoking process, shall
139 be set.
140 Otherwise, the file mode bits represented by the specified who and perm
142 values shall be set.
143 - If perm is not specified, the '-' operation shall not change the
145 file mode bits.
146 If who is not specified, the file mode bits represented by perm for the
148 owner, group, and other permissions, except for those with correspond‐
149 ing bits in the file mode creation mask of the invoking process, shall
150 be cleared.
151 Otherwise, the file mode bits represented by the specified who and perm
153 values shall be cleared.
154 = Clear the file mode bits specified by the who value, or, if no
156 who value is specified, all of the file mode bits specified in
157 this volume of IEEE Std 1003.1-2001.
158 If perm is not specified, the '=' operation shall make no further modi‐
160 fications to the file mode bits.
161 If who is not specified, the file mode bits represented by perm for the
163 owner, group, and other permissions, except for those with correspond‐
164 ing bits in the file mode creation mask of the invoking process, shall
165 be set.
166 Otherwise, the file mode bits represented by the specified who and perm
168 values shall be set.
169 When using the symbolic mode form on a regular file, it is implementa‐
172 tion-defined whether or not:
173 * Requests to set the set-user-ID-on-execution or set-group-ID-on-exe‐
175 cution bit when all execute bits are currently clear and none are
176 being set are ignored.
177 * Requests to clear all execute bits also clear the set-user-ID-on-
179 execution and set-group-ID-on-execution bits.
180 * Requests to clear the set-user-ID-on-execution or set-group-ID-on-
182 execution bits when all execute bits are currently clear are
183 ignored. However, if the command ls -l file writes an s in the posi‐
184 tion indicating that the set-user-ID-on-execution or set-group-ID-
185 on-execution is set, the commands chmod u-s file or chmod g-s file,
186 respectively, shall not be ignored.
187 When using the symbolic mode form on other file types, it is implemen‐
189 tation-defined whether or not requests to set or clear the set-user-ID-
190 on-execution or set-group-ID-on-execution bits are honored.
191 If the who symbol o is used in conjunction with the perm symbol s with
193 no other who symbols being specified, the set-user-ID-on-execution and
194 set-group-ID-on-execution bits shall not be modified. It shall not be
195 an error to specify the who symbol o in conjunction with the perm sym‐
196 bol s.
197 The perm symbol t shall specify the S_ISVTX bit. When used with a file
199 of type directory, it can be used with the who symbol a, or with no who
200 symbol. It shall not be an error to specify a who symbol of u, g, or o
201 in conjunction with the perm symbol t, but the meaning of these combi‐
202 nations is unspecified. The effect when using the perm symbol t with
203 any file type other than directory is unspecified.
204 For an octal integer mode operand, the file mode bits shall be set
206 absolutely.
207 For each bit set in the octal number, the corresponding file permission
209 bit shown in the following table shall be set; all other file permis‐
210 sion bits shall be cleared. For regular files, for each bit set in the
211 octal number corresponding to the set-user-ID-on-execution or the set-
212 group-ID-on-execution, bits shown in the following table shall be set;
213 if these bits are not set in the octal number, they are cleared. For
214 other file types, it is implementation-defined whether or not requests
215 to set or clear the set-user-ID-on-execution or set-group-ID-on-execu‐
216 tion bits are honored.
217 Octal Mode Bit Octal Mode Bit Octal Mode Bit Octal Mode Bit
219 4000 S_ISUID 0400 S_IRUSR 0040 S_IRGRP 0004 S_IROTH
220 2000 S_ISGID 0200 S_IWUSR 0020 S_IWGRP 0002 S_IWOTH
221 1000 S_ISVTX 0100 S_IXUSR 0010 S_IXGRP 0001 S_IXOTH
222 When bits are set in the octal number other than those listed in the
224 table above, the behavior is unspecified.
225 Grammar for chmod
227 The grammar and lexical conventions in this section describe the syntax
228 for the symbolic_mode operand. The general conventions for this style
229 of grammar are described in Grammar Conventions . A valid symbolic_mode
230 can be represented as the non-terminal symbol symbolic_mode in the
231 grammar. This formal syntax shall take precedence over the preceding
232 text syntax description.
233 The lexical processing is based entirely on single characters. Imple‐
235 mentations need not allow <blank>s within the single argument being
236 processed.
237 %start symbolic_mode
240 %%
241 symbolic_mode : clause
244 | symbolic_mode ',' clause
245 ;
246 clause : actionlist
249 | wholist actionlist
250 ;
251 wholist : who
254 | wholist who
255 ;
256 who : 'u' | 'g' | 'o' | 'a'
259 ;
260 actionlist : action
263 | actionlist action
264 ;
265 action : op
268 | op permlist
269 | op permcopy
270 ;
271 permcopy : 'u' | 'g' | 'o'
274 ;
275 op : '+' | '-' | '='
278 ;
279 permlist : perm
282 | perm permlist
283 ;
284 perm : 'r' | 'w' | 'x' | 'X' | 's' | 't'
288 ;
289
291 The following exit values shall be returned:
292 0 The utility executed successfully and all requested changes were
294 made.
295 >0 An error occurred.
297
300 Default.
301 The following sections are informative.
303
305 Some implementations of the chmod utility change the mode of a direc‐
306 tory before the files in the directory when performing a recursive ( -R
307 option) change; others change the directory mode after the files in the
308 directory. If an application tries to remove read or search permission
309 for a file hierarchy, the removal attempt fails if the directory is
310 changed first; on the other hand, trying to re-enable permissions to a
311 restricted hierarchy fails if directories are changed last. Users
312 should not try to make a hierarchy inaccessible to themselves.
313 Some implementations of chmod never used the process' umask when chang‐
315 ing modes; systems conformant with this volume of IEEE Std 1003.1-2001
316 do so when who is not specified. Note the difference between:
317 chmod a-w file
320 which removes all write permissions, and:
322 chmod -- -w file
325 which removes write permissions that would be allowed if file was cre‐
327 ated with the same umask.
328 Conforming applications should never assume that they know how the set-
330 user-ID and set-group-ID bits on directories are interpreted.
331
333 Mode Results
334 a+= Equivalent to a+, a=; clears all file
335 mode bits.
336 go+-w Equivalent to go+, go- w; clears group
337 and other write bits.
338 g=o-w Equivalent to g= o, g- w; sets group bit
339 to match other bits and then clears
340 group write bit.
341 g-r+w Equivalent to g- r, g+ w; clears group
342 read bit and sets group write bit.
343 uo=g Sets owner bits to match group bits and
344 sets other bits to match group bits.
345
347 The functionality of chmod is described substantially through refer‐
348 ences to concepts defined in the System Interfaces volume of
349 IEEE Std 1003.1-2001. In this way, there is less duplication of effort
350 required for describing the interactions of permissions. However, the
351 behavior of this utility is not described in terms of the chmod() func‐
352 tion from the System Interfaces volume of IEEE Std 1003.1-2001 because
353 that specification requires certain side effects upon alternate file
354 access control mechanisms that might not be appropriate, depending on
355 the implementation.
356 Implementations that support mandatory file and record locking as spec‐
358 ified by the 1984 /usr/group standard historically used the combination
359 of set-group-ID bit set and group execute bit clear to indicate manda‐
360 tory locking. This condition is usually set or cleared with the sym‐
361 bolic mode perm symbol l instead of the perm symbols s and x so that
362 the mandatory locking mode is not changed without explicit indication
363 that that was what the user intended. Therefore, the details on how the
364 implementation treats these conditions must be defined in the documen‐
365 tation. This volume of IEEE Std 1003.1-2001 does not require mandatory
366 locking (nor does the System Interfaces volume of
367 IEEE Std 1003.1-2001), but does allow it as an extension. However, this
368 volume of IEEE Std 1003.1-2001 does require that the ls and chmod util‐
369 ities work consistently in this area. If ls -l file indicates that the
370 set-group-ID bit is set, chmod g-s file must clear it (assuming appro‐
371 priate privileges exist to change modes).
372 The System V and BSD versions use different exit status codes. Some
374 implementations used the exit status as a count of the number of errors
375 that occurred; this practice is unworkable since it can overflow the
376 range of valid exit status values. This problem is avoided here by
377 specifying only 0 and >0 as exit values.
378 The System Interfaces volume of IEEE Std 1003.1-2001 indicates that
380 implementation-defined restrictions may cause the S_ISUID and S_ISGID
381 bits to be ignored. This volume of IEEE Std 1003.1-2001 allows the
382 chmod utility to choose to modify these bits before calling chmod() (or
383 some function providing equivalent capabilities) for non-regular files.
384 Among other things, this allows implementations that use the set-user-
385 ID and set-group-ID bits on directories to enable extended features to
386 handle these extensions in an intelligent manner.
387 The X perm symbol was adopted from BSD-based systems because it pro‐
389 vides commonly desired functionality when doing recursive ( -R option)
390 modifications. Similar functionality is not provided by the find util‐
391 ity. Historical BSD versions of chmod, however, only supported X with
392 op+; it has been extended in this volume of IEEE Std 1003.1-2001
393 because it is also useful with op=. (It has also been added for op-
394 even though it duplicates x, in this case, because it is intuitive and
395 easier to explain.)
396 The grammar was extended with the permcopy non-terminal to allow his‐
398 torical-practice forms of symbolic modes like o= u -g (that is, set the
399 "other" permissions to the permissions of "owner" minus the permissions
400 of "group").
401
403 None.
404
406 ls, umask, the System Interfaces volume of IEEE Std 1003.1-2001,
407 chmod()
408
410 Portions of this text are reprinted and reproduced in electronic form
411 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
412 -- Portable Operating System Interface (POSIX), The Open Group Base
413 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
414 Electrical and Electronics Engineers, Inc and The Open Group. In the
415 event of any discrepancy between this version and the original IEEE and
416 The Open Group Standard, the original IEEE and The Open Group Standard
417 is the referee document. The original Standard can be obtained online
418 at http://www.opengroup.org/unix/online.html .
419IEEE/The Open Group 2003 CHMOD(1P)