|
HTML rendering created 2025-02-02 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
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)
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.
set — set or unset options and positional parameters
set [-abCefhmnuvx] [-o option] [argument...]
set [+abCefhmnuvx] [+o option] [argument...]
set -- [argument...]
set -o
set +o
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.
See the DESCRIPTION.
See the DESCRIPTION.
Not used.
None.
None.
Default.
See the DESCRIPTION.
The standard error shall be used only for diagnostic messages.
None.
None.
0 Successful completion.
>0 An invalid option was specified, or an error occurred.
Default.
The following sections are informative.
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).
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
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.
None.
Section 2.14, Special Built-In Utilities, hash(1p)
The Base Definitions volume of POSIX.1‐2017, Section 4.23,
Variable Assignment, Section 12.2, Utility Syntax Guidelines
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(1P)
Pages that refer to this page: pathchk(1p), sh(1p)
|
HTML rendering created 2025-02-02 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|