PROLOG | NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OPERANDS | STDIN | INPUT FILES | ENVIRONMENT VARIABLES | ASYNCHRONOUS EVENTS | STDOUT | STDERR | OUTPUT FILES | EXTENDED DESCRIPTION | EXIT STATUS | CONSEQUENCES OF ERRORS | APPLICATION USAGE | EXAMPLES | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT

SET(1P)                   POSIX Programmer's Manual                  SET(1P)

PROLOG         top

       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.

NAME         top

       set — set or unset options and positional parameters

SYNOPSIS         top

       set [−abCefhmnuvx] [−o option] [argument...]

       set [+abCefhmnuvx] [+o option] [argument...]

       set −− [argument...]

       set −o

       set +o

DESCRIPTION         top

       If no options or arguments are specified, set shall write the names
       and values of all shell variables in the collation sequence of the
       current locale. Each name shall start on a separate line, using the
       format:

           "%s=%s\n", <name>, <value>

       The value string shall be written with appropriate quoting; see the
       description of shell quoting in Section 2.2, Quoting.  The output
       shall be suitable for reinput to the shell, setting or resetting, as
       far as possible, the variables that are currently set; read-only
       variables cannot be reset.

       When options are specified, they shall set or unset attributes of the
       shell, as described below. When arguments are specified, they cause
       positional parameters to be set or unset, as described below. Setting
       or unsetting attributes and positional parameters are not necessarily
       related actions, but they can be combined in a single invocation of
       set.

       The set special built-in shall support the Base Definitions volume of
       POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines except that
       options can be specified with either a leading <hyphen> (meaning
       enable the option) or <plus-sign> (meaning disable it) unless
       otherwise specified.

       Implementations shall support the options in the following list in
       both their <hyphen> and <plus-sign> forms. These options can also be
       specified as options to sh.

       −a    When this option is on, the export attribute shall be set for
             each variable to which an assignment is performed; see the Base
             Definitions volume of POSIX.1‐2008, Section 4.22, Variable
             Assignment.  If the assignment precedes a utility name in a
             command, the export attribute shall not persist in the current
             execution environment after the utility completes, with the
             exception that preceding one of the special built-in utilities
             causes the export attribute to persist after the built-in has
             completed. If the assignment does not precede a utility name in
             the command, or if the assignment is a result of the operation
             of the getopts or read utilities, the export attribute shall
             persist until the variable is unset.

       −b    This option shall be supported if the implementation supports
             the User Portability Utilities option. It shall cause the shell
             to notify the user asynchronously of background job
             completions. The following message is written to standard
             error:

                 "[%d]%c %s%s\n", <job-number>, <current>, <status>, <job-name>

             where the fields shall be as follows:

             <current>   The character '+' identifies the job that would be
                         used as a default for the fg or bg utilities; this
                         job can also be specified using the job_id "%+" or
                         "%%".  The character '−' identifies the job that
                         would become the default if the current default job
                         were to exit; this job can also be specified using
                         the job_id "%−".  For other jobs, this field is a
                         <space>.  At most one job can be identified with
                         '+' and at most one job can be identified with '−'.
                         If there is any suspended job, then the current job
                         shall be a suspended job. If there are at least two
                         suspended jobs, then the previous job also shall be
                         a suspended job.

             <job-number>
                         A number that can be used to identify the process
                         group to the wait, fg, bg, and kill utilities.
                         Using these utilities, the job can be identified by
                         prefixing the job number with '%'.

             <status>    Unspecified.

             <job-name>  Unspecified.

             When the shell notifies the user a job has been completed, it
             may remove the job's process ID from the list of those known in
             the current shell execution environment; see Section 2.9.3.1,
             Examples.  Asynchronous notification shall not be enabled by
             default.

       −C    (Uppercase C.) Prevent existing files from being overwritten by
             the shell's '>' redirection operator (see Section 2.7.2,
             Redirecting Output); the ">|" redirection operator shall
             override this noclobber option for an individual file.

       −e    When this option is on, when any command fails (for any of the
             reasons listed in Section 2.8.1, Consequences of Shell Errors
             or by returning an exit status greater than zero), the shell
             immediately shall exit with the following exceptions:

              1. The failure of any individual command in a multi-command
                 pipeline shall not cause the shell to exit. Only the
                 failure of the pipeline itself shall be considered.

              2. The −e setting shall be ignored when executing the compound
                 list following the while, until, if, or elif reserved word,
                 a pipeline beginning with the !  reserved word, or any
                 command of an AND-OR list other than the last.

              3. If the exit status of a compound command other than a
                 subshell command was the result of a failure while −e was
                 being ignored, then −e shall not apply to this command.

             This requirement applies to the shell environment and each
             subshell environment separately. For example, in:

                 set -e; (false; echo one) | cat; echo two

             the false command causes the subshell to exit without executing
             echo one; however, echo two is executed because the exit status
             of the pipeline (false; echo one) | cat is zero.

       −f    The shell shall disable pathname expansion.

       −h    Locate and remember utilities invoked by functions as those
             functions are defined (the utilities are normally located when
             the function is executed).

       −m    This option shall be supported if the implementation supports
             the User Portability Utilities option. All jobs shall be run in
             their own process groups. Immediately before the shell issues a
             prompt after completion of the background job, a message
             reporting the exit status of the background job shall be
             written to standard error. If a foreground job stops, the shell
             shall write a message to standard error to that effect,
             formatted as described by the jobs utility. In addition, if a
             job changes status other than exiting (for example, if it stops
             for input or output or is stopped by a SIGSTOP signal), the
             shell shall write a similar message immediately prior to
             writing the next prompt. This option is enabled by default for
             interactive shells.

       −n    The shell shall read commands but does not execute them; this
             can be used to check for shell script syntax errors. An
             interactive shell may ignore this option.

       −o    Write the current settings of the options to standard output in
             an unspecified format.

       +o    Write the current option settings to standard output in a
             format that is suitable for reinput to the shell as commands
             that achieve the same options settings.

       −o option
             This option is supported if the system supports the User
             Portability Utilities option. It shall set various options,
             many of which shall be equivalent to the single option letters.
             The following values of option shall be supported:

             allexport Equivalent to −a.

             errexit   Equivalent to −e.

             ignoreeof Prevent an interactive shell from exiting on end-of-
                       file. This setting prevents accidental logouts when
                       <control>‐D is entered. A user shall explicitly exit
                       to leave the interactive shell.

             monitor   Equivalent to −m.  This option is supported if the
                       system supports the User Portability Utilities
                       option.

             noclobber Equivalent to −C (uppercase C).

             noglob    Equivalent to −f.

             noexec    Equivalent to −n.

             nolog     Prevent the entry of function definitions into the
                       command history; see Command History List.

             notify    Equivalent to −b.

             nounset   Equivalent to −u.

             verbose   Equivalent to −v.

             vi        Allow shell command line editing using the built-in
                       vi editor. Enabling vi mode shall disable any other
                       command line editing mode provided as an
                       implementation extension.

                       It need not be possible to set vi mode on for certain
                       block-mode terminals.

             xtrace    Equivalent to −x.

       −u    When the shell tries to expand an unset parameter other than
             the '@' and '*' special parameters, it shall write a message to
             standard error and shall not execute the command containing the
             expansion, but for the purposes of setting the '?'  special
             parameter and the exit status of the shell the command shall be
             treated as having been executed and returned an exit status of
             between 1 and 125 inclusive. A non-interactive shell shall
             immediately exit. An interactive shell shall not exit.

       −v    The shell shall write its input to standard error as it is
             read.

       −x    The shell shall write to standard error a trace for each
             command after it expands the command and before it executes it.
             It is unspecified whether the command that turns tracing off is
             traced.

       The default for all these options shall be off (unset) unless stated
       otherwise in the description of the option or unless the shell was
       invoked with them on; see sh.

       The remaining arguments shall be assigned in order to the positional
       parameters. The special parameter '#' shall be set to reflect the
       number of positional parameters. All positional parameters shall be
       unset before any new values are assigned.

       If the first argument is '−', the results are unspecified.

       The special argument "−−" immediately following the set command name
       can be used to delimit the arguments if the first argument begins
       with '+' or '−', or to prevent inadvertent listing of all shell
       variables when there are no arguments. The command set −− without
       argument shall unset all positional parameters and set the special
       parameter '#' to zero.

OPTIONS         top

       See the DESCRIPTION.

OPERANDS         top

       See the DESCRIPTION.

STDIN         top

       Not used.

INPUT FILES         top

       None.

ENVIRONMENT VARIABLES         top

       None.

ASYNCHRONOUS EVENTS         top

       Default.

STDOUT         top

       See the DESCRIPTION.

STDERR         top

       The standard error shall be used only for diagnostic messages.

OUTPUT FILES         top

       None.

EXTENDED DESCRIPTION         top

       None.

EXIT STATUS         top

       Zero.

CONSEQUENCES OF ERRORS         top

       Default.

       The following sections are informative.

APPLICATION USAGE         top

       Application writers should avoid relying on set −e within functions.
       For example, in the following script:

           set -e
           start() {
               some_server
               echo some_server started successfully
           }
           start || echo >&2 some_server failed

       the −e setting is ignored within the function body (because the
       function is a command in an AND-OR list other than the last).
       Therefore, if some_server fails, the function carries on to echo
       "some_serverstartedsuccessfully", and the exit status of the function
       is zero (which means "some_serverfailed" is not output).

EXAMPLES         top

       Write out all variables and their values:

           set

       Set $1, $2, and $3 and set "$#" to 3:

           set c a b

       Turn on the −x and −v options:

           set −xv

       Unset all positional parameters:

           set −−

       Set $1 to the value of x, even if it begins with '−' or '+':

           set −− "$x"

       Set the positional parameters to the expansion of x, even if x
       expands with a leading '−' or '+':

           set −− $x

