umask.1p (9448B)
- '\" et
- .TH UMASK "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- umask
- \(em get or set the file mode creation mask
- .SH SYNOPSIS
- .LP
- .nf
- umask \fB[\fR-S\fB] [\fImask\fB]\fR
- .fi
- .SH DESCRIPTION
- The
- .IR umask
- utility shall set the file mode creation mask of the current shell
- execution environment (see
- .IR "Section 2.12" ", " "Shell Execution Environment")
- to the value specified by the
- .IR mask
- operand. This mask shall affect the initial value of the file
- permission bits of subsequently created files. If
- .IR umask
- is called in a subshell or separate utility execution environment, such
- as one of the following:
- .sp
- .RS 4
- .nf
- (umask 002)
- nohup umask ...
- find . -exec umask ... \e;
- .fi
- .P
- .RE
- .P
- it shall not affect the file mode creation mask of the caller's
- environment.
- .P
- If the
- .IR mask
- operand is not specified, the
- .IR umask
- utility shall write to standard output the value of the
- file mode creation mask of the invoking process.
- .SH OPTIONS
- The
- .IR umask
- utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 12.2" ", " "Utility Syntax Guidelines".
- .P
- The following option shall be supported:
- .IP "\fB\-S\fP" 10
- Produce symbolic output.
- .P
- The default output style is unspecified, but shall be recognized on a
- subsequent invocation of
- .IR umask
- on the same system as a
- .IR mask
- operand to restore the previous file mode creation mask.
- .SH OPERANDS
- The following operand shall be supported:
- .IP "\fImask\fR" 10
- A string specifying the new file mode creation mask. The string is
- treated in the same way as the
- .IR mode
- operand described in the EXTENDED DESCRIPTION section for
- .IR chmod .
- .RS 10
- .P
- For a
- .IR symbolic_mode
- value, the new value of the file mode creation mask shall be the
- logical complement of the file permission bits portion of the file mode
- specified by the
- .IR symbolic_mode
- string.
- .P
- In a
- .IR symbolic_mode
- value, the permissions
- .IR op
- characters
- .BR '\(pl'
- and
- .BR '\-'
- shall be interpreted relative to the current file mode creation mask;
- .BR '\(pl'
- shall cause the bits for the indicated permissions to be cleared in the
- mask;
- .BR '\-'
- shall cause the bits for the indicated permissions to be set in the
- mask.
- .P
- The interpretation of
- .IR mode
- values that specify file mode bits other than the file permission bits
- is unspecified.
- .P
- In the octal integer form of
- .IR mode ,
- the specified bits are set in the file mode creation mask.
- .P
- The file mode creation mask shall be set to the resulting numeric
- value.
- .P
- The default output of a prior invocation of
- .IR umask
- on the same system with no operand also shall be recognized as a
- .IR mask
- operand.
- .RE
- .SH STDIN
- Not used.
- .SH "INPUT FILES"
- None.
- .SH "ENVIRONMENT VARIABLES"
- The following environment variables shall affect the execution of
- .IR umask :
- .IP "\fILANG\fP" 10
- Provide a default value for the internationalization variables that are
- unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 8.2" ", " "Internationalization Variables"
- for the precedence of internationalization variables used to determine
- the values of locale categories.)
- .IP "\fILC_ALL\fP" 10
- If set to a non-empty string value, override the values of all the
- other internationalization variables.
- .IP "\fILC_CTYPE\fP" 10
- Determine the locale for the interpretation of sequences of bytes of
- text data as characters (for example, single-byte as opposed to
- multi-byte characters in arguments).
- .IP "\fILC_MESSAGES\fP" 10
- .br
- Determine the locale that should be used to affect the format and
- contents of diagnostic messages written to standard error.
- .IP "\fINLSPATH\fP" 10
- Determine the location of message catalogs for the processing of
- .IR LC_MESSAGES .
- .SH "ASYNCHRONOUS EVENTS"
- Default.
- .SH STDOUT
- When the
- .IR mask
- operand is not specified, the
- .IR umask
- utility shall write a message to standard output that can later be used
- as a
- .IR umask
- .IR mask
- operand.
- .P
- If
- .BR \-S
- is specified, the message shall be in the following format:
- .sp
- .RS 4
- .nf
- "u=%s,g=%s,o=%s\en", <\fIowner permissions\fR>, <\fIgroup permissions\fR>,
- <\fIother permissions\fR>
- .fi
- .P
- .RE
- .P
- where the three values shall be combinations of letters from the set
- {\c
- .IR r ,
- .IR w ,
- .IR x };
- the presence of a letter shall indicate that the corresponding bit is
- clear in the file mode creation mask.
- .P
- If a
- .IR mask
- operand is specified, there shall be no output written to standard
- output.
- .SH STDERR
- The standard error shall be used only for diagnostic messages.
- .SH "OUTPUT FILES"
- None.
- .SH "EXTENDED DESCRIPTION"
- None.
- .SH "EXIT STATUS"
- The following exit values shall be returned:
- .IP "\00" 6
- The file mode creation mask was successfully changed, or no
- .IR mask
- operand was supplied.
- .IP >0 6
- An error occurred.
- .SH "CONSEQUENCES OF ERRORS"
- Default.
- .LP
- .IR "The following sections are informative."
- .SH "APPLICATION USAGE"
- Since
- .IR umask
- affects the current shell execution environment, it is generally
- provided as a shell regular built-in.
- .P
- In contrast to the negative permission logic provided by the file mode
- creation mask and the octal number form of the
- .IR mask
- argument, the symbolic form of the
- .IR mask
- argument specifies those permissions that are left alone.
- .SH EXAMPLES
- Either of the commands:
- .sp
- .RS 4
- .nf
- umask a=rx,ug+w
- .P
- umask 002
- .fi
- .P
- .RE
- .P
- sets the mode mask so that subsequently created files have their
- S_IWOTH bit cleared.
- .P
- After setting the mode mask with either of the above commands, the
- .IR umask
- command can be used to write out the current value of the mode mask:
- .sp
- .RS 4
- .nf
- \fB$ \fRumask
- \fB0002\fR
- .fi
- .P
- .RE
- .P
- (The output format is unspecified, but historical implementations use
- the octal integer mode format.)
- .sp
- .RS 4
- .nf
- \fB$ \fRumask -S
- \fBu=rwx,g=rwx,o=rx\fR
- .fi
- .P
- .RE
- .P
- Either of these outputs can be used as the mask operand to a subsequent
- invocation of the
- .IR umask
- utility.
- .P
- Assuming the mode mask is set as above, the command:
- .sp
- .RS 4
- .nf
- umask g-w
- .fi
- .P
- .RE
- .P
- sets the mode mask so that subsequently created files have their
- S_IWGRP and S_IWOTH bits cleared.
- .P
- The command:
- .sp
- .RS 4
- .nf
- umask -- -w
- .fi
- .P
- .RE
- .P
- sets the mode mask so that subsequently created files have all their
- write bits cleared. Note that
- .IR mask
- operands
- .BR \-r ,
- .BR \-w ,
- .BR \-x
- or anything beginning with a
- <hyphen-minus>,
- must be preceded by
- .BR \(dq--\(dq
- to keep it from being interpreted as an option.
- .SH RATIONALE
- Since
- .IR umask
- affects the current shell execution environment,
- it is generally provided as a shell regular built-in. If it is called
- in a subshell or separate utility execution environment, such as one of
- the following:
- .sp
- .RS 4
- .nf
- (umask 002)
- nohup umask ...
- find . -exec umask ... \e;
- .fi
- .P
- .RE
- .P
- it does not affect the file mode creation mask of the environment of
- the caller.
- .P
- The description of the historical utility was modified to allow it to
- use the symbolic modes of
- .IR chmod .
- The
- .BR \-s
- option used in early proposals was changed to
- .BR \-S
- because
- .BR \-s
- could be confused with a
- .IR symbolic_mode
- form of mask referring to the S_ISUID and S_ISGID bits.
- .P
- The default output style is unspecified to permit implementors to
- provide migration to the new symbolic style at the time most
- appropriate to their users. A
- .BR \-o
- flag to force octal mode output was omitted because the octal mode may
- not be sufficient to specify all of the information that may be present
- in the file mode creation mask when more secure file access permission
- checks are implemented.
- .P
- It has been suggested that trusted systems developers might appreciate
- ameliorating the requirement that the mode mask ``affects'' the file
- access permissions, since it seems access control lists might replace
- the mode mask to some degree. The wording has been changed to say that
- it affects the file permission bits, and it leaves the details of the
- behavior of how they affect the file access permissions to the
- description in the System Interfaces volume of POSIX.1\(hy2017.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "Chapter 2" ", " "Shell Command Language",
- .IR "\fIchmod\fR\^"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "Chapter 8" ", " "Environment Variables",
- .IR "Section 12.2" ", " "Utility Syntax Guidelines"
- .P
- The System Interfaces volume of POSIX.1\(hy2017,
- .IR "\fIumask\fR\^(\|)"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- In the event of any discrepancy between this version and the original IEEE and
- The Open Group Standard, the original IEEE and The Open Group Standard
- is the referee document. The original Standard can be obtained online at
- http://www.opengroup.org/unix/online.html .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .