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



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

NNAAMMEE
       set -- set or unset options and positional parameters

SSYYNNOOPPSSIISS
       set [[-abCefhmnuvx]] [[-o _o_p_t_i_o_n]] [[_a_r_g_u_m_e_n_t...]]

       set [[+abCefhmnuvx]] [[+o _o_p_t_i_o_n]] [[_a_r_g_u_m_e_n_t...]]

       set -- [[_a_r_g_u_m_e_n_t...]]

       set -o

       set +o

DDEESSCCRRIIPPTTIIOONN
       If no _o_p_t_i_o_ns or _a_r_g_u_m_e_n_ts are specified, _s_e_t shall write the names and
       values of all shell variables in the collation sequence of the current
       locale. Each _n_a_m_e shall start on a separate line, using the format:


           "%s=%s\n", <_n_a_m_e>, <_v_a_l_u_e>

       The _v_a_l_u_e string shall be written with appropriate quoting; see the
       description of shell quoting in _S_e_c_t_i_o_n _2_._2, _Q_u_o_t_i_n_g.  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 _a_r_g_u_m_e_n_ts 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
       _s_e_t.

       The _s_e_t special built-in shall support the Base Definitions volume of
       POSIX.1-2017, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s except that
       options can be specified with either a leading <hyphen-minus> (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-minus> and <plus-sign> forms. These options can also be
       specified as options to _s_h.

       --aa    When this option is on, the _e_x_p_o_r_t attribute shall be set for
             each variable to which an assignment is performed; see the Base
             Definitions volume of POSIX.1-2017, _S_e_c_t_i_o_n _4_._2_3, _V_a_r_i_a_b_l_e
             _A_s_s_i_g_n_m_e_n_t.  If the assignment precedes a utility name in a
             command, the _e_x_p_o_r_t 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 _e_x_p_o_r_t 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 _g_e_t_o_p_t_s or _r_e_a_d utilities, the _e_x_p_o_r_t attribute shall persist
             until the variable is unset.

       --bb    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", <_j_o_b_-_n_u_m_b_e_r>, <_c_u_r_r_e_n_t>, <status>, <job-name>

             where the fields shall be as follows:

             <_c_u_r_r_e_n_t>   The character ''++'' identifies the job that would be
                         used as a default for the _f_g or _b_g utilities; this
                         job can also be specified using the _j_o_b___i_d ""%%++"" 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 _j_o_b___i_d ""%%--"".  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.

             <_j_o_b_-_n_u_m_b_e_r>
                         A number that can be used to identify the process
                         group to the _w_a_i_t, _f_g, _b_g, and _k_i_l_l utilities. Using
                         these utilities, the job can be identified by
                         prefixing the job number with ''%%''.

             <_s_t_a_t_u_s>    Unspecified.

             <_j_o_b_-_n_a_m_e>  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 _S_e_c_t_i_o_n _2_._9_._3_._1,
             _E_x_a_m_p_l_e_s.  Asynchronous notification shall not be enabled by
             default.

       --CC    (Uppercase C.) Prevent existing files from being overwritten by
             the shell's ''>>'' redirection operator (see _S_e_c_t_i_o_n _2_._7_._2,
             _R_e_d_i_r_e_c_t_i_n_g _O_u_t_p_u_t); the "">>||"" redirection operator shall override
             this _n_o_c_l_o_b_b_e_r option for an individual file.

       --ee    When this option is on, when any command fails (for any of the
             reasons listed in _S_e_c_t_i_o_n _2_._8_._1, _C_o_n_s_e_q_u_e_n_c_e_s _o_f _S_h_e_l_l _E_r_r_o_r_s or
             by returning an exit status greater than zero), the shell
             immediately shall exit, as if by executing the _e_x_i_t special
             built-in utility with no arguments, 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 --ee setting shall be ignored when executing the compound
                 list following the wwhhiillee, uunnttiill, iiff, or eelliiff 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 --ee was
                 being ignored, then --ee 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 _f_a_l_s_e command causes the subshell to exit without executing
             _e_c_h_o _o_n_e; however, _e_c_h_o _t_w_o is executed because the exit status
             of the pipeline _(_f_a_l_s_e_; _e_c_h_o _o_n_e_) _| _c_a_t is zero.

       --ff    The shell shall disable pathname expansion.

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

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

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

       --oo    Write the current settings of the options to standard output in
             an unspecified format.

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

       --oo _o_p_t_i_o_n
             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 _o_p_t_i_o_n shall be supported:

             _a_l_l_e_x_p_o_r_t Equivalent to --aa.

             _e_r_r_e_x_i_t   Equivalent to --ee.

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

             _m_o_n_i_t_o_r   Equivalent to --mm.  This option is supported if the
                       system supports the User Portability Utilities option.

             _n_o_c_l_o_b_b_e_r Equivalent to --CC (uppercase C).

             _n_o_g_l_o_b    Equivalent to --ff.

             _n_o_e_x_e_c    Equivalent to --nn.

             _n_o_l_o_g     Prevent the entry of function definitions into the
                       command history; see _C_o_m_m_a_n_d _H_i_s_t_o_r_y _L_i_s_t.

             _n_o_t_i_f_y    Equivalent to --bb.

             _n_o_u_n_s_e_t   Equivalent to --uu.

             _v_e_r_b_o_s_e   Equivalent to --vv.

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

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

             _x_t_r_a_c_e    Equivalent to --xx.

       --uu    When the shell tries to expand an unset parameter other than the
             ''@@'' and ''**'' special parameters, it shall write a message to
             standard error and the expansion shall fail with the consequences
             specified in _S_e_c_t_i_o_n _2_._8_._1, _C_o_n_s_e_q_u_e_n_c_e_s _o_f _S_h_e_l_l _E_r_r_o_r_s.

       --vv    The shell shall write its input to standard error as it is read.

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

       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 _s_e_t 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 _s_e_t ---- without _a_r_g_u_m_e_n_t shall
       unset all positional parameters and set the special parameter ''##'' to
       zero.

