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