Debian Codegraph @

upstream/mageia-cauldron/man1/builtins.1

raw
1 .lf 1 ./builtins.1
2 .\" This is a hack to force bash builtins into the whatis database
3 .\" and to get the list of builtins to come up with the man command.
4 .\"
5 .\" File Name macro. This used to be `.PN', for Path Name,
6 .\" but Sun doesn't seem to like that very much.
7 .\"
8 .de FN
9 \fI\|\\$1\|\fP
10 ..
11 .TH BASH_BUILTINS 1 "2023 January 27" "GNU Bash 5.2"
12 .SH NAME
13 :, ., [, alias, bg, bind, break, builtin, caller,
14 cd, command, compgen, complete, compopt,
15 continue, declare, dirs, disown, echo, enable, eval, exec, exit,
16 export, false, fc, fg, getopts, hash, help, history, jobs, kill,
17 let, local, logout, mapfile, popd, printf, pushd, pwd, read,
18 readarray, readonly, return, set,
19 shift, shopt, source, suspend, test, times, trap, true, type, typeset,
20 ulimit, umask, unalias, unset, wait \- bash built-in commands, see \fBbash\fR(1)
21 .SH BASH BUILTIN COMMANDS
22 .nr zZ 1
23 .lf 1 ./bash.1
24 .\"
25 .\" MAN PAGE COMMENTS to
26 .\"
27 .\" Chet Ramey
28 .\" Case Western Reserve University
29 .\" [email protected]
30 .\"
31 .\" Last Change: Mon Apr 7 16:59:13 EDT 2025
32 .\"
33 .\" For bash_builtins, strip all but "SHELL BUILTIN COMMANDS" section
34 .\" For rbash, strip all but "RESTRICTED SHELL" section
35 .\"
36 .\" Both conditionalize text based on the base page being formatted
37 .\" using the zZ and zY registers, respectively
38 .\"
39 .\" Ensure the registers are initialized to avoid groff warnings.
40 .nr zZ +0
41 .nr zY +0
42 .\" Ensure the macros/strings are initialized to avoid groff warnings.
43 .ds zZ \" empty
44 .ds zY \" empty
45 .PP
46 Unless otherwise noted, each builtin command documented in this
47 section as accepting options preceded by
48 .B \-
49 accepts
50 .B \-\-
51 to signify the end of the options.
52 The \fB:\fP, \fBtrue\fP, \fBfalse\fP, and \fBtest\fP/\fB[\fP builtins
53 do not accept options and do not treat \fB\-\-\fP specially.
54 The \fBexit\fP, \fBlogout\fP, \fBreturn\fP,
55 \fBbreak\fP, \fBcontinue\fP, \fBlet\fP,
56 and \fBshift\fP builtins accept and process arguments beginning with
57 \fB\-\fP without requiring \fB\-\-\fP.
58 Other builtins that accept arguments but are not specified as accepting
59 options interpret arguments beginning with \fB\-\fP as invalid options and
60 require \fB\-\-\fP to prevent this interpretation.
61 .PP
62 .PD 0
63 .TP
64 \fB:\fP [\fIarguments\fP]
65 .PD
66 No effect; the command does nothing beyond expanding
67 .I arguments
68 and performing any specified
69 redirections.
70 The return status is zero.
71 .TP
72 \fB\&.\&\fP [\fB\-p\fP \fIpath\fP] \fIfilename\fP [\fIarguments\fP]
73 .PD 0
74 .TP
75 \fBsource\fP [\fB\-p\fP \fIpath\fP] \fIfilename\fP [\fIarguments\fP]
76 .PD
77 The \fB\&.\&\fP command (\fBsource\fP) reads and execute commands from
78 .I filename
79 in the current shell environment and returns the exit status of the
80 last command executed from
81 .IR filename .
82 .IP
83 If \fIfilename\fP does not contain a slash, \fB\&.\&\fP searches for it.
84 If the \fB\-p\fP option is supplied, \fB\&.\&\fP treats \fIpath\fP
85 as a colon-separated list of directories in which to find \fIfilename\fP;
86 otherwise, \fB\&.\&\fP uses the entries in
87 .SM
88 .B PATH
89 to find the directory containing
90 .IR filename .
91 \fIfilename\fP does not need to be executable.
92 When \fBbash\fP is not in posix mode, it searches
93 the current directory if \fIfilename\fP is not found in
94 .SM
95 .BR PATH ,
96 but does not search the current directory if \fB\-p\fP is supplied.
97 If the
98 .B sourcepath
99 option to the
100 .B shopt
101 builtin command is turned off, \fB\&.\&\fP does not search
102 .SM
103 .BR PATH .
104 .IP
105 If any \fIarguments\fP are supplied, they become the positional
106 parameters when \fIfilename\fP is executed.
107 Otherwise the positional parameters are unchanged.
108 .IP
109 If the \fB\-T\fP option is enabled, \fB.\fP inherits any trap on
110 \fBDEBUG\fP; if it is not, any \fBDEBUG\fP trap string is saved and
111 restored around the call to \fB.\fP, and \fB.\fP unsets the
112 \fBDEBUG\fP trap while it executes.
113 If \fB\-T\fP is not set, and the sourced file changes
114 the \fBDEBUG\fP trap, the new value persists after \fB.\fP completes.
115 The return status is the status of the last command executed from
116 \fIfilename\fP (0 if no commands are executed), and non-zero if
117 .I filename
118 is not found or cannot be read.
119 .TP
120 \fBalias\fP [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] .\|.\|.]
121 With no arguments or with the
122 .B \-p
123 option, \fBalias\fP prints the list of aliases in the form
124 \fBalias\fP \fIname\fP=\fIvalue\fP on standard output.
125 When arguments are supplied, define an alias for
126 each \fIname\fP whose \fIvalue\fP is given.
127 A trailing space in \fIvalue\fP causes the next word to be
128 checked for alias substitution when the alias is expanded
129 during command parsing.
130 For each \fIname\fP in the argument list for which no \fIvalue\fP
131 is supplied, print the name and value of the alias \fIname\fP.
132 \fBalias\fP returns true unless a \fIname\fP is given
133 (without a corresponding =\fIvalue\fP)
134 for which no alias has been defined.
135 .TP
136 \fBbg\fP [\fIjobspec\fP .\|.\|.]
137 Resume each suspended job \fIjobspec\fP in the background, as if it
138 had been started with
139 .BR & .
140 If
141 .I jobspec
142 is not present, the shell uses its notion of the \fIcurrent job\fP.
143 .B bg
144 .I jobspec
145 returns 0 unless run when job control is disabled or, when run with
146 job control enabled, any specified \fIjobspec\fP was not found
147 or was started without job control.
148 .TP
149 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-lsvSVX\fP]
150 .PD 0
151 .TP
152 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-q\fP \fIfunction\fP] [\fB\-u\fP \fIfunction\fP] [\fB\-r\fP \fIkeyseq\fP]
153 .TP
154 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB\-f\fP \fIfilename\fP
155 .TP
156 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB\-x\fP \fIkeyseq\fP[:] \fIshell\-command\fP
157 .TP
158 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fIkeyseq\fP:\fIfunction\-name\fP
159 .TP
160 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB\-p\fP|\fB\-P\fP [\fIreadline\-command\fP]
161 .TP
162 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fIkeyseq\fP:\fIreadline\-command\fP
163 .TP
164 \fBbind\fP \fIreadline-command-line\fP
165 .PD
166 Display current
167 .B readline
168 key and function bindings, bind a key sequence to a
169 .B readline
170 function or macro
171 or to a shell command, or set a
172 .B readline
173 variable.
174 Each non-option argument is a key binding or command as it would appear in a
175 .B readline
176 initialization file such as
177 .IR .inputrc ,
178 but each binding or command must be passed as a separate argument;
179 e.g., \*'\*"\eC\-x\eC\-r\*": re\-read\-init\-file\*'.
180 In the following descriptions, output available to be re-read is formatted
181 as commands that would appear in a
182 .B readline
183 initialization file or that would be supplied as individual arguments to a
184 .B bind
185 command.
186 Options, if supplied, have the following meanings:
187 .RS
188 .PD 0
189 .TP
190 .B \-m \fIkeymap\fP
191 Use
192 .I keymap
193 as the keymap to be affected by the subsequent bindings.
194 Acceptable
195 .I keymap
196 names are
197 \fIemacs, emacs\-standard, emacs\-meta, emacs\-ctlx, vi,
198 vi\-move, vi\-command\fP, and
199 .IR vi\-insert .
200 \fIvi\fP is equivalent to \fIvi\-command\fP
201 (\fIvi\-move\fP is also a synonym);
202 \fIemacs\fP is equivalent to \fIemacs\-standard\fP.
203 .TP
204 .B \-l
205 List the names of all \fBreadline\fP functions.
206 .TP
207 .B \-p
208 Display \fBreadline\fP function names and bindings in such a way
209 that they can be
210 used as an argument to a subsequent
211 \fBbind\fP command or in a \fBreadline\fP initialization file.
212 If arguments remain after option processing, \fBbind\fP treats
213 them as \fBreadline\fP command names and restricts output to those names.
214 .TP
215 .B \-P
216 List current \fBreadline\fP function names and bindings.
217 If arguments remain after option processing, \fBbind\fP treats
218 them as \fBreadline\fP command names and restricts output to those names.
219 .TP
220 .B \-s
221 Display \fBreadline\fP key sequences bound to macros and the strings
222 they output in such a way that they can be used
223 as an argument to a subsequent \fBbind\fP command
224 or in a \fBreadline\fP initialization file.
225 .TP
226 .B \-S
227 Display \fBreadline\fP key sequences bound to macros and the strings
228 they output.
229 .TP
230 .B \-v
231 Display \fBreadline\fP variable names and values in such a way that they
232 can be
233 used as an argument to a subsequent
234 \fBbind\fP command or in a \fBreadline\fP initialization file.
235 .TP
236 .B \-V
237 List current \fBreadline\fP variable names and values.
238 .TP
239 .B \-f \fIfilename\fP
240 Read key bindings from \fIfilename\fP.
241 .TP
242 .B \-q \fIfunction\fP
243 Display key sequences that invoke the named \fBreadline\fP \fIfunction\fP.
244 .TP
245 .B \-u \fIfunction\fP
246 Unbind all key sequences bound to the named \fBreadline\fP \fIfunction\fP.
247 .TP
248 .B \-r \fIkeyseq\fP
249 Remove any current binding for \fIkeyseq\fP.
250 .TP
251 .B \-x \fIkeyseq\fP[: ]\fIshell\-command\fP
252 Cause \fIshell\-command\fP to be executed whenever \fIkeyseq\fP is
253 entered.
254 The separator between \fIkeyseq\fP and \fIshell\-command\fP is either
255 whitespace or a colon optionally followed by whitespace.
256 If the separator is whitespace, \fIshell\-command\fP
257 must be enclosed in double quotes and \fBreadline\fP expands any of its
258 special backslash-escapes in \fIshell\-command\fP before saving it.
259 If the separator is a colon, any enclosing double quotes are optional, and
260 \fBreadline\fP does not expand the command string before saving it.
261 Since the entire key binding expression must be a single argument, it
262 should be enclosed in single quotes.
263 When \fIshell\-command\fP is executed, the shell sets the
264 .SM
265 .B READLINE_LINE
266 variable to the contents of the \fBreadline\fP line buffer and the
267 .SM
268 .B READLINE_POINT
269 and
270 .SM
271 .B READLINE_MARK
272 variables to the current location of the insertion point and the saved
273 insertion point (the mark), respectively.
274 The shell assigns any numeric argument the user supplied to the
275 .SM
276 .B READLINE_ARGUMENT
277 variable.
278 If there was no argument, that variable is not set.
279 If the executed command changes the value of any of
280 .SM
281 .BR READLINE_LINE ,
282 .SM
283 .BR READLINE_POINT ,
284 or
285 .SM
286 .BR READLINE_MARK ,
287 those new values will be reflected in the editing state.
288 .TP
289 .B \-X
290 List all key sequences bound to shell commands and the associated commands
291 in a format that can be reused as
292 an argument to a subsequent \fBbind\fP command.
293 .PD
294 .PP
295 The return value is 0 unless an unrecognized option is supplied or an
296 error occurred.
297 .RE
298 .TP
299 \fBbreak\fP [\fIn\fP]
300 Exit from within a
301 .BR for ,
302 .BR while ,
303 .BR until ,
304 or
305 .B select
306 loop.
307 If \fIn\fP is specified, \fBbreak\fP exits \fIn\fP enclosing loops.
308 .I n
309 must be \(>= 1. If
310 .I n
311 is greater than the number of enclosing loops, all enclosing loops
312 are exited.
313 The return value is 0 unless \fIn\fP is not greater than or equal to 1.
314 .TP
315 \fBbuiltin\fP \fIshell\-builtin\fP [\fIarguments\fP]
316 Execute the specified shell builtin \fIshell\-builtin\fP, passing it
317 .IR arguments ,
318 and return its exit status.
319 This is useful when defining a
320 function whose name is the same as a shell builtin,
321 retaining the functionality of the builtin within the function.
322 The \fBcd\fP builtin is commonly redefined this way.
323 The return status is false if
324 .I shell\-builtin
325 is not a shell builtin command.
326 .TP
327 \fBcaller\fP [\fIexpr\fP]
328 Returns the context of any active subroutine call (a shell function or
329 a script executed with the \fB.\fP or \fBsource\fP builtins).
330 .IP
331 Without \fIexpr\fP, \fBcaller\fP displays the line number and source
332 filename of the current subroutine call.
333 If a non-negative integer is supplied as \fIexpr\fP, \fBcaller\fP
334 displays the line number, subroutine name, and source file corresponding
335 to that position in the current execution call stack.
336 This extra information may be used, for example, to print a stack trace.
337 The current frame is frame 0.
338 .IP
339 The return value is 0 unless the shell is not executing a subroutine
340 call or \fIexpr\fP does not correspond to a valid position in the
341 call stack.
342 .TP
343 .PD 0
344 \fBcd\fP [\fB\-L\fP] [\fB\-@\fP] [\fIdir\fP]
345 .TP
346 \fBcd\fP \fB\-P\fP [\fB\-e\fP] [\fB\-@\fP] [\fIdir\fP]
347 .PD
348 Change the current directory to \fIdir\fP.
349 if \fIdir\fP is not supplied, the value of the
350 .SM
351 .B HOME
352 shell variable is used as \fIdir\fP.
353 The variable
354 .SM
355 .B CDPATH
356 exists,
357 and \fIdir\fP does not begin with a slash (/),
358 \fBcd\fP uses it as a search path:
359 the shell searches each directory name in
360 .SM
361 .B CDPATH
362 for \fIdir\fP.
363 Alternative directory names in
364 .SM
365 .B CDPATH
366 are separated by a colon (:).
367 A null directory name in
368 .SM
369 .B CDPATH
370 is the same as the current directory, i.e.,
371 .Q .\& .
372 .IP
373 The
374 .B \-P
375 option causes \fBcd\fP to use the physical directory structure
376 by resolving symbolic links while traversing \fIdir\fP and
377 before processing instances of
378 .FN .\|.\&
379 in \fIdir\fP (see also the
380 .B \-P
381 option to the
382 .B set
383 builtin command).
384 .IP
385 The
386 .B \-L
387 option forces \fBcd\fP to follow symbolic links by resolving the link
388 after processing instances of
389 .FN .\|.\&
390 in \fIdir\fP.
391 If
392 .FN .\|.\&
393 appears in \fIdir\fP, \fBcd\fP processes it by removing the
394 immediately previous pathname component from \fIdir\fP, back to a slash
395 or the beginning of \fIdir\fP,
396 and verifying that the portion of \fIdir\fP it has processed to
397 that point is still a valid directory name after removing the pathname
398 component.
399 If it is not a valid directory name, \fBcd\fP returns a non-zero status.
400 If neither
401 .B \-L
402 nor
403 .B \-P
404 is supplied,
405 .B cd
406 behaves as if
407 .B \-L
408 had been supplied.
409 .IP
410 If the
411 .B \-e
412 option is supplied with
413 .BR \-P ,
414 and \fBcd\fP cannot successfully determine the current working directory
415 after a successful directory change, it returns a non-zero status.
416 .IP
417 On systems that support it, the \fB\-@\fP option presents the extended
418 attributes associated with a file as a directory.
419 .IP
420 An argument of
421 .B \-
422 is converted to
423 .SM
424 .B $OLDPWD
425 before attempting the directory change.
426 .IP
427 If \fBcd\fP uses a non-empty directory name from
428 .SM
429 .BR CDPATH ,
430 or if \fB\-\fP is the first argument, and the directory change is
431 successful, \fBcd\fP writes the absolute pathname of the new
432 working directory to the standard output.
433 .IP
434 If the directory change is successful, \fBcd\fP sets the value of the
435 \fBPWD\fP environment variable to the new directory name, and sets the
436 \fBOLDPWD\fP environment variable to the value of the current working
437 directory before the change.
438 .IP
439 The return value is true if the directory was successfully changed;
440 false otherwise.
441 .TP
442 \fBcommand\fP [\fB\-pVv\fP] \fIcommand\fP [\fIarg\fP .\|.\|.]
443 The \fBcommand\fP builtin runs
444 .I command
445 with
446 .I args
447 suppressing the normal shell function lookup for \fIcommand\fP.
448 Only builtin commands or commands found in the
449 .SM
450 .B PATH
451 named \fIcommand\fP are executed.
452 If the
453 .B \-p
454 option is supplied, the search for
455 .I command
456 is performed using a default value for
457 .SM
458 .B PATH
459 that is guaranteed to find all of the standard utilities.
460 .IP
461 If either the
462 .B \-V
463 or
464 .B \-v
465 option is supplied, \fBcommand\fP prints a description of
466 .IR command .
467 The
468 .B \-v
469 option displays a single word indicating the command or filename
470 used to invoke
471 .IR command ;
472 the
473 .B \-V
474 option produces a more verbose description.
475 .IP
476 If the
477 .B \-V
478 or
479 .B \-v
480 option is supplied, the exit status is zero if
481 .I command
482 was found, and non-zero if not.
483 If neither option is supplied and an error occurred or
484 .I command
485 cannot be found, the exit status is 127.
486 Otherwise, the exit status of the
487 .B command
488 builtin is the exit status of
489 .IR command .
490 .TP
491 \fBcompgen\fP [\fB\-V\fP \fIvarname\fP] [\fIoption\fP] [\fIword\fP]
492 Generate possible completion matches for \fIword\fP according to
493 the \fIoption\fPs, which may be any option accepted by the
494 .B complete
495 builtin with the exceptions of
496 .BR \-p ,
497 .BR \-r ,
498 .BR \-D ,
499 .BR \-E ,
500 and
501 .BR \-I ,
502 and write the matches to the standard output.
503 .IP
504 If the \fB\-V\fP option is supplied, \fBcompgen\fP stores the generated
505 completions into the indexed array variable \fIvarname\fP instead of writing
506 them to the standard output.
507 .IP
508 When using the \fB\-F\fP or \fB\-C\fP options, the various shell variables
509 set by the programmable completion facilities, while available, will not
510 have useful values.
511 .IP
512 The matches will be generated in the same way as if the programmable
513 completion code had generated them directly from a completion specification
514 with the same flags.
515 If \fIword\fP is specified, only those completions matching \fIword\fP
516 will be displayed or stored.
517 .IP
518 The return value is true unless an invalid option is supplied, or no
519 matches were generated.
520 .TP
521 \fBcomplete\fP [\fB\-abcdefgjksuv\fP] [\fB\-o\fP \fIcomp-option\fP] [\fB\-DEI\fP] [\fB\-A\fP \fIaction\fP]
522 .br
523 [\fB\-G\fP \fIglobpat\fP] [\fB\-W\fP \fIwordlist\fP] [\fB\-F\fP \fIfunction\fP] [\fB\-C\fP \fIcommand\fP]
524 .br
525 [\fB\-X\fP \fIfilterpat\fP] [\fB\-P\fP \fIprefix\fP] \
526 [\fB\-S\fP \fIsuffix\fP] \fIname\fP [\fIname\fP .\|.\|.]
527 .PD 0
528 .TP
529 \fBcomplete\fP \fB\-pr\fP [\fB\-DEI\fP] [\fIname\fP .\|.\|.]
530 .PD
531 Specify how arguments to each \fIname\fP should be completed.
532 .IP
533 If the \fB\-p\fP option is supplied, or if no options or \fIname\fPs
534 are supplied, print existing completion specifications
535 in a way that allows them to be reused as input.
536 The \fB\-r\fP option removes a completion specification for
537 each \fIname\fP, or, if no \fIname\fPs are supplied, all
538 completion specifications.
539 .IP
540 The \fB\-D\fP option indicates that other supplied options and actions should
541 apply to the
542 .Q default
543 command completion; that is, completion attempted
544 on a command for which no completion has previously been defined.
545 The \fB\-E\fP option indicates that other supplied options and actions should
546 apply to
547 .Q empty
548 command completion; that is, completion attempted on a
549 blank line.
550 The \fB\-I\fP option indicates that other supplied options and actions should
551 apply to completion on the initial non-assignment word on the line, or after
552 a command delimiter such as \fB;\fP or \fB|\fP, which is usually command
553 name completion.
554 If multiple options are supplied, the \fB\-D\fP option takes precedence
555 over \fB\-E\fP, and both take precedence over \fB\-I\fP.
556 If any of \fB\-D\fP, \fB\-E\fP, or \fB\-I\fP are supplied, any other
557 \fIname\fP arguments are ignored; these completions only apply to the case
558 specified by the option.
559 .IP
560 The process of applying these completion specifications when
561 attempting word completion is described
562 .ie \n(zZ=1 in \fIbash\fP(1).
563 .el above under \fBProgrammable Completion\fP.
564 .IP
565 Other options, if specified, have the following meanings.
566 The arguments to the \fB\-G\fP, \fB\-W\fP, and \fB\-X\fP options
567 (and, if necessary, the \fB\-P\fP and \fB\-S\fP options)
568 should be quoted to protect them from expansion before the
569 .B complete
570 builtin is invoked.
571 .IP
572 .RS
573 .PD 0
574 .TP 8
575 \fB\-o\fP \fIcomp-option\fP
576 The \fIcomp-option\fP controls several aspects of the compspec's behavior
577 beyond the simple generation of completions.
578 \fIcomp-option\fP may be one of:
579 .RS
580 .TP 8
581 .B bashdefault
582 Perform the rest of the default \fBbash\fP completions if the compspec
583 generates no matches.
584 .TP 8
585 .B default
586 Use \fBreadline\fP's default filename completion if the compspec generates
587 no matches.
588 .TP 8
589 .B dirnames
590 Perform directory name completion if the compspec generates no matches.
591 .TP 8
592 .B filenames
593 Tell \fBreadline\fP that the compspec generates filenames, so it can perform
594 any filename\-specific processing (such as adding a slash to directory names,
595 quoting special characters, or suppressing trailing spaces).
596 This is intended to be used with shell functions.
597 .TP 8
598 .B fullquote
599 Tell \fBreadline\fP to quote all the completed words even if they are not
600 filenames.
601 .TP 8
602 .B noquote
603 Tell \fBreadline\fP not to quote the completed words if they are filenames
604 (quoting filenames is the default).
605 .TP 8
606 .B nosort
607 Tell \fBreadline\fP not to sort the list of possible completions
608 alphabetically.
609 .TP 8
610 .B nospace
611 Tell \fBreadline\fP not to append a space (the default) to words completed
612 at the end of the line.
613 .TP 8
614 .B plusdirs
615 After generating any matches defined by the compspec,
616 attempt directory name completion and add any
617 matches to the results of the other actions.
618 .RE
619 .TP 8
620 \fB\-A\fP \fIaction\fP
621 The \fIaction\fP may be one of the following to generate a list of possible
622 completions:
623 .RS
624 .TP 8
625 .B alias
626 Alias names.
627 May also be specified as \fB\-a\fP.
628 .TP 8
629 .B arrayvar
630 Array variable names.
631 .TP 8
632 .B binding
633 \fBReadline\fP key binding names.
634 .TP 8
635 .B builtin
636 Names of shell builtin commands.
637 May also be specified as \fB\-b\fP.
638 .TP 8
639 .B command
640 Command names.
641 May also be specified as \fB\-c\fP.
642 .TP 8
643 .B directory
644 Directory names.
645 May also be specified as \fB\-d\fP.
646 .TP 8
647 .B disabled
648 Names of disabled shell builtins.
649 .TP 8
650 .B enabled
651 Names of enabled shell builtins.
652 .TP 8
653 .B export
654 Names of exported shell variables.
655 May also be specified as \fB\-e\fP.
656 .TP 8
657 .B file
658 File and directory names, similar to \fBreadline\fP's filename completion.
659 May also be specified as \fB\-f\fP.
660 .TP 8
661 .B function
662 Names of shell functions.
663 .TP 8
664 .B group
665 Group names.
666 May also be specified as \fB\-g\fP.
667 .TP 8
668 .B helptopic
669 Help topics as accepted by the \fBhelp\fP builtin.
670 .TP 8
671 .B hostname
672 Hostnames, as taken from the file specified by the
673 .SM
674 .B HOSTFILE
675 shell variable.
676 .TP 8
677 .B job
678 Job names, if job control is active.
679 May also be specified as \fB\-j\fP.
680 .TP 8
681 .B keyword
682 Shell reserved words.
683 May also be specified as \fB\-k\fP.
684 .TP 8
685 .B running
686 Names of running jobs, if job control is active.
687 .TP 8
688 .B service
689 Service names.
690 May also be specified as \fB\-s\fP.
691 .TP 8
692 .B setopt
693 Valid arguments for the \fB\-o\fP option to the \fBset\fP builtin.
694 .TP 8
695 .B shopt
696 Shell option names as accepted by the \fBshopt\fP builtin.
697 .TP 8
698 .B signal
699 Signal names.
700 .TP 8
701 .B stopped
702 Names of stopped jobs, if job control is active.
703 .TP 8
704 .B user
705 User names.
706 May also be specified as \fB\-u\fP.
707 .TP 8
708 .B variable
709 Names of all shell variables.
710 May also be specified as \fB\-v\fP.
711 .RE
712 .TP 8
713 \fB\-C\fP \fIcommand\fP
714 \fIcommand\fP is executed in a subshell environment, and its output is
715 used as the possible completions.
716 Arguments are passed as with the \fB\-F\fP option.
717 .TP 8
718 \fB\-F\fP \fIfunction\fP
719 The shell function \fIfunction\fP is executed in the current shell
720 environment.
721 When the function is executed,
722 the first argument (\fB$1\fP) is the name of the command whose arguments are
723 being completed,
724 the second argument (\fB$2\fP) is the word being completed, and
725 the third argument (\fB$3\fP) is the word preceding the word being
726 completed on the current command line.
727 When \fIfunction\fP finishes,
728 programmable completion retrieves
729 the possible completions from the value of the
730 .SM
731 .B COMPREPLY
732 array variable.
733 .TP 8
734 \fB\-G\fP \fIglobpat\fP
735 Expand the pathname expansion pattern \fIglobpat\fP to generate
736 the possible completions.
737 .TP 8
738 \fB\-P\fP \fIprefix\fP
739 Add \fIprefix\fP to the beginning of each possible completion
740 after all other options have been applied.
741 .TP 8
742 \fB\-S\fP \fIsuffix\fP
743 Append \fIsuffix\fP to each possible completion
744 after all other options have been applied.
745 .TP 8
746 \fB\-W\fP \fIwordlist\fP
747 Split the \fIwordlist\fP using the characters in the
748 .SM
749 .B IFS
750 special variable as delimiters, and expand each resulting word.
751 Shell quoting is honored within \fIwordlist\fP,
752 in order to provide a
753 mechanism for the words to contain shell metacharacters or characters
754 in the value of
755 .SM
756 .BR IFS .
757 The possible completions are the members of the resultant list which
758 match a prefix of the word being completed.
759 .TP 8
760 \fB\-X\fP \fIfilterpat\fP
761 \fIfilterpat\fP is a pattern as used for pathname expansion.
762 It is applied to the list of possible completions generated by the
763 preceding options and arguments, and each completion matching
764 \fIfilterpat\fP is removed from the list.
765 A leading \fB!\fP in \fIfilterpat\fP negates the pattern; in this
766 case, any completion not matching \fIfilterpat\fP is removed.
767 .PD
768 .PP
769 The return value is true unless an invalid option is supplied, an option
770 other than
771 .BR \-p ,
772 .BR \-r ,
773 .BR \-D ,
774 .BR \-E ,
775 or
776 .B \-I
777 is supplied without a \fIname\fP
778 argument, an attempt is made to remove a completion specification for
779 a \fIname\fP for which no specification exists, or
780 an error occurs adding a completion specification.
781 .RE
782 .TP
783 \fBcompopt\fP [\fB\-o\fP \fIoption\fP] [\fB\-DEI\fP] [\fB+o\fP \fIoption\fP] [\fIname\fP]
784 Modify completion options for each \fIname\fP according to the
785 \fIoption\fPs, or for the
786 currently-executing completion if no \fIname\fPs are supplied.
787 If no \fIoption\fPs are supplied, display the completion options for each
788 \fIname\fP or the current completion.
789 The possible values of \fIoption\fP are those valid for the \fBcomplete\fP
790 builtin described above.
791 .IP
792 The \fB\-D\fP option indicates that other supplied options should
793 apply to the
794 .Q default
795 command completion;
796 the \fB\-E\fP option indicates that other supplied options should
797 apply to
798 .Q empty
799 command completion; and
800 the \fB\-I\fP option indicates that other supplied options should
801 apply to completion on the initial word on the line.
802 These are determined in the same way as the \fBcomplete\fP builtin.
803 .IP
804 If multiple options are supplied, the \fB\-D\fP option takes precedence
805 over \fB\-E\fP, and both take precedence over \fB\-I\fP.
806 .IP
807 The return value is true unless an invalid option is supplied, an attempt
808 is made to modify the options for a \fIname\fP for which no completion
809 specification exists, or an output error occurs.
810 .TP
811 \fBcontinue\fP [\fIn\fP]
812 \fBcontinue\fP resumes the next iteration of the enclosing
813 .BR for ,
814 .BR while ,
815 .BR until ,
816 or
817 .B select
818 loop.
819 If
820 .I n
821 is specified, \fBbash\fP resumes the \fIn\fPth enclosing loop.
822 .I n
823 must be \(>= 1.
824 If
825 .I n
826 is greater than the number of enclosing loops, the shell resumes
827 the last enclosing loop
828 (the
829 .Q top-level
830 loop).
831 The return value is 0 unless \fIn\fP is not greater than or equal to 1.
832 .TP
833 \fBdeclare\fP [\fB\-aAfFgiIlnrtux\fP] [\fB\-p\fP] \
834 [\fIname\fP[=\fIvalue\fP] .\|.\|.]
835 .PD 0
836 .TP
837 \fBtypeset\fP [\fB\-aAfFgiIlnrtux\fP] [\fB\-p\fP] \
838 [\fIname\fP[=\fIvalue\fP] .\|.\|.]
839 .PD
840 Declare variables and/or give them attributes.
841 If no \fIname\fPs are given then display the values of variables
842 or functions.
843 The
844 .B \-p
845 option will display the attributes and values of each
846 .IR name .
847 When
848 .B \-p
849 is used with \fIname\fP arguments, additional options,
850 other than \fB\-f\fP and \fB\-F\fP, are ignored.
851 .IP
852 When
853 .B \-p
854 is supplied without \fIname\fP arguments,
855 \fBdeclare\fP will display the attributes and values
856 of all variables having the attributes specified by the additional options.
857 If no other options are supplied with \fB\-p\fP, \fBdeclare\fP will
858 display the attributes and values of all shell variables.
859 The \fB\-f\fP option restricts the display to shell functions.
860 .IP
861 The
862 .B \-F
863 option inhibits the display of function definitions; only the
864 function name and attributes are printed.
865 If the \fBextdebug\fP shell option is enabled using \fBshopt\fP,
866 the source file name and line number where each \fIname\fP
867 is defined are displayed as well.
868 The
869 .B \-F
870 option implies
871 .BR \-f .
872 .IP
873 The
874 .B \-g
875 option forces variables to be created or modified at the global scope,
876 even when \fBdeclare\fP is executed in a shell function.
877 It is ignored when \fBdeclare\fP is not executed in a shell function.
878 .IP
879 The
880 .B \-I
881 option causes local variables to inherit the attributes
882 (except the \fInameref\fP attribute)
883 and value of any existing variable with the same
884 \fIname\fP at a surrounding scope.
885 If there is no existing variable, the local variable is initially unset.
886 .IP
887 The following options can
888 be used to restrict output to variables with the specified attribute or
889 to give variables attributes:
890 .RS
891 .PD 0
892 .TP
893 .B \-a
894 Each \fIname\fP is an indexed array variable (see
895 .B Arrays
896 .ie \n(zZ=1 in \fIbash\fP(1)).
897 .el above).
898 .TP
899 .B \-A
900 Each \fIname\fP is an associative array variable (see
901 .B Arrays
902 .ie \n(zZ=1 in \fIbash\fP(1)).
903 .el above).
904 .TP
905 .B \-f
906 Each \fIname\fP refers to a shell function.
907 .TP
908 .B \-i
909 The variable is treated as an integer;
910 arithmetic evaluation (see
911 .SM
912 .B "ARITHMETIC EVALUATION"
913 .ie \n(zZ=1 in \fIbash\fP(1))
914 .el above)
915 is performed when the variable is assigned a value.
916 .TP
917 .B \-l
918 When the variable is assigned a value, all upper-case characters are
919 converted to lower-case.
920 The upper-case attribute is disabled.
921 .TP
922 .B \-n
923 Give each \fIname\fP the \fInameref\fP attribute, making
924 it a name reference to another variable.
925 That other variable is defined by the value of \fIname\fP.
926 All references, assignments, and attribute modifications
927 to \fIname\fP, except those using or changing the
928 \fB\-n\fP attribute itself, are performed on the variable referenced by
929 \fIname\fP's value.
930 The nameref attribute cannot be applied to array variables.
931 .TP
932 .B \-r
933 Make \fIname\fPs readonly.
934 These names cannot then be assigned values
935 by subsequent assignment statements or unset.
936 .TP
937 .B \-t
938 Give each \fIname\fP the \fItrace\fP attribute.
939 Traced functions inherit the \fBDEBUG\fP and \fBRETURN\fP traps from
940 the calling shell.
941 The trace attribute has no special meaning for variables.
942 .TP
943 .B \-u
944 When the variable is assigned a value, all lower-case characters are
945 converted to upper-case.
946 The lower-case attribute is disabled.
947 .TP
948 .B \-x
949 Mark each \fIname\fP for export to subsequent commands via the environment.
950 .PD
951 .PP
952 Using
953 .Q +
954 instead of
955 .Q \-
956 turns off the specified
957 attribute instead, with the exceptions that \fB+a\fP and \fB+A\fP
958 may not be used to destroy array variables and \fB+r\fP will not
959 remove the readonly attribute.
960 .PP
961 When used in a function,
962 .B declare
963 and
964 .B typeset
965 make each
966 \fIname\fP local, as with the
967 .B local
968 command,
969 unless the \fB\-g\fP option is supplied.
970 If a variable name is followed by =\fIvalue\fP, the value of
971 the variable is set to \fIvalue\fP.
972 When using \fB\-a\fP or \fB\-A\fP and the compound assignment syntax to
973 create array variables, additional attributes do not take effect until
974 subsequent assignments.
975 .PP
976 The return value is 0 unless an invalid option is encountered,
977 an attempt is made to define a function using
978 .Q "\-f foo=bar" ,
979 an attempt is made to assign a value to a readonly variable,
980 an attempt is made to assign a value to an array variable without
981 using the compound assignment syntax (see
982 .B Arrays
983 .ie \n(zZ=1 in \fIbash\fP(1)),
984 .el above),
985 one of the \fInames\fP is not a valid shell variable name,
986 an attempt is made to turn off readonly status for a readonly variable,
987 an attempt is made to turn off array status for an array variable,
988 or an attempt is made to display a non-existent function with \fB\-f\fP.
989 .RE
990 .TP
991 .B dirs [\fB\-clpv\fP] [+\fIn\fP] [\-\fIn\fP]
992 Without options, display the list of currently remembered directories.
993 The default display is on a single line with directory names separated
994 by spaces.
995 Directories are added to the list with the
996 .B pushd
997 command; the
998 .B popd
999 command removes entries from the list.
1000 The current directory is always the first directory in the stack.
1001 .IP
1002 Options, if supplied, have the following meanings:
1003 .RS
1004 .PD 0
1005 .TP
1006 .B \-c
1007 Clears the directory stack by deleting all of the entries.
1008 .TP
1009 .B \-l
1010 Produces a listing using full pathnames;
1011 the default listing format uses a tilde to denote the home directory.
1012 .TP
1013 .B \-p
1014 Print the directory stack with one entry per line.
1015 .TP
1016 .B \-v
1017 Print the directory stack with one entry per line,
1018 prefixing each entry with its index in the stack.
1019 .TP
1020 \fB+\fP\fIn\fP
1021 Displays the \fIn\fPth entry counting from the left of the list
1022 shown by
1023 .B dirs
1024 when invoked without options, starting with zero.
1025 .TP
1026 \fB\-\fP\fIn\fP
1027 Displays the \fIn\fPth entry counting from the right of the list
1028 shown by
1029 .B dirs
1030 when invoked without options, starting with zero.
1031 .PD
1032 .PP
1033 The return value is 0 unless an
1034 invalid option is supplied or \fIn\fP indexes beyond the end
1035 of the directory stack.
1036 .RE
1037 .TP
1038 \fBdisown\fP [\fB\-ar\fP] [\fB\-h\fP] [\fIid\fP .\|.\|.]
1039 Without options, remove each
1040 .I id
1041 from the table of active jobs.
1042 Each \fIid\fP may be a job specification \fIjobspec\fP
1043 or a process ID \fIpid\fP;
1044 if \fIid\fP is a \fIpid\fP,
1045 \fBdisown\fP uses the job containing \fIpid\fP as \fIjobspec\fP.
1046 .IP
1047 If the \fB\-h\fP option is supplied,
1048 \fBdisown\fP does not remove the jobs corresponding to each
1049 .I id
1050 from the jobs table,
1051 but rather marks them so the shell does not send
1052 .SM
1053 .B SIGHUP
1054 to the job if the shell receives a
1055 .SM
1056 .BR SIGHUP .
1057 .IP
1058 If no
1059 .I id
1060 is supplied, the
1061 .B \-a
1062 option means to remove or mark all jobs; the
1063 .B \-r
1064 option without an
1065 .I id
1066 argument removes or marks running jobs.
1067 If no
1068 .I id
1069 is supplied, and neither the \fB\-a\fP nor the \fB\-r\fP option
1070 is supplied, \fBdisown\fP removes or marks the current job.
1071 .IP
1072 The return value is 0 unless an
1073 .I id
1074 does not specify a valid job.
1075 .TP
1076 \fBecho\fP [\fB\-neE\fP] [\fIarg\fP .\|.\|.]
1077 Output the \fIarg\fPs, separated by spaces, followed by a newline.
1078 The return status is 0 unless a write error occurs.
1079 If \fB\-n\fP is specified, the trailing newline is not printed.
1080 .IP
1081 If the \fB\-e\fP option is given, \fBecho\fP interprets
1082 the following backslash-escaped characters.
1083 The
1084 .B \-E
1085 option disables interpretation of these escape characters,
1086 even on systems where they are interpreted by default.
1087 The \fBxpg_echo\fP shell option determines
1088 whether or not \fBecho\fP interprets any options
1089 and expands these escape characters.
1090 .B echo
1091 does not interpret \fB\-\-\fP to mean the end of options.
1092 .IP
1093 .B echo
1094 interprets the following escape sequences:
1095 .RS
1096 .PD 0
1097 .TP
1098 .B \ea
1099 alert (bell)
1100 .TP
1101 .B \eb
1102 backspace
1103 .TP
1104 .B \ec
1105 suppress further output
1106 .TP
1107 .B \ee
1108 .TP
1109 .B \eE
1110 an escape character
1111 .TP
1112 .B \ef
1113 form feed
1114 .TP
1115 .B \en
1116 new line
1117 .TP
1118 .B \er
1119 carriage return
1120 .TP
1121 .B \et
1122 horizontal tab
1123 .TP
1124 .B \ev
1125 vertical tab
1126 .TP
1127 .B \e\e
1128 backslash
1129 .TP
1130 .B \e0\fInnn\fP
1131 The eight-bit character whose value is the octal value \fInnn\fP
1132 (zero to three octal digits).
1133 .TP
1134 .B \ex\fIHH\fP
1135 The eight-bit character whose value is the hexadecimal value \fIHH\fP
1136 (one or two hex digits).
1137 .TP
1138 .B \eu\fIHHHH\fP
1139 The Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
1140 \fIHHHH\fP (one to four hex digits).
1141 .TP
1142 .B \eU\fIHHHHHHHH\fP
1143 The Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
1144 \fIHHHHHHHH\fP (one to eight hex digits).
1145 .PD
1146 .PP
1147 \fBecho\fP writes any unrecognized backslash-escaped characters unchanged.
1148 .RE
1149 .TP
1150 \fBenable\fP [\fB\-a\fP] [\fB\-dnps\fP] [\fB\-f\fP \fIfilename\fP] \
1151 [\fIname\fP .\|.\|.]
1152 Enable and disable builtin shell commands.
1153 Disabling a builtin allows an executable file which has the same name
1154 as a shell builtin to be executed without specifying a full pathname,
1155 even though the shell normally searches for builtins before files.
1156 .IP
1157 If \fB\-n\fP is supplied, each \fIname\fP is disabled; otherwise,
1158 \fIname\fPs are enabled.
1159 For example, to use the
1160 .B test
1161 binary found using
1162 .SM
1163 .B PATH
1164 instead of the shell builtin version, run
1165 .QN "enable \-n test" .
1166 .IP
1167 If no \fIname\fP arguments are supplied, or if the
1168 .B \-p
1169 option is supplied, print a list of shell builtins.
1170 With no other option arguments, the list consists of all enabled
1171 shell builtins.
1172 If \fB\-n\fP is supplied, print only disabled builtins.
1173 If \fB\-a\fP is supplied, the list printed includes all builtins, with an
1174 indication of whether or not each is enabled.
1175 The \fB\-s\fP option means to restrict the output to the
1176 .SM POSIX
1177 \fIspecial\fP builtins.
1178 .IP
1179 The
1180 .B \-f
1181 option means to load the new builtin command
1182 .I name
1183 from shared object
1184 .IR filename ,
1185 on systems that support dynamic loading.
1186 If \fIfilename\fP does not contain a slash,
1187 \fBBash\fP will use the value of the \fBBASH_LOADABLES_PATH\fP variable as a
1188 colon-separated list of directories in which to search for \fIfilename\fP.
1189 The default for \fBBASH_LOADABLES_PATH\fP is system-dependent,
1190 and may include
1191 .Q .\&
1192 to force a search of the current directory.
1193 The
1194 .B \-d
1195 option will delete a builtin previously loaded with \fB\-f\fP.
1196 If \fI\-s\fP is used with \fI\-f\fP, the new builtin becomes a
1197 .SM POSIX
1198 special builtin.
1199 .IP
1200 If no options are supplied and a \fIname\fP is not a shell builtin,
1201 \fBenable\fP will attempt to load \fIname\fP from a shared
1202 object named \fIname\fP, as if the command were
1203 .QN "enable \-f \fIname name\fP" .
1204 .IP
1205 The return value is 0 unless a
1206 .I name
1207 is not a shell builtin or there is an error loading a new builtin
1208 from a shared object.
1209 .TP
1210 \fBeval\fP [\fIarg\fP .\|.\|.]
1211 Concatenate the \fIarg\fPs together into a single command, separating
1212 them with spaces.
1213 \fBBash\fP then reads and execute this command, and returns its exit status
1214 as the return status of \fBeval\fP.
1215 If there are no
1216 .IR args ,
1217 or only null arguments,
1218 .B eval
1219 returns 0.
1220 .TP
1221 \fBexec\fP [\fB\-cl\fP] [\fB\-a\fP \fIname\fP] [\fIcommand\fP [\fIarguments\fP]]
1222 If
1223 .I command
1224 is specified, it replaces the shell without creating a new process.
1225 \fIcommand\fP cannot be a shell builtin or function.
1226 The
1227 .I arguments
1228 become the arguments to \fIcommand\fP.
1229 If the
1230 .B \-l
1231 option is supplied,
1232 the shell places a dash at the beginning of the zeroth argument passed to
1233 .IR command .
1234 This is what
1235 .IR login (1)
1236 does. The
1237 .B \-c
1238 option causes
1239 .I command
1240 to be executed with an empty environment.
1241 If
1242 .B \-a
1243 is supplied, the shell passes
1244 .I name
1245 as the zeroth argument to the executed command.
1246 .IP
1247 If
1248 .I command
1249 cannot be executed for some reason, a non-interactive shell exits,
1250 unless the
1251 .B execfail
1252 shell option is enabled.
1253 In that case, it returns a non-zero status.
1254 An interactive shell returns a non-zero status if the file cannot be executed.
1255 A subshell exits unconditionally if \fBexec\fP fails.
1256 .IP
1257 If
1258 .I command
1259 is not specified, any redirections take effect in the current shell,
1260 and the return status is 0. If there is a redirection error, the
1261 return status is 1.
1262 .TP
1263 \fBexit\fP [\fIn\fP]
1264 Cause the shell to exit with a status of \fIn\fP.
1265 If
1266 .I n
1267 is omitted, the exit status is that of the last command executed.
1268 Any trap on
1269 .SM
1270 .B EXIT
1271 is executed before the shell terminates.
1272 .TP
1273 \fBexport\fP [\fB\-fn\fP\^] [\fIname\fP[=\fIvalue\fP]] .\|.\|.
1274 .PD 0
1275 .TP
1276 .B export \-p [\fB\-f\fP\^]
1277 .PD
1278 The supplied
1279 .I names
1280 are marked for automatic export to the environment of
1281 subsequently executed commands.
1282 If the
1283 .B \-f
1284 option is given, the
1285 .I names
1286 refer to functions.
1287 .IP
1288 The
1289 .B \-n
1290 option unexports, or removes the export attribute, from each \fIname\fP.
1291 If no
1292 .I names
1293 are given, or if only the
1294 .B \-p
1295 option is supplied,
1296 \fBexport\fP displays a list of names of all exported
1297 variables on the standard output.
1298 Using \fB\-p\fP and \fB\-f\fP together displays exported functions.
1299 The \fB\-p\fP option displays output in a form that may be reused as input.
1300 .IP
1301 \fBexport\fP allows the value of a variable to be set when it is exported
1302 or unexported by following the variable name with =\fIvalue\fP.
1303 This sets the value of the variable to \fIvalue\fP while modifying the
1304 export attribute.
1305 .B export
1306 returns an exit status of 0 unless an invalid option is
1307 encountered,
1308 one of the \fInames\fP is not a valid shell variable name, or
1309 .B \-f
1310 is supplied with a
1311 .I name
1312 that is not a function.
1313 .TP
1314 \fBfalse\fP
1315 Does nothing; returns a non-zero status.
1316 .TP
1317 \fBfc\fP [\fB\-e\fP \fIename\fP] [\fB\-lnr\fP] [\fIfirst\fP] [\fIlast\fP]
1318 .PD 0
1319 .TP
1320 \fBfc\fP \fB\-s\fP [\fIpat\fP=\fIrep\fP] [\fIcmd\fP]
1321 .PD
1322 The first form selects a range of commands from
1323 .I first
1324 to
1325 .I last
1326 from the history list and displays or edits and re-executes them.
1327 .I First
1328 and
1329 .I last
1330 may be specified as a string (to locate the last command beginning
1331 with that string) or as a number (an index into the history list,
1332 where a negative number is used as an offset from the current
1333 command number).
1334 .IP
1335 When listing, a \fIfirst\fP or \fIlast\fP of 0 is equivalent to \-1
1336 and \-0 is equivalent to the current command
1337 (usually the \fBfc\fP command);
1338 otherwise 0 is equivalent to \-1 and \-0 is invalid.
1339 If
1340 .I last
1341 is not specified, it is set to
1342 the current command for listing (so that
1343 .QN "fc \-l \-10"
1344 prints the last 10 commands) and to
1345 .I first
1346 otherwise.
1347 If
1348 .I first
1349 is not specified, it is set to the previous
1350 command for editing and \-16 for listing.
1351 .IP
1352 If the
1353 .B \-l
1354 option is supplied, the commands are listed on the standard output.
1355 The
1356 .B \-n
1357 option suppresses
1358 the command numbers when listing.
1359 The
1360 .B \-r
1361 option reverses the order of
1362 the commands.
1363 .IP
1364 Otherwise, \fBfc\fP invokes the editor named by
1365 .I ename
1366 on a file containing those commands.
1367 If
1368 .I ename
1369 is not supplied, \fBfc\fP uses the value of the
1370 .SM
1371 .B FCEDIT
1372 variable, and
1373 the value of
1374 .SM
1375 .B EDITOR
1376 if
1377 .SM
1378 .B FCEDIT
1379 is not set.
1380 If neither variable is set, \fBfc\fP uses
1381 .FN vi.
1382 When editing is complete, \fBfc\fP reads the file containing
1383 the edited commands and echoes and executes them.
1384 .IP
1385 In the second form, \fBfc\fP re-executes \fIcommand\fP
1386 after replacing each instance of \fIpat\fP with \fIrep\fP.
1387 \fICommand\fP is interpreted the same as \fIfirst\fP above.
1388 .IP
1389 A useful alias to use with \fBfc\fP is
1390 .Q "r=\*"fc \-s\*"" ,
1391 so that typing
1392 .Q "r cc"
1393 runs the last command beginning with
1394 .Q cc
1395 and typing
1396 .Q r
1397 re-executes the last command.
1398 .IP
1399 If the first form is used, the return value is zero unless an invalid
1400 option is encountered or
1401 .I first
1402 or
1403 .I last
1404 specify history lines out of range.
1405 When editing and re-executing a file of commands,
1406 the return value is the value of the last command executed
1407 or failure if an error occurs with the temporary file.
1408 If the second form is used, the return status
1409 is that of the re-executed command, unless
1410 .I cmd
1411 does not specify a valid history entry, in which case
1412 .B fc
1413 returns a non-zero status.
1414 .TP
1415 \fBfg\fP [\fIjobspec\fP]
1416 Resume
1417 .I jobspec
1418 in the foreground, and make it the current job.
1419 If
1420 .I jobspec
1421 is not present, \fBfg\fP uses the shell's notion of the \fIcurrent job\fP.
1422 The return value is that of the command placed into the foreground,
1423 or failure if run when job control is disabled or, when run with
1424 job control enabled, if
1425 .I jobspec
1426 does not specify a valid job or
1427 .I jobspec
1428 specifies a job that was started without job control.
1429 .TP
1430 \fBgetopts\fP \fIoptstring\fP \fIname\fP [\fIarg\fP .\|.\|.]
1431 .B getopts
1432 is used by shell scripts and functions to parse positional parameters
1433 and obtain options and their arguments.
1434 .I optstring
1435 contains the option characters to be recognized; if a character
1436 is followed by a colon, the option is expected to have an
1437 argument, which should be separated from it by white space.
1438 The colon and question mark characters may not be used as
1439 option characters.
1440 .IP
1441 Each time it is invoked,
1442 .B getopts
1443 places the next option in the shell variable
1444 .IR name ,
1445 initializing
1446 .I name
1447 if it does not exist,
1448 and the index of the next argument to be processed into the
1449 variable
1450 .SM
1451 .BR OPTIND .
1452 .SM
1453 .B OPTIND
1454 is initialized to 1 each time the shell or a shell script
1455 is invoked.
1456 When an option requires an argument,
1457 .B getopts
1458 places that argument into the variable
1459 .SM
1460 .BR OPTARG .
1461 .IP
1462 The shell does not reset
1463 .SM
1464 .B OPTIND
1465 automatically; it must be manually reset between multiple
1466 calls to
1467 .B getopts
1468 within the same shell invocation to use a new set of parameters.
1469 .IP
1470 When it reaches the end of options, \fBgetopts\fP exits with a
1471 return value greater than zero.
1472 .SM
1473 .B OPTIND
1474 is set to the index of the first non-option argument,
1475 and \fIname\fP is set to ?.
1476 .IP
1477 .B getopts
1478 normally parses the positional parameters, but if more arguments are
1479 supplied as
1480 .I arg
1481 values,
1482 .B getopts
1483 parses those instead.
1484 .IP
1485 .B getopts
1486 can report errors in two ways.
1487 If the first character of
1488 .I optstring
1489 is a colon, \fBgetopts\fP uses
1490 .I silent
1491 error reporting.
1492 In normal operation, \fBgetopts\fP prints diagnostic messages
1493 when it encounters invalid options or missing option arguments.
1494 If the variable
1495 .SM
1496 .B OPTERR
1497 is set to 0,
1498 .B getopts
1499 does not display any error messages,
1500 even if the first character of
1501 .I optstring
1502 is not a colon.
1503 .IP
1504 If
1505 .B getopts
1506 detects an invalid option, it places ? into
1507 .I name
1508 and, if not silent,
1509 prints an error message and unsets
1510 .SM
1511 .BR OPTARG .
1512 If
1513 .B getopts
1514 is silent, it assigns the option character found to
1515 .SM
1516 .B OPTARG
1517 and does not print a diagnostic message.
1518 .IP
1519 If a required argument is not found, and
1520 .B getopts
1521 is not silent, it sets the value of \fIname\fP to
1522 a question mark (\^\fB?\fP\^), unsets
1523 .SM
1524 .BR OPTARG ,
1525 and prints a diagnostic message.
1526 If
1527 .B getopts
1528 is silent, it sets the value of \fIname\fP to a colon (\^\fB:\fP\^)
1529 and sets
1530 .SM
1531 .B OPTARG
1532 to the option character found.
1533 .IP
1534 .B getopts
1535 returns true if an option, specified or unspecified, is found.
1536 It returns false if the end of options is encountered or an
1537 error occurs.
1538 .TP
1539 \fBhash\fP [\fB\-lr\fP] [\fB\-p\fP \fIfilename\fP] [\fB\-dt\fP] [\fIname\fP]
1540 Each time \fBhash\fP is invoked, it remembers
1541 the full pathname of the command
1542 .I name
1543 as determined by searching
1544 the directories in
1545 .BR $PATH .
1546 Any previously-remembered pathname associated with \fIname\fP is discarded.
1547 If the
1548 .B \-p
1549 option is supplied, \fBhash\fP uses
1550 .I filename
1551 as the full pathname of the command.
1552 .IP
1553 The
1554 .B \-r
1555 option causes the shell to forget all
1556 remembered locations.
1557 Assigning to the \fBPATH\fP variable also clears all hashed filenames.
1558 The
1559 .B \-d
1560 option causes the shell to forget the remembered location of each \fIname\fP.
1561 .IP
1562 If the
1563 .B \-t
1564 option is supplied, \fBhash\fP prints the full pathname corresponding to
1565 each \fIname\fP.
1566 If multiple \fIname\fP arguments are supplied with \fB\-t\fP,
1567 \fBhash\fP prints the \fIname\fP before the corresponding hashed
1568 full pathname.
1569 The
1570 .B \-l
1571 option displays output in a format that may be reused as input.
1572 .IP
1573 If no arguments are given, or if only \fB\-l\fP is supplied,
1574 \fBhash\fP prints information about remembered commands.
1575 The \fB\-t\fP, \fB\-d\fP, and \fB\-p\fP options (the options that
1576 act on the \fIname\fP arguments) are mutually exclusive.
1577 Only one will be active.
1578 If more than one is supplied, \fB\-t\fP has higher priority than
1579 \fB\-p\fP, and both have higher priority than \fB\-d\fP.
1580 .IP
1581 The return status is zero unless a
1582 .I name
1583 is not found or an invalid option is supplied.
1584 .TP
1585 \fBhelp\fP [\fB\-dms\fP] [\fIpattern\fP]
1586 Display helpful information about builtin commands.
1587 If
1588 .I pattern
1589 is specified,
1590 .B help
1591 gives detailed help on all commands matching
1592 .I pattern
1593 as described below;
1594 otherwise it displays a list of
1595 all the builtins and shell compound commands.
1596 .IP
1597 Options, if supplied, have the follow meanings:
1598 .RS
1599 .TP
1600 .PD 0
1601 .B \-d
1602 Display a short description of each \fIpattern\fP
1603 .TP
1604 .B \-m
1605 Display the description of each \fIpattern\fP in a manpage-like format
1606 .TP
1607 .B \-s
1608 Display only a short usage synopsis for each \fIpattern\fP
1609 .PD
1610 .RE
1611 .IP
1612 If \fIpattern\fP contains pattern matching characters
1613 (see
1614 .SM
1615 .B "Pattern Matching"
1616 above)
1617 it's treated as a shell pattern and
1618 \fBhelp\fP prints the description of each
1619 help topic matching \fIpattern\fP.
1620 .IP
1621 If not, and \fIpattern\fP exactly matches the name of a help topic,
1622 \fBhelp\fP prints the description
1623 associated with that topic.
1624 Otherwise, \fBhelp\fP performs prefix matching and
1625 prints the descriptions of all matching help topics.
1626 .IP
1627 The return status is 0 unless no command matches
1628 .IR pattern .
1629 .TP
1630 \fBhistory [\fIn\fP]
1631 .PD 0
1632 .TP
1633 \fBhistory\fP \fB\-c\fP
1634 .TP
1635 \fBhistory \-d\fP \fIoffset\fP
1636 .TP
1637 \fBhistory \-d\fP \fIstart\fP-\fIend\fP
1638 .TP
1639 \fBhistory\fP \fB\-anrw\fP [\fIfilename\fP]
1640 .TP
1641 \fBhistory\fP \fB\-p\fP \fIarg\fP [\fIarg\fP .\|.\|.]
1642 .TP
1643 \fBhistory\fP \fB\-s\fP \fIarg\fP [\fIarg\fP .\|.\|.]
1644 .PD
1645 With no options, display the command history list with numbers.
1646 Entries prefixed with a
1647 .B *
1648 have been modified.
1649 An argument of
1650 .I n
1651 lists only the last
1652 .I n
1653 entries.
1654 If the shell variable
1655 .SM
1656 .B HISTTIMEFORMAT
1657 is set and not null,
1658 it is used as a format string for
1659 .IR strftime (3)
1660 to display the time stamp associated with each displayed history entry.
1661 If
1662 .B history
1663 uses
1664 .SM
1665 .BR HISTTIMEFORMAT ,
1666 it does not print an intervening space between the formatted time stamp
1667 and the history entry.
1668 .IP
1669 If \fIfilename\fP is supplied, \fBhistory\fP uses it as the
1670 name of the history file; if not, it uses the value of
1671 .SM
1672 .BR HISTFILE .
1673 If \fIfilename\fP is not supplied and
1674 .SM
1675 .B HISTFILE
1676 is unset or null, the \fB\-a, \-n, \-r,\fP and \fB\-w\fP options
1677 have no effect.
1678 .IP
1679 Options, if supplied, have the following meanings:
1680 .RS
1681 .PD 0
1682 .TP
1683 .B \-c
1684 Clear the history list by deleting all the entries.
1685 This can be used with the other options to replace the history list.
1686 .TP
1687 \fB\-d\fP \fIoffset\fP
1688 Delete the history entry at position \fIoffset\fP.
1689 If \fIoffset\fP is negative, it is interpreted as relative to one greater
1690 than the last history position, so negative indices count back from the
1691 end of the history, and an index of \-1 refers to the current
1692 \fBhistory \-d\fP command.
1693 .TP
1694 \fB\-d\fP \fIstart\fP\-\fIend\fP
1695 Delete the range of history entries between positions \fIstart\fP and
1696 \fIend\fP, inclusive.
1697 Positive and negative values for \fIstart\fP and \fIend\fP
1698 are interpreted as described above.
1699 .TP
1700 .B \-a
1701 Append the
1702 .Q new
1703 history lines to the history file.
1704 These are history lines entered since the beginning of the current
1705 \fBbash\fP session, but not already appended to the history file.
1706 .TP
1707 .B \-n
1708 Read the history lines not already read from the history file
1709 and add them to the current history list.
1710 These are lines appended to the history file since the beginning of the
1711 current \fBbash\fP session.
1712 .TP
1713 .B \-r
1714 Read the history file and append its contents to the current history list.
1715 .TP
1716 .B \-w
1717 Write the current history list to the history file, overwriting
1718 the history file.
1719 .TP
1720 .B \-p
1721 Perform history substitution on the following \fIargs\fP and display
1722 the result on the standard output,
1723 without storing the results in the history list.
1724 Each \fIarg\fP must be quoted to disable normal history expansion.
1725 .TP
1726 .B \-s
1727 Store the
1728 .I args
1729 in the history list as a single entry.
1730 The last command in the
1731 history list is removed before adding the
1732 .IR args .
1733 .PD
1734 .RE
1735 .IP
1736 If the
1737 .SM
1738 .B HISTTIMEFORMAT
1739 variable is set, \fBhistory\fP writes the time stamp information
1740 associated with each history entry to the history file,
1741 marked with the history comment character as described above.
1742 When the history file is read, lines beginning with the history
1743 comment character followed immediately by a digit are interpreted
1744 as timestamps for the following history entry.
1745 .IP
1746 The return value is 0 unless an invalid option is encountered, an
1747 error occurs while reading or writing the history file, an invalid
1748 \fIoffset\fP or range is supplied as an argument to \fB\-d\fP, or the
1749 history expansion supplied as an argument to \fB\-p\fP fails.
1750 .TP
1751 \fBjobs\fP [\fB\-lnprs\fP] [ \fIjobspec\fP .\|.\|. ]
1752 .PD 0
1753 .TP
1754 \fBjobs\fP \fB\-x\fP \fIcommand\fP [ \fIargs\fP .\|.\|. ]
1755 .PD
1756 The first form lists the active jobs.
1757 The options have the following meanings:
1758 .RS
1759 .PD 0
1760 .TP
1761 .B \-l
1762 List process IDs in addition to the normal information.
1763 .TP
1764 .B \-n
1765 Display information only about jobs that have changed status since
1766 the user was last notified of their status.
1767 .TP
1768 .B \-p
1769 List only the process ID of the job's process group leader.
1770 .TP
1771 .B \-r
1772 Display only running jobs.
1773 .TP
1774 .B \-s
1775 Display only stopped jobs.
1776 .PD
1777 .RE
1778 .IP
1779 If
1780 .I jobspec
1781 is supplied, \fBjobs\fP restricts output to information about that job.
1782 The return status is 0 unless an invalid option is encountered
1783 or an invalid
1784 .I jobspec
1785 is supplied.
1786 .IP
1787 If the
1788 .B \-x
1789 option is supplied,
1790 .B jobs
1791 replaces any
1792 .I jobspec
1793 found in
1794 .I command
1795 or
1796 .I args
1797 with the corresponding process group ID, and executes
1798 .IR command ,
1799 passing it
1800 .IR args ,
1801 returning its exit status.
1802 .TP
1803 \fBkill\fP [\fB\-s\fP \fIsigspec\fP | \fB\-n\fP \fIsignum\fP | \fB\-\fP\fIsigspec\fP] \
1804 \fIid\fP [ .\|.\|. ]
1805 .PD 0
1806 .TP
1807 \fBkill\fP \fB\-l\fP|\fB\-L\fP [\fIsigspec\fP | \fIexit_status\fP]
1808 .PD
1809 Send the signal specified by
1810 .I sigspec
1811 or
1812 .I signum
1813 to the processes named by each
1814 .IR id .
1815 Each
1816 .I id
1817 may be a job specification \fIjobspec\fP
1818 or a process ID \fIpid\fP.
1819 .I sigspec
1820 is either a case-insensitive signal name such as
1821 .SM
1822 .B SIGKILL
1823 (with or without the
1824 .SM
1825 .B SIG
1826 prefix) or a signal number;
1827 .I signum
1828 is a signal number.
1829 If
1830 .I sigspec
1831 is not supplied, then
1832 .B kill
1833 sends
1834 .SM
1835 .BR SIGTERM .
1836 .IP
1837 The
1838 .B \-l
1839 option lists the signal names.
1840 If any arguments are supplied when
1841 .B \-l
1842 is given,
1843 .B kill
1844 lists the names of the signals corresponding to the arguments,
1845 and the return status is 0.
1846 The \fIexit_status\fP argument to
1847 .B \-l
1848 is a number specifying either a signal number or the exit status of
1849 a process terminated by a signal;
1850 if it is supplied, \fBkill\fP prints the name of the signal that caused
1851 the process to terminate.
1852 \fBkill\fP assumes that process exit statuses are greater than 128;
1853 anything less than that is a signal number.
1854 The
1855 .B \-L
1856 option is equivalent to \fB\-l\fP.
1857 .IP
1858 .B kill
1859 returns true if at least one signal was successfully sent, or false
1860 if an error occurs or an invalid option is encountered.
1861 .TP
1862 \fBlet\fP \fIarg\fP [\fIarg\fP .\|.\|.]
1863 Each
1864 .I arg
1865 is evaluated as an arithmetic expression (see
1866 .SM
1867 .B "ARITHMETIC EVALUATION"
1868 .ie \n(zZ=1 in \fIbash\fP(1)).
1869 .el above).
1870 If the last
1871 .I arg
1872 evaluates to 0,
1873 .B let
1874 returns 1; otherwise
1875 .B let
1876 returns 0.
1877 .TP
1878 \fBlocal\fP [\fIoption\fP] [\fIname\fP[=\fIvalue\fP] .\|.\|. | \- ]
1879 For each argument, create a local variable named
1880 .I name
1881 and assign it
1882 .IR value .
1883 The \fIoption\fP can be any of the options accepted by \fBdeclare\fP.
1884 When
1885 .B local
1886 is used within a function, it causes the variable
1887 .I name
1888 to have a visible scope restricted to that function and its children.
1889 It is an error to use
1890 .B local
1891 when not within a function.
1892 .IP
1893 If \fIname\fP is \-, it makes the set of shell options
1894 local to the function in which \fBlocal\fP is invoked:
1895 any shell options changed using the \fBset\fP builtin inside
1896 the function after the call to \fBlocal\fP are restored to their
1897 original values when the function returns.
1898 The restore is performed as if a series of \fBset\fP commands were
1899 executed to restore the values that were in place before the function.
1900 .IP
1901 With no operands,
1902 .B local
1903 writes a list of local variables to the standard output.
1904 .IP
1905 The return status is 0 unless
1906 .B local
1907 is used outside a function, an invalid
1908 .I name
1909 is supplied, or
1910 \fIname\fP is a readonly variable.
1911 .TP
1912 .B logout [\fIn\fP]
1913 Exit a login shell,
1914 returning a status of \fIn\fP to the shell's parent.
1915 .TP
1916 \fBmapfile\fP [\fB\-d\fP \fIdelim\fP] [\fB\-n\fP \fIcount\fP] [\fB\-O\fP \fIorigin\fP] [\fB\-s\fP \fIcount\fP] [\fB\-t\fP] [\fB\-u\fP \fIfd\fP] [\fB\-C\fP \fIcallback\fP] [\fB\-c\fP \fIquantum\fP] [\fIarray\fP]
1917 .PD 0
1918 .TP
1919 \fBreadarray\fP [\fB\-d\fP \fIdelim\fP] [\fB\-n\fP \fIcount\fP] [\fB\-O\fP \fIorigin\fP] [\fB\-s\fP \fIcount\fP] [\fB\-t\fP] [\fB\-u\fP \fIfd\fP] [\fB\-C\fP \fIcallback\fP] [\fB\-c\fP \fIquantum\fP] [\fIarray\fP]
1920 .PD
1921 Read lines from the standard input,
1922 or from file descriptor
1923 .I fd
1924 if the
1925 .B \-u
1926 option is supplied,
1927 into the indexed array variable
1928 .IR array .
1929 The variable
1930 .SM
1931 .B MAPFILE
1932 is the default \fIarray\fP.
1933 Options, if supplied, have the following meanings:
1934 .RS
1935 .PD 0
1936 .TP
1937 .B \-d
1938 Use the first character of \fIdelim\fP to terminate each input line,
1939 rather than newline.
1940 If \fIdelim\fP is the empty string, \fBmapfile\fP will terminate a line
1941 when it reads a NUL character.
1942 .TP
1943 .B \-n
1944 Copy at most
1945 .I count
1946 lines.
1947 If \fIcount\fP is 0, copy all lines.
1948 .TP
1949 .B \-O
1950 Begin assigning to
1951 .I array
1952 at index
1953 .IR origin .
1954 The default index is 0.
1955 .TP
1956 .B \-s
1957 Discard the first \fIcount\fP lines read.
1958 .TP
1959 .B \-t
1960 Remove a trailing \fIdelim\fP (default newline) from each line read.
1961 .TP
1962 .B \-u
1963 Read lines from file descriptor \fIfd\fP instead of the standard input.
1964 .TP
1965 .B \-C
1966 Evaluate
1967 .I callback
1968 each time \fIquantum\fP lines are read.
1969 The \fB\-c\fP option specifies
1970 .IR quantum .
1971 .TP
1972 .B \-c
1973 Specify the number of lines read between each call to
1974 .IR callback .
1975 .PD
1976 .RE
1977 .IP
1978 If
1979 .B \-C
1980 is specified without
1981 .BR \-c ,
1982 the default quantum is 5000.
1983 When \fIcallback\fP is evaluated, it is supplied the index of the next
1984 array element to be assigned and the line to be assigned to that element
1985 as additional arguments.
1986 \fIcallback\fP is evaluated after the line is read but before the
1987 array element is assigned.
1988 .IP
1989 If not supplied with an explicit origin, \fBmapfile\fP will clear \fIarray\fP
1990 before assigning to it.
1991 .IP
1992 \fBmapfile\fP returns zero unless an invalid option or option
1993 argument is supplied, \fIarray\fP is invalid or unassignable, or if
1994 \fIarray\fP is not an indexed array.
1995 .TP
1996 \fBpopd\fP [\-\fBn\fP] [+\fIn\fP] [\-\fIn\fP]
1997 Remove entries from the directory stack.
1998 The elements are numbered from 0 starting at the first directory
1999 listed by \fBdirs\fP, so \fBpopd\fP is equivalent to
2000 .Q "popd +0."
2001 With no arguments, \fBpopd\fP removes the top directory from the stack,
2002 and changes to the new top directory.
2003 Arguments, if supplied, have the following meanings:
2004 .RS
2005 .PD 0
2006 .TP
2007 .B \-n
2008 Suppress the normal change of directory when removing directories
2009 from the stack, only manipulate the stack.
2010 .TP
2011 \fB+\fP\fIn\fP
2012 Remove the \fIn\fPth entry counting from the left of the list
2013 shown by
2014 .BR dirs ,
2015 starting with zero, from the stack.
2016 For example:
2017 .Q "popd +0"
2018 removes the first directory,
2019 .Q "popd +1"
2020 the second.
2021 .TP
2022 \fB\-\fP\fIn\fP
2023 Remove the \fIn\fPth entry counting from the right of the list
2024 shown by
2025 .BR dirs ,
2026 starting with zero. For example:
2027 .Q "popd \-0"
2028 removes the last directory,
2029 .Q "popd \-1"
2030 the next to last.
2031 .PD
2032 .RE
2033 .IP
2034 If the top element of the directory stack is modified, and
2035 the \fI\-n\fP option was not supplied, \fBpopd\fP uses the \fBcd\fP
2036 builtin to change to the directory at the top of the stack.
2037 If the \fBcd\fP fails, \fBpopd\fP returns a non-zero value.
2038 .IP
2039 Otherwise,
2040 .B popd
2041 returns false if an invalid option is supplied, the directory stack
2042 is empty, or \fIn\fP specifies a non-existent directory stack entry.
2043 .IP
2044 If the
2045 .B popd
2046 command is successful,
2047 \fBbash\fP runs
2048 .B dirs
2049 to show the final contents of the directory stack,
2050 and the return status is 0.
2051 .TP
2052 \fBprintf\fP [\fB\-v\fP \fIvar\fP] \fIformat\fP [\fIarguments\fP]
2053 Write the formatted \fIarguments\fP to the standard output under the
2054 control of the \fIformat\fP.
2055 The \fB\-v\fP option assigns the output to the variable
2056 \fIvar\fP rather than printing it to the standard output.
2057 .IP
2058 The \fIformat\fP is a character string which contains three types of objects:
2059 plain characters, which are simply copied to standard output, character
2060 escape sequences, which are converted and copied to the standard output, and
2061 format specifications, each of which causes printing of the next successive
2062 \fIargument\fP.
2063 In addition to the standard
2064 .IR printf (3)
2065 format characters
2066 .BR cCsSndiouxXeEfFgGaA ,
2067 \fBprintf\fP interprets the following additional format specifiers:
2068 .RS
2069 .PD 0
2070 .TP
2071 .B %b
2072 causes
2073 \fBprintf\fP to expand backslash escape sequences in the corresponding
2074 \fIargument\fP
2075 in the same way as \fBecho \-e\fP.
2076 .TP
2077 .B %q
2078 causes \fBprintf\fP to output the corresponding
2079 \fIargument\fP in a format that can be reused as shell input.
2080 \fB%q\fP and \fB%Q\fP use the \fB$\*'\*'\fP quoting style if any characters
2081 in the argument string require it, and backslash quoting otherwise.
2082 If the format string uses the \fIprintf\fP alternate form, these two
2083 formats quote the argument string using single quotes.
2084 .TP
2085 .B %Q
2086 like \fB%q\fP, but applies any supplied precision to the \fIargument\fP
2087 before quoting it.
2088 .TP
2089 .B %(\fIdatefmt\fP)T
2090 causes \fBprintf\fP to output the date-time string resulting from using
2091 \fIdatefmt\fP as a format string for
2092 .IR strftime (3).
2093 The corresponding \fIargument\fP is an integer representing the number of
2094 seconds since the epoch.
2095 This format specifier recognizes two special argument values:
2096 \-1 represents the current time,
2097 and \-2 represents the time the shell was invoked.
2098 If no argument is specified, conversion behaves as if \-1 had been supplied.
2099 This is an exception to the usual \fBprintf\fP behavior.
2100 .PD
2101 .RE
2102 .IP
2103 The %b, %q, and %T format specifiers all use the field width and precision
2104 arguments from the format specification and write that many bytes from
2105 (or use that wide a field for) the expanded argument, which usually
2106 contains more characters than the original.
2107 .IP
2108 The %n format specifier accepts a corresponding argument that is treated
2109 as a shell variable name.
2110 .IP
2111 The %s and %c format specifiers accept an l (long) modifier, which forces
2112 them to convert the argument string to a wide-character string and apply
2113 any supplied field width and precision in terms of characters, not bytes.
2114 The %S and %C format specifiers are equivalent to %ls and %lc, respectively.
2115 .\" .IP
2116 .\" The %s format specifier understands the "altform" flag (#) and behaves
2117 .\" identically to the %b format specifier if it's supplied.
2118 .IP
2119 Arguments to non-string format specifiers are treated as C constants,
2120 except that a leading plus or minus sign is allowed, and if the leading
2121 character is a single or double quote, the value is the numeric value of
2122 the following character, using the current locale.
2123 .IP
2124 The \fIformat\fP is reused as necessary to consume all of the \fIarguments\fP.
2125 If the \fIformat\fP requires more \fIarguments\fP than are supplied, the
2126 extra format specifications behave as if a zero value or null string, as
2127 appropriate, had been supplied.
2128 The return value is zero on success,
2129 non-zero if an invalid option is supplied or a write or assignment error
2130 occurs.
2131 .TP
2132 \fBpushd\fP [\fB\-n\fP] [+\fIn\fP] [\-\fIn\fP]
2133 .PD 0
2134 .TP
2135 \fBpushd\fP [\fB\-n\fP] [\fIdir\fP]
2136 .PD
2137 Add a directory to the top of the directory stack, or rotate
2138 the stack, making the new top of the stack the current working
2139 directory.
2140 With no arguments, \fBpushd\fP exchanges the top two elements of
2141 the directory stack.
2142 Arguments, if supplied, have the following meanings:
2143 .RS
2144 .PD 0
2145 .TP
2146 .B \-n
2147 Suppress the normal change of directory when rotating or
2148 adding directories to the stack, only manipulate the stack.
2149 .TP
2150 \fB+\fP\fIn\fP
2151 Rotate the stack so that the \fIn\fPth directory
2152 (counting from the left of the list shown by
2153 .BR dirs ,
2154 starting with zero)
2155 is at the top.
2156 .TP
2157 \fB\-\fP\fIn\fP
2158 Rotates the stack so that the \fIn\fPth directory
2159 (counting from the right of the list shown by
2160 .BR dirs ,
2161 starting with zero) is at the top.
2162 .TP
2163 .I dir
2164 Adds
2165 .I dir
2166 to the directory stack at the top.
2167 .PD
2168 .RE
2169 .IP
2170 After the stack has been modified, if the \fB\-n\fP option was not
2171 supplied, \fBpushd\fP uses the \fBcd\fP builtin to change to the
2172 directory at the top of the stack.
2173 If the \fBcd\fP fails, \fBpushd\fP returns a non-zero value.
2174 .IP
2175 Otherwise, if no arguments are supplied,
2176 .B pushd
2177 returns zero unless the directory stack is empty.
2178 When rotating the directory stack,
2179 .B pushd
2180 returns zero unless the directory stack is empty or
2181 \fIn\fP specifies a non-existent directory stack element.
2182 .IP
2183 If the
2184 .B pushd
2185 command is successful,
2186 \fBbash\fP runs
2187 .B dirs
2188 to show the final contents of the directory stack.
2189 .TP
2190 \fBpwd\fP [\fB\-LP\fP]
2191 Print the absolute pathname of the current working directory.
2192 The pathname printed contains no symbolic links if the
2193 .B \-P
2194 option is supplied or the
2195 .B \-o physical
2196 option to the
2197 .B set
2198 builtin command is enabled.
2199 If the
2200 .B \-L
2201 option is used, the pathname printed may contain symbolic links.
2202 The return status is 0 unless an error occurs while
2203 reading the name of the current directory or an
2204 invalid option is supplied.
2205 .TP
2206 \fBread\fP [\fB\-Eers\fP] [\fB\-a\fP \fIaname\fP] \
2207 [\fB\-d\fP \fIdelim\fP] [\fB\-i\fP \fItext\fP] \
2208 [\fB\-n\fP \fInchars\fP] [\fB\-N\fP \fInchars\fP] \
2209 [\fB\-p\fP \fIprompt\fP] [\fB\-t\fP \fItimeout\fP] \
2210 [\fB\-u\fP \fIfd\fP] [\fIname\fP .\|.\|.]
2211 Read one line from the standard input, or from the file descriptor
2212 \fIfd\fP supplied as an argument to the \fB\-u\fP option,
2213 split it into words as described
2214 .ie \n(zZ=1 in \fIbash\fP (1)
2215 .el above
2216 under \fBWord Splitting\fP,
2217 and assign the first word to the first
2218 .IR name ,
2219 the second word to the second
2220 .IR name ,
2221 and so on.
2222 If there are more words than names, the remaining words and their
2223 intervening delimiters are assigned to the last
2224 .IR name .
2225 If there are fewer words read from the input stream than names,
2226 the remaining names are assigned empty values.
2227 The characters in the value of the
2228 .SM
2229 .B IFS
2230 variable
2231 are used to split the line into words using the same rules the shell
2232 uses for expansion (described
2233 .ie \n(zZ=1 in \fIbash\fP (1)
2234 .el above
2235 under \fBWord Splitting\fP).
2236 The backslash character (\fB\e\fP) removes any special
2237 meaning for the next character read and is used for line continuation.
2238 .IP
2239 Options, if supplied, have the following meanings:
2240 .RS
2241 .PD 0
2242 .TP
2243 .B \-a \fIaname\fP
2244 The words are assigned to sequential indices of the array variable
2245 .IR aname ,
2246 starting at 0.
2247 .I aname
2248 is unset before any new values are assigned.
2249 Other \fIname\fP arguments are ignored.
2250 .TP
2251 .B \-d \fIdelim\fP
2252 The first character of \fIdelim\fP terminates the input line,
2253 rather than newline.
2254 If \fIdelim\fP is the empty string, \fBread\fP will terminate a line
2255 when it reads a NUL character.
2256 .TP
2257 .B \-e
2258 If the standard input is coming from a terminal,
2259 \fBread\fP uses
2260 .B readline
2261 (see
2262 .SM
2263 .B READLINE
2264 .ie \n(zZ=1 in \fIbash\fP(1))
2265 .el above)
2266 to obtain the line.
2267 \fBReadline\fP uses the current
2268 (or default, if line editing was not previously active)
2269 editing settings, but uses \fBreadline\fP's default filename completion.
2270 .TP
2271 .B \-E
2272 If the standard input is coming from a terminal,
2273 \fBread\fP uses
2274 .B readline
2275 (see
2276 .SM
2277 .B READLINE
2278 .ie \n(zZ=1 in \fIbash\fP(1))
2279 .el above)
2280 to obtain the line.
2281 .B Readline
2282 uses the current (or default, if line editing was not previously
2283 active) editing settings, but uses bash's default completion, including
2284 programmable completion.
2285 .TP
2286 .B \-i \fItext\fP
2287 If
2288 .B readline
2289 is being used to read the line, \fBread\fP places \fItext\fP into
2290 the editing buffer before editing begins.
2291 .TP
2292 .B \-n \fInchars\fP
2293 \fBread\fP returns after reading \fInchars\fP characters rather than
2294 waiting for a complete line of input,
2295 unless it encounters EOF or \fBread\fP times out,
2296 but honors a delimiter if it reads fewer
2297 than \fInchars\fP characters before the delimiter.
2298 .TP
2299 .B \-N \fInchars\fP
2300 \fBread\fP returns after reading exactly \fInchars\fP characters rather
2301 than waiting for a complete line of input,
2302 unless it encounters EOF or \fBread\fP times out.
2303 Any delimiter characters in the input are
2304 not treated specially and do not cause \fBread\fP to return until
2305 it has read \fInchars\fP characters.
2306 The result is not split on the characters in \fBIFS\fP; the intent is
2307 that the variable is assigned exactly the characters read
2308 (with the exception of backslash; see the \fB\-r\fP option below).
2309 .TP
2310 .B \-p \fIprompt\fP
2311 Display \fIprompt\fP on standard error, without a
2312 trailing newline, before attempting to read any input, but
2313 only if input is coming from a terminal.
2314 .TP
2315 .B \-r
2316 Backslash does not act as an escape character.
2317 The backslash is considered to be part of the line.
2318 In particular, a backslash-newline pair may not then be used as a line
2319 continuation.
2320 .TP
2321 .B \-s
2322 Silent mode.
2323 If input is coming from a terminal, characters are not echoed.
2324 .TP
2325 .B \-t \fItimeout\fP
2326 Cause \fBread\fP to time out and return failure if it does not read
2327 a complete line of input (or a specified number of characters)
2328 within \fItimeout\fP seconds.
2329 \fItimeout\fP may be a decimal number with a fractional portion following
2330 the decimal point.
2331 This option is only effective if \fBread\fP is reading input from a
2332 terminal, pipe, or other special file; it has no effect when reading
2333 from regular files.
2334 If \fBread\fP times out, it saves any partial input read into
2335 the specified variable \fIname\fP, and the exit status is greater than 128.
2336 If \fItimeout\fP is 0, \fBread\fP returns immediately, without trying to
2337 read any data.
2338 In this case, the exit status is 0 if input is available on the specified
2339 file descriptor, or the read will return EOF, non-zero otherwise.
2340 .TP
2341 .B \-u \fIfd\fP
2342 Read input from file descriptor \fIfd\fP instead of the standard input.
2343 .PD
2344 .RE
2345 .IP
2346 Other than the case where \fIdelim\fP is the empty string, \fBread\fP
2347 ignores any NUL characters in the input.
2348 .IP
2349 If no
2350 .I names
2351 are supplied, \fBread\fP assigns the line read,
2352 without the ending delimiter but otherwise unmodified,
2353 to the variable
2354 .SM
2355 .BR REPLY .
2356 .IP
2357 The exit status is zero, unless end-of-file is encountered, \fBread\fP
2358 times out (in which case the status is greater than 128),
2359 a variable assignment error (such as assigning to a readonly variable) occurs,
2360 or an invalid file descriptor is supplied as the argument to \fB\-u\fP.
2361 .TP
2362 \fBreadonly\fP [\fB\-aAf\fP] [\fB\-p\fP] [\fIname\fP[=\fIword\fP] .\|.\|.]
2363 .PD
2364 The given
2365 \fInames\fP are marked readonly; the values of these
2366 .I names
2367 may not be changed by subsequent assignment or unset.
2368 If the
2369 .B \-f
2370 option is supplied, each \fIname\fP refers to a shell function.
2371 The
2372 .B \-a
2373 option restricts the variables to indexed arrays; the
2374 .B \-A
2375 option restricts the variables to associative arrays.
2376 If both options are supplied,
2377 .B \-A
2378 takes precedence.
2379 If no
2380 .I name
2381 arguments are supplied, or if the
2382 .B \-p
2383 option is supplied, print a list of all readonly names.
2384 The other options may be used to restrict the output to a subset of
2385 the set of readonly names.
2386 The
2387 .B \-p
2388 option displays output in a format that may be reused as input.
2389 .IP
2390 \fBreadonly\fP allows the value of a variable to be set at the same time
2391 the readonly attribute is changed by following the variable name with
2392 =\fIvalue\fP.
2393 This sets the value of the variable is to \fIvalue\fP while modifying
2394 the readonly attribute.
2395 .IP
2396 The return status is 0 unless an invalid option is encountered,
2397 one of the
2398 .I names
2399 is not a valid shell variable name, or
2400 .B \-f
2401 is supplied with a
2402 .I name
2403 that is not a function.
2404 .TP
2405 \fBreturn\fP [\fIn\fP]
2406 Stop executing a shell function or sourced file and return the value
2407 specified by
2408 .I n
2409 to its caller.
2410 If
2411 .I n
2412 is omitted, the return status is that of the last command
2413 executed.
2414 If \fBreturn\fP is executed by a trap handler, the last command used to
2415 determine the status is the last command executed before the trap handler.
2416 If \fBreturn\fP is executed during a \fBDEBUG\fP trap, the last command
2417 used to determine the status is the last command executed by the trap
2418 handler before \fBreturn\fP was invoked.
2419 .IP
2420 When
2421 .B return
2422 is used to terminate execution of a script being executed by the
2423 .B .
2424 (\fBsource\fP) command, it causes the shell to stop executing
2425 that script and return either
2426 .I n
2427 or the exit status of the last command executed within the
2428 script as the exit status of the script.
2429 If \fIn\fP is supplied, the return value is its least significant
2430 8 bits.
2431 .IP
2432 Any command associated with the \fBRETURN\fP trap is executed
2433 before execution resumes after the function or script.
2434 .IP
2435 The return status is non-zero if
2436 .B return
2437 is supplied a non-numeric argument, or is used outside a
2438 function and not during execution of a script by \fB.\fP\^ or \fBsource\fP.
2439 .TP
2440 \fBset\fP [\fB\-abefhkmnptuvxBCEHPT\fP] [\fB\-o\fP \fIoption\-name\fP] \
2441 [\fB\-\-\fP] [\fB\-\fP] [\fIarg\fP .\|.\|.]
2442 .PD 0
2443 .TP
2444 \fBset\fP [\fB+abefhkmnptuvxBCEHPT\fP] [\fB+o\fP \fIoption\-name\fP] \
2445 [\fB\-\-\fP] [\fB\-\fP] [\fIarg\fP .\|.\|.]
2446 .TP
2447 \fBset \-o\fP
2448 .TP
2449 \fBset +o\fP
2450 .PD
2451 Without options, display the name and value of each shell variable
2452 in a format that can be reused as input
2453 for setting or resetting the currently-set variables.
2454 Read-only variables cannot be reset.
2455 In posix mode, only shell variables are listed.
2456 The output is sorted according to the current locale.
2457 When options are specified, they set or unset shell attributes.
2458 Any arguments remaining after option processing are treated
2459 as values for the positional parameters and are assigned, in order, to
2460 .BR $1 ,
2461 .BR $2 ,
2462 \&.\|.\|.,
2463 .BR $\fIn\fP .
2464 Options, if specified, have the following meanings:
2465 .RS
2466 .PD 0
2467 .TP 8
2468 .B \-a
2469 Each variable or function that is created or modified is given the
2470 export attribute and marked for export to the environment of
2471 subsequent commands.
2472 .TP 8
2473 .B \-b
2474 Report the status of terminated background jobs
2475 immediately, rather than before the next primary prompt or after a
2476 foreground command terminates.
2477 This is effective only when job control is enabled.
2478 .TP 8
2479 .B \-e
2480 .PD
2481 Exit immediately if a
2482 \fIpipeline\fP (which may consist of a single \fIsimple command\fP),
2483 a \fIlist\fP,
2484 or a \fIcompound command\fP
2485 (see
2486 .SM
2487 .B "SHELL GRAMMAR"
2488 .ie \n(zZ=1 in \fIbash\fP(1)),
2489 .el above),
2490 exits with a non-zero status.
2491 The shell does not exit if the
2492 command that fails is part of the command list immediately following a
2493 .B while
2494 or
2495 .B until
2496 reserved word,
2497 part of the test following the
2498 .B if
2499 or
2500 .B elif
2501 reserved words, part of any command executed in a
2502 .B &&
2503 or
2504 .B ||
2505 list except the command following the final \fB&&\fP or \fB||\fP,
2506 any command in a pipeline but the last
2507 (subject to the state of the \fBpipefail\fP shell option),
2508 or if the command's return value is
2509 being inverted with
2510 .BR ! .
2511 If a compound command other than a subshell
2512 returns a non-zero status because a command failed
2513 while \fB\-e\fP was being ignored, the shell does not exit.
2514 A trap on \fBERR\fP, if set, is executed before the shell exits.
2515 This option applies to the shell environment and each subshell environment
2516 separately (see
2517 .SM
2518 .B "COMMAND EXECUTION ENVIRONMENT"
2519 .ie \n(zZ=1 in \fIbash\fP(1)),
2520 .el above),
2521 and may cause
2522 subshells to exit before executing all the commands in the subshell.
2523 .IP
2524 If a compound command or shell function executes in a context
2525 where \fB\-e\fP is being ignored,
2526 none of the commands executed within the compound command or function body
2527 will be affected by the \fB\-e\fP setting, even if \fB\-e\fP is set
2528 and a command returns a failure status.
2529 If a compound command or shell function sets \fB\-e\fP while executing in
2530 a context where \fB\-e\fP is ignored, that setting will not have any
2531 effect until the compound command or the command containing the function
2532 call completes.
2533 .PD 0
2534 .TP 8
2535 .B \-f
2536 Disable pathname expansion.
2537 .TP 8
2538 .B \-h
2539 Remember the location of commands as they are looked up for execution.
2540 This is enabled by default.
2541 .TP 8
2542 .B \-k
2543 All arguments in the form of assignment statements
2544 are placed in the environment for a command, not just
2545 those that precede the command name.
2546 .TP 8
2547 .B \-m
2548 Monitor mode.
2549 Job control is enabled.
2550 This option is on by default for interactive shells on systems
2551 that support it (see
2552 .SM
2553 .B "JOB CONTROL"
2554 .ie \n(zZ=1 in \fIbash\fP(1)).
2555 .el above).
2556 All processes run in a separate process group.
2557 When a background job completes, the shell prints a line
2558 containing its exit status.
2559 .TP 8
2560 .B \-n
2561 Read commands but do not execute them.
2562 This may be used to check a shell script for syntax errors.
2563 This is ignored by interactive shells.
2564 .TP 8
2565 .B \-o \fIoption\-name\fP
2566 The \fIoption\-name\fP can be one of the following:
2567 .RS
2568 .TP 8
2569 .B allexport
2570 Same as
2571 .BR \-a .
2572 .TP 8
2573 .B braceexpand
2574 Same as
2575 .BR \-B .
2576 .TP 8
2577 .B emacs
2578 Use an emacs-style command line editing interface. This is enabled
2579 by default when the shell is interactive, unless the shell is started
2580 with the
2581 .B \-\-noediting
2582 option.
2583 This also affects the editing interface used for \fBread \-e\fP.
2584 .TP 8
2585 .B errexit
2586 Same as
2587 .BR \-e .
2588 .TP 8
2589 .B errtrace
2590 Same as
2591 .BR \-E .
2592 .TP 8
2593 .B functrace
2594 Same as
2595 .BR \-T .
2596 .TP 8
2597 .B hashall
2598 Same as
2599 .BR \-h .
2600 .TP 8
2601 .B histexpand
2602 Same as
2603 .BR \-H .
2604 .TP 8
2605 .B history
2606 Enable command history, as described
2607 .ie \n(zZ=1 in \fIbash\fP(1)
2608 .el above
2609 under
2610 .SM
2611 .BR HISTORY .
2612 This option is on by default in interactive shells.
2613 .TP 8
2614 .B ignoreeof
2615 The effect is as if the shell command
2616 .QN "IGNOREEOF=10"
2617 had been executed
2618 (see
2619 .B "Shell Variables"
2620 .ie \n(zZ=1 in \fIbash\fP(1)).
2621 .el above).
2622 .TP 8
2623 .B keyword
2624 Same as
2625 .BR \-k .
2626 .TP 8
2627 .B monitor
2628 Same as
2629 .BR \-m .
2630 .TP 8
2631 .B noclobber
2632 Same as
2633 .BR \-C .
2634 .TP 8
2635 .B noexec
2636 Same as
2637 .BR \-n .
2638 .TP 8
2639 .B noglob
2640 Same as
2641 .BR \-f .
2642 .TP 8
2643 .B nolog
2644 Currently ignored.
2645 .TP 8
2646 .B notify
2647 Same as
2648 .BR \-b .
2649 .TP 8
2650 .B nounset
2651 Same as
2652 .BR \-u .
2653 .TP 8
2654 .B onecmd
2655 Same as
2656 .BR \-t .
2657 .TP 8
2658 .B physical
2659 Same as
2660 .BR \-P .
2661 .TP 8
2662 .B pipefail
2663 If set, the return value of a pipeline is the value of the last
2664 (rightmost) command to exit with a non-zero status, or zero if all
2665 commands in the pipeline exit successfully.
2666 This option is disabled by default.
2667 .TP 8
2668 .B posix
2669 Enable posix mode;
2670 change the behavior of
2671 .B bash
2672 where the default operation differs
2673 from the
2674 .SM POSIX
2675 standard to match the standard.
2676 See
2677 .SM
2678 .B "SEE ALSO"
2679 .ie \n(zZ=1 in \fIbash\fP(1)
2680 .el below
2681 for a reference to a document that details how posix mode affects
2682 bash's behavior.
2683 .TP 8
2684 .B privileged
2685 Same as
2686 .BR \-p .
2687 .TP 8
2688 .B verbose
2689 Same as
2690 .BR \-v .
2691 .TP 8
2692 .B vi
2693 Use a vi-style command line editing interface.
2694 This also affects the editing interface used for \fBread \-e\fP.
2695 .TP 8
2696 .B xtrace
2697 Same as
2698 .BR \-x .
2699 .PP
2700 If
2701 .B \-o
2702 is supplied with no \fIoption\-name\fP,
2703 \fBset\fP prints the current shell option settings.
2704 If
2705 .B +o
2706 is supplied with no \fIoption\-name\fP,
2707 \fBset\fP prints a series of
2708 .B set
2709 commands to recreate the current option settings
2710 on the standard output.
2711 .RE
2712 .TP 8
2713 .B \-p
2714 Turn on
2715 .I privileged
2716 mode. In this mode, the shell does not read the
2717 .SM
2718 .B $ENV
2719 and
2720 .SM
2721 .B $BASH_ENV
2722 files, shell functions are not inherited from the
2723 environment, and the
2724 .SM
2725 .BR SHELLOPTS ,
2726 .SM
2727 .BR BASHOPTS ,
2728 .SM
2729 .BR CDPATH ,
2730 and
2731 .SM
2732 .B GLOBIGNORE
2733 variables, if they appear in the environment, are ignored.
2734 If the shell is started with the effective user (group) id not equal to the
2735 real user (group) id, and the \fB\-p\fP option is not supplied, these actions
2736 are taken and the effective user id is set to the real user id.
2737 If the \fB\-p\fP option is supplied at startup, the effective user id is
2738 not reset.
2739 Turning this option off causes the effective user
2740 and group ids to be set to the real user and group ids.
2741 .TP 8
2742 .B \-r
2743 Enable restricted shell mode.
2744 This option cannot be unset once it has been set.
2745 .TP 8
2746 .B \-t
2747 Exit after reading and executing one command.
2748 .TP 8
2749 .B \-u
2750 Treat unset variables and parameters other than the special
2751 parameters
2752 .Q @
2753 and
2754 .Q * ,
2755 or array variables subscripted with
2756 .Q @
2757 or
2758 .Q * ,
2759 as an error when performing parameter expansion.
2760 If expansion is attempted on an unset variable or parameter,
2761 the shell prints an error message, and,
2762 if not interactive, exits with a non-zero status.
2763 .TP 8
2764 .B \-v
2765 Print shell input lines as they are read.
2766 .TP 8
2767 .B \-x
2768 After expanding each \fIsimple command\fP,
2769 \fBfor\fP command, \fBcase\fP command, \fBselect\fP command, or
2770 arithmetic \fBfor\fP command, display the expanded value of
2771 .SM
2772 .BR PS4 ,
2773 followed by the command and its expanded arguments
2774 or associated word list, to the standard error.
2775 .TP 8
2776 .B \-B
2777 The shell performs brace expansion (see
2778 .B "Brace Expansion"
2779 .ie \n(zZ=1 in \fIbash\fP(1)).
2780 .el above).
2781 This is on by default.
2782 .TP 8
2783 .B \-C
2784 If set,
2785 .B bash
2786 does not overwrite an existing file with the
2787 .BR > ,
2788 .BR >& ,
2789 and
2790 .B <>
2791 redirection operators.
2792 Using the redirection operator
2793 .B >|
2794 instead of
2795 .B >
2796 will override this and force the creation of an output file.
2797 .TP 8
2798 .B \-E
2799 If set, any trap on \fBERR\fP is inherited by shell functions, command
2800 substitutions, and commands executed in a subshell environment.
2801 The \fBERR\fP trap is normally not inherited in such cases.
2802 .TP 8
2803 .B \-H
2804 Enable
2805 .B !
2806 style history substitution.
2807 This option is on by default when the shell is interactive.
2808 .TP 8
2809 .B \-P
2810 If set, the shell does not resolve symbolic links when executing
2811 commands such as
2812 .B cd
2813 that change the current working directory.
2814 It uses the physical directory structure instead.
2815 By default,
2816 .B bash
2817 follows the logical chain of directories when performing commands
2818 which change the current directory.
2819 .TP 8
2820 .B \-T
2821 If set, any traps on \fBDEBUG\fP and \fBRETURN\fP are inherited by shell
2822 functions, command substitutions, and commands executed in a
2823 subshell environment.
2824 The \fBDEBUG\fP and \fBRETURN\fP traps are normally not inherited
2825 in such cases.
2826 .TP 8
2827 .B \-\-
2828 If no arguments follow this option, unset the positional parameters.
2829 Otherwise, set the positional parameters to the
2830 \fIarg\fPs, even if some of them begin with a
2831 .BR \- .
2832 .TP 8
2833 .B \-
2834 Signal the end of options, and assign all remaining \fIarg\fPs to
2835 the positional parameters.
2836 The
2837 .B \-x
2838 and
2839 .B \-v
2840 options are turned off.
2841 If there are no \fIarg\fPs, the positional parameters remain unchanged.
2842 .PD
2843 .PP
2844 The options are off by default unless otherwise noted.
2845 Using + rather than \- causes these options to be turned off.
2846 The options can also be specified as arguments to an invocation of
2847 the shell.
2848 The current set of options may be found in
2849 .BR $\- .
2850 The return status is always zero unless an invalid option is encountered.
2851 .RE
2852 .TP
2853 \fBshift\fP [\fIn\fP]
2854 Rename positional parameters from \fIn\fP+1 .\|.\|.\& to
2855 .B $1
2856 .B .\|.\|..
2857 Parameters represented by the numbers \fB$#\fP
2858 down to \fB$#\fP\-\fIn\fP+1 are unset.
2859 .I n
2860 must be a non-negative number less than or equal to \fB$#\fP.
2861 If
2862 .I n
2863 is 0, no parameters are changed.
2864 If
2865 .I n
2866 is not given, it is assumed to be 1.
2867 If
2868 .I n
2869 is greater than \fB$#\fP, the positional parameters are not changed.
2870 The return status is greater than zero if
2871 .I n
2872 is greater than
2873 .B $#
2874 or less than zero; otherwise 0.
2875 .TP
2876 \fBshopt\fP [\fB\-pqsu\fP] [\fB\-o\fP] [\fIoptname\fP .\|.\|.]
2877 Toggle the values of settings controlling optional shell behavior.
2878 The settings can be either those listed below, or, if the
2879 .B \-o
2880 option is used, those available with the
2881 .B \-o
2882 option to the \fBset\fP builtin command.
2883 .IP
2884 With no options, or with the
2885 .B \-p
2886 option, display a list of all settable options, with
2887 an indication of whether or not each is set;
2888 if any \fIoptnames\fP are supplied, the output is restricted to those options.
2889 The \fB\-p\fP option displays output in a form that
2890 may be reused as input.
2891 .IP
2892 Other options have the following meanings:
2893 .RS
2894 .PD 0
2895 .TP
2896 .B \-s
2897 Enable (set) each \fIoptname\fP.
2898 .TP
2899 .B \-u
2900 Disable (unset) each \fIoptname\fP.
2901 .TP
2902 .B \-q
2903 Suppresses normal output (quiet mode); the return status indicates
2904 whether the \fIoptname\fP is set or unset.
2905 If multiple \fIoptname\fP arguments are supplied with
2906 .BR \-q ,
2907 the return status is zero if all \fIoptnames\fP are enabled; non-zero
2908 otherwise.
2909 .TP
2910 .B \-o
2911 Restricts the values of \fIoptname\fP to be those defined for the
2912 .B \-o
2913 option to the
2914 .B set
2915 builtin.
2916 .PD
2917 .PP
2918 If either
2919 .B \-s
2920 or
2921 .B \-u
2922 is used with no \fIoptname\fP arguments,
2923 .B shopt
2924 shows only those options which are set or unset, respectively.
2925 Unless otherwise noted, the \fBshopt\fP options are disabled (unset)
2926 by default.
2927 .PP
2928 The return status when listing options is zero if all \fIoptnames\fP
2929 are enabled, non-zero otherwise. When setting or unsetting options,
2930 the return status is zero unless an \fIoptname\fP is not a valid shell
2931 option.
2932 .PP
2933 The list of \fBshopt\fP options is:
2934 .PP
2935 .PD 0
2936 .TP 8
2937 .B array_expand_once
2938 If set, the shell suppresses multiple evaluation of
2939 associative and indexed array subscripts
2940 during arithmetic expression evaluation, while executing
2941 builtins that can perform variable assignments,
2942 and while executing builtins that perform array dereferencing.
2943 .TP 8
2944 .B assoc_expand_once
2945 Deprecated; a synonym for \fBarray_expand_once\fP.
2946 .TP 8
2947 .B autocd
2948 If set, a command name that is the name of a directory is executed as if
2949 it were the argument to the \fBcd\fP command.
2950 This option is only used by interactive shells.
2951 .TP 8
2952 .B bash_source_fullpath
2953 If set, filenames added to the \fBBASH_SOURCE\fP array variable are
2954 converted to full pathnames (see \fBShell Variables\fP above).
2955 .TP 8
2956 .B cdable_vars
2957 If set, an argument to the
2958 .B cd
2959 builtin command that
2960 is not a directory is assumed to be the name of a variable whose
2961 value is the directory to change to.
2962 .TP 8
2963 .B cdspell
2964 If set, the
2965 .B cd
2966 command attempts to correct
2967 minor errors in the spelling of a directory component.
2968 Minor errors include transposed characters,
2969 a missing character, and one extra character.
2970 If \fBcd\fP corrects the directory name, it prints the corrected filename,
2971 and the command proceeds.
2972 This option is only used by interactive shells.
2973 .TP 8
2974 .B checkhash
2975 If set, \fBbash\fP checks that a command found in the hash
2976 table exists before trying to execute it.
2977 If a hashed command no longer exists, \fBbash\fP performs a normal path search.
2978 .TP 8
2979 .B checkjobs
2980 If set, \fBbash\fP lists the status of any stopped and running jobs before
2981 exiting an interactive shell.
2982 If any jobs are running, \fBbash\fP defers the exit until a second
2983 exit is attempted without an intervening command (see
2984 .SM
2985 .B "JOB CONTROL"
2986 .ie \n(zZ=1 in \fIbash\fP(1)).
2987 .el above).
2988 The shell always postpones exiting if any jobs are stopped.
2989 .TP 8
2990 .B checkwinsize
2991 If set, \fBbash\fP checks the window size after each external (non-builtin)
2992 command
2993 and, if necessary, updates the values of
2994 .SM
2995 .B LINES
2996 and
2997 .SM
2998 .BR COLUMNS ,
2999 using the file descriptor associated with the standard error
3000 if it is a terminal.
3001 This option is enabled by default.
3002 .TP 8
3003 .B cmdhist
3004 If set,
3005 .B bash
3006 attempts to save all lines of a multiple-line
3007 command in the same history entry.
3008 This allows easy re-editing of multi-line commands.
3009 This option is enabled by default, but only has an effect if command
3010 history is enabled, as described
3011 .ie \n(zZ=1 in \fIbash\fP(1)
3012 .el above
3013 under
3014 .SM
3015 .BR HISTORY .
3016 .PD 0
3017 .TP 8
3018 .B compat31
3019 .TP 8
3020 .B compat32
3021 .TP 8
3022 .B compat40
3023 .TP 8
3024 .B compat41
3025 .TP 8
3026 .B compat42
3027 .TP 8
3028 .B compat43
3029 .TP 8
3030 .B compat44
3031 .PD
3032 These control aspects of the shell's compatibility mode
3033 (see
3034 .SM
3035 .B "SHELL COMPATIBILITY MODE"
3036 .ie \n(zZ=1 in \fIbash\fP(1)).
3037 .el below).
3038 .PD 0
3039 .TP 8
3040 .B complete_fullquote
3041 If set,
3042 .B bash
3043 quotes all shell metacharacters in filenames and directory names when
3044 performing completion.
3045 If not set,
3046 .B bash
3047 removes metacharacters such as the dollar sign from the set of
3048 characters that will be quoted in completed filenames
3049 when these metacharacters appear in shell variable references in words to be
3050 completed.
3051 This means that dollar signs in variable names that expand to directories
3052 will not be quoted;
3053 however, any dollar signs appearing in filenames will not be quoted, either.
3054 This is active only when bash is using backslashes to quote completed
3055 filenames.
3056 This variable is set by default, which is the default bash behavior in
3057 versions through 4.2.
3058 .TP 8
3059 .B direxpand
3060 If set,
3061 .B bash
3062 replaces directory names with the results of word expansion when performing
3063 filename completion.
3064 This changes the contents of the \fBreadline\fP editing buffer.
3065 If not set,
3066 .B bash
3067 attempts to preserve what the user typed.
3068 .TP 8
3069 .B dirspell
3070 If set,
3071 .B bash
3072 attempts spelling correction on directory names during word completion
3073 if the directory name initially supplied does not exist.
3074 .TP 8
3075 .B dotglob
3076 If set,
3077 .B bash
3078 includes filenames beginning with a
3079 .Q .\&
3080 in the results of pathname expansion.
3081 The filenames
3082 .FN .\&
3083 and
3084 .FN ..\&
3085 must always be matched explicitly, even if
3086 .B dotglob
3087 is set.
3088 .TP 8
3089 .B execfail
3090 If set, a non-interactive shell will not exit if
3091 it cannot execute the file specified as an argument to the
3092 .B exec
3093 builtin.
3094 An interactive shell does not exit if
3095 .B exec
3096 fails.
3097 .TP 8
3098 .B expand_aliases
3099 If set, aliases are expanded as described
3100 .ie \n(zZ=1 in \fIbash\fP(1)
3101 .el above
3102 under
3103 .SM
3104 .BR ALIASES .
3105 This option is enabled by default for interactive shells.
3106 .TP 8
3107 .B extdebug
3108 If set at shell invocation, or in a shell startup file,
3109 arrange to execute the debugger profile
3110 before the shell starts, identical to the \fB\-\-debugger\fP option.
3111 If set after invocation, behavior intended for use by debuggers is enabled:
3112 .RS
3113 .TP
3114 .B 1.
3115 The \fB\-F\fP option to the \fBdeclare\fP builtin displays the source
3116 file name and line number corresponding to each function name supplied
3117 as an argument.
3118 .TP
3119 .B 2.
3120 If the command run by the \fBDEBUG\fP trap returns a non-zero value, the
3121 next command is skipped and not executed.
3122 .TP
3123 .B 3.
3124 If the command run by the \fBDEBUG\fP trap returns a value of 2, and the
3125 shell is executing in a subroutine (a shell function or a shell script
3126 executed by the \fB.\fP or \fBsource\fP builtins), the shell simulates
3127 a call to \fBreturn\fP.
3128 .TP
3129 .B 4.
3130 .SM
3131 .B BASH_ARGC
3132 and
3133 .SM
3134 .B BASH_ARGV
3135 are updated as described in their descriptions
3136 .ie \n(zZ=1 in \fIbash\fP(1)).
3137 .el above).
3138 .TP
3139 .B 5.
3140 Function tracing is enabled: command substitution, shell functions, and
3141 subshells invoked with \fB(\fP \fIcommand\fP \fB)\fP inherit the
3142 \fBDEBUG\fP and \fBRETURN\fP traps.
3143 .TP
3144 .B 6.
3145 Error tracing is enabled: command substitution, shell functions, and
3146 subshells invoked with \fB(\fP \fIcommand\fP \fB)\fP inherit the
3147 \fBERR\fP trap.
3148 .RE
3149 .TP 8
3150 .B extglob
3151 If set, enable the extended pattern matching features described
3152 .ie \n(zZ=1 in \fIbash\fP(1)
3153 .el above
3154 under
3155 \fBPathname Expansion\fP.
3156 .TP 8
3157 .B extquote
3158 If set, \fB$\fP\*'\fIstring\fP\*' and \fB$\fP\*"\fIstring\fP\*" quoting is
3159 performed within \fB${\fP\fIparameter\fP\fB}\fP expansions
3160 enclosed in double quotes.
3161 This option is enabled by default.
3162 .TP 8
3163 .B failglob
3164 If set, patterns which fail to match filenames during pathname expansion
3165 result in an expansion error.
3166 .TP 8
3167 .B force_fignore
3168 If set, the suffixes specified by the
3169 .SM
3170 .B FIGNORE
3171 shell variable
3172 cause words to be ignored when performing word completion even if
3173 the ignored words are the only possible completions.
3174 See
3175 .B "Shell Variables"
3176 .ie \n(zZ=1 in \fIbash\fP(1)
3177 .el above
3178 for a description of
3179 .SM
3180 .BR FIGNORE .
3181 This option is enabled by default.
3182 .TP 8
3183 .B globasciiranges
3184 If set, range expressions used in pattern matching bracket expressions (see
3185 .SM
3186 .B "Pattern Matching"
3187 .ie \n(zZ=1 in \fIbash\fP(1))
3188 .el above)
3189 behave as if in the traditional C locale when performing comparisons.
3190 That is, pattern matching does not take
3191 the current locale's collating sequence into account, so
3192 .B b
3193 will not collate between
3194 .B A
3195 and
3196 .BR B ,
3197 and upper-case and lower-case ASCII characters will collate together.
3198 .TP 8
3199 .B globskipdots
3200 If set, pathname expansion will never match the filenames
3201 .FN .\&
3202 and
3203 .FN ..\& ,
3204 even if the pattern begins with a
3205 .Q .\& .
3206 This option is enabled by default.
3207 .TP 8
3208 .B globstar
3209 If set, the pattern \fB**\fP used in a pathname expansion context will
3210 match all files and zero or more directories and subdirectories.
3211 If the pattern is followed by a \fB/\fP, only directories and
3212 subdirectories match.
3213 .TP 8
3214 .B gnu_errfmt
3215 If set, shell error messages are written in the standard GNU error
3216 message format.
3217 .TP 8
3218 .B histappend
3219 If set, the history list is appended to the file named by the value
3220 of the
3221 .SM
3222 .B HISTFILE
3223 variable when the shell exits, rather than overwriting the file.
3224 .TP 8
3225 .B histreedit
3226 If set, and
3227 .B readline
3228 is being used, the user is given the opportunity to re-edit a
3229 failed history substitution.
3230 .TP 8
3231 .B histverify
3232 If set, and
3233 .B readline
3234 is being used, the results of history substitution are not immediately
3235 passed to the shell parser.
3236 Instead, the resulting line is loaded into the \fBreadline\fP editing buffer,
3237 allowing further modification.
3238 .TP 8
3239 .B hostcomplete
3240 If set, and
3241 .B readline
3242 is being used, \fBbash\fP will attempt to perform hostname completion when a
3243 word containing a \fB@\fP is being completed (see
3244 .B Completing
3245 under
3246 .SM
3247 .B READLINE
3248 .ie \n(zZ=1 in \fIbash\fP(1)).
3249 .el above).
3250 This is enabled by default.
3251 .TP 8
3252 .B huponexit
3253 If set, \fBbash\fP will send
3254 .SM
3255 .B SIGHUP
3256 to all jobs when an interactive login shell exits.
3257 .TP 8
3258 .B inherit_errexit
3259 If set, command substitution inherits the value of the \fBerrexit\fP option,
3260 instead of unsetting it in the subshell environment.
3261 This option is enabled when posix mode is enabled.
3262 .TP 8
3263 .B interactive_comments
3264 In an interactive shell, a word beginning with \fB#\fP
3265 causes that word and all remaining characters on that
3266 line to be ignored, as in a non-interactive shell
3267 (see
3268 .SM
3269 .B COMMENTS
3270 .ie \n(zZ=1 in \fIbash\fP(1)).
3271 .el above).
3272 This option is enabled by default.
3273 .TP 8
3274 .B lastpipe
3275 If set, and job control is not active, the shell runs the last command of
3276 a pipeline not executed in the background in the current shell environment.
3277 .TP 8
3278 .B lithist
3279 If set, and the
3280 .B cmdhist
3281 option is enabled, multi-line commands are saved to the history with
3282 embedded newlines rather than using semicolon separators where possible.
3283 .TP 8
3284 .B localvar_inherit
3285 If set, local variables inherit the value and attributes of a variable of
3286 the same name that exists at a previous scope before any new value is
3287 assigned.
3288 The nameref attribute is not inherited.
3289 .TP 8
3290 .B localvar_unset
3291 If set, calling \fBunset\fP on local variables in previous function scopes
3292 marks them so subsequent lookups find them unset until that function
3293 returns.
3294 This is identical to the behavior of unsetting local variables at the
3295 current function scope.
3296 .TP 8
3297 .B login_shell
3298 The shell sets this option if it is started as a login shell (see
3299 .SM
3300 .B "INVOCATION"
3301 .ie \n(zZ=1 in \fIbash\fP(1)).
3302 .el above).
3303 The value may not be changed.
3304 .TP 8
3305 .B mailwarn
3306 If set, and a file that \fBbash\fP is checking for mail has been
3307 accessed since the last time it was checked,
3308 \fBbash\fP displays the message
3309 .Q "The mail in \fImailfile\fP has been read" .
3310 .TP 8
3311 .B no_empty_cmd_completion
3312 If set, and
3313 .B readline
3314 is being used,
3315 .B bash
3316 does not search
3317 .SM
3318 .B PATH
3319 for possible completions when completion is attempted on an empty line.
3320 .TP 8
3321 .B nocaseglob
3322 If set,
3323 .B bash
3324 matches filenames in a case\-insensitive fashion when performing pathname
3325 expansion (see
3326 .B "Pathname Expansion"
3327 .ie \n(zZ=1 in \fIbash\fP(1)).
3328 .el above).
3329 .TP 8
3330 .B nocasematch
3331 If set,
3332 .B bash
3333 matches patterns in a case\-insensitive fashion when performing matching
3334 while executing \fBcase\fP or \fB[[\fP conditional commands,
3335 when performing pattern substitution word expansions,
3336 or when filtering possible completions as part of programmable completion.
3337 .TP 8
3338 .B noexpand_translation
3339 If set,
3340 .B bash
3341 encloses the translated results of
3342 .BR $\*" .\|.\|.\& \*"
3343 quoting in single quotes instead of double quotes.
3344 If the string is not translated, this has no effect.
3345 .TP 8
3346 .B nullglob
3347 If set, pathname expansion patterns which match no files
3348 (see
3349 .B "Pathname Expansion"
3350 .ie \n(zZ=1 in \fIbash\fP(1))
3351 .el above)
3352 expand to nothing and are removed, rather than expanding to themselves.
3353 .TP 8
3354 .B patsub_replacement
3355 If set, \fBbash\fP
3356 expands occurrences of \fB&\fP in the replacement string of pattern
3357 substitution to the text matched by the pattern, as described
3358 under \fBParameter Expansion\fP
3359 .ie \n(zZ=1 in \fIbash\fP(1).
3360 .el above.
3361 This option is enabled by default.
3362 .TP 8
3363 .B progcomp
3364 If set, enable the programmable completion facilities (see
3365 \fBProgrammable Completion\fP
3366 .ie \n(zZ=1 in \fIbash\fP(1)).
3367 .el above).
3368 This option is enabled by default.
3369 .TP 8
3370 .B progcomp_alias
3371 If set, and programmable completion is enabled, \fBbash\fP treats a command
3372 name that doesn't have any completions as a possible alias and attempts
3373 alias expansion.
3374 If it has an alias, \fBbash\fP attempts programmable
3375 completion using the command word resulting from the expanded alias.
3376 .TP 8
3377 .B promptvars
3378 If set, prompt strings undergo
3379 parameter expansion, command substitution, arithmetic
3380 expansion, and quote removal after being expanded as described in
3381 .SM
3382 .B PROMPTING
3383 .ie \n(zZ=1 in \fIbash\fP(1).
3384 .el above.
3385 This option is enabled by default.
3386 .TP 8
3387 .B restricted_shell
3388 The shell sets this option if it is started in restricted mode
3389 (see
3390 .SM
3391 .B "RESTRICTED SHELL"
3392 .ie \n(zZ=1 in \fIbash\fP(1)).
3393 .el below).
3394 The value may not be changed.
3395 This is not reset when the startup files are executed, allowing
3396 the startup files to discover whether or not a shell is restricted.
3397 .TP 8
3398 .B shift_verbose
3399 If set, the
3400 .B shift
3401 builtin prints an error message when the shift count exceeds the
3402 number of positional parameters.
3403 .TP 8
3404 .B sourcepath
3405 If set, the
3406 \fB.\fP (\fBsource\fP) builtin uses the value of
3407 .SM
3408 .B PATH
3409 to find the directory containing the file supplied as an argument when
3410 the \fB\-p\fP option is not supplied.
3411 This option is enabled by default.
3412 .TP 8
3413 .B varredir_close
3414 If set, the shell automatically closes file descriptors assigned using the
3415 \fI{varname}\fP redirection syntax (see
3416 .SM
3417 .B REDIRECTION
3418 .ie \n(zZ=1 in \fIbash\fP(1))
3419 .el above)
3420 instead of leaving them open when the command completes.
3421 .TP 8
3422 .B xpg_echo
3423 If set, the \fBecho\fP builtin expands backslash-escape sequences
3424 by default.
3425 If the \fBposix\fP shell option is also enabled, \fBecho\fP does not
3426 interpret any options.
3427 .RE
3428 .PD
3429 .TP
3430 \fBsuspend\fP [\fB\-f\fP]
3431 Suspend the execution of this shell until it receives a
3432 .SM
3433 .B SIGCONT
3434 signal.
3435 A login shell, or a shell without job control enabled,
3436 cannot be suspended; the
3437 .B \-f
3438 option will override this and force the suspension.
3439 The return status is 0 unless the shell is a login shell
3440 or job control is not enabled
3441 and
3442 .B \-f
3443 is not supplied.
3444 .TP
3445 \fBtest\fP \fIexpr\fP
3446 .PD 0
3447 .TP
3448 \fB[\fP \fIexpr\fP \fB]\fP
3449 .PD
3450 Return a status of 0 (true) or 1 (false) depending on
3451 the evaluation of the conditional expression
3452 .IR expr .
3453 Each operator and operand must be a separate argument.
3454 Expressions are composed of the primaries described
3455 .ie \n(zZ=1 in \fIbash\fP(1)
3456 .el above
3457 under
3458 .SM
3459 .BR "CONDITIONAL EXPRESSIONS" .
3460 \fBtest\fP does not accept any options, nor does it accept and ignore
3461 an argument of \fB\-\-\fP as signifying the end of options.
3462 .IP
3463 Expressions may be combined using the following operators, listed
3464 in decreasing order of precedence.
3465 The evaluation depends on the number of arguments; see below.
3466 \fBtest\fP uses operator precedence when there are five or more arguments.
3467 .RS
3468 .PD 0
3469 .TP
3470 .B ! \fIexpr\fP
3471 True if
3472 .I expr
3473 is false.
3474 .TP
3475 .B ( \fIexpr\fP )
3476 Returns the value of \fIexpr\fP.
3477 This may be used to override normal operator precedence.
3478 .TP
3479 \fIexpr1\fP \-\fBa\fP \fIexpr2\fP
3480 True if both
3481 .I expr1
3482 and
3483 .I expr2
3484 are true.
3485 .TP
3486 \fIexpr1\fP \-\fBo\fP \fIexpr2\fP
3487 True if either
3488 .I expr1
3489 or
3490 .I expr2
3491 is true.
3492 .PD
3493 .PP
3494 \fBtest\fP and \fB[\fP evaluate conditional
3495 expressions using a set of rules based on the number of arguments.
3496 .PP
3497 .PD 0
3498 .TP
3499 0 arguments
3500 The expression is false.
3501 .TP
3502 1 argument
3503 The expression is true if and only if the argument is not null.
3504 .TP
3505 2 arguments
3506 If the first argument is \fB!\fP, the expression is true if and
3507 only if the second argument is null.
3508 If the first argument is one of the unary conditional operators listed
3509 .ie \n(zZ=1 in \fIbash\fP(1)
3510 .el above
3511 under
3512 .SM
3513 .BR "CONDITIONAL EXPRESSIONS" ,
3514 the expression is true if the unary test is true.
3515 If the first argument is not a valid unary conditional operator, the expression
3516 is false.
3517 .TP
3518 3 arguments
3519 The following conditions are applied in the order listed.
3520 If the second argument is one of the binary conditional operators listed
3521 .ie \n(zZ=1 in \fIbash\fP(1)
3522 .el above
3523 under
3524 .SM
3525 .BR "CONDITIONAL EXPRESSIONS" ,
3526 the result of the expression is the result of the binary test using
3527 the first and third arguments as operands.
3528 The \fB\-a\fP and \fB\-o\fP operators are considered binary operators
3529 when there are three arguments.
3530 If the first argument is \fB!\fP, the value is the negation of
3531 the two-argument test using the second and third arguments.
3532 If the first argument is exactly \fB(\fP and the third argument is
3533 exactly \fB)\fP, the result is the one-argument test of the second
3534 argument.
3535 Otherwise, the expression is false.
3536 .TP
3537 4 arguments
3538 The following conditions are applied in the order listed.
3539 If the first argument is \fB!\fP, the result is the negation of
3540 the three-argument expression composed of the remaining arguments.
3541 If the first argument is exactly \fB(\fP and the fourth argument is
3542 exactly \fB)\fP, the result is the two-argument test of the second
3543 and third arguments.
3544 Otherwise, the expression is parsed and evaluated according to
3545 precedence using the rules listed above.
3546 .TP
3547 5 or more arguments
3548 The expression is parsed and evaluated according to precedence
3549 using the rules listed above.
3550 .PD
3551 .PP
3552 When the shell is in posix mode, or if the expression is part
3553 of the \fB[[\fP command,
3554 the \fB<\fP and \fB>\fP operators sort using the
3555 current locale.
3556 If the shell is not in posix mode, the \fBtest\fP and \fB[\fP
3557 commands sort lexicographically using ASCII ordering.
3558 .PP
3559 The historical operator-precedence parsing with 4 or more arguments can
3560 lead to ambiguities when it encounters strings that look like primaries.
3561 The
3562 .SM POSIX
3563 standard has deprecated the \fB\-a\fP and \fB\-o\fP
3564 primaries and enclosing expressions within parentheses.
3565 Scripts should no longer use them.
3566 It's much more reliable to restrict test invocations to a single primary,
3567 and to replace uses of \fB\-a\fP and \fB\-o\fP with the shell's
3568 \fB&&\fP and \fB||\fP list operators.
3569 .RE
3570 .TP
3571 .B times
3572 Print the accumulated user and system times for the shell and
3573 for processes run from the shell.
3574 The return status is 0.
3575 .TP
3576 \fBtrap\fP [\fB\-lpP\fP] [[\fIaction\fP] \fIsigspec\fP .\|.\|.]
3577 The
3578 .I action
3579 is a command that is read and executed when the shell receives
3580 any of the signals
3581 .IR sigspec .
3582 If
3583 .I action
3584 is absent (and there is a single \fIsigspec\fP) or
3585 .BR \- ,
3586 each specified \fIsigspec\fP is
3587 reset to the value it had when the shell was started.
3588 If
3589 .I action
3590 is the null string the signal specified by each
3591 .I sigspec
3592 is ignored by the shell and by the commands it invokes.
3593 .IP
3594 If no arguments are supplied,
3595 .B trap
3596 displays the actions associated with each trapped signal
3597 as a set of \fBtrap\fP commands
3598 that can be reused as shell input to
3599 restore the current signal dispositions.
3600 If
3601 .B \-p
3602 is given,
3603 and
3604 .I action
3605 is not present,
3606 then \fBtrap\fP displays the actions associated with each
3607 .I sigspec
3608 or, if none are supplied, for all trapped signals,
3609 as a set of \fBtrap\fP commands
3610 that can be reused as shell input to
3611 restore the current signal dispositions.
3612 The
3613 .B \-P
3614 option behaves similarly, but displays only the actions
3615 associated with each \fIsigspec\fP argument.
3616 .B \-P
3617 requires at least one \fIsigspec\fP argument.
3618 The \fB\-P\fP or \fB\-p\fP options may be used
3619 in a subshell environment (e.g., command substitution) and, as
3620 long as they are used before \fBtrap\fP is used to change a signal's
3621 handling, will display the state of its parent's traps.
3622 .IP
3623 The
3624 .B \-l
3625 option prints a list of signal names and
3626 their corresponding numbers.
3627 Each
3628 .I sigspec
3629 is either
3630 a signal name defined in <\fIsignal.h\fP>, or a signal number.
3631 Signal names are case insensitive and the
3632 .SM
3633 .B SIG
3634 prefix is optional.
3635 If \fB\-l\fP is supplied with no \fIsigspec\fP arguments, it prints a
3636 list of valid signal names.
3637 .IP
3638 If a
3639 .I sigspec
3640 is
3641 .SM
3642 .B EXIT
3643 (0),
3644 .I action
3645 is executed on exit from the shell.
3646 If a
3647 .I sigspec
3648 is
3649 .SM
3650 .BR DEBUG ,
3651 .I action
3652 is executed before every \fIsimple command\fP, \fIfor\fP command,
3653 \fIcase\fP command, \fIselect\fP command, (( arithmetic command,
3654 [[ conditional command,
3655 arithmetic \fIfor\fP command, and before the first command executes
3656 in a shell function (see
3657 .SM
3658 .B "SHELL GRAMMAR"
3659 .ie \n(zZ=1 in \fIbash\fP(1)).
3660 .el above).
3661 Refer to the description of the \fBextdebug\fP shell option
3662 (see
3663 .B shopt
3664 .ie \n(zZ=1 in \fIbash\fP(1))
3665 .el above)
3666 for details of its effect on the \fBDEBUG\fP trap.
3667 If a
3668 .I sigspec
3669 is
3670 .SM
3671 .BR RETURN ,
3672 .I action
3673 is executed each time a shell function or a script executed with
3674 the \fB.\fP or \fBsource\fP builtins finishes executing.
3675 .IP
3676 If a
3677 .I sigspec
3678 is
3679 .SM
3680 .BR ERR ,
3681 .I action
3682 is executed whenever
3683 a pipeline (which may consist of a single simple
3684 command), a list, or a compound command returns a
3685 non\-zero exit status,
3686 subject to the following conditions.
3687 The
3688 .SM
3689 .B ERR
3690 trap is not executed if the failed
3691 command is part of the command list immediately following a
3692 .B while
3693 or
3694 .B until
3695 reserved word,
3696 part of the test in an
3697 .I if
3698 statement, part of a command executed in a
3699 .B &&
3700 or
3701 .B ||
3702 list except the command following the final \fB&&\fP or \fB||\fP,
3703 any command in a pipeline but the last
3704 (subject to the state of the \fBpipefail\fP shell option),
3705 or if the command's return value is
3706 being inverted using
3707 .BR ! .
3708 These are the same conditions obeyed by the \fBerrexit\fP (\fB\-e\fP) option.
3709 .IP
3710 When the shell is not interactive,
3711 signals ignored upon entry to the shell cannot be trapped or reset.
3712 Interactive shells permit trapping signals ignored on entry.
3713 Trapped signals that are not being ignored are reset to their original
3714 values in a subshell or subshell environment when one is created.
3715 The return status is false if any
3716 .I sigspec
3717 is invalid; otherwise
3718 .B trap
3719 returns true.
3720 .TP
3721 \fBtrue\fP
3722 Does nothing, returns a 0 status.
3723 .TP
3724 \fBtype\fP [\fB\-aftpP\fP] \fIname\fP [\fIname\fP .\|.\|.]
3725 Indicate how each
3726 .I name
3727 would be interpreted if used as a command name.
3728 .IP
3729 If the
3730 .B \-t
3731 option is used,
3732 .B type
3733 prints a string which is one of
3734 .IR alias ,
3735 .IR keyword ,
3736 .IR function ,
3737 .IR builtin ,
3738 or
3739 .I file
3740 if
3741 .I name
3742 is an alias, shell reserved word, function, builtin, or executable file,
3743 respectively.
3744 If the
3745 .I name
3746 is not found, \fBtype\fP prints nothing and returns a non-zero exit status.
3747 .IP
3748 If the
3749 .B \-p
3750 option is used,
3751 .B type
3752 either returns the pathname of the executable file
3753 that would be found by searching
3754 .B $PATH
3755 for
3756 .I name
3757 or nothing if
3758 .Q "type \-t name"
3759 would not return
3760 .IR file .
3761 The
3762 .B \-P
3763 option forces a
3764 .SM
3765 .B PATH
3766 search for each \fIname\fP, even if
3767 .Q "type \-t name"
3768 would not return
3769 .IR file .
3770 If \fIname\fP is present in the table of hashed commands,
3771 .B \-p
3772 and
3773 .B \-P
3774 print the hashed value, which is not necessarily the file that appears
3775 first in
3776 .SM
3777 .BR PATH .
3778 .IP
3779 If the
3780 .B \-a
3781 option is used,
3782 .B type
3783 prints all of the places that contain a command named
3784 .IR name .
3785 This includes aliases, reserved words, functions, and builtins,
3786 but the path search options (\fB\-p\fP and \fB\-P\fP)
3787 can be supplied to restrict the output to executable files.
3788 \fBtype\fP does not consult the table of hashed commands
3789 when using
3790 .B \-a
3791 with
3792 .BR \-p ,
3793 and only performs a
3794 .SM
3795 .B PATH
3796 search for \fIname\fP.
3797 .IP
3798 The
3799 .B \-f
3800 option suppresses shell function lookup, as with the \fBcommand\fP builtin.
3801 .B type
3802 returns true if all of the arguments are found, false if
3803 any are not found.
3804 .TP
3805 \fBulimit\fP [\fB\-HS\fP] \fB\-a\fP
3806 .PD 0
3807 .TP
3808 \fBulimit\fP [\fB\-HS\fP] [\fB\-bcdefiklmnpqrstuvxPRT\fP [\fIlimit\fP]]
3809 .PD
3810 Provides control over the resources available to the shell and to
3811 processes it starts, on systems that allow such control.
3812 .IP
3813 The \fB\-H\fP and \fB\-S\fP options specify whether
3814 the hard or soft limit is set for the given resource.
3815 A hard limit cannot be increased by a non-root user once it is set;
3816 a soft limit may be increased up to the value of the hard limit.
3817 If neither \fB\-H\fP nor \fB\-S\fP is specified,
3818 \fBulimit\fP sets both the soft and hard limits.
3819 .IP
3820 The value of
3821 .I limit
3822 can be a number in the unit specified for the resource
3823 or one of the special values
3824 .BR hard ,
3825 .BR soft ,
3826 or
3827 .BR unlimited ,
3828 which stand for the current hard limit, the current soft limit, and
3829 no limit, respectively.
3830 If
3831 .I limit
3832 is omitted, \fBulimit\fP prints the current value of the soft limit of
3833 the resource, unless the \fB\-H\fP option is given.
3834 When more than one resource is specified, the limit name and unit,
3835 if appropriate, are printed before the value.
3836 Other options are interpreted as follows:
3837 .RS
3838 .PD 0
3839 .TP
3840 .B \-a
3841 Report all current limits; no limits are set.
3842 .TP
3843 .B \-b
3844 The maximum socket buffer size.
3845 .TP
3846 .B \-c
3847 The maximum size of core files created.
3848 .TP
3849 .B \-d
3850 The maximum size of a process's data segment.
3851 .TP
3852 .B \-e
3853 The maximum scheduling priority (\c
3854 .Q nice ).
3855 .TP
3856 .B \-f
3857 The maximum size of files written by the shell and its children.
3858 .TP
3859 .B \-i
3860 The maximum number of pending signals.
3861 .TP
3862 .B \-k
3863 The maximum number of kqueues that may be allocated.
3864 .TP
3865 .B \-l
3866 The maximum size that may be locked into memory.
3867 .TP
3868 .B \-m
3869 The maximum resident set size (many systems do not honor this limit).
3870 .TP
3871 .B \-n
3872 The maximum number of open file descriptors (most systems do not
3873 allow this value to be set).
3874 .TP
3875 .B \-p
3876 The pipe size in 512-byte blocks (this may not be set).
3877 .TP
3878 .B \-q
3879 The maximum number of bytes in
3880 .SM POSIX
3881 message queues.
3882 .TP
3883 .B \-r
3884 The maximum real-time scheduling priority.
3885 .TP
3886 .B \-s
3887 The maximum stack size.
3888 .TP
3889 .B \-t
3890 The maximum amount of cpu time in seconds.
3891 .TP
3892 .B \-u
3893 The maximum number of processes available to a single user.
3894 .TP
3895 .B \-v
3896 The maximum amount of virtual memory available to the shell and, on
3897 some systems, to its children.
3898 .TP
3899 .B \-x
3900 The maximum number of file locks.
3901 .TP
3902 .B \-P
3903 The maximum number of pseudoterminals.
3904 .TP
3905 .B \-R
3906 The maximum time a real-time process can run before blocking, in microseconds.
3907 .TP
3908 .B \-T
3909 The maximum number of threads.
3910 .PD
3911 .PP
3912 If
3913 .I limit
3914 is supplied, and the
3915 .B \-a
3916 option is not used,
3917 \fIlimit\fP is the new value of the specified resource.
3918 If no option is supplied, then
3919 .B \-f
3920 is assumed.
3921 .PP
3922 Values are in 1024-byte increments, except for
3923 .BR \-t ,
3924 which is in seconds;
3925 .BR \-R ,
3926 which is in microseconds;
3927 .BR \-p ,
3928 which is in units of 512-byte blocks;
3929 .BR \-P ,
3930 .BR \-T ,
3931 .BR \-b ,
3932 .BR \-k ,
3933 .BR \-n ,
3934 and
3935 .BR \-u ,
3936 which are unscaled values;
3937 and, when in posix mode,
3938 .B \-c
3939 and
3940 .BR \-f ,
3941 which are in 512-byte increments.
3942 The return status is 0 unless an invalid option or argument is supplied,
3943 or an error occurs while setting a new limit.
3944 .RE
3945 .TP
3946 \fBumask\fP [\fB\-p\fP] [\fB\-S\fP] [\fImode\fP]
3947 Set the user file-creation mask to
3948 .IR mode .
3949 If
3950 .I mode
3951 begins with a digit, it is interpreted as an octal number;
3952 otherwise it is interpreted as a symbolic mode mask similar
3953 to that accepted by
3954 .IR chmod (1).
3955 If
3956 .I mode
3957 is omitted, \fBumask\fP prints the current value of the mask.
3958 The
3959 .B \-S
3960 option without a \fImode\fP argument
3961 prints the mask in a symbolic format;
3962 the default output is an octal number.
3963 If the
3964 .B \-p
3965 option is supplied, and
3966 .I mode
3967 is omitted, the output is in a form that may be reused as input.
3968 The return status is zero if the mode was successfully changed or
3969 if no \fImode\fP argument was supplied, and non-zero otherwise.
3970 .TP
3971 \fBunalias\fP [\-\fBa\fP] [\fIname\fP .\|.\|.]
3972 Remove each \fIname\fP from the list of defined aliases.
3973 If
3974 .B \-a
3975 is supplied, remove all alias definitions.
3976 The return value is true unless a supplied
3977 .I name
3978 is not a defined alias.
3979 .TP
3980 \fBunset\fP [\-\fBfv\fP] [\-\fBn\fP] [\fIname\fP .\|.\|.]
3981 For each
3982 .IR name ,
3983 remove the corresponding variable or function.
3984 If the
3985 .B \-v
3986 option is given, each
3987 .I name
3988 refers to a shell variable, and that variable is removed.
3989 If
3990 .B \-f
3991 is specified, each
3992 .I name
3993 refers to a shell function, and the function definition
3994 is removed.
3995 If the
3996 .B \-n
3997 option is supplied, and \fIname\fP is a variable with the \fInameref\fP
3998 attribute, \fIname\fP will be unset rather than the variable it
3999 references.
4000 \fB\-n\fP has no effect if the \fB\-f\fP option is supplied.
4001 Read-only variables and functions may not be unset.
4002 When variables or functions are removed, they are also removed
4003 from the environment passed to subsequent commands.
4004 If no options are supplied, each \fIname\fP refers to a variable; if
4005 there is no variable by that name, a function with that name, if any, is
4006 unset.
4007 Some shell variables may not be unset.
4008 If any of
4009 .SM
4010 .BR BASH_ALIASES ,
4011 .SM
4012 .BR BASH_ARGV0 ,
4013 .SM
4014 .BR BASH_CMDS ,
4015 .SM
4016 .BR BASH_COMMAND ,
4017 .SM
4018 .BR BASH_SUBSHELL ,
4019 .SM
4020 .BR BASHPID ,
4021 .SM
4022 .BR COMP_WORDBREAKS ,
4023 .SM
4024 .BR DIRSTACK ,
4025 .SM
4026 .BR EPOCHREALTIME ,
4027 .SM
4028 .BR EPOCHSECONDS ,
4029 .SM
4030 .BR FUNCNAME ,
4031 .SM
4032 .BR GROUPS ,
4033 .SM
4034 .BR HISTCMD ,
4035 .SM
4036 .BR LINENO ,
4037 .SM
4038 .BR RANDOM ,
4039 .SM
4040 .BR SECONDS ,
4041 or
4042 .SM
4043 .B SRANDOM
4044 are unset, they lose their special properties, even if they are
4045 subsequently reset.
4046 The exit status is true unless a
4047 .I name
4048 is readonly or may not be unset.
4049 .TP
4050 \fBwait\fP [\fB\-fn\fP] [\fP\-p\fP \fIvarname\fP] [\fIid\fP .\|.\|.]
4051 Wait for each specified child process \fIid\fP and return the
4052 termination status of the last \fIid\fP.
4053 Each \fIid\fP may be a process ID \fIpid\fP
4054 or a job specification \fIjobspec\fP;
4055 if a jobspec is supplied, \fBwait\fP waits for all processes in the job.
4056 .IP
4057 If no options or \fIid\fPs are supplied,
4058 \fBwait\fP waits for all running background jobs and
4059 the last-executed process substitution,
4060 if its process id is the same as \fB$!\fP,
4061 and the return status is zero.
4062 .IP
4063 If the \fB\-n\fP option is supplied, \fBwait\fP waits for any one of
4064 the given \fIid\fPs or,
4065 if no \fIid\fPs are supplied, any job or process substitution,
4066 to complete and returns its exit status.
4067 If none of the supplied \fIid\fPs is a child of the shell,
4068 or if no \fIid\fPs are supplied and the shell has no unwaited-for children,
4069 the exit status is 127.
4070 .IP
4071 If the \fB\-p\fP option is supplied, \fBwait\fP assigns
4072 the process or job identifier of the job
4073 for which the exit status is returned to the
4074 variable \fIvarname\fP named by the option argument.
4075 The variable,
4076 which cannot be readonly,
4077 will be unset initially, before any assignment.
4078 This is useful only when used with the \fB\-n\fP option.
4079 .IP
4080 Supplying the \fB\-f\fP option, when job control is enabled,
4081 forces \fBwait\fP to wait for each \fIid\fP to terminate before
4082 returning its status, instead of returning when it changes status.
4083 .IP
4084 If none of the \fIid\fPs specify one of the shell's active child
4085 processes, the return status is 127.
4086 If \fBwait\fP is interrupted by a signal,
4087 any \fIvarname\fP will remain unset,
4088 and the return status will be greater
4089 than 128, as described under
4090 .B SIGNALS
4091 .ie \n(zZ=1 in \fIbash\fP(1).
4092 .el above.
4093 Otherwise, the return status is the exit status of the last \fIid\fP.
4094 .SH "SHELL COMPATIBILITY MODE"
4095 Bash-4.0 introduced the concept of a \fIshell compatibility level\fP,
4096 specified as a set of options to the shopt builtin (\c
4097 .BR compat31 ,
4098 .BR compat32 ,
4099 .BR compat40 ,
4100 .BR compat41 ,
4101 and so on).
4102 There is only one current
4103 compatibility level \(em each option is mutually exclusive.
4104 The compatibility level is intended to allow users to select behavior
4105 from previous versions that is incompatible with newer versions
4106 while they migrate scripts to use current features and behavior.
4107 It's intended to be a temporary solution.
4108 .PP
4109 This section does not mention behavior that is standard for a particular
4110 version (e.g., setting \fBcompat32\fP means that quoting the right hand
4111 side of the regexp
4112 matching operator quotes special regexp characters in the word, which is
4113 default behavior in bash-3.2 and subsequent versions).
4114 .PP
4115 If a user enables, say, \fBcompat32\fP, it may affect the behavior of other
4116 compatibility levels up to and including the current compatibility level.
4117 The idea is that each compatibility level controls behavior that changed
4118 in that version of \fBbash\fP,
4119 but that behavior may have been present in earlier versions.
4120 For instance, the change to use locale-based comparisons with the \fB[[\fP
4121 command came in bash-4.1, and earlier versions used ASCII-based comparisons,
4122 so enabling \fBcompat32\fP will enable ASCII-based comparisons as well.
4123 That granularity may not be sufficient for
4124 all uses, and as a result users should employ compatibility levels carefully.
4125 Read the documentation for a particular feature to find out the
4126 current behavior.
4127 .PP
4128 Bash-4.3 introduced a new shell variable:
4129 .SM
4130 .BR BASH_COMPAT .
4131 The value assigned
4132 to this variable (a decimal version number like 4.2, or an integer
4133 corresponding to the \fBcompat\fP\fINN\fP option, like 42) determines the
4134 compatibility level.
4135 .PP
4136 Starting with bash-4.4, \fBbash\fP began deprecating older compatibility
4137 levels.
4138 Eventually, the options will be removed in favor of
4139 .SM
4140 .BR BASH_COMPAT .
4141 .PP
4142 Bash-5.0 was the final version for which there was an individual shopt
4143 option for the previous version.
4144 .SM
4145 .B BASH_COMPAT
4146 is the only mechanism to control the compatibility level
4147 in versions newer than bash-5.0.
4148 .PP
4149 The following table describes the behavior changes controlled by each
4150 compatibility level setting.
4151 The \fBcompat\fP\fINN\fP tag is used as shorthand for setting the
4152 compatibility level
4153 to \fINN\fP using one of the following mechanisms.
4154 For versions prior to bash-5.0, the compatibility level may be set using
4155 the corresponding \fBcompat\fP\fINN\fP shopt option.
4156 For bash-4.3 and later versions, the
4157 .SM
4158 .B BASH_COMPAT
4159 variable is preferred,
4160 and it is required for bash-5.1 and later versions.
4161 .TP
4162 \fBcompat31\fP
4163 .PD 0
4164 .RS
4165 .IP \(bu
4166 Quoting the rhs of the \fB[[\fP command's regexp matching operator (=\*~)
4167 has no special effect.
4168 .RE
4169 .PD
4170 .TP
4171 \fBcompat32\fP
4172 .PD 0
4173 .RS
4174 .IP \(bu
4175 The \fB<\fP and \fB>\fP operators to the \fB[[\fP command do not
4176 consider the current locale when comparing strings; they use ASCII
4177 ordering.
4178 .RE
4179 .PD
4180 .TP
4181 \fBcompat40\fP
4182 .PD 0
4183 .RS
4184 .IP \(bu
4185 The \fB<\fP and \fB>\fP operators to the \fB[[\fP command do not
4186 consider the current locale when comparing strings; they use ASCII
4187 ordering.
4188 \fBBash\fP versions prior to bash-4.1 use ASCII collation and
4189 .IR strcmp (3);
4190 bash-4.1 and later use the current locale's collation sequence and
4191 .IR strcoll (3).
4192 .RE
4193 .PD
4194 .TP
4195 \fBcompat41\fP
4196 .PD 0
4197 .RS
4198 .IP \(bu
4199 In posix mode, \fBtime\fP may be followed by options and still be
4200 recognized as a reserved word (this is
4201 .SM POSIX
4202 interpretation 267).
4203 .IP \(bu
4204 In \fIposix\fP mode, the parser requires that an even number of single
4205 quotes occur in the \fIword\fP portion of a double-quoted
4206 parameter expansion and treats them specially, so that characters within
4207 the single quotes are considered quoted
4208 (this is
4209 .SM POSIX
4210 interpretation 221).
4211 .RE
4212 .PD
4213 .TP
4214 \fBcompat42\fP
4215 .PD 0
4216 .RS
4217 .IP \(bu
4218 The replacement string in double-quoted pattern substitution does not
4219 undergo quote removal, as it does in versions after bash-4.2.
4220 .IP \(bu
4221 In posix mode, single quotes are considered special when expanding
4222 the \fIword\fP portion of a double-quoted parameter expansion
4223 and can be used to quote a closing brace or other special character
4224 (this is part of
4225 .SM POSIX
4226 interpretation 221);
4227 in later versions, single quotes
4228 are not special within double-quoted word expansions.
4229 .RE
4230 .PD
4231 .TP
4232 \fBcompat43\fP
4233 .PD 0
4234 .RS
4235 .IP \(bu
4236 Word expansion errors are considered non-fatal errors that cause the
4237 current command to fail, even in posix mode
4238 (the default behavior is to make them fatal errors that cause the shell
4239 to exit).
4240 .IP \(bu
4241 When executing a shell function, the loop state (while/until/etc.)
4242 is not reset, so \fBbreak\fP or \fBcontinue\fP in that function will break
4243 or continue loops in the calling context.
4244 Bash-4.4 and later reset the loop state to prevent this.
4245 .RE
4246 .PD
4247 .TP
4248 \fBcompat44\fP
4249 .PD 0
4250 .RS
4251 .IP \(bu
4252 The shell sets up the values used by
4253 .SM
4254 .B BASH_ARGV
4255 and
4256 .SM
4257 .B BASH_ARGC
4258 so they can expand to the shell's positional parameters even if extended
4259 debugging mode is not enabled.
4260 .IP \(bu
4261 A subshell inherits loops from its parent context, so \fBbreak\fP
4262 or \fBcontinue\fP will cause the subshell to exit.
4263 Bash-5.0 and later reset the loop state to prevent the exit
4264 .IP \(bu
4265 Variable assignments preceding builtins like \fBexport\fP and \fBreadonly\fP
4266 that set attributes continue to affect variables with the same
4267 name in the calling environment even if the shell is not in posix
4268 mode.
4269 .RE
4270 .PD
4271 .TP
4272 \fBcompat50\fP
4273 .PD 0
4274 .RS
4275 .IP \(bu
4276 Bash-5.1 changed the way
4277 .SM
4278 .B $RANDOM
4279 is generated to introduce slightly more randomness.
4280 If the shell compatibility level is set to 50 or
4281 lower, it reverts to the method from bash-5.0 and previous versions,
4282 so seeding the random number generator by assigning a value to
4283 .SM
4284 .B RANDOM
4285 will produce the same sequence as in bash-5.0.
4286 .IP \(bu
4287 If the command hash table is empty, bash versions prior to bash-5.1
4288 printed an informational message to that effect, even when producing
4289 output that can be reused as input.
4290 Bash-5.1 suppresses that message
4291 when the \fB\-l\fP option is supplied.
4292 .RE
4293 .PD
4294 .TP
4295 \fBcompat51\fP
4296 .PD 0
4297 .RS
4298 .IP \(bu
4299 The \fBunset\fP builtin treats attempts to unset array subscripts \fB@\fP
4300 and \fB*\fP differently depending on whether the array is indexed or
4301 associative, and differently than in previous versions.
4302 .IP \(bu
4303 Arithmetic commands (
4304 .BR (( .\|.\|.\& ))
4305 ) and the expressions in an arithmetic for
4306 statement can be expanded more than once.
4307 .IP \(bu
4308 Expressions used as arguments to arithmetic operators in the \fB[[\fP
4309 conditional command can be expanded more than once.
4310 .IP \(bu
4311 The expressions in substring parameter brace expansion can be
4312 expanded more than once.
4313 .IP \(bu
4314 The expressions in the
4315 .BR $(( .\|.\|.\& ))
4316 word expansion can be expanded more than once.
4317 .IP \(bu
4318 Arithmetic expressions used as indexed array subscripts can be
4319 expanded more than once.
4320 .IP \(bu
4321 \fBtest \-v\fP, when given an argument of \fBA[@]\fP, where \fBA\fP is
4322 an existing associative array, will return true if the array has any set
4323 elements.
4324 Bash-5.2 will look for and report on a key named \fB@\fP.
4325 .IP \(bu
4326 The ${\fIparameter\fP\fB[:]=\fP\fIvalue\fP} word expansion will return
4327 \fIvalue\fP, before any variable-specific transformations have been
4328 performed (e.g., converting to lowercase).
4329 Bash-5.2 will return the final value assigned to the variable.
4330 .IP \(bu
4331 Parsing command substitutions will behave as if extended globbing
4332 (see the description of the
4333 .B shopt
4334 builtin above)
4335 is enabled, so that parsing a command substitution containing an extglob
4336 pattern (say, as part of a shell function) will not fail.
4337 This assumes the intent is to enable extglob before the command is executed
4338 and word expansions are performed.
4339 It will fail at word expansion time if extglob hasn't been
4340 enabled by the time the command is executed.
4341 .RE
4342 .PD
4343 .TP
4344 \fBcompat52\fP
4345 .PD 0
4346 .RS
4347 .IP \(bu
4348 The \fBtest\fP builtin uses its historical algorithm to parse parenthesized
4349 subexpressions when given five or more arguments.
4350 .IP \(bu
4351 If the \fB\-p\fP or \fB\-P\fP option is supplied to the \fBbind\fP builtin,
4352 \fBbind\fP treats any arguments remaining after option processing
4353 as bindable command names, and
4354 displays any key sequences bound to those commands, instead of treating
4355 the arguments as key sequences to bind.
4356 .RE
4357 .PD
4358 .\" bash_builtins
4359 .zY
4360 .lf 23 ./builtins.1
4361 .SH SEE ALSO
4362 bash(1), sh(1)