mirror of https://github.com/mkerrisk/man-pages
311 lines
8.7 KiB
Groff
311 lines
8.7 KiB
Groff
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "UMASK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" umask
|
|
.SH NAME
|
|
umask \- get or set the file mode creation mask
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fBumask\fP \fB[\fP\fB-S\fP\fB][\fP\fImask\fP\fB]\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fIumask\fP utility shall set the file mode creation mask of the
|
|
current shell execution environment (see \fIShell Execution Environment\fP
|
|
) to the value specified by the \fImask\fP operand. This mask
|
|
shall affect the initial value of the file permission bits of subsequently
|
|
created files. If \fIumask\fP is called in a subshell
|
|
or separate utility execution environment, such as one of the following:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB(umask 002)
|
|
nohup umask ...
|
|
find . -exec umask ... \\;
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
it shall not affect the file mode creation mask of the caller's environment.
|
|
.LP
|
|
If the \fImask\fP operand is not specified, the \fIumask\fP utility
|
|
shall write to standard output the value of the invoking
|
|
process' file mode creation mask.
|
|
.SH OPTIONS
|
|
.LP
|
|
The \fIumask\fP utility shall conform to the Base Definitions volume
|
|
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
|
|
.LP
|
|
The following option shall be supported:
|
|
.TP 7
|
|
\fB-S\fP
|
|
Produce symbolic output.
|
|
.sp
|
|
.LP
|
|
The default output style is unspecified, but shall be recognized on
|
|
a subsequent invocation of \fIumask\fP on the same system
|
|
as a \fImask\fP operand to restore the previous file mode creation
|
|
mask.
|
|
.SH OPERANDS
|
|
.LP
|
|
The following operand shall be supported:
|
|
.TP 7
|
|
\fImask\fP
|
|
A string specifying the new file mode creation mask. The string is
|
|
treated in the same way as the \fImode\fP operand described
|
|
in the EXTENDED DESCRIPTION section for \fIchmod\fP.
|
|
.LP
|
|
For a \fIsymbolic_mode\fP 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 \fIsymbolic_mode\fP
|
|
string.
|
|
.LP
|
|
In a \fIsymbolic_mode\fP value, the permissions \fIop\fP characters
|
|
\fB'+'\fP and \fB'-'\fP shall be interpreted
|
|
relative to the current file mode creation mask; \fB'+'\fP shall cause
|
|
the bits for the indicated permissions to be cleared in
|
|
the mask; \fB'-'\fP shall cause the bits for the indicated permissions
|
|
to be set in the mask.
|
|
.LP
|
|
The interpretation of \fImode\fP values that specify file mode bits
|
|
other than the file permission bits is unspecified.
|
|
.LP
|
|
In the octal integer form of \fImode\fP, the specified bits are set
|
|
in the file mode creation mask.
|
|
.LP
|
|
The file mode creation mask shall be set to the resulting numeric
|
|
value.
|
|
.LP
|
|
The default output of a prior invocation of \fIumask\fP on the same
|
|
system with no operand also shall be recognized as a
|
|
\fImask\fP operand.
|
|
.sp
|
|
.SH STDIN
|
|
.LP
|
|
Not used.
|
|
.SH INPUT FILES
|
|
.LP
|
|
None.
|
|
.SH ENVIRONMENT VARIABLES
|
|
.LP
|
|
The following environment variables shall affect the execution of
|
|
\fIumask\fP:
|
|
.TP 7
|
|
\fILANG\fP
|
|
Provide a default value for the internationalization variables that
|
|
are unset or null. (See the Base Definitions volume of
|
|
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
|
|
for
|
|
the precedence of internationalization variables used to determine
|
|
the values of locale categories.)
|
|
.TP 7
|
|
\fILC_ALL\fP
|
|
If set to a non-empty string value, override the values of all the
|
|
other internationalization variables.
|
|
.TP 7
|
|
\fILC_CTYPE\fP
|
|
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).
|
|
.TP 7
|
|
\fILC_MESSAGES\fP
|
|
Determine the locale that should be used to affect the format and
|
|
contents of diagnostic messages written to standard
|
|
error.
|
|
.TP 7
|
|
\fINLSPATH\fP
|
|
Determine the location of message catalogs for the processing of \fILC_MESSAGES
|
|
\&.\fP
|
|
.sp
|
|
.SH ASYNCHRONOUS EVENTS
|
|
.LP
|
|
Default.
|
|
.SH STDOUT
|
|
.LP
|
|
When the \fImask\fP operand is not specified, the \fIumask\fP utility
|
|
shall write a message to standard output that can later
|
|
be used as a \fIumask\fP \fImask\fP operand.
|
|
.LP
|
|
If \fB-S\fP is specified, the message shall be in the following format:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB"u=%s,g=%s,o=%s\\n", <\fP\fIowner permissions\fP\fB>, <\fP\fIgroup permissions\fP\fB>,
|
|
<\fP\fIother permissions\fP\fB>
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
where the three values shall be combinations of letters from the set
|
|
{ \fIr\fP, \fIw\fP, \fIx\fP}; the presence of a letter
|
|
shall indicate that the corresponding bit is clear in the file mode
|
|
creation mask.
|
|
.LP
|
|
If a \fImask\fP operand is specified, there shall be no output written
|
|
to standard output.
|
|
.SH STDERR
|
|
.LP
|
|
The standard error shall be used only for diagnostic messages.
|
|
.SH OUTPUT FILES
|
|
.LP
|
|
None.
|
|
.SH EXTENDED DESCRIPTION
|
|
.LP
|
|
None.
|
|
.SH EXIT STATUS
|
|
.LP
|
|
The following exit values shall be returned:
|
|
.TP 7
|
|
\ 0
|
|
The file mode creation mask was successfully changed, or no \fImask\fP
|
|
operand was supplied.
|
|
.TP 7
|
|
>0
|
|
An error occurred.
|
|
.sp
|
|
.SH CONSEQUENCES OF ERRORS
|
|
.LP
|
|
Default.
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
Since \fIumask\fP affects the current shell execution environment,
|
|
it is generally provided as a shell regular built-in.
|
|
.LP
|
|
In contrast to the negative permission logic provided by the file
|
|
mode creation mask and the octal number form of the
|
|
\fImask\fP argument, the symbolic form of the \fImask\fP argument
|
|
specifies those permissions that are left alone.
|
|
.SH EXAMPLES
|
|
.LP
|
|
Either of the commands:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBumask a=rx,ug+w
|
|
.sp
|
|
|
|
umask 002
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
sets the mode mask so that subsequently created files have their S_IWOTH
|
|
bit cleared.
|
|
.LP
|
|
After setting the mode mask with either of the above commands, the
|
|
\fIumask\fP command can be used to write out the current
|
|
value of the mode mask:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB$\fP \fBumask
|
|
\fP\fB0002\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
(The output format is unspecified, but historical implementations
|
|
use the octal integer mode format.)
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB$\fP \fBumask -S
|
|
\fP\fBu=rwx,g=rwx,o=rx\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
Either of these outputs can be used as the mask operand to a subsequent
|
|
invocation of the \fIumask\fP utility.
|
|
.LP
|
|
Assuming the mode mask is set as above, the command:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBumask g-w
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
sets the mode mask so that subsequently created files have their S_IWGRP
|
|
and S_IWOTH bits cleared.
|
|
.LP
|
|
The command:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBumask -- -w
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
sets the mode mask so that subsequently created files have all their
|
|
write bits cleared. Note that \fImask\fP operands
|
|
\fB-r\fP, \fB-w\fP, \fB-x\fP or anything beginning with a hyphen,
|
|
must be preceded by \fB"--"\fP to keep it from being
|
|
interpreted as an option.
|
|
.SH RATIONALE
|
|
.LP
|
|
Since \fIumask\fP 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
|
|
.nf
|
|
|
|
\fB(umask 002)
|
|
nohup umask ...
|
|
find . -exec umask ... \\;
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
it does not affect the file mode creation mask of the environment
|
|
of the caller.
|
|
.LP
|
|
The description of the historical utility was modified to allow it
|
|
to use the symbolic modes of \fIchmod\fP. The \fB-s\fP option used
|
|
in early proposals was changed to \fB-S\fP because \fB-s\fP
|
|
could be confused with a \fIsymbolic_mode\fP form of mask referring
|
|
to the S_ISUID and S_ISGID bits.
|
|
.LP
|
|
The default output style is implementation-defined to permit implementors
|
|
to provide migration to the new symbolic style at the
|
|
time most appropriate to their users. A \fB-o\fP 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.
|
|
.LP
|
|
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 IEEE\ Std\ 1003.1-2001.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIShell Command Language\fP , \fIchmod\fP , the System
|
|
Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIumask\fP()
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 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 .
|