1BASH_BUILTINS(1) General Commands Manual BASH_BUILTINS(1)
2
6 :, ., [, alias, bg, bind, break, builtin, caller, cd, command, compgen,
7 complete, compopt, continue, declare, dirs, disown, echo, enable, eval,
8 exec, exit, export, false, fc, fg, getopts, hash, help, history, jobs,
9 kill, let, local, logout, mapfile, popd, printf, pushd, pwd, read,
10 readarray, readonly, return, set, shift, shopt, source, suspend, test,
11 times, trap, true, type, typeset, ulimit, umask, unalias, unset, wait -
12 bash built-in commands, see bash(1)
13
15 Unless otherwise noted, each builtin command documented in this section
16 as accepting options preceded by - accepts -- to signify the end of the
17 options. The :, true, false, and test/[ builtins do not accept options
18 and do not treat -- specially. The exit, logout, return, break, con‐
19 tinue, let, and shift builtins accept and process arguments beginning
20 with - without requiring --. Other builtins that accept arguments but
21 are not specified as accepting options interpret arguments beginning
22 with - as invalid options and require -- to prevent this interpreta‐
23 tion.
24 : [arguments]
25 No effect; the command does nothing beyond expanding arguments
26 and performing any specified redirections. The return status is
27 zero.
28 . filename [arguments]
30 source filename [arguments]
31 Read and execute commands from filename in the current shell en‐
32 vironment and return the exit status of the last command exe‐
33 cuted from filename. If filename does not contain a slash,
34 filenames in PATH are used to find the directory containing
35 filename, but filename does not need to be executable. The file
36 searched for in PATH need not be executable. When bash is not
37 in posix mode, it searches the current directory if no file is
38 found in PATH. If the sourcepath option to the shopt builtin
39 command is turned off, the PATH is not searched. If any argu‐
40 ments are supplied, they become the positional parameters when
41 filename is executed. Otherwise the positional parameters are
42 unchanged. If the -T option is enabled, . inherits any trap on
43 DEBUG; if it is not, any DEBUG trap string is saved and restored
44 around the call to ., and . unsets the DEBUG trap while it exe‐
45 cutes. If -T is not set, and the sourced file changes the DEBUG
46 trap, the new value is retained when . completes. The return
47 status is the status of the last command exited within the
48 script (0 if no commands are executed), and false if filename is
49 not found or cannot be read.
50 alias [-p] [name[=value] ...]
52 Alias with no arguments or with the -p option prints the list of
53 aliases in the form alias name=value on standard output. When
54 arguments are supplied, an alias is defined for each name whose
55 value is given. A trailing space in value causes the next word
56 to be checked for alias substitution when the alias is expanded.
57 For each name in the argument list for which no value is sup‐
58 plied, the name and value of the alias is printed. Alias re‐
59 turns true unless a name is given for which no alias has been
60 defined.
61 bg [jobspec ...]
63 Resume each suspended job jobspec in the background, as if it
64 had been started with &. If jobspec is not present, the shell's
65 notion of the current job is used. bg jobspec returns 0 unless
66 run when job control is disabled or, when run with job control
67 enabled, any specified jobspec was not found or was started
68 without job control.
69 bind [-m keymap] [-lpsvPSVX]
71 bind [-m keymap] [-q function] [-u function] [-r keyseq]
72 bind [-m keymap] -f filename
73 bind [-m keymap] -x keyseq:shell-command
74 bind [-m keymap] keyseq:function-name
75 bind [-m keymap] keyseq:readline-command
76 bind readline-command-line
77 Display current readline key and function bindings, bind a key
78 sequence to a readline function or macro, or set a readline
79 variable. Each non-option argument is a command as it would ap‐
80 pear in a readline initialization file such as .inputrc, but
81 each binding or command must be passed as a separate argument;
82 e.g., '"\C-x\C-r": re-read-init-file'. Options, if supplied,
83 have the following meanings:
84 -m keymap
85 Use keymap as the keymap to be affected by the subsequent
86 bindings. Acceptable keymap names are emacs, emacs-stan‐
87 dard, emacs-meta, emacs-ctlx, vi, vi-move, vi-command,
88 and vi-insert. vi is equivalent to vi-command (vi-move
89 is also a synonym); emacs is equivalent to emacs-stan‐
90 dard.
91 -l List the names of all readline functions.
92 -p Display readline function names and bindings in such a
93 way that they can be re-read.
94 -P List current readline function names and bindings.
95 -s Display readline key sequences bound to macros and the
96 strings they output in such a way that they can be re-
97 read.
98 -S Display readline key sequences bound to macros and the
99 strings they output.
100 -v Display readline variable names and values in such a way
101 that they can be re-read.
102 -V List current readline variable names and values.
103 -f filename
104 Read key bindings from filename.
105 -q function
106 Query about which keys invoke the named function.
107 -u function
108 Unbind all keys bound to the named function.
109 -r keyseq
110 Remove any current binding for keyseq.
111 -x keyseq:shell-command
112 Cause shell-command to be executed whenever keyseq is en‐
113 tered. When shell-command is executed, the shell sets
114 the READLINE_LINE variable to the contents of the read‐
115 line line buffer and the READLINE_POINT and READLINE_MARK
116 variables to the current location of the insertion point
117 and the saved insertion point (the mark), respectively.
118 The shell assigns any numeric argument the user supplied
119 to the READLINE_ARGUMENT variable. If there was no argu‐
120 ment, that variable is not set. If the executed command
121 changes the value of any of READLINE_LINE, READ‐
122 LINE_POINT, or READLINE_MARK, those new values will be
123 reflected in the editing state.
124 -X List all key sequences bound to shell commands and the
125 associated commands in a format that can be reused as in‐
126 put.
127 The return value is 0 unless an unrecognized option is given or
129 an error occurred.
130 break [n]
132 Exit from within a for, while, until, or select loop. If n is
133 specified, break n levels. n must be ≥ 1. If n is greater than
134 the number of enclosing loops, all enclosing loops are exited.
135 The return value is 0 unless n is not greater than or equal to
136 1.
137 builtin shell-builtin [arguments]
139 Execute the specified shell builtin, passing it arguments, and
140 return its exit status. This is useful when defining a function
141 whose name is the same as a shell builtin, retaining the func‐
142 tionality of the builtin within the function. The cd builtin is
143 commonly redefined this way. The return status is false if
144 shell-builtin is not a shell builtin command.
145 caller [expr]
147 Returns the context of any active subroutine call (a shell func‐
148 tion or a script executed with the . or source builtins). With‐
149 out expr, caller displays the line number and source filename of
150 the current subroutine call. If a non-negative integer is sup‐
151 plied as expr, caller displays the line number, subroutine name,
152 and source file corresponding to that position in the current
153 execution call stack. This extra information may be used, for
154 example, to print a stack trace. The current frame is frame 0.
155 The return value is 0 unless the shell is not executing a sub‐
156 routine call or expr does not correspond to a valid position in
157 the call stack.
158 cd [-L|[-P [-e]] [-@]] [dir]
160 Change the current directory to dir. if dir is not supplied,
161 the value of the HOME shell variable is the default. The vari‐
162 able CDPATH defines the search path for the directory containing
163 dir: each directory name in CDPATH is searched for dir. Alter‐
164 native directory names in CDPATH are separated by a colon (:).
165 A null directory name in CDPATH is the same as the current di‐
166 rectory, i.e., ``.''. If dir begins with a slash (/), then CD‐
167 PATH is not used. The -P option causes cd to use the physical
168 directory structure by resolving symbolic links while traversing
169 dir and before processing instances of .. in dir (see also the
170 -P option to the set builtin command); the -L option forces sym‐
171 bolic links to be followed by resolving the link after process‐
172 ing instances of .. in dir. If .. appears in dir, it is pro‐
173 cessed by removing the immediately previous pathname component
174 from dir, back to a slash or the beginning of dir. If the -e
175 option is supplied with -P, and the current working directory
176 cannot be successfully determined after a successful directory
177 change, cd will return an unsuccessful status. On systems that
178 support it, the -@ option presents the extended attributes asso‐
179 ciated with a file as a directory. An argument of - is con‐
180 verted to $OLDPWD before the directory change is attempted. If
181 a non-empty directory name from CDPATH is used, or if - is the
182 first argument, and the directory change is successful, the ab‐
183 solute pathname of the new working directory is written to the
184 standard output. If the directory change is successful, cd sets
185 the value of the PWD environment variable to the new directory
186 name, and sets the OLDPWD environment variable to the value of
187 the current working directory before the change. The return
188 value is true if the directory was successfully changed; false
189 otherwise.
190 command [-pVv] command [arg ...]
192 Run command with args suppressing the normal shell function
193 lookup. Only builtin commands or commands found in the PATH are
194 executed. If the -p option is given, the search for command is
195 performed using a default value for PATH that is guaranteed to
196 find all of the standard utilities. If either the -V or -v op‐
197 tion is supplied, a description of command is printed. The -v
198 option causes a single word indicating the command or filename
199 used to invoke command to be displayed; the -V option produces a
200 more verbose description. If the -V or -v option is supplied,
201 the exit status is 0 if command was found, and 1 if not. If
202 neither option is supplied and an error occurred or command can‐
203 not be found, the exit status is 127. Otherwise, the exit sta‐
204 tus of the command builtin is the exit status of command.
205 compgen [option] [word]
207 Generate possible completion matches for word according to the
208 options, which may be any option accepted by the complete
209 builtin with the exception of -p and -r, and write the matches
210 to the standard output. When using the -F or -C options, the
211 various shell variables set by the programmable completion fa‐
212 cilities, while available, will not have useful values.
213 The matches will be generated in the same way as if the program‐
215 mable completion code had generated them directly from a comple‐
216 tion specification with the same flags. If word is specified,
217 only those completions matching word will be displayed.
218 The return value is true unless an invalid option is supplied,
220 or no matches were generated.
221 complete [-abcdefgjksuv] [-o comp-option] [-DEI] [-A action] [-G glob‐
223 pat] [-W wordlist]
224 [-F function] [-C command] [-X filterpat] [-P prefix] [-S suf‐
225 fix] name [name ...]
226 complete -pr [-DEI] [name ...]
227 Specify how arguments to each name should be completed. If the
228 -p option is supplied, or if no options are supplied, existing
229 completion specifications are printed in a way that allows them
230 to be reused as input. The -r option removes a completion spec‐
231 ification for each name, or, if no names are supplied, all com‐
232 pletion specifications. The -D option indicates that other sup‐
233 plied options and actions should apply to the ``default'' com‐
234 mand completion; that is, completion attempted on a command for
235 which no completion has previously been defined. The -E option
236 indicates that other supplied options and actions should apply
237 to ``empty'' command completion; that is, completion attempted
238 on a blank line. The -I option indicates that other supplied
239 options and actions should apply to completion on the initial
240 non-assignment word on the line, or after a command delimiter
241 such as ; or |, which is usually command name completion. If
242 multiple options are supplied, the -D option takes precedence
243 over -E, and both take precedence over -I. If any of -D, -E, or
244 -I are supplied, any other name arguments are ignored; these
245 completions only apply to the case specified by the option.
246 The process of applying these completion specifications when
248 word completion is attempted is described in bash(1).
249 Other options, if specified, have the following meanings. The
251 arguments to the -G, -W, and -X options (and, if necessary, the
252 -P and -S options) should be quoted to protect them from expan‐
253 sion before the complete builtin is invoked.
254 -o comp-option
255 The comp-option controls several aspects of the comp‐
256 spec's behavior beyond the simple generation of comple‐
257 tions. comp-option may be one of:
258 bashdefault
259 Perform the rest of the default bash completions
260 if the compspec generates no matches.
261 default Use readline's default filename completion if
262 the compspec generates no matches.
263 dirnames
264 Perform directory name completion if the comp‐
265 spec generates no matches.
266 filenames
267 Tell readline that the compspec generates file‐
268 names, so it can perform any filename-specific
269 processing (like adding a slash to directory
270 names, quoting special characters, or suppress‐
271 ing trailing spaces). Intended to be used with
272 shell functions.
273 noquote Tell readline not to quote the completed words
274 if they are filenames (quoting filenames is the
275 default).
276 nosort Tell readline not to sort the list of possible
277 completions alphabetically.
278 nospace Tell readline not to append a space (the de‐
279 fault) to words completed at the end of the
280 line.
281 plusdirs
282 After any matches defined by the compspec are
283 generated, directory name completion is at‐
284 tempted and any matches are added to the results
285 of the other actions.
286 -A action
287 The action may be one of the following to generate a
288 list of possible completions:
289 alias Alias names. May also be specified as -a.
290 arrayvar
291 Array variable names.
292 binding Readline key binding names.
293 builtin Names of shell builtin commands. May also be
294 specified as -b.
295 command Command names. May also be specified as -c.
296 directory
297 Directory names. May also be specified as -d.
298 disabled
299 Names of disabled shell builtins.
300 enabled Names of enabled shell builtins.
301 export Names of exported shell variables. May also be
302 specified as -e.
303 file File names. May also be specified as -f.
304 function
305 Names of shell functions.
306 group Group names. May also be specified as -g.
307 helptopic
308 Help topics as accepted by the help builtin.
309 hostname
310 Hostnames, as taken from the file specified by
311 the HOSTFILE shell variable.
312 job Job names, if job control is active. May also
313 be specified as -j.
314 keyword Shell reserved words. May also be specified as
315 -k.
316 running Names of running jobs, if job control is active.
317 service Service names. May also be specified as -s.
318 setopt Valid arguments for the -o option to the set
319 builtin.
320 shopt Shell option names as accepted by the shopt
321 builtin.
322 signal Signal names.
323 stopped Names of stopped jobs, if job control is active.
324 user User names. May also be specified as -u.
325 variable
326 Names of all shell variables. May also be spec‐
327 ified as -v.
328 -C command
329 command is executed in a subshell environment, and its
330 output is used as the possible completions. Arguments
331 are passed as with the -F option.
332 -F function
333 The shell function function is executed in the current
334 shell environment. When the function is executed, the
335 first argument ($1) is the name of the command whose ar‐
336 guments are being completed, the second argument ($2) is
337 the word being completed, and the third argument ($3) is
338 the word preceding the word being completed on the cur‐
339 rent command line. When it finishes, the possible com‐
340 pletions are retrieved from the value of the COMPREPLY
341 array variable.
342 -G globpat
343 The pathname expansion pattern globpat is expanded to
344 generate the possible completions.
345 -P prefix
346 prefix is added at the beginning of each possible com‐
347 pletion after all other options have been applied.
348 -S suffix
349 suffix is appended to each possible completion after all
350 other options have been applied.
351 -W wordlist
352 The wordlist is split using the characters in the IFS
353 special variable as delimiters, and each resultant word
354 is expanded. Shell quoting is honored within wordlist,
355 in order to provide a mechanism for the words to contain
356 shell metacharacters or characters in the value of IFS.
357 The possible completions are the members of the resul‐
358 tant list which match the word being completed.
359 -X filterpat
360 filterpat is a pattern as used for pathname expansion.
361 It is applied to the list of possible completions gener‐
362 ated by the preceding options and arguments, and each
363 completion matching filterpat is removed from the list.
364 A leading ! in filterpat negates the pattern; in this
365 case, any completion not matching filterpat is removed.
366 The return value is true unless an invalid option is supplied,
368 an option other than -p or -r is supplied without a name argu‐
369 ment, an attempt is made to remove a completion specification
370 for a name for which no specification exists, or an error occurs
371 adding a completion specification.
372 compopt [-o option] [-DEI] [+o option] [name]
374 Modify completion options for each name according to the op‐
375 tions, or for the currently-executing completion if no names are
376 supplied. If no options are given, display the completion op‐
377 tions for each name or the current completion. The possible
378 values of option are those valid for the complete builtin de‐
379 scribed above. The -D option indicates that other supplied op‐
380 tions should apply to the ``default'' command completion; that
381 is, completion attempted on a command for which no completion
382 has previously been defined. The -E option indicates that other
383 supplied options should apply to ``empty'' command completion;
384 that is, completion attempted on a blank line. The -I option
385 indicates that other supplied options should apply to completion
386 on the initial non-assignment word on the line, or after a com‐
387 mand delimiter such as ; or |, which is usually command name
388 completion.
389 The return value is true unless an invalid option is supplied,
391 an attempt is made to modify the options for a name for which no
392 completion specification exists, or an output error occurs.
393 continue [n]
395 Resume the next iteration of the enclosing for, while, until, or
396 select loop. If n is specified, resume at the nth enclosing
397 loop. n must be ≥ 1. If n is greater than the number of en‐
398 closing loops, the last enclosing loop (the ``top-level'' loop)
399 is resumed. The return value is 0 unless n is not greater than
400 or equal to 1.
401 declare [-aAfFgiIlnrtux] [-p] [name[=value] ...]
403 typeset [-aAfFgiIlnrtux] [-p] [name[=value] ...]
404 Declare variables and/or give them attributes. If no names are
405 given then display the values of variables. The -p option will
406 display the attributes and values of each name. When -p is used
407 with name arguments, additional options, other than -f and -F,
408 are ignored. When -p is supplied without name arguments, it
409 will display the attributes and values of all variables having
410 the attributes specified by the additional options. If no other
411 options are supplied with -p, declare will display the at‐
412 tributes and values of all shell variables. The -f option will
413 restrict the display to shell functions. The -F option inhibits
414 the display of function definitions; only the function name and
415 attributes are printed. If the extdebug shell option is enabled
416 using shopt, the source file name and line number where each
417 name is defined are displayed as well. The -F option implies
418 -f. The -g option forces variables to be created or modified at
419 the global scope, even when declare is executed in a shell func‐
420 tion. It is ignored in all other cases. The -I option causes
421 local variables to inherit the attributes (except the nameref
422 attribute) and value of any existing variable with the same name
423 at a surrounding scope. If there is no existing variable, the
424 local variable is initially unset. The following options can be
425 used to restrict output to variables with the specified attri‐
426 bute or to give variables attributes:
427 -a Each name is an indexed array variable (see Arrays in
428 bash(1)).
429 -A Each name is an associative array variable (see Arrays in
430 bash(1)).
431 -f Use function names only.
432 -i The variable is treated as an integer; arithmetic evalua‐
433 tion (see ARITHMETIC EVALUATION in bash(1)) is performed
434 when the variable is assigned a value.
435 -l When the variable is assigned a value, all upper-case
436 characters are converted to lower-case. The upper-case
437 attribute is disabled.
438 -n Give each name the nameref attribute, making it a name
439 reference to another variable. That other variable is
440 defined by the value of name. All references, assign‐
441 ments, and attribute modifications to name, except those
442 using or changing the -n attribute itself, are performed
443 on the variable referenced by name's value. The nameref
444 attribute cannot be applied to array variables.
445 -r Make names readonly. These names cannot then be assigned
446 values by subsequent assignment statements or unset.
447 -t Give each name the trace attribute. Traced functions in‐
448 herit the DEBUG and RETURN traps from the calling shell.
449 The trace attribute has no special meaning for variables.
450 -u When the variable is assigned a value, all lower-case
451 characters are converted to upper-case. The lower-case
452 attribute is disabled.
453 -x Mark names for export to subsequent commands via the en‐
454 vironment.
455 Using `+' instead of `-' turns off the attribute instead, with
457 the exceptions that +a and +A may not be used to destroy array
458 variables and +r will not remove the readonly attribute. When
459 used in a function, declare and typeset make each name local, as
460 with the local command, unless the -g option is supplied. If a
461 variable name is followed by =value, the value of the variable
462 is set to value. When using -a or -A and the compound assign‐
463 ment syntax to create array variables, additional attributes do
464 not take effect until subsequent assignments. The return value
465 is 0 unless an invalid option is encountered, an attempt is made
466 to define a function using ``-f foo=bar'', an attempt is made to
467 assign a value to a readonly variable, an attempt is made to as‐
468 sign a value to an array variable without using the compound as‐
469 signment syntax (see Arrays in bash(1)), one of the names is not
470 a valid shell variable name, an attempt is made to turn off
471 readonly status for a readonly variable, an attempt is made to
472 turn off array status for an array variable, or an attempt is
473 made to display a non-existent function with -f.
474 dirs [-clpv] [+n] [-n]
476 Without options, displays the list of currently remembered di‐
477 rectories. The default display is on a single line with direc‐
478 tory names separated by spaces. Directories are added to the
479 list with the pushd command; the popd command removes entries
480 from the list. The current directory is always the first direc‐
481 tory in the stack.
482 -c Clears the directory stack by deleting all of the en‐
483 tries.
484 -l Produces a listing using full pathnames; the default
485 listing format uses a tilde to denote the home directory.
486 -p Print the directory stack with one entry per line.
487 -v Print the directory stack with one entry per line, pre‐
488 fixing each entry with its index in the stack.
489 +n Displays the nth entry counting from the left of the list
490 shown by dirs when invoked without options, starting with
491 zero.
492 -n Displays the nth entry counting from the right of the
493 list shown by dirs when invoked without options, starting
494 with zero.
495 The return value is 0 unless an invalid option is supplied or n
497 indexes beyond the end of the directory stack.
498 disown [-ar] [-h] [jobspec ... | pid ... ]
500 Without options, remove each jobspec from the table of active
501 jobs. If jobspec is not present, and neither the -a nor the -r
502 option is supplied, the current job is used. If the -h option
503 is given, each jobspec is not removed from the table, but is
504 marked so that SIGHUP is not sent to the job if the shell re‐
505 ceives a SIGHUP. If no jobspec is supplied, the -a option means
506 to remove or mark all jobs; the -r option without a jobspec ar‐
507 gument restricts operation to running jobs. The return value is
508 0 unless a jobspec does not specify a valid job.
509 echo [-neE] [arg ...]
511 Output the args, separated by spaces, followed by a newline.
512 The return status is 0 unless a write error occurs. If -n is
513 specified, the trailing newline is suppressed. If the -e option
514 is given, interpretation of the following backslash-escaped
515 characters is enabled. The -E option disables the interpreta‐
516 tion of these escape characters, even on systems where they are
517 interpreted by default. The xpg_echo shell option may be used
518 to dynamically determine whether or not echo expands these es‐
519 cape characters by default. echo does not interpret -- to mean
520 the end of options. echo interprets the following escape se‐
521 quences:
522 \a alert (bell)
523 \b backspace
524 \c suppress further output
525 \e
526 \E an escape character
527 \f form feed
528 \n new line
529 \r carriage return
530 \t horizontal tab
531 \v vertical tab
532 \\ backslash
533 \0nnn the eight-bit character whose value is the octal value
534 nnn (zero to three octal digits)
535 \xHH the eight-bit character whose value is the hexadecimal
536 value HH (one or two hex digits)
537 \uHHHH the Unicode (ISO/IEC 10646) character whose value is the
538 hexadecimal value HHHH (one to four hex digits)
539 \UHHHHHHHH
540 the Unicode (ISO/IEC 10646) character whose value is the
541 hexadecimal value HHHHHHHH (one to eight hex digits)
542 enable [-a] [-dnps] [-f filename] [name ...]
544 Enable and disable builtin shell commands. Disabling a builtin
545 allows a disk command which has the same name as a shell builtin
546 to be executed without specifying a full pathname, even though
547 the shell normally searches for builtins before disk commands.
548 If -n is used, each name is disabled; otherwise, names are en‐
549 abled. For example, to use the test binary found via the PATH
550 instead of the shell builtin version, run ``enable -n test''.
551 The -f option means to load the new builtin command name from
552 shared object filename, on systems that support dynamic loading.
553 Bash will use the value of the BASH_LOADABLES_PATH variable as a
554 colon-separated list of directories in which to search for file‐
555 name. The default is system-dependent. The -d option will
556 delete a builtin previously loaded with -f. If no name argu‐
557 ments are given, or if the -p option is supplied, a list of
558 shell builtins is printed. With no other option arguments, the
559 list consists of all enabled shell builtins. If -n is supplied,
560 only disabled builtins are printed. If -a is supplied, the list
561 printed includes all builtins, with an indication of whether or
562 not each is enabled. If -s is supplied, the output is re‐
563 stricted to the POSIX special builtins. If no options are sup‐
564 plied and a name is not a shell builtin, enable will attempt to
565 load name from a shared object named name, as if the command
566 were ``enable -f name name . The return value is 0 unless a
567 name is not a shell builtin or there is an error loading a new
568 builtin from a shared object.
569 eval [arg ...]
571 The args are read and concatenated together into a single com‐
572 mand. This command is then read and executed by the shell, and
573 its exit status is returned as the value of eval. If there are
574 no args, or only null arguments, eval returns 0.
575 exec [-cl] [-a name] [command [arguments]]
577 If command is specified, it replaces the shell. No new process
578 is created. The arguments become the arguments to command. If
579 the -l option is supplied, the shell places a dash at the begin‐
580 ning of the zeroth argument passed to command. This is what lo‐
581 gin(1) does. The -c option causes command to be executed with
582 an empty environment. If -a is supplied, the shell passes name
583 as the zeroth argument to the executed command. If command can‐
584 not be executed for some reason, a non-interactive shell exits,
585 unless the execfail shell option is enabled. In that case, it
586 returns failure. An interactive shell returns failure if the
587 file cannot be executed. A subshell exits unconditionally if
588 exec fails. If command is not specified, any redirections take
589 effect in the current shell, and the return status is 0. If
590 there is a redirection error, the return status is 1.
591 exit [n]
593 Cause the shell to exit with a status of n. If n is omitted,
594 the exit status is that of the last command executed. A trap on
595 EXIT is executed before the shell terminates.
596 export [-fn] [name[=word]] ...
598 export -p
599 The supplied names are marked for automatic export to the envi‐
600 ronment of subsequently executed commands. If the -f option is
601 given, the names refer to functions. If no names are given, or
602 if the -p option is supplied, a list of names of all exported
603 variables is printed. The -n option causes the export property
604 to be removed from each name. If a variable name is followed by
605 =word, the value of the variable is set to word. export returns
606 an exit status of 0 unless an invalid option is encountered, one
607 of the names is not a valid shell variable name, or -f is sup‐
608 plied with a name that is not a function.
609 fc [-e ename] [-lnr] [first] [last]
611 fc -s [pat=rep] [cmd]
612 The first form selects a range of commands from first to last
613 from the history list and displays or edits and re-executes
614 them. First and last may be specified as a string (to locate
615 the last command beginning with that string) or as a number (an
616 index into the history list, where a negative number is used as
617 an offset from the current command number). When listing, a
618 first or last of 0 is equivalent to -1 and -0 is equivalent to
619 the current command (usually the fc command); otherwise 0 is
620 equivalent to -1 and -0 is invalid. If last is not specified,
621 it is set to the current command for listing (so that ``fc -l
622 -10'' prints the last 10 commands) and to first otherwise. If
623 first is not specified, it is set to the previous command for
624 editing and -16 for listing.
625 The -n option suppresses the command numbers when listing. The
627 -r option reverses the order of the commands. If the -l option
628 is given, the commands are listed on standard output. Other‐
629 wise, the editor given by ename is invoked on a file containing
630 those commands. If ename is not given, the value of the FCEDIT
631 variable is used, and the value of EDITOR if FCEDIT is not set.
632 If neither variable is set, vi is used. When editing is com‐
633 plete, the edited commands are echoed and executed.
634 In the second form, command is re-executed after each instance
636 of pat is replaced by rep. Command is interpreted the same as
637 first above. A useful alias to use with this is ``r="fc -s"'',
638 so that typing ``r cc'' runs the last command beginning with
639 ``cc'' and typing ``r'' re-executes the last command.
640 If the first form is used, the return value is 0 unless an in‐
642 valid option is encountered or first or last specify history
643 lines out of range. If the -e option is supplied, the return
644 value is the value of the last command executed or failure if an
645 error occurs with the temporary file of commands. If the second
646 form is used, the return status is that of the command re-exe‐
647 cuted, unless cmd does not specify a valid history line, in
648 which case fc returns failure.
649 fg [jobspec]
651 Resume jobspec in the foreground, and make it the current job.
652 If jobspec is not present, the shell's notion of the current job
653 is used. The return value is that of the command placed into
654 the foreground, or failure if run when job control is disabled
655 or, when run with job control enabled, if jobspec does not spec‐
656 ify a valid job or jobspec specifies a job that was started
657 without job control.
658 getopts optstring name [arg ...]
660 getopts is used by shell procedures to parse positional parame‐
661 ters. optstring contains the option characters to be recog‐
662 nized; if a character is followed by a colon, the option is ex‐
663 pected to have an argument, which should be separated from it by
664 white space. The colon and question mark characters may not be
665 used as option characters. Each time it is invoked, getopts
666 places the next option in the shell variable name, initializing
667 name if it does not exist, and the index of the next argument to
668 be processed into the variable OPTIND. OPTIND is initialized to
669 1 each time the shell or a shell script is invoked. When an op‐
670 tion requires an argument, getopts places that argument into the
671 variable OPTARG. The shell does not reset OPTIND automatically;
672 it must be manually reset between multiple calls to getopts
673 within the same shell invocation if a new set of parameters is
674 to be used.
675 When the end of options is encountered, getopts exits with a re‐
677 turn value greater than zero. OPTIND is set to the index of the
678 first non-option argument, and name is set to ?.
679 getopts normally parses the positional parameters, but if more
681 arguments are supplied as arg values, getopts parses those in‐
682 stead.
683 getopts can report errors in two ways. If the first character
685 of optstring is a colon, silent error reporting is used. In
686 normal operation, diagnostic messages are printed when invalid
687 options or missing option arguments are encountered. If the
688 variable OPTERR is set to 0, no error messages will be dis‐
689 played, even if the first character of optstring is not a colon.
690 If an invalid option is seen, getopts places ? into name and, if
692 not silent, prints an error message and unsets OPTARG. If
693 getopts is silent, the option character found is placed in OP‐
694 TARG and no diagnostic message is printed.
695 If a required argument is not found, and getopts is not silent,
697 a question mark (?) is placed in name, OPTARG is unset, and a
698 diagnostic message is printed. If getopts is silent, then a
699 colon (:) is placed in name and OPTARG is set to the option
700 character found.
701 getopts returns true if an option, specified or unspecified, is
703 found. It returns false if the end of options is encountered or
704 an error occurs.
705 hash [-lr] [-p filename] [-dt] [name]
707 Each time hash is invoked, the full pathname of the command name
708 is determined by searching the directories in $PATH and remem‐
709 bered. Any previously-remembered pathname is discarded. If the
710 -p option is supplied, no path search is performed, and filename
711 is used as the full filename of the command. The -r option
712 causes the shell to forget all remembered locations. The -d op‐
713 tion causes the shell to forget the remembered location of each
714 name. If the -t option is supplied, the full pathname to which
715 each name corresponds is printed. If multiple name arguments
716 are supplied with -t, the name is printed before the hashed full
717 pathname. The -l option causes output to be displayed in a for‐
718 mat that may be reused as input. If no arguments are given, or
719 if only -l is supplied, information about remembered commands is
720 printed. The return status is true unless a name is not found
721 or an invalid option is supplied.
722 help [-dms] [pattern]
724 Display helpful information about builtin commands. If pattern
725 is specified, help gives detailed help on all commands matching
726 pattern; otherwise help for all the builtins and shell control
727 structures is printed.
728 -d Display a short description of each pattern
729 -m Display the description of each pattern in a manpage-like
730 format
731 -s Display only a short usage synopsis for each pattern
732 The return status is 0 unless no command matches pattern.
734 history [n]
736 history -c
737 history -d offset
738 history -d start-end
739 history -anrw [filename]
740 history -p arg [arg ...]
741 history -s arg [arg ...]
742 With no options, display the command history list with line num‐
743 bers. Lines listed with a * have been modified. An argument of
744 n lists only the last n lines. If the shell variable HISTTIME‐
745 FORMAT is set and not null, it is used as a format string for
746 strftime(3) to display the time stamp associated with each dis‐
747 played history entry. No intervening blank is printed between
748 the formatted time stamp and the history line. If filename is
749 supplied, it is used as the name of the history file; if not,
750 the value of HISTFILE is used. Options, if supplied, have the
751 following meanings:
752 -c Clear the history list by deleting all the entries.
753 -d offset
754 Delete the history entry at position offset. If offset
755 is negative, it is interpreted as relative to one greater
756 than the last history position, so negative indices count
757 back from the end of the history, and an index of -1
758 refers to the current history -d command.
759 -d start-end
760 Delete the range of history entries between positions
761 start and end, inclusive. Positive and negative values
762 for start and end are interpreted as described above.
763 -a Append the ``new'' history lines to the history file.
764 These are history lines entered since the beginning of
765 the current bash session, but not already appended to the
766 history file.
767 -n Read the history lines not already read from the history
768 file into the current history list. These are lines ap‐
769 pended to the history file since the beginning of the
770 current bash session.
771 -r Read the contents of the history file and append them to
772 the current history list.
773 -w Write the current history list to the history file, over‐
774 writing the history file's contents.
775 -p Perform history substitution on the following args and
776 display the result on the standard output. Does not
777 store the results in the history list. Each arg must be
778 quoted to disable normal history expansion.
779 -s Store the args in the history list as a single entry.
780 The last command in the history list is removed before
781 the args are added.
782 If the HISTTIMEFORMAT variable is set, the time stamp informa‐
784 tion associated with each history entry is written to the his‐
785 tory file, marked with the history comment character. When the
786 history file is read, lines beginning with the history comment
787 character followed immediately by a digit are interpreted as
788 timestamps for the following history entry. The return value is
789 0 unless an invalid option is encountered, an error occurs while
790 reading or writing the history file, an invalid offset or range
791 is supplied as an argument to -d, or the history expansion sup‐
792 plied as an argument to -p fails.
793 jobs [-lnprs] [ jobspec ... ]
795 jobs -x command [ args ... ]
796 The first form lists the active jobs. The options have the fol‐
797 lowing meanings:
798 -l List process IDs in addition to the normal information.
799 -n Display information only about jobs that have changed
800 status since the user was last notified of their status.
801 -p List only the process ID of the job's process group
802 leader.
803 -r Display only running jobs.
804 -s Display only stopped jobs.
805 If jobspec is given, output is restricted to information about
807 that job. The return status is 0 unless an invalid option is
808 encountered or an invalid jobspec is supplied.
809 If the -x option is supplied, jobs replaces any jobspec found in
811 command or args with the corresponding process group ID, and ex‐
812 ecutes command passing it args, returning its exit status.
813 kill [-s sigspec | -n signum | -sigspec] [pid | jobspec] ...
815 kill -l|-L [sigspec | exit_status]
816 Send the signal named by sigspec or signum to the processes
817 named by pid or jobspec. sigspec is either a case-insensitive
818 signal name such as SIGKILL (with or without the SIG prefix) or
819 a signal number; signum is a signal number. If sigspec is not
820 present, then SIGTERM is assumed. An argument of -l lists the
821 signal names. If any arguments are supplied when -l is given,
822 the names of the signals corresponding to the arguments are
823 listed, and the return status is 0. The exit_status argument to
824 -l is a number specifying either a signal number or the exit
825 status of a process terminated by a signal. The -L option is
826 equivalent to -l. kill returns true if at least one signal was
827 successfully sent, or false if an error occurs or an invalid op‐
828 tion is encountered.
829 let arg [arg ...]
831 Each arg is an arithmetic expression to be evaluated (see ARITH‐
832 METIC EVALUATION in bash(1)). If the last arg evaluates to 0,
833 let returns 1; 0 is returned otherwise.
834 local [option] [name[=value] ... | - ]
836 For each argument, a local variable named name is created, and
837 assigned value. The option can be any of the options accepted
838 by declare. When local is used within a function, it causes the
839 variable name to have a visible scope restricted to that func‐
840 tion and its children. If name is -, the set of shell options
841 is made local to the function in which local is invoked: shell
842 options changed using the set builtin inside the function are
843 restored to their original values when the function returns.
844 The restore is effected as if a series of set commands were exe‐
845 cuted to restore the values that were in place before the func‐
846 tion. With no operands, local writes a list of local variables
847 to the standard output. It is an error to use local when not
848 within a function. The return status is 0 unless local is used
849 outside a function, an invalid name is supplied, or name is a
850 readonly variable.
851 logout Exit a login shell.
853 mapfile [-d delim] [-n count] [-O origin] [-s count] [-t] [-u fd] [-C
855 callback] [-c quantum] [array]
856 readarray [-d delim] [-n count] [-O origin] [-s count] [-t] [-u fd] [-C
857 callback] [-c quantum] [array]
858 Read lines from the standard input into the indexed array vari‐
859 able array, or from file descriptor fd if the -u option is sup‐
860 plied. The variable MAPFILE is the default array. Options, if
861 supplied, have the following meanings:
862 -d The first character of delim is used to terminate each
863 input line, rather than newline. If delim is the empty
864 string, mapfile will terminate a line when it reads a NUL
865 character.
866 -n Copy at most count lines. If count is 0, all lines are
867 copied.
868 -O Begin assigning to array at index origin. The default
869 index is 0.
870 -s Discard the first count lines read.
871 -t Remove a trailing delim (default newline) from each line
872 read.
873 -u Read lines from file descriptor fd instead of the stan‐
874 dard input.
875 -C Evaluate callback each time quantum lines are read. The
876 -c option specifies quantum.
877 -c Specify the number of lines read between each call to
878 callback.
879 If -C is specified without -c, the default quantum is 5000.
881 When callback is evaluated, it is supplied the index of the next
882 array element to be assigned and the line to be assigned to that
883 element as additional arguments. callback is evaluated after
884 the line is read but before the array element is assigned.
885 If not supplied with an explicit origin, mapfile will clear ar‐
887 ray before assigning to it.
888 mapfile returns successfully unless an invalid option or option
890 argument is supplied, array is invalid or unassignable, or if
891 array is not an indexed array.
892 popd [-n] [+n] [-n]
894 Removes entries from the directory stack. The elements are num‐
895 bered from 0 starting at the first directory listed by dirs.
896 With no arguments, popd removes the top directory from the
897 stack, and changes to the new top directory. Arguments, if sup‐
898 plied, have the following meanings:
899 -n Suppresses the normal change of directory when removing
900 directories from the stack, so that only the stack is ma‐
901 nipulated.
902 +n Removes the nth entry counting from the left of the list
903 shown by dirs, starting with zero, from the stack. For
904 example: ``popd +0'' removes the first directory, ``popd
905 +1'' the second.
906 -n Removes the nth entry counting from the right of the list
907 shown by dirs, starting with zero. For example: ``popd
908 -0'' removes the last directory, ``popd -1'' the next to
909 last.
910 If the top element of the directory stack is modified, and the
912 -n option was not supplied, popd uses the cd builtin to change
913 to the directory at the top of the stack. If the cd fails, popd
914 returns a non-zero value.
915 Otherwise, popd returns false if an invalid option is encoun‐
917 tered, the directory stack is empty, or a non-existent directory
918 stack entry is specified.
919 If the popd command is successful, bash runs dirs to show the
921 final contents of the directory stack, and the return status is
922 0.
923 printf [-v var] format [arguments]
925 Write the formatted arguments to the standard output under the
926 control of the format. The -v option causes the output to be
927 assigned to the variable var rather than being printed to the
928 standard output.
929 The format is a character string which contains three types of
931 objects: plain characters, which are simply copied to standard
932 output, character escape sequences, which are converted and
933 copied to the standard output, and format specifications, each
934 of which causes printing of the next successive argument. In
935 addition to the standard printf(1) format specifications, printf
936 interprets the following extensions:
937 %b causes printf to expand backslash escape sequences in the
938 corresponding argument in the same way as echo -e.
939 %q causes printf to output the corresponding argument in a
940 format that can be reused as shell input.
941 %Q like %q, but applies any supplied precision to the argu‐
942 ment before quoting it.
943 %(datefmt)T
944 causes printf to output the date-time string resulting
945 from using datefmt as a format string for strftime(3).
946 The corresponding argument is an integer representing the
947 number of seconds since the epoch. Two special argument
948 values may be used: -1 represents the current time, and
949 -2 represents the time the shell was invoked. If no ar‐
950 gument is specified, conversion behaves as if -1 had been
951 given. This is an exception to the usual printf behav‐
952 ior.
953 The %b, %q, and %T directives all use the field width and preci‐
955 sion arguments from the format specification and write that many
956 bytes from (or use that wide a field for) the expanded argument,
957 which usually contains more characters than the original.
958 Arguments to non-string format specifiers are treated as C con‐
960 stants, except that a leading plus or minus sign is allowed, and
961 if the leading character is a single or double quote, the value
962 is the ASCII value of the following character.
963 The format is reused as necessary to consume all of the argu‐
965 ments. If the format requires more arguments than are supplied,
966 the extra format specifications behave as if a zero value or
967 null string, as appropriate, had been supplied. The return
968 value is zero on success, non-zero on failure.
969 pushd [-n] [+n] [-n]
971 pushd [-n] [dir]
972 Adds a directory to the top of the directory stack, or rotates
973 the stack, making the new top of the stack the current working
974 directory. With no arguments, pushd exchanges the top two ele‐
975 ments of the directory stack. Arguments, if supplied, have the
976 following meanings:
977 -n Suppresses the normal change of directory when rotating
978 or adding directories to the stack, so that only the
979 stack is manipulated.
980 +n Rotates the stack so that the nth directory (counting
981 from the left of the list shown by dirs, starting with
982 zero) is at the top.
983 -n Rotates the stack so that the nth directory (counting
984 from the right of the list shown by dirs, starting with
985 zero) is at the top.
986 dir Adds dir to the directory stack at the top
987 After the stack has been modified, if the -n option was not sup‐
989 plied, pushd uses the cd builtin to change to the directory at
990 the top of the stack. If the cd fails, pushd returns a non-zero
991 value.
992 Otherwise, if no arguments are supplied, pushd returns 0 unless
994 the directory stack is empty. When rotating the directory
995 stack, pushd returns 0 unless the directory stack is empty or a
996 non-existent directory stack element is specified.
997 If the pushd command is successful, bash runs dirs to show the
999 final contents of the directory stack.
1000 pwd [-LP]
1002 Print the absolute pathname of the current working directory.
1003 The pathname printed contains no symbolic links if the -P option
1004 is supplied or the -o physical option to the set builtin command
1005 is enabled. If the -L option is used, the pathname printed may
1006 contain symbolic links. The return status is 0 unless an error
1007 occurs while reading the name of the current directory or an in‐
1008 valid option is supplied.
1009 read [-ers] [-a aname] [-d delim] [-i text] [-n nchars] [-N nchars] [-p
1011 prompt] [-t timeout] [-u fd] [name ...]
1012 One line is read from the standard input, or from the file de‐
1013 scriptor fd supplied as an argument to the -u option, split into
1014 words as described in bash(1) under Word Splitting, and the
1015 first word is assigned to the first name, the second word to the
1016 second name, and so on. If there are more words than names, the
1017 remaining words and their intervening delimiters are assigned to
1018 the last name. If there are fewer words read from the input
1019 stream than names, the remaining names are assigned empty val‐
1020 ues. The characters in IFS are used to split the line into
1021 words using the same rules the shell uses for expansion (de‐
1022 scribed in bash(1) under Word Splitting). The backslash charac‐
1023 ter (\) may be used to remove any special meaning for the next
1024 character read and for line continuation. Options, if supplied,
1025 have the following meanings:
1026 -a aname
1027 The words are assigned to sequential indices of the array
1028 variable aname, starting at 0. aname is unset before any
1029 new values are assigned. Other name arguments are ig‐
1030 nored.
1031 -d delim
1032 The first character of delim is used to terminate the in‐
1033 put line, rather than newline. If delim is the empty
1034 string, read will terminate a line when it reads a NUL
1035 character.
1036 -e If the standard input is coming from a terminal, readline
1037 (see READLINE in bash(1)) is used to obtain the line.
1038 Readline uses the current (or default, if line editing
1039 was not previously active) editing settings, but uses
1040 readline's default filename completion.
1041 -i text
1042 If readline is being used to read the line, text is
1043 placed into the editing buffer before editing begins.
1044 -n nchars
1045 read returns after reading nchars characters rather than
1046 waiting for a complete line of input, but honors a delim‐
1047 iter if fewer than nchars characters are read before the
1048 delimiter.
1049 -N nchars
1050 read returns after reading exactly nchars characters
1051 rather than waiting for a complete line of input, unless
1052 EOF is encountered or read times out. Delimiter charac‐
1053 ters encountered in the input are not treated specially
1054 and do not cause read to return until nchars characters
1055 are read. The result is not split on the characters in
1056 IFS; the intent is that the variable is assigned exactly
1057 the characters read (with the exception of backslash; see
1058 the -r option below).
1059 -p prompt
1060 Display prompt on standard error, without a trailing new‐
1061 line, before attempting to read any input. The prompt is
1062 displayed only if input is coming from a terminal.
1063 -r Backslash does not act as an escape character. The back‐
1064 slash is considered to be part of the line. In particu‐
1065 lar, a backslash-newline pair may not then be used as a
1066 line continuation.
1067 -s Silent mode. If input is coming from a terminal, charac‐
1068 ters are not echoed.
1069 -t timeout
1070 Cause read to time out and return failure if a complete
1071 line of input (or a specified number of characters) is
1072 not read within timeout seconds. timeout may be a deci‐
1073 mal number with a fractional portion following the deci‐
1074 mal point. This option is only effective if read is
1075 reading input from a terminal, pipe, or other special
1076 file; it has no effect when reading from regular files.
1077 If read times out, read saves any partial input read into
1078 the specified variable name. If timeout is 0, read re‐
1079 turns immediately, without trying to read any data. The
1080 exit status is 0 if input is available on the specified
1081 file descriptor, or the read will return EOF, non-zero
1082 otherwise. The exit status is greater than 128 if the
1083 timeout is exceeded.
1084 -u fd Read input from file descriptor fd.
1085 If no names are supplied, the line read, without the ending de‐
1087 limiter but otherwise unmodified, is assigned to the variable
1088 REPLY. The exit status is zero, unless end-of-file is encoun‐
1089 tered, read times out (in which case the status is greater than
1090 128), a variable assignment error (such as assigning to a read‐
1091 only variable) occurs, or an invalid file descriptor is supplied
1092 as the argument to -u.
1093 readonly [-aAf] [-p] [name[=word] ...]
1095 The given names are marked readonly; the values of these names
1096 may not be changed by subsequent assignment. If the -f option
1097 is supplied, the functions corresponding to the names are so
1098 marked. The -a option restricts the variables to indexed ar‐
1099 rays; the -A option restricts the variables to associative ar‐
1100 rays. If both options are supplied, -A takes precedence. If no
1101 name arguments are given, or if the -p option is supplied, a
1102 list of all readonly names is printed. The other options may be
1103 used to restrict the output to a subset of the set of readonly
1104 names. The -p option causes output to be displayed in a format
1105 that may be reused as input. If a variable name is followed by
1106 =word, the value of the variable is set to word. The return
1107 status is 0 unless an invalid option is encountered, one of the
1108 names is not a valid shell variable name, or -f is supplied with
1109 a name that is not a function.
1110 return [n]
1112 Causes a function to stop executing and return the value speci‐
1113 fied by n to its caller. If n is omitted, the return status is
1114 that of the last command executed in the function body. If re‐
1115 turn is executed by a trap handler, the last command used to de‐
1116 termine the status is the last command executed before the trap
1117 handler. If return is executed during a DEBUG trap, the last
1118 command used to determine the status is the last command exe‐
1119 cuted by the trap handler before return was invoked. If return
1120 is used outside a function, but during execution of a script by
1121 the . (source) command, it causes the shell to stop executing
1122 that script and return either n or the exit status of the last
1123 command executed within the script as the exit status of the
1124 script. If n is supplied, the return value is its least signif‐
1125 icant 8 bits. The return status is non-zero if return is sup‐
1126 plied a non-numeric argument, or is used outside a function and
1127 not during execution of a script by . or source. Any command
1128 associated with the RETURN trap is executed before execution re‐
1129 sumes after the function or script.
1130 set [-abefhkmnptuvxBCEHPT] [-o option-name] [--] [-] [arg ...]
1132 set [+abefhkmnptuvxBCEHPT] [+o option-name] [--] [-] [arg ...]
1133 Without options, display the name and value of each shell vari‐
1134 able in a format that can be reused as input for setting or re‐
1135 setting the currently-set variables. Read-only variables cannot
1136 be reset. In posix mode, only shell variables are listed. The
1137 output is sorted according to the current locale. When options
1138 are specified, they set or unset shell attributes. Any argu‐
1139 ments remaining after option processing are treated as values
1140 for the positional parameters and are assigned, in order, to $1,
1141 $2, ... $n. Options, if specified, have the following mean‐
1142 ings:
1143 -a Each variable or function that is created or modified is
1144 given the export attribute and marked for export to the
1145 environment of subsequent commands.
1146 -b Report the status of terminated background jobs immedi‐
1147 ately, rather than before the next primary prompt. This
1148 is effective only when job control is enabled.
1149 -e Exit immediately if a pipeline (which may consist of a
1150 single simple command), a list, or a compound command
1151 (see SHELL GRAMMAR in bash(1)), exits with a non-zero
1152 status. The shell does not exit if the command that
1153 fails is part of the command list immediately following
1154 a while or until keyword, part of the test following the
1155 if or elif reserved words, part of any command executed
1156 in a && or || list except the command following the fi‐
1157 nal && or ||, any command in a pipeline but the last, or
1158 if the command's return value is being inverted with !.
1159 If a compound command other than a subshell returns a
1160 non-zero status because a command failed while -e was
1161 being ignored, the shell does not exit. A trap on ERR,
1162 if set, is executed before the shell exits. This option
1163 applies to the shell environment and each subshell envi‐
1164 ronment separately (see COMMAND EXECUTION ENVIRONMENT in
1165 bash(1)), and may cause subshells to exit before execut‐
1166 ing all the commands in the subshell.
1167 If a compound command or shell function executes in a
1169 context where -e is being ignored, none of the commands
1170 executed within the compound command or function body
1171 will be affected by the -e setting, even if -e is set
1172 and a command returns a failure status. If a compound
1173 command or shell function sets -e while executing in a
1174 context where -e is ignored, that setting will not have
1175 any effect until the compound command or the command
1176 containing the function call completes.
1177 -f Disable pathname expansion.
1178 -h Remember the location of commands as they are looked up
1179 for execution. This is enabled by default.
1180 -k All arguments in the form of assignment statements are
1181 placed in the environment for a command, not just those
1182 that precede the command name.
1183 -m Monitor mode. Job control is enabled. This option is
1184 on by default for interactive shells on systems that
1185 support it (see JOB CONTROL in bash(1)). All processes
1186 run in a separate process group. When a background job
1187 completes, the shell prints a line containing its exit
1188 status.
1189 -n Read commands but do not execute them. This may be used
1190 to check a shell script for syntax errors. This is ig‐
1191 nored by interactive shells.
1192 -o option-name
1193 The option-name can be one of the following:
1194 allexport
1195 Same as -a.
1196 braceexpand
1197 Same as -B.
1198 emacs Use an emacs-style command line editing inter‐
1199 face. This is enabled by default when the shell
1200 is interactive, unless the shell is started with
1201 the --noediting option. This also affects the
1202 editing interface used for read -e.
1203 errexit Same as -e.
1204 errtrace
1205 Same as -E.
1206 functrace
1207 Same as -T.
1208 hashall Same as -h.
1209 histexpand
1210 Same as -H.
1211 history Enable command history, as described in bash(1)
1212 under HISTORY. This option is on by default in
1213 interactive shells.
1214 ignoreeof
1215 The effect is as if the shell command ``IG‐
1216 NOREEOF=10'' had been executed (see Shell Vari‐
1217 ables in bash(1)).
1218 keyword Same as -k.
1219 monitor Same as -m.
1220 noclobber
1221 Same as -C.
1222 noexec Same as -n.
1223 noglob Same as -f.
1224 nolog Currently ignored.
1225 notify Same as -b.
1226 nounset Same as -u.
1227 onecmd Same as -t.
1228 physical
1229 Same as -P.
1230 pipefail
1231 If set, the return value of a pipeline is the
1232 value of the last (rightmost) command to exit
1233 with a non-zero status, or zero if all commands
1234 in the pipeline exit successfully. This option
1235 is disabled by default.
1236 posix Change the behavior of bash where the default
1237 operation differs from the POSIX standard to
1238 match the standard (posix mode). See SEE ALSO
1239 in bash(1) for a reference to a document that
1240 details how posix mode affects bash's behavior.
1241 privileged
1242 Same as -p.
1243 verbose Same as -v.
1244 vi Use a vi-style command line editing interface.
1245 This also affects the editing interface used for
1246 read -e.
1247 xtrace Same as -x.
1248 If -o is supplied with no option-name, the values of the
1249 current options are printed. If +o is supplied with no
1250 option-name, a series of set commands to recreate the
1251 current option settings is displayed on the standard
1252 output.
1253 -p Turn on privileged mode. In this mode, the $ENV and
1254 $BASH_ENV files are not processed, shell functions are
1255 not inherited from the environment, and the SHELLOPTS,
1256 BASHOPTS, CDPATH, and GLOBIGNORE variables, if they ap‐
1257 pear in the environment, are ignored. If the shell is
1258 started with the effective user (group) id not equal to
1259 the real user (group) id, and the -p option is not sup‐
1260 plied, these actions are taken and the effective user id
1261 is set to the real user id. If the -p option is sup‐
1262 plied at startup, the effective user id is not reset.
1263 Turning this option off causes the effective user and
1264 group ids to be set to the real user and group ids.
1265 -r Enable restricted shell mode. This option cannot be un‐
1266 set once it has been set.
1267 -t Exit after reading and executing one command.
1268 -u Treat unset variables and parameters other than the spe‐
1269 cial parameters "@" and "*", or array variables sub‐
1270 scripted with "@" or "*", as an error when performing
1271 parameter expansion. If expansion is attempted on an
1272 unset variable or parameter, the shell prints an error
1273 message, and, if not interactive, exits with a non-zero
1274 status.
1275 -v Print shell input lines as they are read.
1276 -x After expanding each simple command, for command, case
1277 command, select command, or arithmetic for command, dis‐
1278 play the expanded value of PS4, followed by the command
1279 and its expanded arguments or associated word list.
1280 -B The shell performs brace expansion (see Brace Expansion
1281 in bash(1)). This is on by default.
1282 -C If set, bash does not overwrite an existing file with
1283 the >, >&, and <> redirection operators. This may be
1284 overridden when creating output files by using the redi‐
1285 rection operator >| instead of >.
1286 -E If set, any trap on ERR is inherited by shell functions,
1287 command substitutions, and commands executed in a sub‐
1288 shell environment. The ERR trap is normally not inher‐
1289 ited in such cases.
1290 -H Enable ! style history substitution. This option is on
1291 by default when the shell is interactive.
1292 -P If set, the shell does not resolve symbolic links when
1293 executing commands such as cd that change the current
1294 working directory. It uses the physical directory
1295 structure instead. By default, bash follows the logical
1296 chain of directories when performing commands which
1297 change the current directory.
1298 -T If set, any traps on DEBUG and RETURN are inherited by
1299 shell functions, command substitutions, and commands ex‐
1300 ecuted in a subshell environment. The DEBUG and RETURN
1301 traps are normally not inherited in such cases.
1302 -- If no arguments follow this option, then the positional
1303 parameters are unset. Otherwise, the positional parame‐
1304 ters are set to the args, even if some of them begin
1305 with a -.
1306 - Signal the end of options, cause all remaining args to
1307 be assigned to the positional parameters. The -x and -v
1308 options are turned off. If there are no args, the posi‐
1309 tional parameters remain unchanged.
1310 The options are off by default unless otherwise noted. Using +
1312 rather than - causes these options to be turned off. The op‐
1313 tions can also be specified as arguments to an invocation of the
1314 shell. The current set of options may be found in $-. The re‐
1315 turn status is always true unless an invalid option is encoun‐
1316 tered.
1317 shift [n]
1319 The positional parameters from n+1 ... are renamed to $1 ....
1320 Parameters represented by the numbers $# down to $#-n+1 are un‐
1321 set. n must be a non-negative number less than or equal to $#.
1322 If n is 0, no parameters are changed. If n is not given, it is
1323 assumed to be 1. If n is greater than $#, the positional param‐
1324 eters are not changed. The return status is greater than zero
1325 if n is greater than $# or less than zero; otherwise 0.
1326 shopt [-pqsu] [-o] [optname ...]
1328 Toggle the values of settings controlling optional shell behav‐
1329 ior. The settings can be either those listed below, or, if the
1330 -o option is used, those available with the -o option to the set
1331 builtin command. With no options, or with the -p option, a list
1332 of all settable options is displayed, with an indication of
1333 whether or not each is set; if optnames are supplied, the output
1334 is restricted to those options. The -p option causes output to
1335 be displayed in a form that may be reused as input. Other op‐
1336 tions have the following meanings:
1337 -s Enable (set) each optname.
1338 -u Disable (unset) each optname.
1339 -q Suppresses normal output (quiet mode); the return status
1340 indicates whether the optname is set or unset. If multi‐
1341 ple optname arguments are given with -q, the return sta‐
1342 tus is zero if all optnames are enabled; non-zero other‐
1343 wise.
1344 -o Restricts the values of optname to be those defined for
1345 the -o option to the set builtin.
1346 If either -s or -u is used with no optname arguments, shopt
1348 shows only those options which are set or unset, respectively.
1349 Unless otherwise noted, the shopt options are disabled (unset)
1350 by default.
1351 The return status when listing options is zero if all optnames
1353 are enabled, non-zero otherwise. When setting or unsetting op‐
1354 tions, the return status is zero unless an optname is not a
1355 valid shell option.
1356 The list of shopt options is:
1358 assoc_expand_once
1360 If set, the shell suppresses multiple evaluation of as‐
1361 sociative array subscripts during arithmetic expression
1362 evaluation, while executing builtins that can perform
1363 variable assignments, and while executing builtins that
1364 perform array dereferencing.
1365 autocd If set, a command name that is the name of a directory
1366 is executed as if it were the argument to the cd com‐
1367 mand. This option is only used by interactive shells.
1368 cdable_vars
1369 If set, an argument to the cd builtin command that is
1370 not a directory is assumed to be the name of a variable
1371 whose value is the directory to change to.
1372 cdspell If set, minor errors in the spelling of a directory com‐
1373 ponent in a cd command will be corrected. The errors
1374 checked for are transposed characters, a missing charac‐
1375 ter, and one character too many. If a correction is
1376 found, the corrected filename is printed, and the com‐
1377 mand proceeds. This option is only used by interactive
1378 shells.
1379 checkhash
1380 If set, bash checks that a command found in the hash ta‐
1381 ble exists before trying to execute it. If a hashed
1382 command no longer exists, a normal path search is per‐
1383 formed.
1384 checkjobs
1385 If set, bash lists the status of any stopped and running
1386 jobs before exiting an interactive shell. If any jobs
1387 are running, this causes the exit to be deferred until a
1388 second exit is attempted without an intervening command
1389 (see JOB CONTROL in bash(1)). The shell always post‐
1390 pones exiting if any jobs are stopped.
1391 checkwinsize
1392 If set, bash checks the window size after each external
1393 (non-builtin) command and, if necessary, updates the
1394 values of LINES and COLUMNS. This option is enabled by
1395 default.
1396 cmdhist If set, bash attempts to save all lines of a multiple-
1397 line command in the same history entry. This allows
1398 easy re-editing of multi-line commands. This option is
1399 enabled by default, but only has an effect if command
1400 history is enabled, as described in bash(1) under HIS‐
1401 TORY.
1402 compat31
1403 compat32
1404 compat40
1405 compat41
1406 compat42
1407 compat43
1408 compat44
1409 compat50
1410 These control aspects of the shell's compatibility mode
1411 (see SHELL COMPATIBILITY MODE in bash(1)).
1412 complete_fullquote
1414 If set, bash quotes all shell metacharacters in file‐
1415 names and directory names when performing completion.
1416 If not set, bash removes metacharacters such as the dol‐
1417 lar sign from the set of characters that will be quoted
1418 in completed filenames when these metacharacters appear
1419 in shell variable references in words to be completed.
1420 This means that dollar signs in variable names that ex‐
1421 pand to directories will not be quoted; however, any
1422 dollar signs appearing in filenames will not be quoted,
1423 either. This is active only when bash is using back‐
1424 slashes to quote completed filenames. This variable is
1425 set by default, which is the default bash behavior in
1426 versions through 4.2.
1427 direxpand
1429 If set, bash replaces directory names with the results
1430 of word expansion when performing filename completion.
1431 This changes the contents of the readline editing buf‐
1432 fer. If not set, bash attempts to preserve what the
1433 user typed.
1434 dirspell
1436 If set, bash attempts spelling correction on directory
1437 names during word completion if the directory name ini‐
1438 tially supplied does not exist.
1439 dotglob If set, bash includes filenames beginning with a `.' in
1441 the results of pathname expansion. The filenames ``.''
1442 and ``..'' must always be matched explicitly, even if
1443 dotglob is set.
1444 execfail
1446 If set, a non-interactive shell will not exit if it can‐
1447 not execute the file specified as an argument to the
1448 exec builtin command. An interactive shell does not
1449 exit if exec fails.
1450 expand_aliases
1452 If set, aliases are expanded as described in bash(1) un‐
1453 der ALIASES. This option is enabled by default for in‐
1454 teractive shells.
1455 extdebug
1457 If set at shell invocation, or in a shell startup file,
1458 arrange to execute the debugger profile before the shell
1459 starts, identical to the --debugger option. If set af‐
1460 ter invocation, behavior intended for use by debuggers
1461 is enabled:
1462 1. The -F option to the declare builtin displays the
1464 source file name and line number corresponding to
1465 each function name supplied as an argument.
1466 2. If the command run by the DEBUG trap returns a
1468 non-zero value, the next command is skipped and
1469 not executed.
1470 3. If the command run by the DEBUG trap returns a
1472 value of 2, and the shell is executing in a sub‐
1473 routine (a shell function or a shell script exe‐
1474 cuted by the . or source builtins), the shell
1475 simulates a call to return.
1476 4. BASH_ARGC and BASH_ARGV are updated as described
1478 in their descriptions in bash(1)).
1479 5. Function tracing is enabled: command substitu‐
1481 tion, shell functions, and subshells invoked with
1482 ( command ) inherit the DEBUG and RETURN traps.
1483 6. Error tracing is enabled: command substitution,
1485 shell functions, and subshells invoked with (
1486 command ) inherit the ERR trap.
1487 extglob If set, the extended pattern matching features described
1489 in bash(1) under Pathname Expansion are enabled.
1490 extquote
1492 If set, $'string' and $"string" quoting is performed
1493 within ${parameter} expansions enclosed in double
1494 quotes. This option is enabled by default.
1495 failglob
1497 If set, patterns which fail to match filenames during
1498 pathname expansion result in an expansion error.
1499 force_fignore
1501 If set, the suffixes specified by the FIGNORE shell
1502 variable cause words to be ignored when performing word
1503 completion even if the ignored words are the only possi‐
1504 ble completions. See SHELL VARIABLES in bash(1) for a
1505 description of FIGNORE. This option is enabled by de‐
1506 fault.
1507 globasciiranges
1509 If set, range expressions used in pattern matching
1510 bracket expressions (see Pattern Matching in bash(1))
1511 behave as if in the traditional C locale when performing
1512 comparisons. That is, the current locale's collating
1513 sequence is not taken into account, so b will not col‐
1514 late between A and B, and upper-case and lower-case
1515 ASCII characters will collate together.
1516 globskipdots
1518 If set, pathname expansion will never match the file‐
1519 names ``.'' and ``..'', even if the pattern begins with
1520 a ``.''. This option is enabled by default.
1521 globstar
1523 If set, the pattern ** used in a pathname expansion con‐
1524 text will match all files and zero or more directories
1525 and subdirectories. If the pattern is followed by a /,
1526 only directories and subdirectories match.
1527 gnu_errfmt
1529 If set, shell error messages are written in the standard
1530 GNU error message format.
1531 histappend
1533 If set, the history list is appended to the file named
1534 by the value of the HISTFILE variable when the shell ex‐
1535 its, rather than overwriting the file.
1536 histreedit
1538 If set, and readline is being used, a user is given the
1539 opportunity to re-edit a failed history substitution.
1540 histverify
1542 If set, and readline is being used, the results of his‐
1543 tory substitution are not immediately passed to the
1544 shell parser. Instead, the resulting line is loaded
1545 into the readline editing buffer, allowing further modi‐
1546 fication.
1547 hostcomplete
1549 If set, and readline is being used, bash will attempt to
1550 perform hostname completion when a word containing a @
1551 is being completed (see Completing under READLINE in
1552 bash(1)). This is enabled by default.
1553 huponexit
1555 If set, bash will send SIGHUP to all jobs when an inter‐
1556 active login shell exits.
1557 inherit_errexit
1559 If set, command substitution inherits the value of the
1560 errexit option, instead of unsetting it in the subshell
1561 environment. This option is enabled when posix mode is
1562 enabled.
1563 interactive_comments
1565 If set, allow a word beginning with # to cause that word
1566 and all remaining characters on that line to be ignored
1567 in an interactive shell (see COMMENTS in bash(1)). This
1568 option is enabled by default.
1569 lastpipe
1571 If set, and job control is not active, the shell runs
1572 the last command of a pipeline not executed in the back‐
1573 ground in the current shell environment.
1574 lithist If set, and the cmdhist option is enabled, multi-line
1576 commands are saved to the history with embedded newlines
1577 rather than using semicolon separators where possible.
1578 localvar_inherit
1580 If set, local variables inherit the value and attributes
1581 of a variable of the same name that exists at a previous
1582 scope before any new value is assigned. The nameref at‐
1583 tribute is not inherited.
1584 localvar_unset
1586 If set, calling unset on local variables in previous
1587 function scopes marks them so subsequent lookups find
1588 them unset until that function returns. This is identi‐
1589 cal to the behavior of unsetting local variables at the
1590 current function scope.
1591 login_shell
1593 The shell sets this option if it is started as a login
1594 shell (see INVOCATION in bash(1)). The value may not be
1595 changed.
1596 mailwarn
1598 If set, and a file that bash is checking for mail has
1599 been accessed since the last time it was checked, the
1600 message ``The mail in mailfile has been read'' is dis‐
1601 played.
1602 no_empty_cmd_completion
1604 If set, and readline is being used, bash will not at‐
1605 tempt to search the PATH for possible completions when
1606 completion is attempted on an empty line.
1607 nocaseglob
1609 If set, bash matches filenames in a case-insensitive
1610 fashion when performing pathname expansion (see Pathname
1611 Expansion in bash(1)).
1612 nocasematch
1614 If set, bash matches patterns in a case-insensitive
1615 fashion when performing matching while executing case or
1616 [[ conditional commands, when performing pattern substi‐
1617 tution word expansions, or when filtering possible com‐
1618 pletions as part of programmable completion.
1619 noexpand_translation
1621 If set, bash encloses the translated results of $"..."
1622 quoting in single quotes instead of double quotes. If
1623 the string is not translated, this has no effect.
1624 nullglob
1626 If set, bash allows patterns which match no files (see
1627 Pathname Expansion in bash(1)) to expand to a null
1628 string, rather than themselves.
1629 patsub_replacement
1631 If set, bash expands occurrences of & in the replacement
1632 string of pattern substitution to the text matched by
1633 the pattern, as described under Parameter Expansion in
1634 bash(1). This option is enabled by default.
1635 progcomp
1637 If set, the programmable completion facilities (see Pro‐
1638 grammable Completion in bash(1)) are enabled. This op‐
1639 tion is enabled by default.
1640 progcomp_alias
1642 If set, and programmable completion is enabled, bash
1643 treats a command name that doesn't have any completions
1644 as a possible alias and attempts alias expansion. If it
1645 has an alias, bash attempts programmable completion us‐
1646 ing the command word resulting from the expanded alias.
1647 promptvars
1649 If set, prompt strings undergo parameter expansion, com‐
1650 mand substitution, arithmetic expansion, and quote re‐
1651 moval after being expanded as described in PROMPTING in
1652 bash(1). This option is enabled by default.
1653 restricted_shell
1655 The shell sets this option if it is started in re‐
1656 stricted mode (see RESTRICTED SHELL in bash(1)). The
1657 value may not be changed. This is not reset when the
1658 startup files are executed, allowing the startup files
1659 to discover whether or not a shell is restricted.
1660 shift_verbose
1662 If set, the shift builtin prints an error message when
1663 the shift count exceeds the number of positional parame‐
1664 ters.
1665 sourcepath
1667 If set, the . (source) builtin uses the value of PATH to
1668 find the directory containing the file supplied as an
1669 argument. This option is enabled by default.
1670 varredir_close
1672 If set, the shell automatically closes file descriptors
1673 assigned using the {varname} redirection syntax (see RE‐
1674 DIRECTION in bash(1)) instead of leaving them open when
1675 the command completes.
1676 syslog_history
1678 If set, command history is logged to syslog.
1679 xpg_echo
1681 If set, the echo builtin expands backslash-escape se‐
1682 quences by default.
1683 suspend [-f]
1685 Suspend the execution of this shell until it receives a SIGCONT
1686 signal. A login shell, or a shell without job control enabled,
1687 cannot be suspended; the -f option can be used to override this
1688 and force the suspension. The return status is 0 unless the
1689 shell is a login shell or job control is not enabled and -f is
1690 not supplied.
1691 test expr
1693 [ expr ]
1694 Return a status of 0 (true) or 1 (false) depending on the evalu‐
1695 ation of the conditional expression expr. Each operator and op‐
1696 erand must be a separate argument. Expressions are composed of
1697 the primaries described in bash(1) under CONDITIONAL EXPRES‐
1698 SIONS. test does not accept any options, nor does it accept and
1699 ignore an argument of -- as signifying the end of options.
1700 Expressions may be combined using the following operators,
1702 listed in decreasing order of precedence. The evaluation de‐
1703 pends on the number of arguments; see below. Operator prece‐
1704 dence is used when there are five or more arguments.
1705 ! expr True if expr is false.
1706 ( expr )
1707 Returns the value of expr. This may be used to override
1708 the normal precedence of operators.
1709 expr1 -a expr2
1710 True if both expr1 and expr2 are true.
1711 expr1 -o expr2
1712 True if either expr1 or expr2 is true.
1713 test and [ evaluate conditional expressions using a set of rules
1715 based on the number of arguments.
1716 0 arguments
1718 The expression is false.
1719 1 argument
1720 The expression is true if and only if the argument is not
1721 null.
1722 2 arguments
1723 If the first argument is !, the expression is true if and
1724 only if the second argument is null. If the first argu‐
1725 ment is one of the unary conditional operators listed in
1726 bash(1) under CONDITIONAL EXPRESSIONS, the expression is
1727 true if the unary test is true. If the first argument is
1728 not a valid unary conditional operator, the expression is
1729 false.
1730 3 arguments
1731 The following conditions are applied in the order listed.
1732 If the second argument is one of the binary conditional
1733 operators listed in bash(1) under CONDITIONAL EXPRES‐
1734 SIONS, the result of the expression is the result of the
1735 binary test using the first and third arguments as oper‐
1736 ands. The -a and -o operators are considered binary op‐
1737 erators when there are three arguments. If the first ar‐
1738 gument is !, the value is the negation of the two-argu‐
1739 ment test using the second and third arguments. If the
1740 first argument is exactly ( and the third argument is ex‐
1741 actly ), the result is the one-argument test of the sec‐
1742 ond argument. Otherwise, the expression is false.
1743 4 arguments
1744 The following conditions are applied in the order listed.
1745 If the first argument is !, the result is the negation of
1746 the three-argument expression composed of the remaining
1747 arguments. the two-argument test using the second and
1748 third arguments. If the first argument is exactly ( and
1749 the fourth argument is exactly ), the result is the two-
1750 argument test of the second and third arguments. Other‐
1751 wise, the expression is parsed and evaluated according to
1752 precedence using the rules listed above.
1753 5 or more arguments
1754 The expression is parsed and evaluated according to
1755 precedence using the rules listed above.
1756 When used with test or [, the < and > operators sort lexico‐
1758 graphically using ASCII ordering.
1759 times Print the accumulated user and system times for the shell and
1761 for processes run from the shell. The return status is 0.
1762 trap [-lp] [[arg] sigspec ...]
1764 The command arg is to be read and executed when the shell re‐
1765 ceives signal(s) sigspec. If arg is absent (and there is a sin‐
1766 gle sigspec) or -, each specified signal is reset to its origi‐
1767 nal disposition (the value it had upon entrance to the shell).
1768 If arg is the null string the signal specified by each sigspec
1769 is ignored by the shell and by the commands it invokes. If arg
1770 is not present and -p has been supplied, then the trap commands
1771 associated with each sigspec are displayed. If no arguments are
1772 supplied or if only -p is given, trap prints the list of com‐
1773 mands associated with each signal. The -l option causes the
1774 shell to print a list of signal names and their corresponding
1775 numbers. Each sigspec is either a signal name defined in <sig‐
1776 nal.h>, or a signal number. Signal names are case insensitive
1777 and the SIG prefix is optional.
1778 If a sigspec is EXIT (0) the command arg is executed on exit
1780 from the shell. If a sigspec is DEBUG, the command arg is exe‐
1781 cuted before every simple command, for command, case command,
1782 select command, every arithmetic for command, and before the
1783 first command executes in a shell function (see SHELL GRAMMAR in
1784 bash(1)). Refer to the description of the extdebug option to
1785 the shopt builtin for details of its effect on the DEBUG trap.
1786 If a sigspec is RETURN, the command arg is executed each time a
1787 shell function or a script executed with the . or source
1788 builtins finishes executing.
1789 If a sigspec is ERR, the command arg is executed whenever a
1791 pipeline (which may consist of a single simple command), a list,
1792 or a compound command returns a non-zero exit status, subject to
1793 the following conditions. The ERR trap is not executed if the
1794 failed command is part of the command list immediately following
1795 a while or until keyword, part of the test in an if statement,
1796 part of a command executed in a && or || list except the command
1797 following the final && or ||, any command in a pipeline but the
1798 last, or if the command's return value is being inverted using
1799 !. These are the same conditions obeyed by the errexit (-e) op‐
1800 tion.
1801 Signals ignored upon entry to the shell cannot be trapped, reset
1803 or listed. Trapped signals that are not being ignored are reset
1804 to their original values in a subshell or subshell environment
1805 when one is created. The return status is false if any sigspec
1806 is invalid; otherwise trap returns true.
1807 type [-aftpP] name [name ...]
1809 With no options, indicate how each name would be interpreted if
1810 used as a command name. If the -t option is used, type prints a
1811 string which is one of alias, keyword, function, builtin, or
1812 file if name is an alias, shell reserved word, function,
1813 builtin, or disk file, respectively. If the name is not found,
1814 then nothing is printed, and an exit status of false is re‐
1815 turned. If the -p option is used, type either returns the name
1816 of the disk file that would be executed if name were specified
1817 as a command name, or nothing if ``type -t name'' would not re‐
1818 turn file. The -P option forces a PATH search for each name,
1819 even if ``type -t name'' would not return file. If a command is
1820 hashed, -p and -P print the hashed value, which is not necessar‐
1821 ily the file that appears first in PATH. If the -a option is
1822 used, type prints all of the places that contain an executable
1823 named name. This includes aliases and functions, if and only if
1824 the -p option is not also used. The table of hashed commands is
1825 not consulted when using -a. The -f option suppresses shell
1826 function lookup, as with the command builtin. type returns true
1827 if all of the arguments are found, false if any are not found.
1828 ulimit [-HS] -a
1830 ulimit [-HS] [-bcdefiklmnpqrstuvxPRT [limit]]
1831 Provides control over the resources available to the shell and
1832 to processes started by it, on systems that allow such control.
1833 The -H and -S options specify that the hard or soft limit is set
1834 for the given resource. A hard limit cannot be increased by a
1835 non-root user once it is set; a soft limit may be increased up
1836 to the value of the hard limit. If neither -H nor -S is speci‐
1837 fied, both the soft and hard limits are set. The value of limit
1838 can be a number in the unit specified for the resource or one of
1839 the special values hard, soft, or unlimited, which stand for the
1840 current hard limit, the current soft limit, and no limit, re‐
1841 spectively. If limit is omitted, the current value of the soft
1842 limit of the resource is printed, unless the -H option is given.
1843 When more than one resource is specified, the limit name and
1844 unit, if appropriate, are printed before the value. Other op‐
1845 tions are interpreted as follows:
1846 -a All current limits are reported; no limits are set
1847 -b The maximum socket buffer size
1848 -c The maximum size of core files created
1849 -d The maximum size of a process's data segment
1850 -e The maximum scheduling priority ("nice")
1851 -f The maximum size of files written by the shell and its
1852 children
1853 -i The maximum number of pending signals
1854 -k The maximum number of kqueues that may be allocated
1855 -l The maximum size that may be locked into memory
1856 -m The maximum resident set size (many systems do not honor
1857 this limit)
1858 -n The maximum number of open file descriptors (most systems
1859 do not allow this value to be set)
1860 -p The pipe size in 512-byte blocks (this may not be set)
1861 -q The maximum number of bytes in POSIX message queues
1862 -r The maximum real-time scheduling priority
1863 -s The maximum stack size
1864 -t The maximum amount of cpu time in seconds
1865 -u The maximum number of processes available to a single
1866 user
1867 -v The maximum amount of virtual memory available to the
1868 shell and, on some systems, to its children
1869 -x The maximum number of file locks
1870 -P The maximum number of pseudoterminals
1871 -R The maximum time a real-time process can run before
1872 blocking, in microseconds
1873 -T The maximum number of threads
1874 If limit is given, and the -a option is not used, limit is the
1876 new value of the specified resource. If no option is given,
1877 then -f is assumed. Values are in 1024-byte increments, except
1878 for -t, which is in seconds; -R, which is in microseconds; -p,
1879 which is in units of 512-byte blocks; -P, -T, -b, -k, -n, and
1880 -u, which are unscaled values; and, when in posix mode, -c and
1881 -f, which are in 512-byte increments. The return status is 0
1882 unless an invalid option or argument is supplied, or an error
1883 occurs while setting a new limit. In POSIX Mode 512-byte blocks
1884 are used for the `-c' and `-f' options.
1885 umask [-p] [-S] [mode]
1887 The user file-creation mask is set to mode. If mode begins with
1888 a digit, it is interpreted as an octal number; otherwise it is
1889 interpreted as a symbolic mode mask similar to that accepted by
1890 chmod(1). If mode is omitted, the current value of the mask is
1891 printed. The -S option causes the mask to be printed in sym‐
1892 bolic form; the default output is an octal number. If the -p
1893 option is supplied, and mode is omitted, the output is in a form
1894 that may be reused as input. The return status is 0 if the mode
1895 was successfully changed or if no mode argument was supplied,
1896 and false otherwise.
1897 unalias [-a] [name ...]
1899 Remove each name from the list of defined aliases. If -a is
1900 supplied, all alias definitions are removed. The return value
1901 is true unless a supplied name is not a defined alias.
1902 unset [-fv] [-n] [name ...]
1904 For each name, remove the corresponding variable or function.
1905 If the -v option is given, each name refers to a shell variable,
1906 and that variable is removed. Read-only variables may not be
1907 unset. If -f is specified, each name refers to a shell func‐
1908 tion, and the function definition is removed. If the -n option
1909 is supplied, and name is a variable with the nameref attribute,
1910 name will be unset rather than the variable it references. -n
1911 has no effect if the -f option is supplied. If no options are
1912 supplied, each name refers to a variable; if there is no vari‐
1913 able by that name, a function with that name, if any, is unset.
1914 Each unset variable or function is removed from the environment
1915 passed to subsequent commands. If any of BASH_ALIASES,
1916 BASH_ARGV0, BASH_CMDS, BASH_COMMAND, BASH_SUBSHELL, BASHPID,
1917 COMP_WORDBREAKS, DIRSTACK, EPOCHREALTIME, EPOCHSECONDS, FUNC‐
1918 NAME, GROUPS, HISTCMD, LINENO, RANDOM, SECONDS, or SRANDOM are
1919 unset, they lose their special properties, even if they are sub‐
1920 sequently reset. The exit status is true unless a name is read‐
1921 only or may not be unset.
1922 wait [-fn] [-p varname] [id ...]
1924 Wait for each specified child process and return its termination
1925 status. Each id may be a process ID or a job specification; if
1926 a job spec is given, all processes in that job's pipeline are
1927 waited for. If id is not given, wait waits for all running
1928 background jobs and the last-executed process substitution, if
1929 its process id is the same as $!, and the return status is zero.
1930 If the -n option is supplied, wait waits for a single job from
1931 the list of ids or, if no ids are supplied, any job, to complete
1932 and returns its exit status. If none of the supplied arguments
1933 is a child of the shell, or if no arguments are supplied and the
1934 shell has no unwaited-for children, the exit status is 127. If
1935 the -p option is supplied, the process or job identifier of the
1936 job for which the exit status is returned is assigned to the
1937 variable varname named by the option argument. The variable
1938 will be unset initially, before any assignment. This is useful
1939 only when the -n option is supplied. Supplying the -f option,
1940 when job control is enabled, forces wait to wait for id to ter‐
1941 minate before returning its status, instead of returning when it
1942 changes status. If id specifies a non-existent process or job,
1943 the return status is 127. If wait is interrupted by a signal,
1944 the return status will be greater than 128, as described under
1945 SIGNALS in bash(1). Otherwise, the return status is the exit
1946 status of the last process or job waited for.
1947
1949 Bash-4.0 introduced the concept of a shell compatibility level, speci‐
1950 fied as a set of options to the shopt builtin ( compat31, compat32,
1951 compat40, compat41, and so on). There is only one current compatibil‐
1952 ity level -- each option is mutually exclusive. The compatibility
1953 level is intended to allow users to select behavior from previous ver‐
1954 sions that is incompatible with newer versions while they migrate
1955 scripts to use current features and behavior. It's intended to be a
1956 temporary solution.
1957 This section does not mention behavior that is standard for a particu‐
1959 lar version (e.g., setting compat32 means that quoting the rhs of the
1960 regexp matching operator quotes special regexp characters in the word,
1961 which is default behavior in bash-3.2 and subsequent versions).
1962 If a user enables, say, compat32, it may affect the behavior of other
1964 compatibility levels up to and including the current compatibility
1965 level. The idea is that each compatibility level controls behavior
1966 that changed in that version of bash, but that behavior may have been
1967 present in earlier versions. For instance, the change to use locale-
1968 based comparisons with the [[ command came in bash-4.1, and earlier
1969 versions used ASCII-based comparisons, so enabling compat32 will enable
1970 ASCII-based comparisons as well. That granularity may not be suffi‐
1971 cient for all uses, and as a result users should employ compatibility
1972 levels carefully. Read the documentation for a particular feature to
1973 find out the current behavior.
1974 Bash-4.3 introduced a new shell variable: BASH_COMPAT. The value as‐
1976 signed to this variable (a decimal version number like 4.2, or an inte‐
1977 ger corresponding to the compatNN option, like 42) determines the com‐
1978 patibility level.
1979 Starting with bash-4.4, Bash has begun deprecating older compatibility
1981 levels. Eventually, the options will be removed in favor of BASH_COM‐
1982 PAT.
1983 Bash-5.0 is the final version for which there will be an individual
1985 shopt option for the previous version. Users should use BASH_COMPAT on
1986 bash-5.0 and later versions.
1987 The following table describes the behavior changes controlled by each
1989 compatibility level setting. The compatNN tag is used as shorthand for
1990 setting the compatibility level to NN using one of the following mecha‐
1991 nisms. For versions prior to bash-5.0, the compatibility level may be
1992 set using the corresponding compatNN shopt option. For bash-4.3 and
1993 later versions, the BASH_COMPAT variable is preferred, and it is re‐
1994 quired for bash-5.1 and later versions.
1995 compat31
1997 • quoting the rhs of the [[ command's regexp matching oper‐
1998 ator (=~) has no special effect
1999 compat32
2001 • interrupting a command list such as "a ; b ; c" causes
2002 the execution of the next command in the list (in
2003 bash-4.0 and later versions, the shell acts as if it re‐
2004 ceived the interrupt, so interrupting one command in a
2005 list aborts the execution of the entire list)
2006 compat40
2008 • the < and > operators to the [[ command do not consider
2009 the current locale when comparing strings; they use ASCII
2010 ordering. Bash versions prior to bash-4.1 use ASCII col‐
2011 lation and strcmp(3); bash-4.1 and later use the current
2012 locale's collation sequence and strcoll(3).
2013 compat41
2015 • in posix mode, time may be followed by options and still
2016 be recognized as a reserved word (this is POSIX interpre‐
2017 tation 267)
2018 • in posix mode, the parser requires that an even number of
2019 single quotes occur in the word portion of a double-
2020 quoted parameter expansion and treats them specially, so
2021 that characters within the single quotes are considered
2022 quoted (this is POSIX interpretation 221)
2023 compat42
2025 • the replacement string in double-quoted pattern substitu‐
2026 tion does not undergo quote removal, as it does in ver‐
2027 sions after bash-4.2
2028 • in posix mode, single quotes are considered special when
2029 expanding the word portion of a double-quoted parameter
2030 expansion and can be used to quote a closing brace or
2031 other special character (this is part of POSIX interpre‐
2032 tation 221); in later versions, single quotes are not
2033 special within double-quoted word expansions
2034 compat43
2036 • the shell does not print a warning message if an attempt
2037 is made to use a quoted compound assignment as an argu‐
2038 ment to declare (e.g., declare -a foo='(1 2)'). Later
2039 versions warn that this usage is deprecated
2040 • word expansion errors are considered non-fatal errors
2041 that cause the current command to fail, even in posix
2042 mode (the default behavior is to make them fatal errors
2043 that cause the shell to exit)
2044 • when executing a shell function, the loop state
2045 (while/until/etc.) is not reset, so break or continue in
2046 that function will break or continue loops in the calling
2047 context. Bash-4.4 and later reset the loop state to pre‐
2048 vent this
2049 compat44
2051 • the shell sets up the values used by BASH_ARGV and
2052 BASH_ARGC so they can expand to the shell's positional
2053 parameters even if extended debugging mode is not enabled
2054 • a subshell inherits loops from its parent context, so
2055 break or continue will cause the subshell to exit.
2056 Bash-5.0 and later reset the loop state to prevent the
2057 exit
2058 • variable assignments preceding builtins like export and
2059 readonly that set attributes continue to affect variables
2060 with the same name in the calling environment even if the
2061 shell is not in posix mode
2062 compat50
2064 • Bash-5.1 changed the way $RANDOM is generated to intro‐
2065 duce slightly more randomness. If the shell compatibility
2066 level is set to 50 or lower, it reverts to the method
2067 from bash-5.0 and previous versions, so seeding the ran‐
2068 dom number generator by assigning a value to RANDOM will
2069 produce the same sequence as in bash-5.0
2070 • If the command hash table is empty, bash versions prior
2071 to bash-5.1 printed an informational message to that ef‐
2072 fect, even when producing output that can be reused as
2073 input. Bash-5.1 suppresses that message when the -l op‐
2074 tion is supplied.
2075 compat51
2077 • The unset builtin treats attempts to unset array sub‐
2078 scripts @ and * differently depending on whether the ar‐
2079 ray is indexed or associative, and differently than in
2080 previous versions.
2081
2083 bash(1), sh(1)
2084GNU Bash 5.2 2021 November 22 BASH_BUILTINS(1)