OOPPTTIIOONNSS
       See the DESCRIPTION.

OOPPEERRAANNDDSS
       See the DESCRIPTION.

SSTTDDIINN
       Not used.

IINNPPUUTT FFIILLEESS
       None.

EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
       None.

AASSYYNNCCHHRROONNOOUUSS EEVVEENNTTSS
       Default.

SSTTDDOOUUTT
       See the DESCRIPTION.

SSTTDDEERRRR
       The standard error shall be used only for diagnostic messages.

OOUUTTPPUUTT FFIILLEESS
       None.

EEXXTTEENNDDEEDD DDEESSCCRRIIPPTTIIOONN
       None.

EEXXIITT SSTTAATTUUSS
        0    Successful completion.

       >0    An invalid option was specified, or an error occurred.

CCOONNSSEEQQUUEENNCCEESS OOFF EERRRROORRSS
       Default.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       Application writers should avoid relying on _s_e_t --ee 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 --ee setting is ignored within the function body (because the
       function is a command in an AND-OR list other than the last).
       Therefore, if _s_o_m_e___s_e_r_v_e_r fails, the function carries on to echo
       ""ssoommee__sseerrvveerrstartedssuucccceessssffuullllyy"", and the exit status of the function
       is zero (which means ""ssoommee__sseerrvveerrfailed" is not output).

EEXXAAMMPPLLEESS
       Write out all variables and their values:


           set

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


           set c a b

       Turn on the --xx and --vv 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

RRAATTIIOONNAALLEE
       The _s_e_t -- 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 _s_e_t -- form might
       be misinterpreted as being equivalent to _s_e_t without any options or
       arguments. The functionality of this form has been adopted from the
       KornShell. In System V, _s_e_t -- only unsets parameters if there is at
       least one argument; the only way to unset all parameters is to use
       _s_h_i_f_t.  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 _s_e_t + form in early proposals was omitted as being an unnecessary
       duplication of _s_e_t alone and not widespread historical practice.

       The _n_o_c_l_o_b_b_e_r option was changed to allow _s_e_t --CC as well as the _s_e_t --oo
       _n_o_c_l_o_b_b_e_r option. The single-letter version was added so that the
       historical ""$$--"" paradigm would not be broken; see _S_e_c_t_i_o_n _2_._5_._2,
       _S_p_e_c_i_a_l _P_a_r_a_m_e_t_e_r_s.

       The description of the --ee option is intended to match the behavior of
       the 1988 version of the KornShell.

       The --hh flag is related to command name hashing. See _h_a_s_h.

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

       --kk    The --kk 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 _s_e_t
             _n_a_m_e=_v_a_l_u_e had to be used to assign values to shell variables.
             The problem with --kk is that the behavior affects parsing,
             virtually precluding writing any compilers. To explain the
             behavior of --kk, it is necessary to describe the parsing
             algorithm, which is implementation-defined. For example:


                 set -k; echo _n_a_m_e=_v_a_l_u_e

             and:


                 set -k
                 echo _n_a_m_e=_v_a_l_u_e

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

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

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

       The --oo option was adopted from the KornShell to address user needs. In
       addition to its generally friendly interface, --oo is needed to provide
       the _v_i 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 --oo provides ample name space for describing such
       extensions.)

       Historical implementations are inconsistent in the format used for --oo
       option status reporting. The ++oo 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, _s_h did trace the command _s_e_t ++xx, but _k_s_h did not.

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

       The _s_e_t --mm 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 _n_o_t_i_f_y is analogous
       to what is done in _s_e_t --bb or _s_e_t --oo _n_o_t_i_f_y.  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
       _n_o_t_i_f_y.  The syntax is:


           notify [[%job ... ]]

       By issuing _n_o_t_i_f_y with no operands, it causes the C shell to notify the
       user asynchronously when the state of the current job changes. If given
       operands, _n_o_t_i_f_y 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 _t_r_a_p, nor the C shell _n_o_t_i_f_y environment
       variable seemed appropriate (_n_o_t_i_f_y is not a proper POSIX environment
       variable name).

       The _s_e_t --bb option was selected as a compromise.

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

       Historically, some shells applied the --uu 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 --uu for its intended purpose of finding spelling mistakes
       in variable names and uses of unset positional parameters.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _S_e_c_t_i_o_n _2_._1_4, _S_p_e_c_i_a_l _B_u_i_l_t_-_I_n _U_t_i_l_i_t_i_e_s, _h_a_s_h

       The Base Definitions volume of POSIX.1-2017, _S_e_c_t_i_o_n _4_._2_3, _V_a_r_i_a_b_l_e
       _A_s_s_i_g_n_m_e_n_t, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s

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

       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                  2017                               SET(1)
