1SET(1P) POSIX Programmer's Manual SET(1P)
2
3
4
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
11
13 set — set or unset options and positional parameters
14
16 set [−abCefhmnuvx] [−o option] [argument...]
17
18 set [+abCefhmnuvx] [+o option] [argument...]
19
20 set −− [argument...]
21
22 set −o
23
24 set +o
25
27 If no options or arguments are specified, set shall write the names and
28 values of all shell variables in the collation sequence of the current
29 locale. Each name shall start on a separate line, using the format:
30
31 "%s=%s\n", <name>, <value>
32
33 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
39 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
46 The set special built-in shall support the Base Definitions volume of
47 POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines except that
48 options can be specified with either a leading <hyphen> (meaning enable
49 the option) or <plus-sign> (meaning disable it) unless otherwise speci‐
50 fied.
51
52 Implementations shall support the options in the following list in both
53 their <hyphen> and <plus-sign> forms. These options can also be speci‐
54 fied as options to sh.
55
56 −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‐2008, Section 4.22, 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
69 −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
74 "[%d]%c %s%s\n", <job-number>, <current>, <status>, <job-name>
75
76 where the fields shall be as follows:
77
78 <current> The character '+' identifies the job that would be
79 used as a default for the fg or bg utilities; this
80 job can also be specified using the job_id "%+" or
81 "%%". The character '−' identifies the job that
82 would become the default if the current default job
83 were to exit; this job can also be specified using
84 the job_id "%−". For other jobs, this field is a
85 <space>. At most one job can be identified with '+'
86 and at most one job can be identified with '−'. If
87 there is any suspended job, then the current job
88 shall be a suspended job. If there are at least two
89 suspended jobs, then the previous job also shall be a
90 suspended job.
91
92 <job-number>
93 A number that can be used to identify the process
94 group to the wait, fg, bg, and kill utilities. Using
95 these utilities, the job can be identified by prefix‐
96 ing the job number with '%'.
97
98 <status> Unspecified.
99
100 <job-name> Unspecified.
101
102 When the shell notifies the user a job has been completed, it may
103 remove the job's process ID from the list of those known in the
104 current shell execution environment; see Section 2.9.3.1, Exam‐
105 ples. Asynchronous notification shall not be enabled by default.
106
107 −C (Uppercase C.) Prevent existing files from being overwritten by
108 the shell's '>' redirection operator (see Section 2.7.2, Redi‐
109 recting Output); the ">|" redirection operator shall override
110 this noclobber option for an individual file.
111
112 −e When this option is on, when any command fails (for any of the
113 reasons listed in Section 2.8.1, Consequences of Shell Errors or
114 by returning an exit status greater than zero), the shell immedi‐
115 ately shall exit with the following exceptions:
116
117 1. The failure of any individual command in a multi-command
118 pipeline shall not cause the shell to exit. Only the failure
119 of the pipeline itself shall be considered.
120
121 2. The −e setting shall be ignored when executing the compound
122 list following the while, until, if, or elif reserved word, a
123 pipeline beginning with the ! reserved word, or any command
124 of an AND-OR list other than the last.
125
126 3. If the exit status of a compound command other than a sub‐
127 shell command was the result of a failure while −e was being
128 ignored, then −e shall not apply to this command.
129
130 This requirement applies to the shell environment and each sub‐
131 shell environment separately. For example, in:
132
133 set -e; (false; echo one) | cat; echo two
134
135 the false command causes the subshell to exit without executing
136 echo one; however, echo two is executed because the exit status
137 of the pipeline (false; echo one) | cat is zero.
138
139 −f The shell shall disable pathname expansion.
140
141 −h Locate and remember utilities invoked by functions as those func‐
142 tions are defined (the utilities are normally located when the
143 function is executed).
144
145 −m This option shall be supported if the implementation supports the
146 User Portability Utilities option. All jobs shall be run in their
147 own process groups. Immediately before the shell issues a prompt
148 after completion of the background job, a message reporting the
149 exit status of the background job shall be written to standard
150 error. If a foreground job stops, the shell shall write a message
151 to standard error to that effect, formatted as described by the
152 jobs utility. In addition, if a job changes status other than
153 exiting (for example, if it stops for input or output or is
154 stopped by a SIGSTOP signal), the shell shall write a similar
155 message immediately prior to writing the next prompt. This option
156 is enabled by default for interactive shells.
157
158 −n The shell shall read commands but does not execute them; this can
159 be used to check for shell script syntax errors. An interactive
160 shell may ignore this option.
161
162 −o Write the current settings of the options to standard output in
163 an unspecified format.
164
165 +o Write the current option settings to standard output in a format
166 that is suitable for reinput to the shell as commands that
167 achieve the same options settings.
168
169 −o option
170 This option is supported if the system supports the User Porta‐
171 bility Utilities option. It shall set various options, many of
172 which shall be equivalent to the single option letters. The fol‐
173 lowing values of option shall be supported:
174
175 allexport Equivalent to −a.
176
177 errexit Equivalent to −e.
178
179 ignoreeof Prevent an interactive shell from exiting on end-of-
180 file. This setting prevents accidental logouts when
181 <control>‐D is entered. A user shall explicitly exit to
182 leave the interactive shell.
183
184 monitor Equivalent to −m. This option is supported if the sys‐
185 tem supports the User Portability Utilities option.
186
187 noclobber Equivalent to −C (uppercase C).
188
189 noglob Equivalent to −f.
190
191 noexec Equivalent to −n.
192
193 nolog Prevent the entry of function definitions into the com‐
194 mand history; see Command History List.
195
196 notify Equivalent to −b.
197
198 nounset Equivalent to −u.
199
200 verbose Equivalent to −v.
201
202 vi Allow shell command line editing using the built-in vi
203 editor. Enabling vi mode shall disable any other com‐
204 mand line editing mode provided as an implementation
205 extension.
206
207 It need not be possible to set vi mode on for certain
208 block-mode terminals.
209
210 xtrace Equivalent to −x.
211
212 −u When the shell tries to expand an unset parameter other than the
213 '@' and '*' special parameters, it shall write a message to stan‐
214 dard error and shall not execute the command containing the
215 expansion, but for the purposes of setting the '?' special
216 parameter and the exit status of the shell the command shall be
217 treated as having been executed and returned an exit status of
218 between 1 and 125 inclusive. A non-interactive shell shall imme‐
219 diately exit. An interactive shell shall not exit.
220
221 −v The shell shall write its input to standard error as it is read.
222
223 −x The shell shall write to standard error a trace for each command
224 after it expands the command and before it executes it. It is
225 unspecified whether the command that turns tracing off is traced.
226
227 The default for all these options shall be off (unset) unless stated
228 otherwise in the description of the option or unless the shell was
229 invoked with them on; see sh.
230
231 The remaining arguments shall be assigned in order to the positional
232 parameters. The special parameter '#' shall be set to reflect the num‐
233 ber of positional parameters. All positional parameters shall be unset
234 before any new values are assigned.
235
236 If the first argument is '−', the results are unspecified.
237
238 The special argument "−−" immediately following the set command name
239 can be used to delimit the arguments if the first argument begins with
240 '+' or '−', or to prevent inadvertent listing of all shell variables
241 when there are no arguments. The command set −− without argument shall
242 unset all positional parameters and set the special parameter '#' to
243 zero.
244
246 See the DESCRIPTION.
247
249 See the DESCRIPTION.
250
252 Not used.
253
255 None.
256
258 None.
259
261 Default.
262
264 See the DESCRIPTION.
265
267 The standard error shall be used only for diagnostic messages.
268
270 None.
271
273 None.
274
276 Zero.
277
279 Default.
280
281 The following sections are informative.
282
284 Application writers should avoid relying on set −e within functions.
285 For example, in the following script:
286
287 set -e
288 start() {
289 some_server
290 echo some_server started successfully
291 }
292 start || echo >&2 some_server failed
293
294 the −e setting is ignored within the function body (because the func‐
295 tion is a command in an AND-OR list other than the last). Therefore, if
296 some_server fails, the function carries on to echo "some_serverstarted‐
297 successfully", and the exit status of the function is zero (which means
298 "some_serverfailed" is not output).
299
301 Write out all variables and their values:
302
303 set
304
305 Set $1, $2, and $3 and set "$#" to 3:
306
307 set c a b
308
309 Turn on the −x and −v options:
310
311 set −xv
312
313 Unset all positional parameters:
314
315 set −−
316
317 Set $1 to the value of x, even if it begins with '−' or '+':
318
319 set −− "$x"
320
321 Set the positional parameters to the expansion of x, even if x expands
322 with a leading '−' or '+':
323
324 set −− $x
325
327 The set −− form is listed specifically in the SYNOPSIS even though this
328 usage is implied by the Utility Syntax Guidelines. The explanation of
329 this feature removes any ambiguity about whether the set −− form might
330 be misinterpreted as being equivalent to set without any options or
331 arguments. The functionality of this form has been adopted from the
332 KornShell. In System V, set −− only unsets parameters if there is at
333 least one argument; the only way to unset all parameters is to use
334 shift. Using the KornShell version should not affect System V scripts
335 because there should be no reason to issue it without arguments delib‐
336 erately; if it were issued as, for example:
337
338 set −− "$@"
339
340 and there were in fact no arguments resulting from "$@", unsetting the
341 parameters would have no result.
342
343 The set + form in early proposals was omitted as being an unnecessary
344 duplication of set alone and not widespread historical practice.
345
346 The noclobber option was changed to allow set −C as well as the set −o
347 noclobber option. The single-letter version was added so that the his‐
348 torical "$−" paradigm would not be broken; see Section 2.5.2, Special
349 Parameters.
350
351 The description of the −e option is intended to match the behavior of
352 the 1988 version of the KornShell.
353
354 The −h flag is related to command name hashing. See hash.
355
356 The following set flags were omitted intentionally with the following
357 rationale:
358
359 −k The −k flag was originally added by the author of the Bourne
360 shell to make it easier for users of pre-release versions of the
361 shell. In early versions of the Bourne shell the construct set
362 name=value had to be used to assign values to shell variables.
363 The problem with −k is that the behavior affects parsing, virtu‐
364 ally precluding writing any compilers. To explain the behavior of
365 −k, it is necessary to describe the parsing algorithm, which is
366 implementation-defined. For example:
367
368 set −k; echo name=value
369
370 and:
371
372 set −k
373 echo name=value
374
375 behave differently. The interaction with functions is even more
376 complex. What is more, the −k flag is never needed, since the
377 command line could have been reordered.
378
379 −t The −t flag is hard to specify and almost never used. The only
380 known use could be done with here-documents. Moreover, the behav‐
381 ior with ksh and sh differs. The reference page says that it
382 exits after reading and executing one command. What is one com‐
383 mand? If the input is date;date, sh executes both date commands
384 while ksh does only the first.
385
386 Consideration was given to rewriting set to simplify its confusing syn‐
387 tax. A specific suggestion was that the unset utility should be used to
388 unset options instead of using the non-getopt()-able +option syntax.
389 However, the conclusion was reached that the historical practice of
390 using +option was satisfactory and that there was no compelling reason
391 to modify such widespread historical practice.
392
393 The −o option was adopted from the KornShell to address user needs. In
394 addition to its generally friendly interface, −o is needed to provide
395 the vi command line editing mode, for which historical practice yields
396 no single-letter option name. (Although it might have been possible to
397 invent such a letter, it was recognized that other editing modes would
398 be developed and −o provides ample name space for describing such
399 extensions.)
400
401 Historical implementations are inconsistent in the format used for −o
402 option status reporting. The +o format without an option-argument was
403 added to allow portable access to the options that can be saved and
404 then later restored using, for instance, a dot script.
405
406 Historically, sh did trace the command set +x, but ksh did not.
407
408 The ignoreeof setting prevents accidental logouts when the end-of-file
409 character (typically <control>‐D) is entered. A user shall explicitly
410 exit to leave the interactive shell.
411
412 The set −m option was added to apply only to the UPE because it applies
413 primarily to interactive use, not shell script applications.
414
415 The ability to do asynchronous notification became available in the
416 1988 version of the KornShell. To have it occur, the user had to issue
417 the command:
418
419 trap "jobs −n" CLD
420
421 The C shell provides two different levels of an asynchronous notifica‐
422 tion capability. The environment variable notify is analogous to what
423 is done in set −b or set −o notify. When set, it notifies the user
424 immediately of background job completions. When unset, this capability
425 is turned off.
426
427 The other notification ability comes through the built-in utility
428 notify. The syntax is:
429
430 notify [%job ... ]
431
432 By issuing notify with no operands, it causes the C shell to notify the
433 user asynchronously when the state of the current job changes. If given
434 operands, notify asynchronously informs the user of changes in the
435 states of the specified jobs.
436
437 To add asynchronous notification to the POSIX shell, neither the Korn‐
438 Shell extensions to trap, nor the C shell notify environment variable
439 seemed appropriate (notify is not a proper POSIX environment variable
440 name).
441
442 The set −b option was selected as a compromise.
443
444 The notify built-in was considered to have more functionality than was
445 required for simple asynchronous notification.
446
447 Historically, some shells applied the −u option to all parameters
448 including $@ and $*. The standard developers felt that this was a mis‐
449 feature since it is normal and common for $@ and $* to be used in shell
450 scripts regardless of whether they were passed any arguments. Treating
451 these uses as an error when no arguments are passed reduces the value
452 of −u for its intended purpose of finding spelling mistakes in variable
453 names and uses of unset positional parameters.
454
456 None.
457
459 Section 2.14, Special Built-In Utilities, hash
460
461 The Base Definitions volume of POSIX.1‐2008, Section 4.22, Variable
462 Assignment, Section 12.2, Utility Syntax Guidelines
463
465 Portions of this text are reprinted and reproduced in electronic form
466 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
467 -- Portable Operating System Interface (POSIX), The Open Group Base
468 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
469 cal and Electronics Engineers, Inc and The Open Group. (This is
470 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
471 event of any discrepancy between this version and the original IEEE and
472 The Open Group Standard, the original IEEE and The Open Group Standard
473 is the referee document. The original Standard can be obtained online
474 at http://www.unix.org/online.html .
475
476 Any typographical or formatting errors that appear in this page are
477 most likely to have been introduced during the conversion of the source
478 files to man page format. To report such errors, see https://www.ker‐
479 nel.org/doc/man-pages/reporting_bugs.html .
480
481
482
483IEEE/The Open Group 2013 SET(1P)