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

NAME

12       set - set or unset options and positional parameters
13

SYNOPSIS

15       set [-abCefmnuvx][-h][-o option][argument...]
16
17       set [+abCefmnuvx][+h][+o option][argument...]
18
19       set -- [argument...]
20
21       set -o
22
23       set +o
24
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
32              "%s=%s\n", <name>, <value>
33
34       The value string shall be written with  appropriate  quoting;  see  the
35       description  of shell quoting in Quoting . The output shall be suitable
36       for reinput to the shell, setting or resetting, as far as possible, the
37       variables that are currently set; read-only variables 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       IEEE Std 1003.1-2001,  Section  12.2,  Utility Syntax Guidelines except
48       that options can be specified with either  a  leading  hyphen  (meaning
49       enable  the  option) or plus sign (meaning disable it) unless otherwise
50       specified.
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 specified
54       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 IEEE Std 1003.1-2001, Section 4.21,  Vari‐
59              able  Assignment. If the assignment precedes a utility name in a
60              command, the export attribute shall not persist in  the  current
61              execution  environment  after  the  utility  completes, with the
62              exception that preceding one of the special  built-in  utilities
63              causes  the  export  attribute to persist after the built-in has
64              completed. If the assignment does not precede a utility name  in
65              the  command,  or if the assignment is a result of the operation
66              of the getopts or read utilities,  the  export  attribute  shall
67              persist until the variable is unset.
68
69       -b     This  option  shall  be supported if the implementation supports
70              the User Portability Utilities option. It shall cause the  shell
71              to notify the user asynchronously of background job completions.
72              The following message is written to standard error:
73
74
75              "[%d]%c %s%s\n", <job-number>, <current>, <status>, <job-name>
76
77       where the fields shall be as follows:
78
79       <current>
80              The character '+' identifies the job that would  be  used  as  a
81              default  for the fg or bg utilities; this job can also be speci‐
82              fied using the job_id "%+" or "%%" . The character  '-'  identi‐
83              fies  the  job  that  would  become  the  default if the current
84              default job were to exit; this job can also be  specified  using
85              the  job_id  "%-"  . For other jobs, this field is a <space>. At
86              most one job can be identified with '+' and at most one job  can
87              be identified with '-' . If there is any suspended job, then the
88              current job shall be a suspended job. If there are at least  two
89              suspended  jobs, then the previous job also shall be a suspended
90              job.
91
92       <job-number>
93              A number that can be used to identify the process group  to  the
94              wait, fg, bg, and kill utilities. Using these utilities, the job
95              can be identified by prefixing the job number with '%' .
96
97       <status>
98              Unspecified.
99
100       <job-name>
101              Unspecified.
102
103
104       When the shell notifies the user a  job  has  been  completed,  it  may
105       remove the job's process ID from the list of those known in the current
106       shell execution environment;  see  Asynchronous  Lists  .  Asynchronous
107       notification shall not be enabled by default.
108
109       -C     (Uppercase  C.) Prevent existing files from being overwritten by
110              the shell's '>' redirection operator (see Redirecting Output  );
111              the  ">|"  redirection  operator  shall  override this noclobber
112              option for an individual file.
113
114       -e     When this option is on, if a simple command fails for any of the
115              reasons  listed  in  Consequences  of Shell Errors or returns an
116              exit status value >0, and is not part of the compound list  fol‐
117              lowing  a  while,  until, or if keyword, and is not a part of an
118              AND or OR list, and is not a pipeline preceded by the ! reserved
119              word, then the shell shall immediately exit.
120
121       -f     The shell shall disable pathname expansion.
122
123       -h     Locate  and  remember  utilities  invoked  by functions as those
124              functions are defined (the utilities are normally  located  when
125              the function is executed).
126
127       -m     This  option  shall  be supported if the implementation supports
128              the User Portability Utilities option. All jobs shall be run  in
129              their  own process groups. Immediately before the shell issues a
130              prompt after completion of the background job, a message report‐
131              ing  the  exit  status of the background job shall be written to
132              standard error. If a foreground job stops, the shell shall write
133              a  message  to  standard  error  to  that  effect,  formatted as
134              described by the jobs utility.  In addition, if  a  job  changes
135              status other than exiting (for example, if it stops for input or
136              output or is stopped by a SIGSTOP signal), the shell shall write
137              a  similar message immediately prior to writing the next prompt.
138              This option is enabled by default for interactive shells.
139
140       -n     The shell shall read commands but does not  execute  them;  this
141              can be used to check for shell script syntax errors. An interac‐
142              tive shell may ignore this option.
143
144       -o     Write the current settings of the options to standard output  in
145              an unspecified format.
146
147       +o     Write the current option settings to standard output in a format
148              that is suitable for reinput  to  the  shell  as  commands  that
149              achieve the same options settings.
150
151       -o  option
152
153              This  option is supported if the system supports the User Porta‐
154              bility Utilities option. It shall set various options,  many  of
155              which shall be equivalent to the single option letters. The fol‐
156              lowing values of option shall be supported:
157
158       allexport
159              Equivalent to -a.
160
161       errexit
162              Equivalent to -e.
163
164       ignoreeof
165              Prevent an interactive shell from exiting on  end-of-file.  This
166              setting prevents accidental logouts when <control>-D is entered.
167              A user shall explicitly exit to leave the interactive shell.
168
169       monitor
170              Equivalent to -m. This option is supported if  the  system  sup‐
171              ports the User Portability Utilities option.
172
173       noclobber
174              Equivalent to -C (uppercase C).
175
176       noglob
177              Equivalent to -f.
178
179       noexec
180              Equivalent to -n.
181
182       nolog
183              Prevent  the entry of function definitions into the command his‐
184              tory; see Command History List .
185
186       notify
187              Equivalent to -b.
188
189       nounset
190              Equivalent to -u.
191
192       verbose
193              Equivalent to -v.
194
195       vi
196              Allow shell command line editing using the built-in  vi  editor.
197              Enabling  vi  mode  shall disable any other command line editing
198              mode provided as an implementation extension.
199
200              It need not be possible to set vi mode on for certain block-mode
201              terminals.
202
203       xtrace
204              Equivalent to -x.
205
206
207       -u     The  shell shall write a message to standard error when it tries
208              to expand a variable that is not set and  immediately  exit.  An
209              interactive shell shall not exit.
210
211       -v     The shell shall write its input to standard error as it is read.
212
213       -x     The shell shall write to standard error a trace for each command
214              after it expands the command and before it executes  it.  It  is
215              unspecified  whether  the  command  that  turns  tracing  off is
216              traced.
217
218
219       The default for all these options shall be off  (unset)  unless  stated
220       otherwise  in  the  description  of  the option or unless the shell was
221       invoked with them on; see sh.
222
223       The remaining arguments shall be assigned in order  to  the  positional
224       parameters.  The special parameter '#' shall be set to reflect the num‐
225       ber of positional parameters. All positional parameters shall be  unset
226       before any new values are assigned.
227
228       The  special  argument  "--" immediately following the set command name
229       can be used to delimit the arguments if the first argument begins  with
230       '+'  or  '-',  or to prevent inadvertent listing of all shell variables
231       when there are no arguments. The command set -- without argument  shall
232       unset  all  positional  parameters and set the special parameter '#' to
233       zero.
234

