Reordered the sections in the manual to put the "Common Tasks" and
[findutils.git] / doc / perm.texi
blob40e309d15c43786b29e8d96943aafc2d4278e358
1 Each file has a set of @dfn{permissions} that control the kinds of
2 access that users have to that file.  The permissions for a file are
3 also called its @dfn{access mode}.  They can be represented either in
4 symbolic form or as an octal number.
6 @menu
7 * Mode Structure::              Structure of file permissions.
8 * Symbolic Modes::              Mnemonic permissions representation.
9 * Numeric Modes::               Permissions as octal numbers.
10 @end menu
12 @node Mode Structure
13 @section Structure of File Permissions
15 There are three kinds of permissions that a user can have for a file:
17 @enumerate
18 @item
19 @cindex read permission
20 permission to read the file.  For directories, this means permission to
21 list the contents of the directory.
22 @item
23 @cindex write permission
24 permission to write to (change) the file.  For directories, this means
25 permission to create and remove files in the directory.
26 @item
27 @cindex execute permission
28 permission to execute the file (run it as a program).  For directories,
29 this means permission to access files in the directory.
30 @end enumerate
32 There are three categories of users who may have different permissions
33 to perform any of the above operations on a file:
35 @enumerate
36 @item
37 the file's owner;
38 @item
39 other users who are in the file's group;
40 @item
41 everyone else.
42 @end enumerate
44 @cindex owner, default
45 @cindex group owner, default
46 Files are given an owner and group when they are created.  Usually the
47 owner is the current user and the group is the group of the directory
48 the file is in, but this varies with the operating system, the
49 filesystem the file is created on, and the way the file is created.  You
50 can change the owner and group of a file by using the @code{chown} and
51 @code{chgrp} commands.
53 In addition to the three sets of three permissions listed above, a
54 file's permissions have three special components, which affect only
55 executable files (programs) and, on some systems, directories:
57 @enumerate
58 @item
59 @cindex setuid
60 set the process's effective user ID to that of the file upon execution
61 (called the @dfn{setuid bit}).  No effect on directories.
62 @item
63 @cindex setgid
64 set the process's effective group ID to that of the file upon execution
65 (called the @dfn{setgid bit}).  For directories on some systems, put
66 files created in the directory into the same group as the directory, no
67 matter what group the user who creates them is in.
68 @item
69 @cindex sticky
70 @cindex swap space, saving text image in
71 @cindex text image, saving in swap space
72 @cindex append-only directories
73 save the program's text image on the swap device so it will load more
74 quickly when run (called the @dfn{sticky bit}).  For directories on some
75 systems, prevent users from removing files that they do not own in the
76 directory; this is called making the directory @dfn{append-only}.
77 @end enumerate
79 @node Symbolic Modes
80 @section Symbolic Modes
82 @cindex symbolic modes
83 @dfn{Symbolic modes} represent changes to files' permissions as
84 operations on single-character symbols.  They allow you to modify either
85 all or selected parts of files' permissions, optionally based on
86 their previous values, and perhaps on the current @code{umask} as well
87 (@pxref{Umask and Protection}).
89 The format of symbolic modes is:
91 @example
92 @r{[}ugoa@dots{}@r{][[}+-=@r{][}rwxXstugo@dots{}@r{]}@dots{}@r{][},@dots{}@r{]}
93 @end example
95 The following sections describe the operators and other details of
96 symbolic modes.
98 @menu
99 * Setting Permissions::          Basic operations on permissions.
100 * Copying Permissions::          Copying existing permissions.
101 * Changing Special Permissions:: Special permissions.
102 * Conditional Executability::    Conditionally affecting executability.
103 * Multiple Changes::             Making multiple changes.
104 * Umask and Protection::              The effect of the umask.
105 @end menu
107 @node Setting Permissions
108 @subsection Setting Permissions
110 The basic symbolic operations on a file's permissions are adding,
111 removing, and setting the permission that certain users have to read,
112 write, and execute the file.  These operations have the following
113 format:
115 @example
116 @var{users} @var{operation} @var{permissions}
117 @end example
119 @noindent
120 The spaces between the three parts above are shown for readability only;
121 symbolic modes can not contain spaces.
123 The @var{users} part tells which users' access to the file is changed.
124 It consists of one or more of the following letters (or it can be empty;
125 @pxref{Umask and Protection}, for a description of what happens then).  When
126 more than one of these letters is given, the order that they are in does
127 not matter.
129 @table @code
130 @item u
131 @cindex owner of file, permissions for
132 the user who owns the file;
133 @item g
134 @cindex group, permissions for
135 other users who are in the file's group;
136 @item o
137 @cindex other permissions
138 all other users;
139 @item a
140 all users; the same as @samp{ugo}.
141 @end table
143 The @var{operation} part tells how to change the affected users' access
144 to the file, and is one of the following symbols:
146 @table @code
147 @item +
148 @cindex adding permissions
149 to add the @var{permissions} to whatever permissions the @var{users}
150 already have for the file;
151 @item -
152 @cindex removing permissions
153 @cindex subtracting permissions
154 to remove the @var{permissions} from whatever permissions the
155 @var{users} already have for the file;
156 @item =
157 @cindex setting permissions
158 to make the @var{permissions} the only permissions that the @var{users}
159 have for the file.
160 @end table
162 The @var{permissions} part tells what kind of access to the file should
163 be changed; it is zero or more of the following letters.  As with the
164 @var{users} part, the order does not matter when more than one letter is
165 given.  Omitting the @var{permissions} part is useful only with the
166 @samp{=} operation, where it gives the specified @var{users} no access
167 at all to the file.
169 @table @code
170 @item r
171 @cindex read permission, symbolic
172 the permission the @var{users} have to read the file;
173 @item w
174 @cindex write permission, symbolic
175 the permission the @var{users} have to write to the file;
176 @item x
177 @cindex execute permission, symbolic
178 the permission the @var{users} have to execute the file.
179 @end table
181 For example, to give everyone permission to read and write a file,
182 but not to execute it, use:
184 @example
185 a=rw
186 @end example
188 To remove write permission for from all users other than the file's
189 owner, use:
191 @example
192 go-w
193 @end example
195 @noindent
196 The above command does not affect the access that the owner of
197 the file has to it, nor does it affect whether other users can
198 read or execute the file.
200 To give everyone except a file's owner no permission to do anything with
201 that file, use the mode below.  Other users could still remove the file,
202 if they have write permission on the directory it is in.
204 @example
206 @end example
208 @noindent
209 Another way to specify the same thing is:
211 @example
212 og-rxw
213 @end example
215 @node Copying Permissions
216 @subsection Copying Existing Permissions
218 @cindex copying existing permissions
219 @cindex permissions, copying existing
220 You can base part of a file's permissions on part of its existing
221 permissions.  To do this, instead of using @samp{r}, @samp{w}, or
222 @samp{x} after the operator, you use the letter @samp{u}, @samp{g}, or
223 @samp{o}.  For example, the mode
225 @example
227 @end example
229 @noindent
230 @c FIXME describe the ls -l notation for showing permissions.
231 adds the permissions for users who are in a file's group to the
232 permissions that other users have for the file.  Thus, if the file
233 started out as mode 664 (@samp{rw-rw-r--}), the above mode would change
234 it to mode 666 (@samp{rw-rw-rw-}).  If the file had started out as mode
235 741 (@samp{rwxr----x}), the above mode would change it to mode 745
236 (@samp{rwxr--r-x}).  The @samp{-} and @samp{=} operations work
237 analogously.
239 @node Changing Special Permissions
240 @subsection Changing Special Permissions
242 @cindex changing special permissions
243 In addition to changing a file's read, write, and execute permissions,
244 you can change its special permissions.  @xref{Mode Structure}, for a
245 summary of these permissions.
247 To change a file's permission to set the user ID on execution, use
248 @samp{u} in the @var{users} part of the symbolic mode and
249 @samp{s} in the @var{permissions} part.
251 To change a file's permission to set the group ID on execution, use
252 @samp{g} in the @var{users} part of the symbolic mode and
253 @samp{s} in the @var{permissions} part.
255 To change a file's permission to stay permanently on the swap device,
256 use @samp{o} in the @var{users} part of the symbolic mode and
257 @samp{t} in the @var{permissions} part.
259 For example, to add set user ID permission to a program,
260 you can use the mode:
262 @example
264 @end example
266 To remove both set user ID and set group ID permission from
267 it, you can use the mode:
269 @example
270 ug-s
271 @end example
273 To cause a program to be saved on the swap device, you can use
274 the mode:
276 @example
278 @end example
280 Remember that the special permissions only affect files that are
281 executable, plus, on some systems, directories (on which they have
282 different meanings; @pxref{Mode Structure}).  Using @samp{a}
283 in the @var{users} part of a symbolic mode does not cause the special
284 permissions to be affected; thus,
286 @example
288 @end example
290 @noindent
291 has @emph{no effect}.  You must use @samp{u}, @samp{g}, and @samp{o}
292 explicitly to affect the special permissions.  Also, the
293 combinations @samp{u+t}, @samp{g+t}, and @samp{o+s} have no effect.
295 The @samp{=} operator is not very useful with special permissions; for
296 example, the mode:
298 @example
300 @end example
302 @noindent
303 does cause the file to be saved on the swap device, but it also
304 removes all read, write, and execute permissions that users not in the
305 file's group might have had for it.
307 @node Conditional Executability
308 @subsection Conditional Executability
310 @cindex conditional executability
311 There is one more special type of symbolic permission: if you use
312 @samp{X} instead of @samp{x}, execute permission is affected only if the
313 file already had execute permission or is a directory.  It affects
314 directories' execute permission even if they did not initially have any
315 execute permissions set.
317 For example, this mode:
319 @example
321 @end example
323 @noindent
324 gives all users permission to execute files (or search directories) if
325 anyone could before.
327 @node Multiple Changes
328 @subsection Making Multiple Changes
330 @cindex multiple changes to permissions
331 The format of symbolic modes is actually more complex than described
332 above (@pxref{Setting Permissions}).  It provides two ways to make
333 multiple changes to files' permissions.
335 The first way is to specify multiple @var{operation} and
336 @var{permissions} parts after a @var{users} part in the symbolic mode.
338 For example, the mode:
340 @example
341 og+rX-w
342 @end example
344 @noindent
345 gives users other than the owner of the file read permission and, if
346 it is a directory or if someone already had execute permission
347 to it, gives them execute permission; and it also denies them write
348 permission to it file.  It does not affect the permission that the
349 owner of the file has for it.  The above mode is equivalent to
350 the two modes:
352 @example
353 og+rX
354 og-w
355 @end example
357 The second way to make multiple changes is to specify more than one
358 simple symbolic mode, separated by commas.  For example, the mode:
360 @example
361 a+r,go-w
362 @end example
364 @noindent
365 gives everyone permission to read the file and removes write
366 permission on it for all users except its owner.  Another example:
368 @example
369 u=rwx,g=rx,o=
370 @end example
372 @noindent
373 sets all of the non-special permissions for the file explicitly.  (It
374 gives users who are not in the file's group no permission at all for
375 it.)
377 The two methods can be combined.  The mode:
379 @example
380 a+r,g+x-w
381 @end example
383 @noindent
384 gives all users permission to read the file, and gives users who are in
385 the file's group permission to execute it, as well, but not permission
386 to write to it.  The above mode could be written in several different
387 ways; another is:
389 @example
390 u+r,g+rx,o+r,g-w
391 @end example
393 @node Umask and Protection
394 @subsection The Umask and Protection
396 @cindex umask and modes
397 @cindex modes and umask
398 If the @var{users} part of a symbolic mode is omitted, it defaults to
399 @samp{a} (affect all users), except that any permissions that are
400 @emph{set} in the system variable @code{umask} are @emph{not affected}.
401 The value of @code{umask} can be set using the
402 @code{umask} command.  Its default value varies from system to system.
404 @cindex giving away permissions
405 Omitting the @var{users} part of a symbolic mode is generally not useful
406 with operations other than @samp{+}.  It is useful with @samp{+} because
407 it allows you to use @code{umask} as an easily customizable protection
408 against giving away more permission to files than you intended to.
410 As an example, if @code{umask} has the value 2, which removes write
411 permission for users who are not in the file's group, then the mode:
413 @example
415 @end example
417 @noindent
418 adds permission to write to the file to its owner and to other users who
419 are in the file's group, but @emph{not} to other users.  In contrast,
420 the mode:
422 @example
424 @end example
426 @noindent
427 ignores @code{umask}, and @emph{does} give write permission for
428 the file to all users.
430 @node Numeric Modes
431 @section Numeric Modes
433 @cindex numeric modes
434 @cindex file permissions, numeric
435 @cindex octal numbers for file modes
436 File permissions are stored internally as 16 bit integers.  As an
437 alternative to giving a symbolic mode, you can give an octal (base 8)
438 number that corresponds to the internal representation of the new mode.
439 This number is always interpreted in octal; you do not have to add a
440 leading 0, as you do in C.  Mode 0055 is the same as mode 55.
442 A numeric mode is usually shorter than the corresponding symbolic
443 mode, but it is limited in that it can not take into account a file's
444 previous permissions; it can only set them absolutely.
446 The permissions granted to the user, to other users in the file's group,
447 and to other users not in the file's group are each stored as three
448 bits, which are represented as one octal digit.  The three special
449 permissions are also each stored as one bit, and they are as a group
450 represented as another octal digit.  Here is how the bits are arranged
451 in the 16 bit integer, starting with the lowest valued bit:
453 @example
454 Value in  Corresponding
455 Mode      Permission
457           Other users not in the file's group:
458    1      Execute
459    2      Write
460    4      Read
462           Other users in the file's group:
463   10      Execute
464   20      Write
465   40      Read
467           The file's owner:
468  100      Execute
469  200      Write
470  400      Read
472           Special permissions:
473 1000      Save text image on swap device
474 2000      Set group ID on execution
475 4000      Set user ID on execution
476 @end example
478 For example, numeric mode 4755 corresponds to symbolic mode
479 @samp{u=rwxs,go=rx}, and numeric mode 664 corresponds to symbolic mode
480 @samp{ug=rw,o=r}.  Numeric mode 0 corresponds to symbolic mode
481 @samp{ugo=}.
483 @comment texi related words used by Emacs' spell checker ispell.el
485 @comment LocalWords: texinfo setfilename settitle setchapternewpage
486 @comment LocalWords: iftex finalout ifinfo DIR titlepage vskip pt
487 @comment LocalWords: filll dir samp dfn noindent xref pxref
488 @comment LocalWords: var deffn texi deffnx itemx emph asis
489 @comment LocalWords: findex smallexample subsubsection cindex
491 @comment LocalWords: chgrp chown executability filesystem FIXME ls og rw
492 @comment LocalWords: rwx rwxr rwxs rwxXstugo rx rX rxw setgid setuid ug
493 @comment LocalWords: ugo ugoa umask