1UMASK(1P)                  POSIX Programmer's Manual                 UMASK(1P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       umask — get or set the file mode creation mask
13

SYNOPSIS

15       umask [-S] [mask]
16

DESCRIPTION

18       The umask utility shall set the file mode creation mask of the  current
19       shell execution environment (see Section 2.12, Shell Execution Environ‐
20       ment) to the value specified by  the  mask  operand.  This  mask  shall
21       affect  the  initial  value of the file permission bits of subsequently
22       created files. If umask is called in a  subshell  or  separate  utility
23       execution environment, such as one of the following:
24
25
26           (umask 002)
27           nohup umask ...
28           find . -exec umask ... \;
29
30       it  shall  not affect the file mode creation mask of the caller's envi‐
31       ronment.
32
33       If the mask operand is not specified, the umask utility shall write  to
34       standard  output the value of the file mode creation mask of the invok‐
35       ing process.
36

OPTIONS

38       The umask utility shall conform  to  the  Base  Definitions  volume  of
39       POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
40
41       The following option shall be supported:
42
43       -S        Produce symbolic output.
44
45       The  default  output style is unspecified, but shall be recognized on a
46       subsequent invocation of umask on the same system as a mask operand  to
47       restore the previous file mode creation mask.
48

OPERANDS

50       The following operand shall be supported:
51
52       mask      A  string  specifying  the  new  file mode creation mask. The
53                 string is treated  in  the  same  way  as  the  mode  operand
54                 described in the EXTENDED DESCRIPTION section for chmod.
55
56                 For  a  symbolic_mode  value,  the new value of the file mode
57                 creation mask shall be the logical  complement  of  the  file
58                 permission  bits  portion  of  the file mode specified by the
59                 symbolic_mode string.
60
61                 In a symbolic_mode value, the permissions op  characters  '+'
62                 and  '-'  shall  be  interpreted relative to the current file
63                 mode creation mask; '+' shall cause the bits  for  the  indi‐
64                 cated  permissions to be cleared in the mask; '-' shall cause
65                 the bits for the indicated permissions to be set in the mask.
66
67                 The interpretation of mode values that specify file mode bits
68                 other than the file permission bits is unspecified.
69
70                 In the octal integer form of mode, the specified bits are set
71                 in the file mode creation mask.
72
73                 The file mode creation mask shall be  set  to  the  resulting
74                 numeric value.
75
76                 The default output of a prior invocation of umask on the same
77                 system with no operand also shall be recognized as a mask op‐
78                 erand.
79

STDIN

81       Not used.
82

INPUT FILES

84       None.
85

ENVIRONMENT VARIABLES

87       The  following  environment  variables  shall  affect  the execution of
88       umask:
89
90       LANG      Provide a default value for  the  internationalization  vari‐
91                 ables  that are unset or null. (See the Base Definitions vol‐
92                 ume of POSIX.1‐2017, Section 8.2, Internationalization  Vari‐
93                 ables  for  the  precedence of internationalization variables
94                 used to determine the values of locale categories.)
95
96       LC_ALL    If set to a non-empty string value, override  the  values  of
97                 all the other internationalization variables.
98
99       LC_CTYPE  Determine  the  locale for the interpretation of sequences of
100                 bytes of text data as characters (for example, single-byte as
101                 opposed to multi-byte characters in arguments).
102
103       LC_MESSAGES
104                 Determine the locale that should be used to affect the format
105                 and contents  of  diagnostic  messages  written  to  standard
106                 error.
107
108       NLSPATH   Determine the location of message catalogs for the processing
109                 of LC_MESSAGES.
110

ASYNCHRONOUS EVENTS

112       Default.
113

STDOUT

115       When the mask operand is not specified, the umask utility shall write a
116       message to standard output that can later be used as a umask mask oper‐
117       and.
118
119       If -S is specified, the message shall be in the following format:
120
121
122           "u=%s,g=%s,o=%s\n", <owner permissions>, <group permissions>,
123               <other permissions>
124
125       where the three values shall be combinations of letters  from  the  set
126       {r, w, x}; the presence of a letter shall indicate that the correspond‐
127       ing bit is clear in the file mode creation mask.
128
129       If a mask operand is specified, there shall be  no  output  written  to
130       standard output.
131

STDERR

133       The standard error shall be used only for diagnostic messages.
134

OUTPUT FILES

136       None.
137

EXTENDED DESCRIPTION

139       None.
140

EXIT STATUS

142       The following exit values shall be returned:
143
144        0    The  file mode creation mask was successfully changed, or no mask
145             operand was supplied.
146
147       >0    An error occurred.
148

CONSEQUENCES OF ERRORS

150       Default.
151
152       The following sections are informative.
153

APPLICATION USAGE

155       Since umask affects the current shell execution environment, it is gen‐
156       erally provided as a shell regular built-in.
157
158       In  contrast to the negative permission logic provided by the file mode
159       creation mask and the octal number form of the mask argument, the  sym‐
160       bolic  form  of  the mask argument specifies those permissions that are
161       left alone.
162

EXAMPLES

164       Either of the commands:
165
166
167           umask a=rx,ug+w
168
169           umask 002
170
171       sets the mode mask  so  that  subsequently  created  files  have  their
172       S_IWOTH bit cleared.
173
174       After  setting  the  mode  mask  with either of the above commands, the
175       umask command can be used to write out the current value  of  the  mode
176       mask:
177
178
179           $ umask
180           0002
181
182       (The  output  format is unspecified, but historical implementations use
183       the octal integer mode format.)
184
185
186           $ umask -S
187           u=rwx,g=rwx,o=rx
188
189       Either of these outputs can be used as the mask operand to a subsequent
190       invocation of the umask utility.
191
192       Assuming the mode mask is set as above, the command:
193
194
195           umask g-w
196
197       sets  the  mode  mask  so  that  subsequently  created files have their
198       S_IWGRP and S_IWOTH bits cleared.
199
200       The command:
201
202
203           umask -- -w
204
205       sets the mode mask so that subsequently created files  have  all  their
206       write  bits  cleared.  Note  that  mask operands -r, -w, -x or anything
207       beginning with a <hyphen-minus>, must be preceded by "--"  to  keep  it
208       from being interpreted as an option.
209

RATIONALE

211       Since umask affects the current shell execution environment, it is gen‐
212       erally provided as a shell regular built-in. If it is called in a  sub‐
213       shell  or  separate  utility  execution environment, such as one of the
214       following:
215
216
217           (umask 002)
218           nohup umask ...
219           find . -exec umask ... \;
220
221       it does not affect the file mode creation mask of  the  environment  of
222       the caller.
223
224       The  description  of the historical utility was modified to allow it to
225       use the symbolic modes of chmod.  The -s option used in early proposals
226       was  changed  to  -S  because -s could be confused with a symbolic_mode
227       form of mask referring to the S_ISUID and S_ISGID bits.
228
229       The default output style is unspecified to permit implementors to  pro‐
230       vide  migration  to the new symbolic style at the time most appropriate
231       to their users. A -o flag  to  force  octal  mode  output  was  omitted
232       because  the  octal  mode  may  not be sufficient to specify all of the
233       information that may be present in the file  mode  creation  mask  when
234       more secure file access permission checks are implemented.
235
236       It  has been suggested that trusted systems developers might appreciate
237       ameliorating the requirement that the mode mask  ``affects''  the  file
238       access  permissions,  since it seems access control lists might replace
239       the mode mask to some degree. The wording has been changed to say  that
240       it  affects  the file permission bits, and it leaves the details of the
241       behavior of how they affect the file access permissions to the descrip‐
242       tion in the System Interfaces volume of POSIX.1‐2017.
243

FUTURE DIRECTIONS

245       None.
246

SEE ALSO

248       Chapter 2, Shell Command Language, chmod
249
250       The  Base  Definitions  volume  of POSIX.1‐2017, Chapter 8, Environment
251       Variables, Section 12.2, Utility Syntax Guidelines
252
253       The System Interfaces volume of POSIX.1‐2017, umask()
254
256       Portions of this text are reprinted and reproduced in  electronic  form
257       from  IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
258       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
259       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
260       Electrical and Electronics Engineers, Inc and The Open Group.   In  the
261       event of any discrepancy between this version and the original IEEE and
262       The Open Group Standard, the original IEEE and The Open Group  Standard
263       is  the  referee document. The original Standard can be obtained online
264       at http://www.opengroup.org/unix/online.html .
265
266       Any typographical or formatting errors that appear  in  this  page  are
267       most likely to have been introduced during the conversion of the source
268       files to man page format. To report such errors,  see  https://www.ker
269       nel.org/doc/man-pages/reporting_bugs.html .
270
271
272
273IEEE/The Open Group                  2017                            UMASK(1P)
Impressum