OPTIONS

236       See the DESCRIPTION.
237

OPERANDS

239       See the DESCRIPTION.
240

STDIN

242       Not used.
243

INPUT FILES

245       None.
246

ENVIRONMENT VARIABLES

248       None.
249

ASYNCHRONOUS EVENTS

251       Default.
252

STDOUT

254       See the DESCRIPTION.
255

STDERR

257       The standard error shall be used only for diagnostic messages.
258

OUTPUT FILES

260       None.
261

EXTENDED DESCRIPTION

263       None.
264

EXIT STATUS

266       Zero.
267

CONSEQUENCES OF ERRORS

269       Default.
270
271       The following sections are informative.
272

APPLICATION USAGE

274       None.
275

EXAMPLES

277       Write out all variables and their values:
278
279
280              set
281
282       Set $1, $2, and $3 and set "$#" to 3:
283
284
285              set c a b
286
287       Turn on the -x and -v options:
288
289
290              set -xv
291
292       Unset all positional parameters:
293
294
295              set --
296
297       Set $1 to the value of x, even if it begins with '-' or '+' :
298
299
300              set -- "$x"
301
302       Set the positional parameters to the expansion of x, even if x  expands
303       with a leading '-' or '+' :
304
305
306              set -- $x
307

RATIONALE

