SET(P) POSIX Programmer's Manual SET(P)NAMEset - set or unset options and positional parameters
SYNOPSISset [-abCefmnuvx][-h][-o option][argument...]
set [+abCefmnuvx][+h][+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 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
IEEE Std 1003.1-2001, 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 IEEE Std 1003.1-2001, Section 4.21, Vari‐
able 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 speci‐
fied using the job_id "%+" or "%%" . The character '-' identi‐
fies 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 Asynchronous Lists . Asynchronous
notification shall not be enabled by default.
-C (Uppercase C.) Prevent existing files from being overwritten by
the shell's '>' redirection operator (see Redirecting Output );
the ">|" redirection operator shall override this noclobber
option for an individual file.
-e When this option is on, if a simple command fails for any of the
reasons listed in Consequences of Shell Errors or returns an
exit status value >0, and is not part of the compound list fol‐
lowing a while, until, or if keyword, and is not a part of an
AND or OR list, and is not a pipeline preceded by the ! reserved
word, then the shell shall immediately exit.
-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 report‐
ing 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 interac‐
tive 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 Porta‐
bility Utilities option. It shall set various options, many of
which shall be equivalent to the single option letters. The fol‐
lowing 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 sup‐
ports 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 his‐
tory; 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 The shell shall write a message to standard error when it tries
to expand a variable that is not set and 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 num‐
ber of positional parameters. All positional parameters shall be unset
before any new values are assigned.
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
Zero.
CONSEQUENCES OF ERRORS
Default.
The following sections are informative.
APPLICATION USAGE
None.
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 delib‐
erately; 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 his‐
torical "$-" paradigm would not be broken; see Special Parameters .
The -h flag is related to command name hashing and is only required on
XSI-conformant systems.
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, virtu‐
ally 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 com‐
plex. 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 com‐
mands while ksh does only the first.
Consideration was given to rewriting set to simplify its confusing syn‐
tax. 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 notifica‐
tion 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 Korn‐
Shell 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.
FUTURE DIRECTIONS
None.
SEE ALSO
Special Built-In Utilities
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 .
IEEE/The Open Group 2003 SET(P)
