| blob | 4d03e1fca813e6114044a7c7943dd5401a061c7d |
1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright 1989 AT&T
44 .\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved
45 .\" Portions Copyright (c) 1982-2007 AT&T Knowledge Ventures
46 .\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
47 .\"
48 .TH UMASK 1 "Sep 17, 2007"
49 .SH NAME
50 umask \- get or set the file mode creation mask
51 .SH SYNOPSIS
52 .LP
53 .nf
54 \fB/usr/bin/umask\fR [\fB-S\fR] [\fImask\fR]
55 .fi
57 .SS "sh"
58 .LP
59 .nf
60 \fBumask\fR [\fIooo\fR]
61 .fi
63 .SS "csh"
64 .LP
65 .nf
66 \fBumask\fR [\fIooo\fR]
67 .fi
69 .SS "ksh"
70 .LP
71 .nf
72 \fBumask\fR [\fB-S\fR] [\fImask\fR]
73 .fi
75 .SS "ksh93"
76 .LP
77 .nf
78 \fBumask\fR [\fB-S\fR] [\fImask\fR]
79 .fi
81 .SH DESCRIPTION
82 .sp
83 .LP
84 The \fBumask\fR utility sets the file mode creation mask of the current shell
85 execution environment to the value specified by the \fImask\fR operand. This
86 mask affects the initial value of the file permission bits of subsequently
87 created files. If \fBumask\fR is called in a subshell or separate utility
88 execution environment, such as one of the following:
89 .sp
90 .in +2
91 .nf
92 (umask 002)
93 nohup umask ...
94 find . -exec umask ...
95 .fi
96 .in -2
97 .sp
99 .sp
100 .LP
101 it does not affect the file mode creation mask of the caller's environment. For
102 this reason, the \fB/usr/bin/umask\fR utility cannot be used to change the
103 umask in an ongoing session. Its usefulness is limited to checking the caller's
104 umask. To change the umask of an ongoing session you must use one of the shell
105 builtins.
106 .sp
107 .LP
108 If the \fImask\fR operand is not specified, the \fBumask\fR utility writes the
109 value of the invoking process's file mode creation mask to standard output.
110 .SS "sh"
111 .sp
112 .LP
113 The user file-creation mode mask is set to \fIooo\fR. The three octal digits
114 refer to read/write/execute permissions for owner, group, and other,
115 respectively (see \fBchmod\fR(1), \fBchmod\fR(2), and \fBumask\fR(2)). The
116 value of each specified digit is subtracted from the corresponding ``digit''
117 specified by the system for the creation of a file (see \fBcreat\fR(2)). For
118 example, \fBumask\fR \fB022\fR removes write permission for group and other.
119 Files (and directories) normally created with mode \fB777\fR become mode
120 \fB755\fR. Files (and directories) created with mode \fB666\fR become mode
121 \fB644\fR).
122 .RS +4
123 .TP
124 .ie t \(bu
125 .el o
126 If \fIooo\fR is omitted, the current value of the mask is printed.
127 .RE
128 .RS +4
129 .TP
130 .ie t \(bu
131 .el o
132 \fBumask\fR is recognized and executed by the shell.
133 .RE
134 .RS +4
135 .TP
136 .ie t \(bu
137 .el o
138 \fBumask\fR can be included in the user's \fB\&.profile\fR (see
139 \fBprofile\fR(4)) and invoked at login to automatically set the user's
140 permissions on files or directories created.
141 .RE
142 .SS "csh"
143 .sp
144 .LP
145 See the description above for the Bourne shell (\fBsh\fR)\fBumask\fR built-in.
146 .SS "ksh"
147 .sp
148 .LP
149 The user file-creation mask is set to \fImask\fR. \fImask\fR can either be an
150 octal number or a symbolic value as described in \fBchmod\fR(1). If a symbolic
151 value is given, the new \fBumask\fR value is the complement of the result of
152 applying \fImask\fR to the complement of the previous umask value. If
153 \fImask\fR is omitted, the current value of the mask is printed.
154 .SS "ksh93"
155 .sp
156 .LP
157 \fBumask\fR sets the file creation mask of the current shell execution
158 environment to the value specified by the \fBmask\fI\fR\fR operand. This mask
159 affects the file permission bits of subsequently created files. \fImask\fR can
160 either be an octal number or a symbolic value as described in chmod(1). If a
161 symbolic value is specified, the new file creation mask is the complement of
162 the result of applying \fImask\fR to the complement of the current file
163 creation mask. If \fImask\fR is not specified, \fBumask\fR writes the value of
164 the file creation mask for the current process to standard output.
165 .SH OPTIONS
166 .SS "ksh"
167 .sp
168 .LP
169 The following option is supported for \fB/usr/bin/umask\fR and \fBumask\fR in
170 \fBksh\fR:
171 .sp
172 .ne 2
173 .na
174 \fB\fB-S\fR\fR
175 .ad
176 .RS 6n
177 Produces symbolic output.
178 .RE
180 .sp
181 .LP
182 The default output style is unspecified, but will be recognized on a subsequent
183 invocation of \fBumask\fR on the same system as a \fImask\fR operand to restore
184 the previous file mode creation mask.
185 .SS "ksh93"
186 .sp
187 .LP
188 The following option is supported in \fBksh93\fR:
189 .sp
190 .ne 2
191 .na
192 \fB\fB-S\fR\fR
193 .ad
194 .RS 6n
195 Causes the file creation mask to be written or treated as a symbolic value
196 rather than an octal number.
197 .RE
199 .SH OPERANDS
200 .sp
201 .LP
202 The following operand is supported:
203 .sp
204 .ne 2
205 .na
206 \fB\fImask\fR\fR
207 .ad
208 .RS 8n
209 A string specifying the new file mode creation mask. The string is treated in
210 the same way as the \fImode\fR operand described in the \fBchmod\fR(1) manual
211 page.
212 .sp
213 For a \fIsymbolic_mode\fR value, the new value of the file mode creation mask
214 is the logical complement of the file permission bits portion of the file mode
215 specified by the \fIsymbolic_mode\fR string.
216 .sp
217 In a \fIsymbolic_mode\fR value, the permissions \fIop\fR characters \fB+\fR and
218 \fB\(mi\fR are interpreted relative to the current file mode creation mask.
219 \fB+\fR causes the bits for the indicated permissions to be cleared in the
220 mask. \fB\(mi\fR causes the bits of the indicated permissions to be set in the
221 mask.
222 .sp
223 The interpretation of \fImode\fR values that specify file mode bits other than
224 the file permission bits is unspecified.
225 .sp
226 The file mode creation mask is set to the resulting numeric value.
227 .sp
228 The default output of a prior invocation of \fBumask\fR on the same system with
229 no operand will also be recognized as a \fImask\fR operand. The use of an
230 operand obtained in this way is not obsolescent, even if it is an octal number.
231 .RE
233 .SH OUTPUT
234 .sp
235 .LP
236 When the \fImask\fR operand is not specified, the \fBumask\fR utility will
237 write a message to standard output that can later be used as a \fBumask\fR
238 \fImask\fR operand.
239 .sp
240 .LP
241 If \fB-S\fR is specified, the message will be in the following format:
242 .sp
243 .in +2
244 .nf
245 "u=%s,g=%s,o=%s\en", \fIowner permissions\fR, \fIgroup permissions\fR, \e
246 \fIother permissions\fR
247 .fi
248 .in -2
249 .sp
251 .sp
252 .LP
253 where the three values will be combinations of letters from the set
254 \fB{\fRr\fB,\fR \fBw\fR, \fBx\fR}. The presence of a letter will indicate that
255 the corresponding bit is clear in the file mode creation mask.
256 .sp
257 .LP
258 If a \fImask\fR operand is specified, there will be no output written to
259 standard output.
260 .SH EXAMPLES
261 .LP
262 \fBExample 1 \fRUsing the \fBumask\fR Command
263 .sp
264 .LP
265 The examples in this section refer to the \fB/usr/bin/umask\fR utility and the
266 \fBksh umask\fR builtin.
268 .sp
269 .LP
270 Either of the commands:
272 .sp
273 .in +2
274 .nf
275 \fBumask a=rx,ug+w
276 umask 002\fR
277 .fi
278 .in -2
279 .sp
281 .sp
282 .LP
283 sets the mode mask so that subsequently created files have their \fBS_IWOTH\fR
284 bit cleared.
286 .sp
287 .LP
288 After setting the mode mask with either of the above commands, the \fBumask\fR
289 command can be used to write the current value of the mode mask:
291 .sp
292 .in +2
293 .nf
294 example$ \fBumask\fR
295 0002
296 .fi
297 .in -2
298 .sp
300 .sp
301 .LP
302 The output format is unspecified, but historical implementations use the
303 obsolescent octal integer mode format.
305 .sp
306 .in +2
307 .nf
308 example$ \fBumask -S\fR
309 u=rwx,g=rwx,o=rx
310 .fi
311 .in -2
312 .sp
314 .sp
315 .LP
316 Either of these outputs can be used as the mask operand to a subsequent
317 invocation of the \fBumask\fR utility.
319 .sp
320 .LP
321 Assuming the mode mask is set as above, the command:
323 .sp
324 .in +2
325 .nf
326 \fBumask g-w\fR
327 .fi
328 .in -2
329 .sp
331 .sp
332 .LP
333 sets the mode mask so that subsequently created files have their \fBS_IWGRP\fR
334 and \fBS_IWOTH\fR bits cleared.
336 .sp
337 .LP
338 The command:
340 .sp
341 .in +2
342 .nf
343 \fBumask --w\fR
344 .fi
345 .in -2
346 .sp
348 .sp
349 .LP
350 sets the mode mask so that subsequently created files have all their write bits
351 cleared. Notice that \fImask\fR operands \fBr\fR, \fBw\fR, \fBx\fR, or anything
352 beginning with a hyphen (\fB\(mi\fR), must be preceded by \fB-\fR to keep it
353 from being interpreted as an option.
355 .SH ENVIRONMENT VARIABLES
356 .sp
357 .LP
358 See \fBenviron\fR(5) for descriptions of the following environment variables
359 that affect the execution of \fBumask\fR: \fBLANG\fR, \fBLC_ALL\fR,
360 \fBLC_COLLATE\fR\fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
361 .SH EXIT STATUS
362 .sp
363 .LP
364 The following exit values are returned:
365 .sp
366 .ne 2
367 .na
368 \fB\fB0\fR\fR
369 .ad
370 .RS 6n
371 The file mode creation mask was successfully changed, or no \fImask\fR operand
372 was supplied.
373 .RE
375 .sp
376 .ne 2
377 .na
378 \fB\fB>0\fR\fR
379 .ad
380 .RS 6n
381 An error occurred.
382 .RE
384 .SH ATTRIBUTES
385 .sp
386 .LP
387 See \fBattributes\fR(5) for descriptions of the following attributes:
388 .SS "/usr/bin/umask, csh, ksh, sh"
389 .sp
391 .sp
392 .TS
393 box;
394 c | c
395 l | l .
396 ATTRIBUTE TYPE ATTRIBUTE VALUE
397 _
398 Interface Stability Standard
399 .TE
401 .SS "ksh93"
402 .sp
404 .sp
405 .TS
406 box;
407 c | c
408 l | l .
409 ATTRIBUTE TYPE ATTRIBUTE VALUE
410 _
411 Interface Stability External
412 .TE
414 .SH SEE ALSO
415 .sp
416 .LP
417 \fBchmod\fR(1), \fBcsh\fR(1), \fBksh\fR(1), \fBksh93\fR(1), \fBsh\fR(1),
418 \fBchmod\fR(2), \fBcreat\fR(2), \fBumask\fR(2), \fBprofile\fR(4),
419 \fBattributes\fR(5), \fBenviron\fR(5), \fBstandards\fR(5)