Provided by: manpages-posix_2.16-1_all bug

NAME

       umask - get or set the file mode creation mask

SYNOPSIS

       umask [-S][mask]

DESCRIPTION

       The  umask utility shall set the file mode creation mask of the current
       shell execution environment (see Shell Execution Environment )  to  the
       value specified by the mask operand. This mask shall affect the initial
       value of the file permission bits of  subsequently  created  files.  If
       umask   is   called   in  a  subshell  or  separate  utility  execution
       environment, such as one of the following:

              (umask 002)
              nohup umask ...
              find . -exec umask ... \;

       it shall not affect  the  file  mode  creation  mask  of  the  caller’s
       environment.

       If  the mask operand is not specified, the umask utility shall write to
       standard output the value of the invoking process’ file  mode  creation
       mask.

OPTIONS

       The  umask  utility  shall  conform  to  the Base Definitions volume of
       IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.

       The following option shall be supported:

       -S     Produce symbolic output.

       The default output style is unspecified, but shall be recognized  on  a
       subsequent  invocation of umask on the same system as a mask operand to
       restore the previous file mode creation mask.

OPERANDS

       The following operand shall be supported:

       mask   A string specifying the new file mode creation mask. The  string
              is  treated in the same way as the mode operand described in the
              EXTENDED DESCRIPTION section for chmod.

       For a 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 symbolic_mode string.

       In a symbolic_mode value, the permissions op  characters  ’+’  and  ’-’
       shall  be  interpreted relative to the current file mode creation mask;
       ’+’ shall cause the bits for the indicated permissions to be cleared in
       the  mask; ’-’ shall cause the bits for the indicated permissions to be
       set in the mask.

       The interpretation of mode values that specify  file  mode  bits  other
       than the file permission bits is unspecified.

       In  the  octal  integer form of mode, the specified bits are set in the
       file mode creation mask.

       The file mode creation mask shall  be  set  to  the  resulting  numeric
       value.

       The  default  output  of a prior invocation of umask on the same system
       with no operand also shall be recognized as a mask operand.

STDIN

       Not used.

INPUT FILES

       None.

ENVIRONMENT VARIABLES

       The following environment  variables  shall  affect  the  execution  of
       umask:

       LANG   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.)

       LC_ALL If  set  to a non-empty string value, override the values of all
              the other internationalization variables.

       LC_CTYPE
              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).

       LC_MESSAGES
              Determine the locale that should be used to  affect  the  format
              and contents of diagnostic messages written to standard error.

       NLSPATH
              Determine the location of message catalogs for the processing of
              LC_MESSAGES .

ASYNCHRONOUS EVENTS

       Default.

STDOUT

       When the mask operand is not specified, the umask utility shall write a
       message  to  standard  output  that  can  later be used as a umask mask
       operand.

       If -S is specified, the message shall be in the following format:

              "u=%s,g=%s,o=%s\n", <owner permissions>, <group permissions>,
                  <other permissions>

       where the three values shall be combinations of letters from the set  {
       r,   w,   x};  the  presence  of  a  letter  shall  indicate  that  the
       corresponding bit is clear in the file mode creation mask.

       If a mask operand is specified, there shall be  no  output  written  to
       standard output.

STDERR

       The standard error shall be used only for diagnostic messages.

OUTPUT FILES

       None.

EXTENDED DESCRIPTION

       None.

EXIT STATUS

       The following exit values shall be returned:

        0     The file mode creation mask was successfully changed, or no mask
              operand was supplied.

       >0     An error occurred.

CONSEQUENCES OF ERRORS

       Default.

       The following sections are informative.

APPLICATION USAGE

       Since umask affects the current  shell  execution  environment,  it  is
       generally provided as a shell regular built-in.

       In  contrast to the negative permission logic provided by the file mode
       creation mask and the octal number  form  of  the  mask  argument,  the
       symbolic form of the mask argument specifies those permissions that are
       left alone.

EXAMPLES

       Either of the commands:

              umask a=rx,ug+w

              umask 002

       sets the mode mask  so  that  subsequently  created  files  have  their
       S_IWOTH bit cleared.

       After  setting  the  mode  mask  with either of the above commands, the
       umask command can be used to write out the current value  of  the  mode
       mask:

              $ umask
              0002

       (The  output  format is unspecified, but historical implementations use
       the octal integer mode format.)

              $ umask -S
              u=rwx,g=rwx,o=rx

       Either of these outputs can be used as the mask operand to a subsequent
       invocation of the umask utility.

       Assuming the mode mask is set as above, the command:

              umask g-w

       sets  the  mode  mask  so  that  subsequently  created files have their
       S_IWGRP and S_IWOTH bits cleared.

       The command:

              umask -- -w

       sets the mode mask so that subsequently created files  have  all  their
       write  bits  cleared.  Note  that  mask operands -r, -w, -x or anything
       beginning with a hyphen, must be preceded by "--" to keep it from being
       interpreted as an option.

RATIONALE

       Since  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:

              (umask 002)
              nohup umask ...
              find . -exec umask ... \;

       it does not affect the file mode creation mask of  the  environment  of
       the caller.

       The  description  of the historical utility was modified to allow it to
       use the symbolic modes of chmod. The -s option used in early  proposals
       was  changed  to  -S  because -s could be confused with a symbolic_mode
       form of mask referring to the S_ISUID and S_ISGID bits.

       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 -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.

       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.

FUTURE DIRECTIONS

       None.

SEE ALSO

       Shell  Command  Language  ,  chmod  ,  the  System Interfaces volume of
       IEEE Std 1003.1-2001, umask()

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 .