Check for setenv/putenv's success
[dragonfly.git] / bin / chmod / chmod.1
1 .\" Copyright (c) 1989, 1990, 1993, 1994
2 .\"     The Regents of the University of California.  All rights reserved.
3 .\"
4 .\" This code is derived from software contributed to Berkeley by
5 .\" the Institute of Electrical and Electronics Engineers, Inc.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\"    notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\"    notice, this list of conditions and the following disclaimer in the
14 .\"    documentation and/or other materials provided with the distribution.
15 .\" 3. All advertising materials mentioning features or use of this software
16 .\"    must display the following acknowledgement:
17 .\"     This product includes software developed by the University of
18 .\"     California, Berkeley and its contributors.
19 .\" 4. Neither the name of the University nor the names of its contributors
20 .\"    may be used to endorse or promote products derived from this software
21 .\"    without specific prior written permission.
22 .\"
23 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 .\" SUCH DAMAGE.
34 .\"
35 .\"     @(#)chmod.1     8.4 (Berkeley) 3/31/94
36 .\" $FreeBSD: src/bin/chmod/chmod.1,v 1.17.2.16 2003/02/24 03:01:00 trhodes Exp $
37 .\" $DragonFly: src/bin/chmod/chmod.1,v 1.2 2003/06/17 04:22:49 dillon Exp $
38 .\"
39 .Dd March 31, 1994
40 .Dt CHMOD 1
41 .Os
42 .Sh NAME
43 .Nm chmod
44 .Nd change file modes
45 .Sh SYNOPSIS
46 .Nm
47 .Op Fl fhv
48 .Op Fl R Op Fl H | L | P
49 .Ar mode
50 .Ar
51 .Sh DESCRIPTION
52 The
53 .Nm
54 utility modifies the file mode bits of the listed files
55 as specified by the
56 .Ar mode
57 operand.
58 .Pp
59 The options are as follows:
60 .Bl -tag -width indent
61 .It Fl f
62 Do not display a diagnostic message if
63 .Nm
64 could not modify the mode for
65 .Va file ,
66 nor modify the exit status to reflect such failures.
67 .It Fl H
68 If the
69 .Fl R
70 option is specified, symbolic links on the command line are followed.
71 (Symbolic links encountered in the tree traversal are not followed by
72 default.)
73 .It Fl h
74 If the file is a symbolic link, change the mode of the link itself
75 rather than the file that the link points to.
76 .It Fl L
77 If the
78 .Fl R
79 option is specified, all symbolic links are followed.
80 .It Fl P
81 If the
82 .Fl R
83 option is specified, no symbolic links are followed.
84 This is the default.
85 .It Fl R
86 Change the modes of the file hierarchies rooted in the files
87 instead of just the files themselves.
88 .It Fl v
89 Cause
90 .Nm
91 to be verbose, showing filenames as the mode is modified.
92 .El
93 .Pp
94 The
95 .Fl H ,
96 .Fl L
97 and
98 .Fl P
99 options are ignored unless the
100 .Fl R
101 option is specified.
102 In addition, these options override each other and the
103 command's actions are determined by the last one specified.
104 .Pp
105 Only the owner of a file or the super-user is permitted to change
106 the mode of a file.
107 .Sh DIAGNOSTICS
108 .Ex -std
109 .Sh MODES
110 Modes may be absolute or symbolic.
111 An absolute mode is an octal number constructed from the sum of
112 one or more of the following values:
113 .Pp
114 .Bl -tag -width 6n -compact -offset indent
115 .It Li 4000
116 (the setuid bit).
117 Executable files with this bit set
118 will run with effective uid set to the uid of the file owner.
119 Directories with this bit set will force all files and
120 sub-directories created in them to be owned by the directory owner
121 and not by the uid of the creating process, if the underlying file
122 system supports this feature: see
123 .Xr chmod 2
124 and the
125 .Cm suiddir
126 option to
127 .Xr mount 8 .
128 .It Li 2000
129 (the setgid bit).
130 Executable files with this bit set
131 will run with effective gid set to the gid of the file owner.
132 .It Li 1000
133 (the sticky bit).
134 See
135 .Xr chmod 2
136 and
137 .Xr sticky 8 .
138 .It Li 0400
139 Allow read by owner.
140 .It Li 0200
141 Allow write by owner.
142 .It Li 0100
143 For files, allow execution by owner.
144 For directories, allow the owner to
145 search in the directory.
146 .It Li 0040
147 Allow read by group members.
148 .It Li 0020
149 Allow write by group members.
150 .It Li 0010
151 For files, allow execution by group members.
152 For directories, allow
153 group members to search in the directory.
154 .It Li 0004
155 Allow read by others.
156 .It Li 0002
157 Allow write by others.
158 .It Li 0001
159 For files, allow execution by others.
160 For directories allow others to
161 search in the directory.
162 .El
163 .Pp
164 For example, the absolute mode that permits read, write and execute by
165 the owner, read and execute by group members, read and execute by
166 others, and no set-uid or set-gid behaviour is 755
167 (400+200+100+040+010+004+001).
168 .Pp
169 The symbolic mode is described by the following grammar:
170 .Bd -literal -offset indent
171 mode         ::= clause [, clause ...]
172 clause       ::= [who ...] [action ...] action
173 action       ::= op [perm ...]
174 who          ::= a | u | g | o
175 op           ::= + | \- | =
176 perm         ::= r | s | t | w | x | X | u | g | o
177 .Ed
178 .Pp
179 The
180 .Ar who
181 symbols ``u'', ``g'', and ``o'' specify the user, group, and other parts
182 of the mode bits, respectively.
183 The
184 .Ar who
185 symbol ``a'' is equivalent to ``ugo''.
186 .Pp
187 The
188 .Ar perm
189 symbols represent the portions of the mode bits as follows:
190 .Pp
191 .Bl -tag -width Ds -compact -offset indent
192 .It r
193 The read bits.
194 .It s
195 The set-user-ID-on-execution and set-group-ID-on-execution bits.
196 .It t
197 The sticky bit.
198 .It w
199 The write bits.
200 .It x
201 The execute/search bits.
202 .It X
203 The execute/search bits if the file is a directory or any of the
204 execute/search bits are set in the original (unmodified) mode.
205 Operations with the
206 .Ar perm
207 symbol ``X'' are only meaningful in conjunction with the
208 .Ar op
209 symbol ``+'', and are ignored in all other cases.
210 .It u
211 The user permission bits in the original mode of the file.
212 .It g
213 The group permission bits in the original mode of the file.
214 .It o
215 The other permission bits in the original mode of the file.
216 .El
217 .Pp
218 The
219 .Ar op
220 symbols represent the operation performed, as follows:
221 .Bl -tag -width 4n
222 .It +
223 If no value is supplied for
224 .Ar perm ,
225 the ``+'' operation has no effect.
226 If no value is supplied for
227 .Ar who ,
228 each permission bit specified in
229 .Ar perm ,
230 for which the corresponding bit in the file mode creation mask
231 is clear, is set.
232 Otherwise, the mode bits represented by the specified
233 .Ar who
234 and
235 .Ar perm
236 values are set.
237 .It \&\-
238 If no value is supplied for
239 .Ar perm ,
240 the ``\-'' operation has no effect.
241 If no value is supplied for
242 .Ar who ,
243 each permission bit specified in
244 .Ar perm ,
245 for which the corresponding bit in the file mode creation mask
246 is clear, is cleared.
247 Otherwise, the mode bits represented by the specified
248 .Ar who
249 and
250 .Ar perm
251 values are cleared.
252 .It =
253 The mode bits specified by the
254 .Ar who
255 value are cleared, or, if no who value is specified, the owner, group
256 and other mode bits are cleared.
257 Then, if no value is supplied for
258 .Ar who ,
259 each permission bit specified in
260 .Ar perm ,
261 for which the corresponding bit in the file mode creation mask
262 is clear, is set.
263 Otherwise, the mode bits represented by the specified
264 .Ar who
265 and
266 .Ar perm
267 values are set.
268 .El
269 .Pp
270 Each
271 .Ar clause
272 specifies one or more operations to be performed on the mode
273 bits, and each operation is applied to the mode bits in the
274 order specified.
275 .Pp
276 Operations upon the other permissions only (specified by the symbol
277 ``o'' by itself), in combination with the
278 .Ar perm
279 symbols ``s'' or ``t'', are ignored.
280 .Sh EXAMPLES
281 .Bl -tag -width "u=rwx,go=u-w" -compact
282 .It Li 644
283 make a file readable by anyone and writable by the owner only.
284 .Pp
285 .It Li go-w
286 deny write permission to group and others.
287 .Pp
288 .It Li =rw,+X
289 set the read and write permissions to the usual defaults, but
290 retain any execute permissions that are currently set.
291 .Pp
292 .It Li +X
293 make a directory or file searchable/executable by everyone if it is
294 already searchable/executable by anyone.
295 .Pp
296 .It Li 755
297 .It Li u=rwx,go=rx
298 .It Li u=rwx,go=u-w
299 make a file readable/executable by everyone and writable by the owner only.
300 .Pp
301 .It Li go=
302 clear all mode bits for group and others.
303 .Pp
304 .It Li g=u-w
305 set the group bits equal to the user bits, but clear the group write bit.
306 .El
307 .Sh BUGS
308 There's no
309 .Ar perm
310 option for the naughty bits.
311 .Sh COMPATIBILITY
312 The
313 .Fl v
314 option is non-standard and its use in scripts is not recommended.
315 .Sh SEE ALSO
316 .Xr chflags 1 ,
317 .Xr install 1 ,
318 .Xr chmod 2 ,
319 .Xr stat 2 ,
320 .Xr umask 2 ,
321 .Xr fts 3 ,
322 .Xr setmode 3 ,
323 .Xr symlink 7 ,
324 .Xr chown 8 ,
325 .Xr mount 8 ,
326 .Xr sticky 8
327 .Sh STANDARDS
328 The
329 .Nm
330 utility is expected to be
331 .St -p1003.2
332 compatible with the exception of the
333 .Ar perm
334 symbol
335 .Dq t
336 which is not included in that standard.
337 .Sh HISTORY
338 A
339 .Nm
340 command appeared in
341 .At v1 .