1SET(1P) POSIX Programmer's Manual SET(1P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 set — set or unset options and positional parameters
13
15 set [-abCefhmnuvx] [-o option] [argument...]
16 set [+abCefhmnuvx] [+o option] [argument...]
18 set -- [argument...]
20 set -o
22 set +o
24
26 If no options or arguments are specified, set shall write the names and
27 values of all shell variables in the collation sequence of the current
28 locale. Each name shall start on a separate line, using the format:
29 "%s=%s\n", <name>, <value>
32 The value string shall be written with appropriate quoting; see the
34 description of shell quoting in Section 2.2, Quoting. The output shall
35 be suitable for reinput to the shell, setting or resetting, as far as
36 possible, the variables that are currently set; read-only variables
37 cannot be reset.
38 When options are specified, they shall set or unset attributes of the
40 shell, as described below. When arguments are specified, they cause
41 positional parameters to be set or unset, as described below. Setting
42 or unsetting attributes and positional parameters are not necessarily
43 related actions, but they can be combined in a single invocation of
44 set.
45 The set special built-in shall support the Base Definitions volume of
47 POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines except that
48 options can be specified with either a leading <hyphen-minus> (meaning
49 enable the option) or <plus-sign> (meaning disable it) unless otherwise
50 specified.
51 Implementations shall support the options in the following list in both
53 their <hyphen-minus> and <plus-sign> forms. These options can also be
54 specified as options to sh.
55 -a When this option is on, the export attribute shall be set for
57 each variable to which an assignment is performed; see the Base
58 Definitions volume of POSIX.1‐2017, Section 4.23, Variable
59 Assignment. If the assignment precedes a utility name in a com‐
60 mand, the export attribute shall not persist in the current exe‐
61 cution environment after the utility completes, with the excep‐
62 tion that preceding one of the special built-in utilities causes
63 the export attribute to persist after the built-in has completed.
64 If the assignment does not precede a utility name in the command,
65 or if the assignment is a result of the operation of the getopts
66 or read utilities, the export attribute shall persist until the
67 variable is unset.
68 -b This option shall be supported if the implementation supports the
70 User Portability Utilities option. It shall cause the shell to
71 notify the user asynchronously of background job completions. The
72 following message is written to standard error:
73 "[%d]%c %s%s\n", <job-number>, <current>, <status>, <job-name>
76 where the fields shall be as follows:
78 <current> The character '+' identifies the job that would be
80 used as a default for the fg or bg utilities; this
81 job can also be specified using the job_id "%+" or
82 "%%". The character '-' identifies the job that
83 would become the default if the current default job
84 were to exit; this job can also be specified using
85 the job_id "%-". For other jobs, this field is a
86 <space>. At most one job can be identified with '+'
87 and at most one job can be identified with '-'. If
88 there is any suspended job, then the current job
89 shall be a suspended job. If there are at least two
90 suspended jobs, then the previous job also shall be a
91 suspended job.
92 <job-number>
94 A number that can be used to identify the process
95 group to the wait, fg, bg, and kill utilities. Using
96 these utilities, the job can be identified by prefix‐
97 ing the job number with '%'.
98 <status> Unspecified.
100 <job-name> Unspecified.
102 When the shell notifies the user a job has been completed, it may
104 remove the job's process ID from the list of those known in the
105 current shell execution environment; see Section 2.9.3.1, Exam‐
106 ples. Asynchronous notification shall not be enabled by default.
107 -C (Uppercase C.) Prevent existing files from being overwritten by
109 the shell's '>' redirection operator (see Section 2.7.2, Redi‐
110 recting Output); the ">|" redirection operator shall override
111 this noclobber option for an individual file.
112 -e When this option is on, when any command fails (for any of the
114 reasons listed in Section 2.8.1, Consequences of Shell Errors or
115 by returning an exit status greater than zero), the shell immedi‐
116 ately shall exit, as if by executing the exit special built-in
117 utility with no arguments, with the following exceptions:
118 1. The failure of any individual command in a multi-command
120 pipeline shall not cause the shell to exit. Only the failure
121 of the pipeline itself shall be considered.
122 2. The -e setting shall be ignored when executing the compound
124 list following the while, until, if, or elif reserved word, a
125 pipeline beginning with the ! reserved word, or any command
126 of an AND-OR list other than the last.
127 3. If the exit status of a compound command other than a sub‐
129 shell command was the result of a failure while -e was being
130 ignored, then -e shall not apply to this command.
131 This requirement applies to the shell environment and each sub‐
133 shell environment separately. For example, in:
134 set -e; (false; echo one) | cat; echo two
137 the false command causes the subshell to exit without executing
139 echo one; however, echo two is executed because the exit status
140 of the pipeline (false; echo one) | cat is zero.
141 -f The shell shall disable pathname expansion.
143 -h Locate and remember utilities invoked by functions as those func‐
145 tions are defined (the utilities are normally located when the
146 function is executed).
147 -m This option shall be supported if the implementation supports the
149 User Portability Utilities option. All jobs shall be run in their
150 own process groups. Immediately before the shell issues a prompt
151 after completion of the background job, a message reporting the
152 exit status of the background job shall be written to standard
153 error. If a foreground job stops, the shell shall write a message
154 to standard error to that effect, formatted as described by the
155 jobs utility. In addition, if a job changes status other than
156 exiting (for example, if it stops for input or output or is
157 stopped by a SIGSTOP signal), the shell shall write a similar
158 message immediately prior to writing the next prompt. This option
159 is enabled by default for interactive shells.
160 -n The shell shall read commands but does not execute them; this can
162 be used to check for shell script syntax errors. An interactive
163 shell may ignore this option.
164 -o Write the current settings of the options to standard output in
166 an unspecified format.
167 +o Write the current option settings to standard output in a format
169 that is suitable for reinput to the shell as commands that
170 achieve the same options settings.
171 -o option
173 This option is supported if the system supports the User Porta‐
174 bility Utilities option. It shall set various options, many of
175 which shall be equivalent to the single option letters. The fol‐
176 lowing values of option shall be supported:
177 allexport Equivalent to -a.
179 errexit Equivalent to -e.
181 ignoreeof Prevent an interactive shell from exiting on end-of-
183 file. This setting prevents accidental logouts when
184 <control>‐D is entered. A user shall explicitly exit to
185 leave the interactive shell.
186 monitor Equivalent to -m. This option is supported if the sys‐
188 tem supports the User Portability Utilities option.
189 noclobber Equivalent to -C (uppercase C).
191 noglob Equivalent to -f.
193 noexec Equivalent to -n.
195 nolog Prevent the entry of function definitions into the com‐
197 mand history; see Command History List.
198 notify Equivalent to -b.
200 nounset Equivalent to -u.
202 verbose Equivalent to -v.
204 vi Allow shell command line editing using the built-in vi
206 editor. Enabling vi mode shall disable any other com‐
207 mand line editing mode provided as an implementation
208 extension.
209 It need not be possible to set vi mode on for certain
211 block-mode terminals.
212 xtrace Equivalent to -x.
214 -u When the shell tries to expand an unset parameter other than the
216 '@' and '*' special parameters, it shall write a message to stan‐
217 dard error and the expansion shall fail with the consequences
218 specified in Section 2.8.1, Consequences of Shell Errors.
219 -v The shell shall write its input to standard error as it is read.
221 -x The shell shall write to standard error a trace for each command
223 after it expands the command and before it executes it. It is
224 unspecified whether the command that turns tracing off is traced.
225 The default for all these options shall be off (unset) unless stated
227 otherwise in the description of the option or unless the shell was
228 invoked with them on; see sh.
229 The remaining arguments shall be assigned in order to the positional
231 parameters. The special parameter '#' shall be set to reflect the num‐
232 ber of positional parameters. All positional parameters shall be unset
233 before any new values are assigned.
234 If the first argument is '-', the results are unspecified.
236 The special argument "--" immediately following the set command name
238 can be used to delimit the arguments if the first argument begins with
239 '+' or '-', or to prevent inadvertent listing of all shell variables
240 when there are no arguments. The command set -- without argument shall
241 unset all positional parameters and set the special parameter '#' to
242 zero.
243
245 See the DESCRIPTION.
246
248 See the DESCRIPTION.
249
251 Not used.
252
254 None.
255
257 None.
258
260 Default.
261
263 See the DESCRIPTION.
264
266 The standard error shall be used only for diagnostic messages.
267
269 None.
270
272 None.
273
275 0 Successful completion.
276 >0 An invalid option was specified, or an error occurred.
278
280 Default.
281 The following sections are informative.
283
285 Application writers should avoid relying on set -e within functions.
286 For example, in the following script:
287 set -e
290 start() {
291 some_server
292 echo some_server started successfully
293 }
294 start || echo >&2 some_server failed
295 the -e setting is ignored within the function body (because the func‐
297 tion is a command in an AND-OR list other than the last). Therefore, if
298 some_server fails, the function carries on to echo "some_serverstarted‐
299 successfully", and the exit status of the function is zero (which means
300 "some_serverfailed" is not output).
301
303 Write out all variables and their values:
304 set
307 Set $1, $2, and $3 and set "$#" to 3:
309 set c a b
312 Turn on the -x and -v options:
314 set -xv
317 Unset all positional parameters:
319 set --
322 Set $1 to the value of x, even if it begins with '-' or '+':
324 set -- "$x"
327 Set the positional parameters to the expansion of x, even if x expands
329 with a leading '-' or '+':
330 set -- $x
333
335 The set -- form is listed specifically in the SYNOPSIS even though this
336 usage is implied by the Utility Syntax Guidelines. The explanation of
337 this feature removes any ambiguity about whether the set -- form might
338 be misinterpreted as being equivalent to set without any options or
339 arguments. The functionality of this form has been adopted from the
340 KornShell. In System V, set -- only unsets parameters if there is at
341 least one argument; the only way to unset all parameters is to use
342 shift. Using the KornShell version should not affect System V scripts
343 because there should be no reason to issue it without arguments delib‐
344 erately; if it were issued as, for example:
345 set -- "$@"
348 and there were in fact no arguments resulting from "$@", unsetting the
350 parameters would have no result.
351 The set + form in early proposals was omitted as being an unnecessary
353 duplication of set alone and not widespread historical practice.
354 The noclobber option was changed to allow set -C as well as the set -o
356 noclobber option. The single-letter version was added so that the his‐
357 torical "$-" paradigm would not be broken; see Section 2.5.2, Special
358 Parameters.
359 The description of the -e option is intended to match the behavior of
361 the 1988 version of the KornShell.
362 The -h flag is related to command name hashing. See hash.
364 The following set flags were omitted intentionally with the following
366 rationale:
367 -k The -k flag was originally added by the author of the Bourne
369 shell to make it easier for users of pre-release versions of the
370 shell. In early versions of the Bourne shell the construct set
371 name=value had to be used to assign values to shell variables.
372 The problem with -k is that the behavior affects parsing, virtu‐
373 ally precluding writing any compilers. To explain the behavior of
374 -k, it is necessary to describe the parsing algorithm, which is
375 implementation-defined. For example:
376 set -k; echo name=value
379 and:
381 set -k
384 echo name=value
385 behave differently. The interaction with functions is even more
387 complex. What is more, the -k flag is never needed, since the
388 command line could have been reordered.
389 -t The -t flag is hard to specify and almost never used. The only
391 known use could be done with here-documents. Moreover, the behav‐
392 ior with ksh and sh differs. The reference page says that it
393 exits after reading and executing one command. What is one com‐
394 mand? If the input is date;date, sh executes both date commands
395 while ksh does only the first.
396 Consideration was given to rewriting set to simplify its confusing syn‐
398 tax. A specific suggestion was that the unset utility should be used to
399 unset options instead of using the non-getopt()-able +option syntax.
400 However, the conclusion was reached that the historical practice of
401 using +option was satisfactory and that there was no compelling reason
402 to modify such widespread historical practice.
403 The -o option was adopted from the KornShell to address user needs. In
405 addition to its generally friendly interface, -o is needed to provide
406 the vi command line editing mode, for which historical practice yields
407 no single-letter option name. (Although it might have been possible to
408 invent such a letter, it was recognized that other editing modes would
409 be developed and -o provides ample name space for describing such
410 extensions.)
411 Historical implementations are inconsistent in the format used for -o
413 option status reporting. The +o format without an option-argument was
414 added to allow portable access to the options that can be saved and
415 then later restored using, for instance, a dot script.
416 Historically, sh did trace the command set +x, but ksh did not.
418 The ignoreeof setting prevents accidental logouts when the end-of-file
420 character (typically <control>‐D) is entered. A user shall explicitly
421 exit to leave the interactive shell.
422 The set -m option was added to apply only to the UPE because it applies
424 primarily to interactive use, not shell script applications.
425 The ability to do asynchronous notification became available in the
427 1988 version of the KornShell. To have it occur, the user had to issue
428 the command:
429 trap "jobs -n" CLD
432 The C shell provides two different levels of an asynchronous notifica‐
434 tion capability. The environment variable notify is analogous to what
435 is done in set -b or set -o notify. When set, it notifies the user
436 immediately of background job completions. When unset, this capability
437 is turned off.
438 The other notification ability comes through the built-in utility
440 notify. The syntax is:
441 notify [%job ... ]
444 By issuing notify with no operands, it causes the C shell to notify the
446 user asynchronously when the state of the current job changes. If given
447 operands, notify asynchronously informs the user of changes in the
448 states of the specified jobs.
449 To add asynchronous notification to the POSIX shell, neither the Korn‐
451 Shell extensions to trap, nor the C shell notify environment variable
452 seemed appropriate (notify is not a proper POSIX environment variable
453 name).
454 The set -b option was selected as a compromise.
456 The notify built-in was considered to have more functionality than was
458 required for simple asynchronous notification.
459 Historically, some shells applied the -u option to all parameters
461 including $@ and $*. The standard developers felt that this was a mis‐
462 feature since it is normal and common for $@ and $* to be used in shell
463 scripts regardless of whether they were passed any arguments. Treating
464 these uses as an error when no arguments are passed reduces the value
465 of -u for its intended purpose of finding spelling mistakes in variable
466 names and uses of unset positional parameters.
467
469 None.
470
472 Section 2.14, Special Built-In Utilities, hash
473 The Base Definitions volume of POSIX.1‐2017, Section 4.23, Variable
475 Assignment, Section 12.2, Utility Syntax Guidelines
476
478 Portions of this text are reprinted and reproduced in electronic form
479 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
480 table Operating System Interface (POSIX), The Open Group Base Specifi‐
481 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
482 Electrical and Electronics Engineers, Inc and The Open Group. In the
483 event of any discrepancy between this version and the original IEEE and
484 The Open Group Standard, the original IEEE and The Open Group Standard
485 is the referee document. The original Standard can be obtained online
486 at http://www.opengroup.org/unix/online.html .
487 Any typographical or formatting errors that appear in this page are
489 most likely to have been introduced during the conversion of the source
490 files to man page format. To report such errors, see https://www.ker‐
491 nel.org/doc/man-pages/reporting_bugs.html .
492IEEE/The Open Group 2017 SET(1P)