SET
Section: POSIX Programmer's Manual (1P)
Updated: 2017
Page Index
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.
NAME
set
--- set or unset options and positional parameters
SYNOPSIS
set [-abCefhmnuvx] [-o option] [argument...]
set [+abCefhmnuvx] [+o option] [argument...]
set -- [argument...]
set -o
set +o
DESCRIPTION
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-2017,
Section 12.2, Utility Syntax Guidelines
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
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-2017,
Section 4.23, 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, as if by executing the
exit
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
-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
the expansion shall fail with the consequences specified in
Section 2.8.1, Consequences of Shell Errors.
- -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
See the DESCRIPTION.
OPERANDS
See the DESCRIPTION.
STDIN
Not used.
INPUT FILES
None.
ENVIRONMENT VARIABLES
None.
ASYNCHRONOUS EVENTS
Default.
STDOUT
See the DESCRIPTION.
STDERR
The standard error shall be used only for diagnostic messages.
OUTPUT FILES
None.
EXTENDED DESCRIPTION
None.
EXIT STATUS
- 0
-
Successful completion.
- >0
-
An invalid option was specified, or an error occurred.
CONSEQUENCES OF ERRORS
Default.
The following sections are informative.
APPLICATION USAGE
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
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
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.
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
None.
SEE ALSO
Section 2.14,
Special Built-In Utilities,
hash
The Base Definitions volume of POSIX.1-2017,
Section 4.23, Variable Assignment,
Section 12.2, Utility Syntax Guidelines
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 .
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 .