set.1p (19879B)
- '\" et
- .TH SET "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH 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.
- .\"
- .SH NAME
- set
- \(em set or unset options and positional parameters
- .SH SYNOPSIS
- .LP
- .nf
- set \fB[\fR-abCefhmnuvx\fB] [\fR-o \fIoption\fB] [\fIargument\fR...\fB]\fR
- .P
- set \fB[\fR+abCefhmnuvx\fB] [\fR+o \fIoption\fB] [\fIargument\fR...\fB]\fR
- .P
- set --\fB [\fIargument\fR...\fB]\fR
- .P
- set -o
- .P
- set +o
- .fi
- .SH DESCRIPTION
- If no
- .IR option s
- or
- .IR argument s
- are specified,
- .IR set
- shall write the names and values of all shell variables in the collation
- sequence of the current locale. Each
- .IR name
- shall start on a separate line, using the format:
- .sp
- .RS 4
- .nf
- "%s=%s\en", <\fIname\fR>, <\fIvalue\fR>
- .fi
- .P
- .RE
- .P
- The
- .IR value
- string shall be written with appropriate quoting; see the description
- of shell quoting in
- .IR "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.
- .P
- When options are specified, they shall set or unset attributes of the
- shell, as described below. When
- .IR argument s
- 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
- .IR set .
- .P
- The
- .IR set
- special built-in shall support the Base Definitions volume of POSIX.1\(hy2017,
- .IR "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.
- .P
- 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
- .IR sh .
- .IP "\fB\-a\fP" 6
- When this option is on, the
- .IR export
- attribute shall be set for each variable to which an assignment is
- performed; see the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 4.23" ", " "Variable Assignment".
- If the assignment precedes a utility name in a command, the
- .IR 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
- .IR 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
- .IR getopts
- or
- .IR read
- utilities, the
- .IR export
- attribute shall persist until the variable is unset.
- .IP "\fB\-b\fP" 6
- 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:
- .RS 6
- .sp
- .RS 4
- .nf
- "[%d]%c %s%s\en", <\fIjob-number\fR>, <\fIcurrent\fR>, <\fRstatus\fR>, <\fRjob-name\fR>
- .fi
- .P
- .RE
- .P
- where the fields shall be as follows:
- .IP "<\fIcurrent\fR>" 12
- The character
- .BR '+'
- identifies the job that would be used as a default for the
- .IR fg
- or
- .IR bg
- utilities; this job can also be specified using the
- .IR job_id
- .BR \(dq%+\(dq
- or
- .BR \(dq%%\(dq .
- The character
- .BR '\-'
- identifies the job that would become the
- default if the current default job were to exit; this job can also be
- specified using the
- .IR job_id
- .BR \(dq%-\(dq .
- For other jobs, this field is a
- <space>.
- At most one job can be identified with
- .BR '+'
- and at most one job can be identified with
- .BR '\-' .
- 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.
- .IP "<\fIjob-number\fR>" 12
- A number that can be used to identify the process group to the
- .IR wait ,
- .IR fg ,
- .IR bg ,
- and
- .IR kill
- utilities. Using these utilities, the job can be identified by
- prefixing the job number with
- .BR '%' .
- .IP "<\fIstatus\fR>" 12
- Unspecified.
- .IP "<\fIjob-name\fR>" 12
- Unspecified.
- .P
- 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
- .IR "Section 2.9.3.1" ", " "Examples".
- Asynchronous notification shall not be enabled by default.
- .RE
- .IP "\fB\-C\fP" 6
- (Uppercase C.) Prevent existing files from being overwritten by the
- shell's
- .BR '>'
- redirection operator (see
- .IR "Section 2.7.2" ", " "Redirecting Output");
- the
- .BR \(dq>|\(dq
- redirection operator shall override this
- .IR noclobber
- option for an individual file.
- .IP "\fB\-e\fP" 6
- When this option is on, when any command fails (for any of the reasons
- listed in
- .IR "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
- .IR exit
- special built-in utility with no arguments, with the following exceptions:
- .RS 6
- .IP " 1." 4
- 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.
- .IP " 2." 4
- The
- .BR \-e
- setting shall be ignored when executing the compound list following the
- .BR while ,
- .BR until ,
- .BR if ,
- or
- .BR elif
- reserved word, a pipeline beginning with the
- .BR !
- reserved word, or any command of an AND-OR list other than the last.
- .IP " 3." 4
- If the exit status of a compound command other than a subshell command
- was the result of a failure while
- .BR \-e
- was being ignored, then
- .BR \-e
- shall not apply to this command.
- .P
- This requirement applies to the shell environment and each subshell
- environment separately. For example, in:
- .sp
- .RS 4
- .nf
- set -e; (false; echo one) | cat; echo two
- .fi
- .P
- .RE
- .P
- the
- .IR false
- command causes the subshell to exit without executing
- .IR "echo one" ;
- however,
- .IR "echo two"
- is executed because the exit status of the pipeline
- .IR "(false; echo one) | cat"
- is zero.
- .RE
- .IP "\fB\-f\fP" 6
- The shell shall disable pathname expansion.
- .IP "\fB\-h\fP" 6
- Locate and remember utilities invoked by functions as those functions
- are defined (the utilities are normally located when the function is
- executed).
- .IP "\fB\-m\fP" 6
- 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
- .IR 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.
- .IP "\fB\-n\fP" 6
- 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.
- .IP "\fB\-o\fP" 6
- Write the current settings of the options to standard output in an
- unspecified format.
- .IP "\fB+o\fP" 6
- 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.
- .IP "\fB\-o\ \fIoption\fR" 6
- .br
- 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
- .IR option
- shall be supported:
- .RS 6
- .IP "\fIallexport\fR" 10
- Equivalent to
- .BR \-a .
- .IP "\fIerrexit\fR" 10
- Equivalent to
- .BR \-e .
- .IP "\fIignoreeof\fR" 10
- Prevent an interactive shell from exiting on end-of-file. This setting
- prevents accidental logouts when
- <control>\(hyD
- is entered. A user shall explicitly
- .IR exit
- to leave the interactive shell.
- .IP "\fImonitor\fR" 10
- Equivalent to
- .BR \-m .
- This option is supported if the system supports the User Portability
- Utilities option.
- .IP "\fInoclobber\fR" 10
- Equivalent to
- .BR \-C
- (uppercase C).
- .IP "\fInoglob\fR" 10
- Equivalent to
- .BR \-f .
- .IP "\fInoexec\fR" 10
- Equivalent to
- .BR \-n .
- .IP "\fInolog\fR" 10
- Prevent the entry of function definitions into the command history; see
- .IR "Command History List".
- .IP "\fInotify\fR" 10
- Equivalent to
- .BR \-b .
- .IP "\fInounset\fR" 10
- Equivalent to
- .BR \-u .
- .IP "\fIverbose\fR" 10
- Equivalent to
- .BR \-v .
- .IP "\fIvi\fR" 10
- Allow shell command line editing using the built-in
- .IR vi
- editor. Enabling
- .IR vi
- mode shall disable any other command line editing mode provided as an
- implementation extension.
- .RS 10
- .P
- It need not be possible to set
- .IR vi
- mode on for certain block-mode terminals.
- .RE
- .IP "\fIxtrace\fR" 10
- Equivalent to
- .BR \-x .
- .RE
- .IP "\fB\-u\fP" 6
- When the shell tries to expand an unset parameter other than the
- .BR '@'
- and
- .BR '*'
- special parameters, it shall write a message to standard error and
- the expansion shall fail with the consequences specified in
- .IR "Section 2.8.1" ", " "Consequences of Shell Errors".
- .IP "\fB\-v\fP" 6
- The shell shall write its input to standard error as it is read.
- .IP "\fB\-x\fP" 6
- 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.
- .P
- 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
- .IR sh .
- .P
- The remaining arguments shall be assigned in order to the positional
- parameters. The special parameter
- .BR '#'
- shall be set to reflect the number of positional parameters. All
- positional parameters shall be unset before any new values are
- assigned.
- .P
- If the first argument is
- .BR '\-' ,
- the results are unspecified.
- .P
- The special argument
- .BR \(dq--\(dq
- immediately following the
- .IR set
- command name can be used to delimit the arguments if the first argument
- begins with
- .BR '+'
- or
- .BR '\-' ,
- or to prevent inadvertent listing of all shell variables when there are
- no arguments. The command
- .IR set
- .BR \-\|\-
- without
- .IR argument
- shall unset all positional parameters and set the special parameter
- .BR '#'
- to zero.
- .SH OPTIONS
- See the DESCRIPTION.
- .SH OPERANDS
- See the DESCRIPTION.
- .SH STDIN
- Not used.
- .SH "INPUT FILES"
- None.
- .SH "ENVIRONMENT VARIABLES"
- None.
- .SH "ASYNCHRONOUS EVENTS"
- Default.
- .SH STDOUT
- See the DESCRIPTION.
- .SH STDERR
- The standard error shall be used only for diagnostic messages.
- .SH "OUTPUT FILES"
- None.
- .SH "EXTENDED DESCRIPTION"
- None.
- .SH "EXIT STATUS"
- .IP "\00" 6
- Successful completion.
- .IP >0 6
- An invalid option was specified, or an error occurred.
- .SH "CONSEQUENCES OF ERRORS"
- Default.
- .LP
- .IR "The following sections are informative."
- .SH "APPLICATION USAGE"
- Application writers should avoid relying on
- .IR set
- .BR \-e
- within functions. For example, in the following script:
- .sp
- .RS 4
- .nf
- set -e
- start() {
- some_server
- echo some_server started successfully
- }
- start || echo >&2 some_server failed
- .fi
- .P
- .RE
- .P
- the
- .BR \-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
- .IR some_server
- fails, the function carries on to echo
- .BR \(dqsome_server started successfully\(dq ,
- and the exit status of the function is zero (which means
- .BR \(dqsome_server failed\(dq
- is not output).
- .SH EXAMPLES
- Write out all variables and their values:
- .sp
- .RS 4
- .nf
- set
- .fi
- .P
- .RE
- .P
- Set $1, $2, and $3 and set
- .BR \(dq$#\(dq
- to 3:
- .sp
- .RS 4
- .nf
- set c a b
- .fi
- .P
- .RE
- .P
- Turn on the
- .BR \-x
- and
- .BR \-v
- options:
- .sp
- .RS 4
- .nf
- set -xv
- .fi
- .P
- .RE
- .P
- Unset all positional parameters:
- .sp
- .RS 4
- .nf
- set --
- .fi
- .P
- .RE
- .P
- Set $1 to the value of
- .IR x ,
- even if it begins with
- .BR '\-'
- or
- .BR '+' :
- .sp
- .RS 4
- .nf
- set -- "$x"
- .fi
- .P
- .RE
- .P
- Set the positional parameters to the expansion of
- .IR x ,
- even if
- .IR x
- expands with a leading
- .BR '\-'
- or
- .BR '+' :
- .sp
- .RS 4
- .nf
- set -- $x
- .fi
- .P
- .RE
- .SH "RATIONALE"
- The
- .IR 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
- .IR set
- \-\|\- form might be misinterpreted as being equivalent to
- .IR set
- without any options or arguments. The functionality of this form has
- been adopted from the KornShell. In System V,
- .IR set
- \-\|\- only unsets parameters if there is at least one argument;
- the only way to unset all parameters is to use
- .IR 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:
- .sp
- .RS 4
- .nf
- set -- "$@"
- .fi
- .P
- .RE
- .P
- and there were in fact no arguments resulting from
- .BR \(dq$@\(dq ,
- unsetting the parameters would have no result.
- .P
- The
- .IR set
- + form in early proposals was omitted as being an unnecessary
- duplication of
- .IR set
- alone and not widespread historical practice.
- .P
- The
- .IR noclobber
- option was changed to allow
- .IR set
- .BR \-C
- as well as the
- .IR set
- .BR \-o
- .IR noclobber
- option. The single-letter version was added so that the historical
- .BR \(dq$-\(dq
- paradigm would not be broken; see
- .IR "Section 2.5.2" ", " "Special Parameters".
- .P
- The description of the
- .BR \-e
- option is intended to match the behavior of the 1988 version of the
- KornShell.
- .P
- The
- .BR \-h
- flag is related to command name hashing. See
- .IR "\fIhash\fR\^".
- .P
- The following
- .IR set
- flags were omitted intentionally with the following rationale:
- .IP "\fB\-k\fP" 6
- The
- .BR \-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
- .IR set
- .IR name =\c
- .IR value
- had to be used to assign values to shell variables. The problem with
- .BR \-k
- is that the behavior affects parsing, virtually precluding writing any
- compilers. To explain the behavior of
- .BR \-k ,
- it is necessary to describe the parsing algorithm, which is
- implementation-defined. For example:
- .RS 6
- .sp
- .RS 4
- .nf
- set -k; echo \fIname\fR=\fIvalue\fR
- .fi
- .P
- .RE
- .P
- and:
- .sp
- .RS 4
- .nf
- set -k
- echo \fIname\fP=\fIvalue\fR
- .fi
- .P
- .RE
- .P
- behave differently. The interaction with functions is even more
- complex. What is more, the
- .BR \-k
- flag is never needed, since the command line could have been
- reordered.
- .RE
- .IP "\fB\-t\fP" 6
- The
- .BR \-t
- flag is hard to specify and almost never used. The only known use could
- be done with here-documents. Moreover, the behavior with
- .IR ksh
- and
- .IR sh
- differs. The reference page says that it exits after reading and
- executing one command. What is one command? If the input is
- .IR date ;\c
- .IR date ,
- .IR sh
- executes both
- .IR date
- commands while
- .IR ksh
- does only the first.
- .P
- Consideration was given to rewriting
- .IR set
- to simplify its confusing syntax. A specific suggestion was that the
- .IR unset
- utility should be used to unset options instead of using the non-\c
- \fIgetopt\fR()\c
- -able +\c
- .IR option
- syntax. However, the conclusion was reached that the historical
- practice of using +\c
- .IR option
- was satisfactory and that there was no compelling reason to modify such
- widespread historical practice.
- .P
- The
- .BR \-o
- option was adopted from the KornShell to address user needs. In
- addition to its generally friendly interface,
- .BR \-o
- is needed to provide the
- .IR 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
- .BR \-o
- provides ample name space for describing such extensions.)
- .P
- Historical implementations are inconsistent in the format used for
- .BR \-o
- option status reporting. The
- .BR +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.
- .P
- Historically,
- .IR sh
- did trace the command
- .IR set
- .BR +x ,
- but
- .IR ksh
- did not.
- .P
- The
- .IR ignoreeof
- setting prevents accidental logouts when the end-of-file character
- (typically
- <control>\(hyD)
- is entered. A user shall explicitly
- .IR exit
- to leave the interactive shell.
- .P
- The
- .IR set
- .BR \-m
- option was added to apply only to the UPE because it applies primarily
- to interactive use, not shell script applications.
- .P
- 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:
- .sp
- .RS 4
- .nf
- trap "jobs -n" CLD
- .fi
- .P
- .RE
- .P
- The C shell provides two different levels of an asynchronous
- notification capability. The environment variable
- .IR notify
- is analogous to what is done in
- .IR set
- .BR \-b
- or
- .IR set
- .BR \-o
- .IR notify .
- When set, it notifies the user immediately of background job
- completions. When unset, this capability is turned off.
- .P
- The other notification ability comes through the built-in utility
- .IR notify .
- The syntax is:
- .sp
- .RS 4
- .nf
- notify \fB[\fR%job ... \fB]\fR
- .fi
- .P
- .RE
- .P
- By issuing
- .IR 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,
- .IR notify
- asynchronously informs the user of changes in the states of the
- specified jobs.
- .P
- To add asynchronous notification to the POSIX shell, neither the
- KornShell extensions to
- .IR trap ,
- nor the C shell
- .IR notify
- environment variable seemed appropriate (\c
- .IR notify
- is not a proper POSIX environment variable name).
- .P
- The
- .IR set
- .BR \-b
- option was selected as a compromise.
- .P
- The
- .IR notify
- built-in was considered to have more functionality than was required
- for simple asynchronous notification.
- .P
- Historically, some shells applied the
- .BR \-u
- option to all parameters including
- .IR $@
- and
- .IR $* .
- The standard developers felt that this was a misfeature since it is
- normal and common for
- .IR $@
- and
- .IR $*
- 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
- .BR \-u
- for its intended purpose of finding spelling mistakes in variable names
- and uses of unset positional parameters.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "Section 2.14" ", " "Special Built-In Utilities",
- .IR "\fIhash\fR\^"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 4.23" ", " "Variable Assignment",
- .IR "Section 12.2" ", " "Utility Syntax Guidelines"
- .\"
- .SH 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 .
- .PP
- 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 .