RATIONALE         top

       The set −− form is listed specifically in the SYNOPSIS even though
       this usage is implied by the Utility Syntax Guidelines. The
       explanation of this feature removes any ambiguity about whether the
       set −− form might be misinterpreted as being equivalent to set
       without any options or arguments. The functionality of this form has
       been adopted from the KornShell. In System V, set −− only unsets
       parameters if there is at least one argument; the only way to unset
       all parameters is to use shift.  Using the KornShell version should
       not affect System V scripts because there should be no reason to
       issue it without arguments deliberately; if it were issued as, for
       example:

           set −− "$@"

       and there were in fact no arguments resulting from "$@", unsetting
       the parameters would have no result.

       The set + form in early proposals was omitted as being an unnecessary
       duplication of set alone and not widespread historical practice.

       The noclobber option was changed to allow set −C as well as the set
       −o noclobber option. The single-letter version was added so that the
       historical "$−" paradigm would not be broken; see Section 2.5.2,
       Special Parameters.

       The description of the −e option is intended to match the behavior of
       the 1988 version of the KornShell.

       The −h flag is related to command name hashing. See hash(1p).

       The following set flags were omitted intentionally with the following
       rationale:

       −k    The −k flag was originally added by the author of the Bourne
             shell to make it easier for users of pre-release versions of
             the shell. In early versions of the Bourne shell the construct
             set name=value had to be used to assign values to shell
             variables. The problem with −k is that the behavior affects
             parsing, virtually precluding writing any compilers. To explain
             the behavior of −k, it is necessary to describe the parsing
             algorithm, which is implementation-defined. For example:

                 set −k; echo name=value

             and:

                 set −k
                 echo name=value

             behave differently. The interaction with functions is even more
             complex. What is more, the −k flag is never needed, since the
             command line could have been reordered.

       −t    The −t flag is hard to specify and almost never used. The only
             known use could be done with here-documents. Moreover, the
             behavior with ksh and sh differs. The reference page says that
             it exits after reading and executing one command. What is one
             command? If the input is date;date, sh executes both date
             commands while ksh does only the first.

       Consideration was given to rewriting set to simplify its confusing
       syntax. A specific suggestion was that the unset utility should be
       used to unset options instead of using the non-getopt()-able +option
       syntax. However, the conclusion was reached that the historical
       practice of using +option was satisfactory and that there was no
       compelling reason to modify such widespread historical practice.

       The −o option was adopted from the KornShell to address user needs.
       In addition to its generally friendly interface, −o is needed to
       provide the vi command line editing mode, for which historical
       practice yields no single-letter option name. (Although it might have
       been possible to invent such a letter, it was recognized that other
       editing modes would be developed and −o provides ample name space for
       describing such extensions.)

       Historical implementations are inconsistent in the format used for −o
       option status reporting. The +o format without an option-argument was
       added to allow portable access to the options that can be saved and
       then later restored using, for instance, a dot script.

       Historically, sh did trace the command set +x, but ksh did not.

       The ignoreeof setting prevents accidental logouts when the end-of-
       file character (typically <control>‐D) is entered. A user shall
       explicitly exit to leave the interactive shell.

       The set −m option was added to apply only to the UPE because it
       applies primarily to interactive use, not shell script applications.

       The ability to do asynchronous notification became available in the
       1988 version of the KornShell. To have it occur, the user had to
       issue the command:

           trap "jobs −n" CLD

       The C shell provides two different levels of an asynchronous
       notification capability. The environment variable notify is analogous
       to what is done in set −b or set −o notify.  When set, it notifies
       the user immediately of background job completions. When unset, this
       capability is turned off.

       The other notification ability comes through the built-in utility
       notify.  The syntax is:

           notify [%job ... ]

       By issuing notify with no operands, it causes the C shell to notify
       the user asynchronously when the state of the current job changes. If
       given operands, notify asynchronously informs the user of changes in
       the states of the specified jobs.

       To add asynchronous notification to the POSIX shell, neither the
       KornShell extensions to trap, nor the C shell notify environment
       variable seemed appropriate (notify is not a proper POSIX environment
       variable name).

       The set −b option was selected as a compromise.

       The notify built-in was considered to have more functionality than
       was required for simple asynchronous notification.

       Historically, some shells applied the −u option to all parameters
       including $@ and $*.  The standard developers felt that this was a
       misfeature since it is normal and common for $@ and $* to be used in
       shell scripts regardless of whether they were passed any arguments.
       Treating these uses as an error when no arguments are passed reduces
       the value of −u for its intended purpose of finding spelling mistakes
       in variable names and uses of unset positional parameters.

FUTURE DIRECTIONS         top

       None.

SEE ALSO         top

       Section 2.14, Special Built-In Utilities, hash(1p)

       The Base Definitions volume of POSIX.1‐2008, Section 4.22, Variable
       Assignment, Section 12.2, Utility Syntax Guidelines

COPYRIGHT         top

       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information
       Technology -- Portable Operating System Interface (POSIX), The Open
       Group Base Specifications Issue 7, Copyright (C) 2013 by the
       Institute of Electrical and Electronics Engineers, Inc and The Open
       Group.  (This is POSIX.1-2008 with the 2013 Technical Corrigendum 1
       applied.) 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.unix.org/online.html .

       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 .

IEEE/The Open Group                 2013                             SET(1P)

Pages that refer to this page: pathchk(1p)sh(1p)