-WARNS6 cleanup (229 warnings)
[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.3 2006/02/17 19:33:30 swildner 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 EXAMPLES
108 .Bl -tag -width "u=rwx,go=u-w" -compact
109 .It Li 644
110 make a file readable by anyone and writable by the owner only.
111 .Pp
112 .It Li go-w
113 deny write permission to group and others.
114 .Pp
115 .It Li =rw,+X
116 set the read and write permissions to the usual defaults, but
117 retain any execute permissions that are currently set.
118 .Pp
119 .It Li +X
120 make a directory or file searchable/executable by everyone if it is
121 already searchable/executable by anyone.
122 .Pp
123 .It Li 755
124 .It Li u=rwx,go=rx
125 .It Li u=rwx,go=u-w
126 make a file readable/executable by everyone and writable by the owner only.
127 .Pp
128 .It Li go=
129 clear all mode bits for group and others.
130 .Pp
131 .It Li g=u-w
132 set the group bits equal to the user bits, but clear the group write bit.
133 .El
134 .Sh DIAGNOSTICS
135 .Ex -std
136 .Sh MODES
137 Modes may be absolute or symbolic.
138 An absolute mode is an octal number constructed from the sum of
139 one or more of the following values:
140 .Pp
141 .Bl -tag -width 6n -compact -offset indent
142 .It Li 4000
143 (the setuid bit).
144 Executable files with this bit set
145 will run with effective uid set to the uid of the file owner.
146 Directories with this bit set will force all files and
147 sub-directories created in them to be owned by the directory owner
148 and not by the uid of the creating process, if the underlying file
149 system supports this feature: see
150 .Xr chmod 2
151 and the
152 .Cm suiddir
153 option to
154 .Xr mount 8 .
155 .It Li 2000
156 (the setgid bit).
157 Executable files with this bit set
158 will run with effective gid set to the gid of the file owner.
159 .It Li 1000
160 (the sticky bit).
161 See
162 .Xr chmod 2
163 and
164 .Xr sticky 8 .
165 .It Li 0400
166 Allow read by owner.
167 .It Li 0200
168 Allow write by owner.
169 .It Li 0100
170 For files, allow execution by owner.
171 For directories, allow the owner to
172 search in the directory.
173 .It Li 0040
174 Allow read by group members.
175 .It Li 0020
176 Allow write by group members.
177 .It Li 0010
178 For files, allow execution by group members.
179 For directories, allow
180 group members to search in the directory.
181 .It Li 0004
182 Allow read by others.
183 .It Li 0002
184 Allow write by others.
185 .It Li 0001
186 For files, allow execution by others.
187 For directories allow others to
188 search in the directory.
189 .El
190 .Pp
191 For example, the absolute mode that permits read, write and execute by
192 the owner, read and execute by group members, read and execute by
193 others, and no set-uid or set-gid behaviour is 755
194 (400+200+100+040+010+004+001).
195 .Pp
196 The symbolic mode is described by the following grammar:
197 .Bd -literal -offset indent
198 mode         ::= clause [, clause ...]
199 clause       ::= [who ...] [action ...] action
200 action       ::= op [perm ...]
201 who          ::= a | u | g | o
202 op           ::= + | \- | =
203 perm         ::= r | s | t | w | x | X | u | g | o
204 .Ed
205 .Pp
206 The
207 .Ar who
208 symbols ``u'', ``g'', and ``o'' specify the user, group, and other parts
209 of the mode bits, respectively.
210 The
211 .Ar who
212 symbol ``a'' is equivalent to ``ugo''.
213 .Pp
214 The
215 .Ar perm
216 symbols represent the portions of the mode bits as follows:
217 .Pp
218 .Bl -tag -width Ds -compact -offset indent
219 .It r
220 The read bits.
221 .It s
222 The set-user-ID-on-execution and set-group-ID-on-execution bits.
223 .It t
224 The sticky bit.
225 .It w
226 The write bits.
227 .It x
228 The execute/search bits.
229 .It X
230 The execute/search bits if the file is a directory or any of the
231 execute/search bits are set in the original (unmodified) mode.
232 Operations with the
233 .Ar perm
234 symbol ``X'' are only meaningful in conjunction with the
235 .Ar op
236 symbol ``+'', and are ignored in all other cases.
237 .It u
238 The user permission bits in the original mode of the file.
239 .It g
240 The group permission bits in the original mode of the file.
241 .It o
242 The other permission bits in the original mode of the file.
243 .El
244 .Pp
245 The
246 .Ar op
247 symbols represent the operation performed, as follows:
248 .Bl -tag -width 4n
249 .It +
250 If no value is supplied for
251 .Ar perm ,
252 the ``+'' operation has no effect.
253 If no value is supplied for
254 .Ar who ,
255 each permission bit specified in
256 .Ar perm ,
257 for which the corresponding bit in the file mode creation mask
258 is clear, is set.
259 Otherwise, the mode bits represented by the specified
260 .Ar who
261 and
262 .Ar perm
263 values are set.
264 .It \&\-
265 If no value is supplied for
266 .Ar perm ,
267 the ``\-'' operation has no effect.
268 If no value is supplied for
269 .Ar who ,
270 each permission bit specified in
271 .Ar perm ,
272 for which the corresponding bit in the file mode creation mask
273 is clear, is cleared.
274 Otherwise, the mode bits represented by the specified
275 .Ar who
276 and
277 .Ar perm
278 values are cleared.
279 .It =
280 The mode bits specified by the
281 .Ar who
282 value are cleared, or, if no who value is specified, the owner, group
283 and other mode bits are cleared.
284 Then, if no value is supplied for
285 .Ar who ,
286 each permission bit specified in
287 .Ar perm ,
288 for which the corresponding bit in the file mode creation mask
289 is clear, is set.
290 Otherwise, the mode bits represented by the specified
291 .Ar who
292 and
293 .Ar perm
294 values are set.
295 .El
296 .Pp
297 Each
298 .Ar clause
299 specifies one or more operations to be performed on the mode
300 bits, and each operation is applied to the mode bits in the
301 order specified.
302 .Pp
303 Operations upon the other permissions only (specified by the symbol
304 ``o'' by itself), in combination with the
305 .Ar perm
306 symbols ``s'' or ``t'', are ignored.
307 .Sh COMPATIBILITY
308 The
309 .Fl v
310 option is non-standard and its use in scripts is not recommended.
311 .Sh SEE ALSO
312 .Xr chflags 1 ,
313 .Xr install 1 ,
314 .Xr chmod 2 ,
315 .Xr stat 2 ,
316 .Xr umask 2 ,
317 .Xr fts 3 ,
318 .Xr setmode 3 ,
319 .Xr symlink 7 ,
320 .Xr chown 8 ,
321 .Xr mount 8 ,
322 .Xr sticky 8
323 .Sh STANDARDS
324 The
325 .Nm
326 utility is expected to be
327 .St -p1003.2
328 compatible with the exception of the
329 .Ar perm
330 symbol
331 .Dq t
332 which is not included in that standard.
333 .Sh HISTORY
334 A
335 .Nm
336 command appeared in
337 .At v1 .
338 .Sh BUGS
339 There's no
340 .Ar perm
341 option for the naughty bits.