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
13 chmod — change the file modes
14
16 chmod [−R] mode file...
17
19 The chmod utility shall change any or all of the file mode bits of the
20 file named by each file operand in the way specified by the mode oper‐
21 and.
22 It is implementation-defined whether and how the chmod utility affects
24 any alternate or additional file access control mechanism (see the Base
25 Definitions volume of POSIX.1‐2008, Section 4.4, File Access Permis‐
26 sions) being used for the specified file.
27 Only a process whose effective user ID matches the user ID of the file,
29 or a process with appropriate privileges, shall be permitted to change
30 the file mode bits of a file.
31 Upon successfully changing the file mode bits of a file, the chmod
33 utility shall mark for update the last file status change timestamp of
34 the file.
35
37 The chmod utility shall conform to the Base Definitions volume of
38 POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
39 The following option shall be supported:
41 −R Recursively change file mode bits. For each file operand that
43 names a directory, chmod shall change the file mode bits of
44 the directory and all files in the file hierarchy below it.
45
47 The following operands shall be supported:
48 mode Represents the change to be made to the file mode bits of
50 each file named by one of the file operands; see the EXTENDED
51 DESCRIPTION section.
52 file A pathname of a file whose file mode bits shall be modified.
54
56 Not used.
57
59 None.
60
62 The following environment variables shall affect the execution of
63 chmod:
64 LANG Provide a default value for the internationalization vari‐
66 ables that are unset or null. (See the Base Definitions vol‐
67 ume of POSIX.1‐2008, Section 8.2, Internationalization Vari‐
68 ables for the precedence of internationalization variables
69 used to determine the values of locale categories.)
70 LC_ALL If set to a non-empty string value, override the values of
72 all the other internationalization variables.
73 LC_CTYPE Determine the locale for the interpretation of sequences of
75 bytes of text data as characters (for example, single-byte as
76 opposed to multi-byte characters in arguments).
77 LC_MESSAGES
79 Determine the locale that should be used to affect the format
80 and contents of diagnostic messages written to standard
81 error.
82 NLSPATH Determine the location of message catalogs for the processing
84 of LC_MESSAGES.
85
87 Default.
88
90 Not used.
91
93 The standard error shall be used only for diagnostic messages.
94
96 None.
97
99 The mode operand shall be either a symbolic_mode expression or a non-
100 negative octal integer. The symbolic_mode form is described by the
101 grammar later in this section.
102 Each clause shall specify an operation to be performed on the current
104 file mode bits of each file. The operations shall be performed on each
105 file in the order in which the clauses are specified.
106 The who symbols u, g, and o shall specify the user, group, and other
108 parts of the file mode bits, respectively. A who consisting of the sym‐
109 bol a shall be equivalent to ugo.
110 The perm symbols r, w, and x represent the read, write, and exe‐
112 cute/search portions of file mode bits, respectively. The perm symbol s
113 shall represent the set-user-ID-on-execution (when who contains or
114 implies u) and set-group-ID-on-execution (when who contains or implies
115 g) bits.
116 The perm symbol X shall represent the execute/search portion of the
118 file mode bits if the file is a directory or if the current (unmodi‐
119 fied) file mode bits have at least one of the execute bits (S_IXUSR,
120 S_IXGRP, or S_IXOTH) set. It shall be ignored if the file is not a
121 directory and none of the execute bits are set in the current file mode
122 bits.
123 The permcopy symbols u, g, and o shall represent the current permis‐
125 sions associated with the user, group, and other parts of the file mode
126 bits, respectively. For the remainder of this section, perm refers to
127 the non-terminals perm and permcopy in the grammar.
128 If multiple actionlists are grouped with a single wholist in the gram‐
130 mar, each actionlist shall be applied in the order specified with that
131 wholist. The op symbols shall represent the operation performed, as
132 follows:
133 + If perm is not specified, the '+' operation shall not change the
135 file mode bits.
136 If who is not specified, the file mode bits represented by perm
138 for the owner, group, and other permissions, except for those
139 with corresponding bits in the file mode creation mask of the
140 invoking process, shall be set.
141 Otherwise, the file mode bits represented by the specified who
143 and perm values shall be set.
144 − If perm is not specified, the '−' operation shall not change the
146 file mode bits.
147 If who is not specified, the file mode bits represented by perm
149 for the owner, group, and other permissions, except for those
150 with corresponding bits in the file mode creation mask of the
151 invoking process, shall be cleared.
152 Otherwise, the file mode bits represented by the specified who
154 and perm values shall be cleared.
155 = Clear the file mode bits specified by the who value, or, if no
157 who value is specified, all of the file mode bits specified in
158 this volume of POSIX.1‐2008.
159 If perm is not specified, the '=' operation shall make no further
161 modifications to the file mode bits.
162 If who is not specified, the file mode bits represented by perm
164 for the owner, group, and other permissions, except for those
165 with corresponding bits in the file mode creation mask of the
166 invoking process, shall be set.
167 Otherwise, the file mode bits represented by the specified who
169 and perm values shall be set.
170 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-
175 execution bit when all execute bits are currently clear and none
176 are 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
184 position indicating that the set-user-ID-on-execution or set-group-
185 ID-on-execution is set, the commands chmod u−s file or chmod g−s
186 file, 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 ┌─────────────────┬──────────────────┬──────────────────┬──────────────────┐
219 │Octal Mode Bit │ Octal Mode Bit │ Octal Mode Bit │ Octal Mode Bit │
220 ├─────────────────┼──────────────────┼──────────────────┼──────────────────┤
221 │4000 S_ISUID │ 0400 S_IRUSR │ 0040 S_IRGRP │ 0004 S_IROTH │
222 ├─────────────────┼──────────────────┼──────────────────┼──────────────────┤
223 │2000 S_ISGID │ 0200 S_IWUSR │ 0020 S_IWGRP │ 0002 S_IWOTH │
224 ├─────────────────┼──────────────────┼──────────────────┼──────────────────┤
225 │1000 S_ISVTX │ 0100 S_IXUSR │ 0010 S_IXGRP │ 0001 S_IXOTH │
226 └─────────────────┴──────────────────┴──────────────────┴──────────────────┘
227 When bits are set in the octal number other than those listed in the
228 table above, the behavior is unspecified.
229 Grammar for chmod
231 The grammar and lexical conventions in this section describe the syntax
232 for the symbolic_mode operand. The general conventions for this style
233 of grammar are described in Section 1.3, Grammar Conventions. A valid
234 symbolic_mode can be represented as the non-terminal symbol sym‐
235 bolic_mode in the grammar. This formal syntax shall take precedence
236 over the preceding text syntax description.
237 The lexical processing is based entirely on single characters. Imple‐
239 mentations need not allow <blank> characters within the single argument
240 being processed.
241 %start symbolic_mode
243 %%
244 symbolic_mode : clause
246 | symbolic_mode ',' clause
247 ;
248 clause : actionlist
250 | wholist actionlist
251 ;
252 wholist : who
254 | wholist who
255 ;
256 who : 'u' | 'g' | 'o' | 'a'
258 ;
259 actionlist : action
261 | actionlist action
262 ;
263 action : op
265 | op permlist
266 | op permcopy
267 ;
268 permcopy : 'u' | 'g' | 'o'
270 ;
271 op : '+' | '−' | '='
273 ;
274 permlist : perm
276 | perm permlist
277 ;
278 perm : 'r' | 'w' | 'x' | 'X' | 's' | 't'
280 ;
281
283 The following exit values shall be returned:
284 0 The utility executed successfully and all requested changes were
286 made.
287 >0 An error occurred.
289
291 Default.
292 The following sections are informative.
294
296 Some implementations of the chmod utility change the mode of a direc‐
297 tory before the files in the directory when performing a recursive (−R
298 option) change; others change the directory mode after the files in the
299 directory. If an application tries to remove read or search permission
300 for a file hierarchy, the removal attempt fails if the directory is
301 changed first; on the other hand, trying to re-enable permissions to a
302 restricted hierarchy fails if directories are changed last. Users
303 should not try to make a hierarchy inaccessible to themselves.
304 Some implementations of chmod never used the umask of the process when
306 changing modes; systems conformant with this volume of POSIX.1‐2008 do
307 so when who is not specified. Note the difference between:
308 chmod a−w file
310 which removes all write permissions, and:
312 chmod −− −w file
314 which removes write permissions that would be allowed if file was cre‐
316 ated with the same umask.
317 Conforming applications should never assume that they know how the set-
319 user-ID and set-group-ID bits on directories are interpreted.
320
322 ┌──────┬────────────────────────────────┐
323 │Mode │ Results │
324 ├──────┼────────────────────────────────┤
325 │a+= │ Equivalent to a+,a=; clears │
326 │ │ all file mode bits. │
327 │go+−w │ Equivalent to go+,go−w; clears │
328 │ │ group and other write bits. │
329 │g=o−w │ Equivalent to g=o,g−w; sets │
330 │ │ group bit to match other bits │
331 │ │ and then clears group write │
332 │ │ bit. │
333 │g−r+w │ Equivalent to g−r,g+w; clears │
334 │ │ group read bit and sets group │
335 │ │ write bit. │
336 │uo=g │ Sets owner bits to match group │
337 │ │ bits and sets other bits to │
338 │ │ match group bits. │
339 └──────┴────────────────────────────────┘
341 The functionality of chmod is described substantially through refer‐
342 ences to concepts defined in the System Interfaces volume of
343 POSIX.1‐2008. In this way, there is less duplication of effort required
344 for describing the interactions of permissions. However, the behavior
345 of this utility is not described in terms of the chmod() function from
346 the System Interfaces volume of POSIX.1‐2008 because that specification
347 requires certain side-effects upon alternate file access control mecha‐
348 nisms that might not be appropriate, depending on the implementation.
349 Implementations that support mandatory file and record locking as spec‐
351 ified by the 1984 /usr/group standard historically used the combination
352 of set-group-ID bit set and group execute bit clear to indicate manda‐
353 tory locking. This condition is usually set or cleared with the sym‐
354 bolic mode perm symbol l instead of the perm symbols s and x so that
355 the mandatory locking mode is not changed without explicit indication
356 that that was what the user intended. Therefore, the details on how the
357 implementation treats these conditions must be defined in the documen‐
358 tation. This volume of POSIX.1‐2008 does not require mandatory locking
359 (nor does the System Interfaces volume of POSIX.1‐2008), but does allow
360 it as an extension. However, this volume of POSIX.1‐2008 does require
361 that the ls and chmod utilities work consistently in this area. If ls
362 −l file indicates that the set-group-ID bit is set, chmod g−s file must
363 clear it (assuming appropriate privileges exist to change modes).
364 The System V and BSD versions use different exit status codes. Some
366 implementations used the exit status as a count of the number of errors
367 that occurred; this practice is unworkable since it can overflow the
368 range of valid exit status values. This problem is avoided here by
369 specifying only 0 and >0 as exit values.
370 The System Interfaces volume of POSIX.1‐2008 indicates that implementa‐
372 tion-defined restrictions may cause the S_ISUID and S_ISGID bits to be
373 ignored. This volume of POSIX.1‐2008 allows the chmod utility to choose
374 to modify these bits before calling chmod() (or some function providing
375 equivalent capabilities) for non-regular files. Among other things,
376 this allows implementations that use the set-user-ID and set-group-ID
377 bits on directories to enable extended features to handle these exten‐
378 sions in an intelligent manner.
379 The X perm symbol was adopted from BSD-based systems because it pro‐
381 vides commonly desired functionality when doing recursive (−R option)
382 modifications. Similar functionality is not provided by the find util‐
383 ity. Historical BSD versions of chmod, however, only supported X with
384 op+; it has been extended in this volume of POSIX.1‐2008 because it is
385 also useful with op=. (It has also been added for op− even though it
386 duplicates x, in this case, because it is intuitive and easier to
387 explain.)
388 The grammar was extended with the permcopy non-terminal to allow his‐
390 torical-practice forms of symbolic modes like o=u −g (that is, set the
391 ``other'' permissions to the permissions of ``owner'' minus the permis‐
392 sions of ``group'').
393
395 None.
396
398 ls, umask
399 The Base Definitions volume of POSIX.1‐2008, Section 4.4, File Access
401 Permissions, Chapter 8, Environment Variables, Section 12.2, Utility
402 Syntax Guidelines
403 The System Interfaces volume of POSIX.1‐2008, chmod()
405
407 Portions of this text are reprinted and reproduced in electronic form
408 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
409 -- Portable Operating System Interface (POSIX), The Open Group Base
410 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
411 cal and Electronics Engineers, Inc and The Open Group. (This is
412 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
413 event of any discrepancy between this version and the original IEEE and
414 The Open Group Standard, the original IEEE and The Open Group Standard
415 is the referee document. The original Standard can be obtained online
416 at http://www.unix.org/online.html .
417 Any typographical or formatting errors that appear in this page are
419 most likely to have been introduced during the conversion of the source
420 files to man page format. To report such errors, see https://www.ker‐
421 nel.org/doc/man-pages/reporting_bugs.html .
422IEEE/The Open Group 2013 CHMOD(1P)