309       The set -- form is listed specifically in the SYNOPSIS even though this
310       usage is implied by the Utility Syntax Guidelines. The  explanation  of
311       this  feature removes any ambiguity about whether the set -- form might
312       be misinterpreted as being equivalent to set  without  any  options  or
313       arguments.  The  functionality  of  this form has been adopted from the
314       KornShell. In System V, set -- only unsets parameters if  there  is  at
315       least  one  argument;  the  only  way to unset all parameters is to use
316       shift. Using the KornShell version should not affect System  V  scripts
317       because  there should be no reason to issue it without arguments delib‐
318       erately; if it were issued as, for example:
319
320
321              set -- "$@"
322
323       and there were in fact no arguments resulting from "$@", unsetting  the
324       parameters would have no result.
325
326       The  set  + form in early proposals was omitted as being an unnecessary
327       duplication of set alone and not widespread historical practice.
328
329       The noclobber option was changed to allow set -C as well as the set  -o
330       noclobber  option. The single-letter version was added so that the his‐
331       torical "$-" paradigm would not be broken; see Special Parameters .
332
333       The -h flag is related to command name hashing and is only required  on
334       XSI-conformant systems.
335
336       The  following  set flags were omitted intentionally with the following
337       rationale:
338
339       -k     The -k flag was originally added by the  author  of  the  Bourne
340              shell to make it easier for users of pre-release versions of the
341              shell. In early versions of the Bourne shell the  construct  set
342              name=  value had to be used to assign values to shell variables.
343              The problem with -k is that the behavior affects parsing, virtu‐
344              ally  precluding  writing any compilers. To explain the behavior
345              of -k, it is necessary to describe the parsing algorithm,  which
346              is implementation-defined. For example:
347
348
349              set -k; echo name=value
350
351       and:
352
353
354              set -k
355              echo name=value
356
357       behave  differently.  The  interaction with functions is even more com‐
358       plex.  What is more, the -k flag is never  needed,  since  the  command
359       line could have been reordered.
360
361       -t     The  -t  flag is hard to specify and almost never used. The only
362              known use could  be  done  with  here-documents.  Moreover,  the
363              behavior  with  ksh and sh differs. The reference page says that
364              it exits after reading and executing one command.  What  is  one
365              command?  If the input is date; date, sh executes both date com‐
366              mands while ksh does only the first.
367
368
369       Consideration was given to rewriting set to simplify its confusing syn‐
370       tax. A specific suggestion was that the unset utility should be used to
371       unset options instead of using the non- getopt() -able + option syntax.
372       However,  the  conclusion  was  reached that the historical practice of
373       using + option was satisfactory and that there was no compelling reason
374       to modify such widespread historical practice.
375
376       The  -o option was adopted from the KornShell to address user needs. In
377       addition to its generally friendly interface, -o is needed  to  provide
378       the  vi command line editing mode, for which historical practice yields
379       no single-letter option name. (Although it might have been possible  to
380       invent  such a letter, it was recognized that other editing modes would
381       be developed and -o provides  ample  name  space  for  describing  such
382       extensions.)
383
384       Historical  implementations  are inconsistent in the format used for -o
385       option status reporting. The +o format without an  option-argument  was
386       added  to  allow  portable  access to the options that can be saved and
387       then later restored using, for instance, a dot script.
388
389       Historically, sh did trace the command set +x, but ksh did not.
390
391       The ignoreeof setting prevents accidental logouts when the  end-of-file
392       character  (typically  <control>-D) is entered. A user shall explicitly
393       exit to leave the interactive shell.
394
395       The set -m option was added to apply only to the UPE because it applies
396       primarily to interactive use, not shell script applications.
397
398       The  ability  to  do  asynchronous notification became available in the
399       1988 version of the KornShell. To have it occur, the user had to  issue
400       the command:
401
402
403              trap "jobs -n" CLD
404
405       The  C shell provides two different levels of an asynchronous notifica‐
406       tion capability. The environment variable notify is analogous  to  what
407       is  done  in  set  -b  or set -o notify. When set, it notifies the user
408       immediately of background job completions. When unset, this  capability
409       is turned off.
410
411       The  other  notification  ability  comes  through  the built-in utility
412       notify. The syntax is:
413
414
415              notify [%job ... ]
416
417       By issuing notify with no operands, it causes the C shell to notify the
418       user asynchronously when the state of the current job changes. If given
419       operands, notify asynchronously informs the  user  of  changes  in  the
420       states of the specified jobs.
421
422       To  add asynchronous notification to the POSIX shell, neither the Korn‐
423       Shell extensions to trap, nor the C shell notify  environment  variable
424       seemed  appropriate ( notify is not a proper POSIX environment variable
425       name).
426
427       The set -b option was selected as a compromise.
428
429       The notify built-in was considered to have more functionality than  was
430       required for simple asynchronous notification.
431

FUTURE DIRECTIONS

433       None.
434

SEE ALSO

436       Special Built-In Utilities
437
439       Portions  of  this text are reprinted and reproduced in electronic form
440       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
441       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
442       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
443       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
444       event of any discrepancy between this version and the original IEEE and
445       The  Open Group Standard, the original IEEE and The Open Group Standard
446       is the referee document. The original Standard can be  obtained  online
447       at http://www.opengroup.org/unix/online.html .
448
449
450
451IEEE/The Open Group                  2003                              SET(1P)
Impressum