1SET(1P)                    POSIX Programmer's Manual                   SET(1P)
2
3
4

PROLOG

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

NAME

13       set — set or unset options and positional parameters
14

SYNOPSIS

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

DESCRIPTION

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

OPTIONS

246       See the DESCRIPTION.
247

OPERANDS

249       See the DESCRIPTION.
250

STDIN

252       Not used.
253

INPUT FILES

255       None.
256

ENVIRONMENT VARIABLES

258       None.
259

ASYNCHRONOUS EVENTS

261       Default.
262

STDOUT

264       See the DESCRIPTION.
265

STDERR

267       The standard error shall be used only for diagnostic messages.
268

OUTPUT FILES

270       None.
271

EXTENDED DESCRIPTION

273       None.
274

EXIT STATUS

276       Zero.
277

CONSEQUENCES OF ERRORS

279       Default.
280
281       The following sections are informative.
282

APPLICATION USAGE

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

EXAMPLES

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

RATIONALE

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

FUTURE DIRECTIONS

456       None.
457

SEE ALSO

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)
Impressum