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 [-abCefmnuvx][-h][-o option][argument...]
16 set [+abCefmnuvx][+h][+o option][argument...]
18 set -- [argument...]
20 set -o
22 set +o
24
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 "%s=%s\n", <name>, <value>
33 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 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 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 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 -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 -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 "[%d]%c %s%s\n", <job-number>, <current>, <status>, <job-name>
76 where the fields shall be as follows:
78 <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 <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 <status>
98 Unspecified.
99 <job-name>
101 Unspecified.
102 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 -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 -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 -f The shell shall disable pathname expansion.
122 -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 -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 -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 -o Write the current settings of the options to standard output in
145 an unspecified format.
146 +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 -o option
152 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 allexport
159 Equivalent to -a.
160 errexit
162 Equivalent to -e.
163 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 monitor
170 Equivalent to -m. This option is supported if the system sup‐
171 ports the User Portability Utilities option.
172 noclobber
174 Equivalent to -C (uppercase C).
175 noglob
177 Equivalent to -f.
178 noexec
180 Equivalent to -n.
181 nolog
183 Prevent the entry of function definitions into the command his‐
184 tory; see Command History List .
185 notify
187 Equivalent to -b.
188 nounset
190 Equivalent to -u.
191 verbose
193 Equivalent to -v.
194 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 It need not be possible to set vi mode on for certain block-mode
201 terminals.
202 xtrace
204 Equivalent to -x.
205 -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 -v The shell shall write its input to standard error as it is read.
212 -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 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 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 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
236 See the DESCRIPTION.
237
239 See the DESCRIPTION.
240
242 Not used.
243
245 None.
246
248 None.
249
251 Default.
252
254 See the DESCRIPTION.
255
257 The standard error shall be used only for diagnostic messages.
258
260 None.
261
263 None.
264
266 Zero.
267
269 Default.
270 The following sections are informative.
272
274 None.
275
277 Write out all variables and their values:
278 set
281 Set $1, $2, and $3 and set "$#" to 3:
283 set c a b
286 Turn on the -x and -v options:
288 set -xv
291 Unset all positional parameters:
293 set --
296 Set $1 to the value of x, even if it begins with '-' or '+' :
298 set -- "$x"
301 Set the positional parameters to the expansion of x, even if x expands
303 with a leading '-' or '+' :
304 set -- $x
307
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 set -- "$@"
322 and there were in fact no arguments resulting from "$@", unsetting the
324 parameters would have no result.
325 The set + form in early proposals was omitted as being an unnecessary
327 duplication of set alone and not widespread historical practice.
328 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 The -h flag is related to command name hashing and is only required on
334 XSI-conformant systems.
335 The following set flags were omitted intentionally with the following
337 rationale:
338 -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 set -k; echo name=value
350 and:
352 set -k
355 echo name=value
356 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 -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 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 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 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 Historically, sh did trace the command set +x, but ksh did not.
390 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 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 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 trap "jobs -n" CLD
404 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 The other notification ability comes through the built-in utility
412 notify. The syntax is:
413 notify [%job ... ]
416 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 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 The set -b option was selected as a compromise.
428 The notify built-in was considered to have more functionality than was
430 required for simple asynchronous notification.
431
433 None.
434
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 .
448IEEE/The Open Group 2003 SET(1P)