1BASH_BUILTINS(1) General Commands Manual BASH_BUILTINS(1)
2
6 bash, :, ., [, alias, bg, bind, break, builtin, caller, cd, command,
7 compgen, complete, compopt, continue, declare, dirs, disown, echo,
8 enable, eval, exec, exit, export, false, fc, fg, getopts, hash, help,
9 history, jobs, kill, let, local, logout, mapfile, popd, printf, pushd,
10 pwd, read, 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, break, continue, let,
19 and shift builtins accept and process arguments beginning with - with‐
20 out requiring --. Other builtins that accept arguments but are not
21 specified as accepting options interpret arguments beginning with - as
22 invalid options and require -- to prevent this interpretation.
23 : [arguments]
24 No effect; the command does nothing beyond expanding arguments
25 and performing any specified redirections. A zero exit code is
26 returned.
27 . filename [arguments]
29 source filename [arguments]
30 Read and execute commands from filename in the current shell
31 environment and return the exit status of the last command exe‐
32 cuted from filename. If filename does not contain a slash, file
33 names in PATH are used to find the directory containing file‐
34 name. The file searched for in PATH need not be executable.
35 When bash is not in posix mode, the current directory is
36 searched if no file is found in PATH. If the sourcepath option
37 to the shopt builtin command is turned off, the PATH is not
38 searched. If any arguments are supplied, they become the posi‐
39 tional parameters when filename is executed. Otherwise the
40 positional parameters are unchanged. The return status is the
41 status of the last command exited within the script (0 if no
42 commands are executed), and false if filename is not found or
43 cannot be read.
44 alias [-p] [name[=value] ...]
46 Alias with no arguments or with the -p option prints the list of
47 aliases in the form alias name=value on standard output. When
48 arguments are supplied, an alias is defined for each name whose
49 value is given. A trailing space in value causes the next word
50 to be checked for alias substitution when the alias is expanded.
51 For each name in the argument list for which no value is sup‐
52 plied, the name and value of the alias is printed. Alias
53 returns true unless a name is given for which no alias has been
54 defined.
55 bg [jobspec ...]
57 Resume each suspended job jobspec in the background, as if it
58 had been started with &. If jobspec is not present, the shell's
59 notion of the current job is used. bg jobspec returns 0 unless
60 run when job control is disabled or, when run with job control
61 enabled, any specified jobspec was not found or was started
62 without job control.
63 bind [-m keymap] [-lpsvPSV]
65 bind [-m keymap] [-q function] [-u function] [-r keyseq]
66 bind [-m keymap] -f filename
67 bind [-m keymap] -x keyseq:shell-command
68 bind [-m keymap] keyseq:function-name
69 bind readline-command
70 Display current readline key and function bindings, bind a key
71 sequence to a readline function or macro, or set a readline
72 variable. Each non-option argument is a command as it would
73 appear in .inputrc, but each binding or command must be passed
74 as a separate argument; e.g., '"\C-x\C-r": re-read-init-file'.
75 Options, if supplied, have the following meanings:
76 -m keymap
77 Use keymap as the keymap to be affected by the subsequent
78 bindings. Acceptable keymap names are emacs, emacs-stan‐
79 dard, emacs-meta, emacs-ctlx, vi, vi-move, vi-command,
80 and vi-insert. vi is equivalent to vi-command; emacs is
81 equivalent to emacs-standard.
82 -l List the names of all readline functions.
83 -p Display readline function names and bindings in such a
84 way that they can be re-read.
85 -P List current readline function names and bindings.
86 -s Display readline key sequences bound to macros and the
87 strings they output in such a way that they can be re-
88 read.
89 -S Display readline key sequences bound to macros and the
90 strings they output.
91 -v Display readline variable names and values in such a way
92 that they can be re-read.
93 -V List current readline variable names and values.
94 -f filename
95 Read key bindings from filename.
96 -q function
97 Query about which keys invoke the named function.
98 -u function
99 Unbind all keys bound to the named function.
100 -r keyseq
101 Remove any current binding for keyseq.
102 -x keyseq:shell-command
103 Cause shell-command to be executed whenever keyseq is
104 entered. When shell-command is executed, the shell sets
105 the READLINE_LINE variable to the contents of the read‐
106 line line buffer and the READLINE_POINT variable to the
107 current location of the insertion point. If the executed
108 command changes the value of READLINE_LINE or READ‐
109 LINE_POINT, those new values will be reflected in the
110 editing state.
111 The return value is 0 unless an unrecognized option is given or
113 an error occurred.
114 break [n]
116 Exit from within a for, while, until, or select loop. If n is
117 specified, break n levels. n must be ≥ 1. If n is greater than
118 the number of enclosing loops, all enclosing loops are exited.
119 The return value is non-zero when n is ≤ 0; Otherwise, break
120 returns 0 value.
121 builtin shell-builtin [arguments]
123 Execute the specified shell builtin, passing it arguments, and
124 return its exit status. This is useful when defining a function
125 whose name is the same as a shell builtin, retaining the func‐
126 tionality of the builtin within the function. The cd builtin is
127 commonly redefined this way. The return status is false if
128 shell-builtin is not a shell builtin command.
129 caller [expr]
131 Returns the context of any active subroutine call (a shell func‐
132 tion or a script executed with the . or source builtins). With‐
133 out expr, caller displays the line number and source filename of
134 the current subroutine call. If a non-negative integer is sup‐
135 plied as expr, caller displays the line number, subroutine name,
136 and source file corresponding to that position in the current
137 execution call stack. This extra information may be used, for
138 example, to print a stack trace. The current frame is frame 0.
139 The return value is 0 unless the shell is not executing a sub‐
140 routine call or expr does not correspond to a valid position in
141 the call stack.
142 cd [-L|[-P [-e]]] [dir]
144 Change the current directory to dir. The variable HOME is the
145 default dir. The variable CDPATH defines the search path for
146 the directory containing dir. Alternative directory names in
147 CDPATH are separated by a colon (:). A null directory name in
148 CDPATH is the same as the current directory, i.e., ``.''. If
149 dir begins with a slash (/), then CDPATH is not used. The -P
150 option says to use the physical directory structure instead of
151 following symbolic links (see also the -P option to the set
152 builtin command); the -L option forces symbolic links to be fol‐
153 lowed. If the -e option is supplied with -P, and the current
154 working directory cannot be successfully determined after a suc‐
155 cessful directory change, cd will return an unsuccessful status.
156 An argument of - is equivalent to $OLDPWD. If a non-empty
157 directory name from CDPATH is used, or if - is the first argu‐
158 ment, and the directory change is successful, the absolute path‐
159 name of the new working directory is written to the standard
160 output. The return value is true if the directory was success‐
161 fully changed; false otherwise.
162 command [-pVv] command [arg ...]
164 Run command with args suppressing the normal shell function
165 lookup. Only builtin commands or commands found in the PATH are
166 executed. If the -p option is given, the search for command is
167 performed using a default value for PATH that is guaranteed to
168 find all of the standard utilities. If either the -V or -v
169 option is supplied, a description of command is printed. The -v
170 option causes a single word indicating the command or file name
171 used to invoke command to be displayed; the -V option produces a
172 more verbose description. If the -V or -v option is supplied,
173 the exit status is 0 if command was found, and 1 if not. If
174 neither option is supplied and an error occurred or command can‐
175 not be found, the exit status is 127. Otherwise, the exit sta‐
176 tus of the command builtin is the exit status of command.
177 compgen [option] [word]
179 Generate possible completion matches for word according to the
180 options, which may be any option accepted by the complete
181 builtin with the exception of -p and -r, and write the matches
182 to the standard output. When using the -F or -C options, the
183 various shell variables set by the programmable completion
184 facilities, while available, will not have useful values.
185 The matches will be generated in the same way as if the program‐
187 mable completion code had generated them directly from a comple‐
188 tion specification with the same flags. If word is specified,
189 only those completions matching word will be displayed.
190 The return value is true unless an invalid option is supplied,
192 or no matches were generated.
193 complete [-abcdefgjksuv] [-o comp-option] [-DE] [-A action] [-G glob‐
195 pat] [-W wordlist] [-F function] [-C command]
196 [-X filterpat] [-P prefix] [-S suffix] name [name ...]
197 complete -pr [-DE] [name ...]
198 Specify how arguments to each name should be completed. If the
199 -p option is supplied, or if no options are supplied, existing
200 completion specifications are printed in a way that allows them
201 to be reused as input. The -r option removes a completion spec‐
202 ification for each name, or, if no names are supplied, all com‐
203 pletion specifications. The -D option indicates that the
204 remaining options and actions should apply to the ``default''
205 command completion; that is, completion attempted on a command
206 for which no completion has previously been defined. The -E
207 option indicates that the remaining options and actions should
208 apply to ``empty'' command completion; that is, completion
209 attempted on a blank line.
210 The process of applying these completion specifications when
212 word completion is attempted is described above under Program‐
213 mable Completion.
214 Other options, if specified, have the following meanings. The
216 arguments to the -G, -W, and -X options (and, if necessary, the
217 -P and -S options) should be quoted to protect them from expan‐
218 sion before the complete builtin is invoked.
219 -o comp-option
220 The comp-option controls several aspects of the comp‐
221 spec's behavior beyond the simple generation of comple‐
222 tions. comp-option may be one of:
223 bashdefault
224 Perform the rest of the default bash completions
225 if the compspec generates no matches.
226 default Use readline's default filename completion if
227 the compspec generates no matches.
228 dirnames
229 Perform directory name completion if the comp‐
230 spec generates no matches.
231 filenames
232 Tell readline that the compspec generates file‐
233 names, so it can perform any filename-specific
234 processing (like adding a slash to directory
235 names, quoting special characters, or suppress‐
236 ing trailing spaces). Intended to be used with
237 shell functions.
238 nospace Tell readline not to append a space (the
239 default) to words completed at the end of the
240 line.
241 plusdirs
242 After any matches defined by the compspec are
243 generated, directory name completion is
244 attempted and any matches are added to the
245 results of the other actions.
246 -A action
247 The action may be one of the following to generate a
248 list of possible completions:
249 alias Alias names. May also be specified as -a.
250 arrayvar
251 Array variable names.
252 binding Readline key binding names.
253 builtin Names of shell builtin commands. May also be
254 specified as -b.
255 command Command names. May also be specified as -c.
256 directory
257 Directory names. May also be specified as -d.
258 disabled
259 Names of disabled shell builtins.
260 enabled Names of enabled shell builtins.
261 export Names of exported shell variables. May also be
262 specified as -e.
263 file File names. May also be specified as -f.
264 function
265 Names of shell functions.
266 group Group names. May also be specified as -g.
267 helptopic
268 Help topics as accepted by the help builtin.
269 hostname
270 Hostnames, as taken from the file specified by
271 the HOSTFILE shell variable.
272 job Job names, if job control is active. May also
273 be specified as -j.
274 keyword Shell reserved words. May also be specified as
275 -k.
276 running Names of running jobs, if job control is active.
277 service Service names. May also be specified as -s.
278 setopt Valid arguments for the -o option to the set
279 builtin.
280 shopt Shell option names as accepted by the shopt
281 builtin.
282 signal Signal names.
283 stopped Names of stopped jobs, if job control is active.
284 user User names. May also be specified as -u.
285 variable
286 Names of all shell variables. May also be spec‐
287 ified as -v.
288 -C command
289 command is executed in a subshell environment, and its
290 output is used as the possible completions.
291 -F function
292 The shell function function is executed in the current
293 shell environment. When it finishes, the possible com‐
294 pletions are retrieved from the value of the COMPREPLY
295 array variable.
296 -G globpat
297 The pathname expansion pattern globpat is expanded to
298 generate the possible completions.
299 -P prefix
300 prefix is added at the beginning of each possible com‐
301 pletion after all other options have been applied.
302 -S suffix
303 suffix is appended to each possible completion after all
304 other options have been applied.
305 -W wordlist
306 The wordlist is split using the characters in the IFS
307 special variable as delimiters, and each resultant word
308 is expanded. The possible completions are the members
309 of the resultant list which match the word being com‐
310 pleted.
311 -X filterpat
312 filterpat is a pattern as used for pathname expansion.
313 It is applied to the list of possible completions gener‐
314 ated by the preceding options and arguments, and each
315 completion matching filterpat is removed from the list.
316 A leading ! in filterpat negates the pattern; in this
317 case, any completion not matching filterpat is removed.
318 The return value is true unless an invalid option is supplied,
320 an option other than -p or -r is supplied without a name argu‐
321 ment, an attempt is made to remove a completion specification
322 for a name for which no specification exists, or an error occurs
323 adding a completion specification.
324 compopt [-o option] [-DE] [+o option] [name]
326 Modify completion options for each name according to the
327 options, or for the currently-executing completion if no names
328 are supplied. If no options are given, display the completion
329 options for each name or the current completion. The possible
330 values of option are those valid for the complete builtin
331 described above. The -D option indicates that the remaining
332 options should apply to the ``default'' command completion; that
333 is, completion attempted on a command for which no completion
334 has previously been defined. The -E option indicates that the
335 remaining options should apply to ``empty'' command completion;
336 that is, completion attempted on a blank line.
337 The return value is true unless an invalid option is supplied,
339 an attempt is made to modify the options for a name for which no
340 completion specification exists, or an output error occurs.
341 continue [n]
343 Resume the next iteration of the enclosing for, while, until, or
344 select loop. If n is specified, resume at the nth enclosing
345 loop. n must be ≥ 1. If n is greater than the number of
346 enclosing loops, the last enclosing loop (the ``top-level''
347 loop) is resumed. When continue is executed inside of loop, the
348 return value is non-zero when n is ≤ 0; Otherwise, continue
349 returns 0 value. When continue is executed outside of loop, the
350 return value is 0.
351 declare [-aAfFgilrtux] [-p] [name[=value] ...]
353 typeset [-aAfFgilrtux] [-p] [name[=value] ...]
354 Declare variables and/or give them attributes. If no names are
355 given then display the values of variables. The -p option will
356 display the attributes and values of each name. When -p is used
357 with name arguments, additional options are ignored. When -p is
358 supplied without name arguments, it will display the attributes
359 and values of all variables having the attributes specified by
360 the additional options. If no other options are supplied with
361 -p, declare will display the attributes and values of all shell
362 variables. The -f option will restrict the display to shell
363 functions. The -F option inhibits the display of function defi‐
364 nitions; only the function name and attributes are printed. If
365 the extdebug shell option is enabled using shopt, the source
366 file name and line number where the function is defined are dis‐
367 played as well. The -F option implies -f. The -g option forces
368 variables to be created or modified at the global scope, even
369 when declare is executed in a shell function. It is ignored in
370 all other cases. The following options can be used to restrict
371 output to variables with the specified attribute or to give
372 variables attributes:
373 -a Each name is an indexed array variable (see Arrays
374 above).
375 -A Each name is an associative array variable (see Arrays
376 above).
377 -f Use function names only.
378 -i The variable is treated as an integer; arithmetic evalua‐
379 tion (see ARITHMETIC EVALUATION above) is performed when
380 the variable is assigned a value.
381 -l When the variable is assigned a value, all upper-case
382 characters are converted to lower-case. The upper-case
383 attribute is disabled.
384 -r Make names readonly. These names cannot then be assigned
385 values by subsequent assignment statements or unset.
386 -t Give each name the trace attribute. Traced functions
387 inherit the DEBUG and RETURN traps from the calling
388 shell. The trace attribute has no special meaning for
389 variables.
390 -u When the variable is assigned a value, all lower-case
391 characters are converted to upper-case. The lower-case
392 attribute is disabled.
393 -x Mark names for export to subsequent commands via the
394 environment.
395 Using `+' instead of `-' turns off the attribute instead, with
397 the exceptions that +a may not be used to destroy an array vari‐
398 able and +r will not remove the readonly attribute. When used
399 in a function, makes each name local, as with the local command,
400 unless the -g option is supplied, If a variable name is followed
401 by =value, the value of the variable is set to value. The
402 return value is 0 unless an invalid option is encountered, an
403 attempt is made to define a function using ``-f foo=bar'', an
404 attempt is made to assign a value to a readonly variable, an
405 attempt is made to assign a value to an array variable without
406 using the compound assignment syntax (see Arrays above), one of
407 the names is not a valid shell variable name, an attempt is made
408 to turn off readonly status for a readonly variable, an attempt
409 is made to turn off array status for an array variable, or an
410 attempt is made to display a non-existent function with -f.
411 dirs [+n] [-n] [-clpv]
413 Without options, displays the list of currently remembered
414 directories. The default display is on a single line with
415 directory names separated by spaces. Directories are added to
416 the list with the pushd command; the popd command removes
417 entries from the list.
418 +n Displays the nth entry counting from the left of the list
419 shown by dirs when invoked without options, starting with
420 zero.
421 -n Displays the nth entry counting from the right of the
422 list shown by dirs when invoked without options, starting
423 with zero.
424 -c Clears the directory stack by deleting all of the
425 entries.
426 -l Produces a longer listing; the default listing format
427 uses a tilde to denote the home directory.
428 -p Print the directory stack with one entry per line.
429 -v Print the directory stack with one entry per line, pre‐
430 fixing each entry with its index in the stack.
431 The return value is 0 unless an invalid option is supplied or n
433 indexes beyond the end of the directory stack.
434 disown [-ar] [-h] [jobspec ...]
436 Without options, each jobspec is removed from the table of
437 active jobs. If jobspec is not present, and neither -a nor -r
438 is supplied, the shell's notion of the current job is used. If
439 the -h option is given, each jobspec is not removed from the ta‐
440 ble, but is marked so that SIGHUP is not sent to the job if the
441 shell receives a SIGHUP. If no jobspec is present, and neither
442 the -a nor the -r option is supplied, the current job is used.
443 If no jobspec is supplied, the -a option means to remove or mark
444 all jobs; the -r option without a jobspec argument restricts
445 operation to running jobs. The return value is 0 unless a job‐
446 spec does not specify a valid job.
447 echo [-neE] [arg ...]
449 Output the args, separated by spaces, followed by a newline.
450 The return status is always 0. If -n is specified, the trailing
451 newline is suppressed. If the -e option is given, interpreta‐
452 tion of the following backslash-escaped characters is enabled.
453 The -E option disables the interpretation of these escape char‐
454 acters, even on systems where they are interpreted by default.
455 The xpg_echo shell option may be used to dynamically determine
456 whether or not echo expands these escape characters by default.
457 echo does not interpret -- to mean the end of options. echo
458 interprets the following escape sequences:
459 \a alert (bell)
460 \b backspace
461 \c suppress further output
462 \e
463 \E an escape character
464 \f form feed
465 \n new line
466 \r carriage return
467 \t horizontal tab
468 \v vertical tab
469 \\ backslash
470 \0nnn the eight-bit character whose value is the octal value
471 nnn (zero to three octal digits)
472 \xHH the eight-bit character whose value is the hexadecimal
473 value HH (one or two hex digits)
474 \uHHHH the Unicode (ISO/IEC 10646) character whose value is the
475 hexadecimal value HHHH (one to four hex digits)
476 \UHHHHHHHH
477 the Unicode (ISO/IEC 10646) character whose value is the
478 hexadecimal value HHHHHHHH (one to eight hex digits)
479 enable [-a] [-dnps] [-f filename] [name ...]
481 Enable and disable builtin shell commands. Disabling a builtin
482 allows a disk command which has the same name as a shell builtin
483 to be executed without specifying a full pathname, even though
484 the shell normally searches for builtins before disk commands.
485 If -n is used, each name is disabled; otherwise, names are
486 enabled. For example, to use the test binary found via the PATH
487 instead of the shell builtin version, run ``enable -n test''.
488 The -f option means to load the new builtin command name from
489 shared object filename, on systems that support dynamic loading.
490 The -d option will delete a builtin previously loaded with -f.
491 If no name arguments are given, or if the -p option is supplied,
492 a list of shell builtins is printed. With no other option argu‐
493 ments, the list consists of all enabled shell builtins. If -n
494 is supplied, only disabled builtins are printed. If -a is sup‐
495 plied, the list printed includes all builtins, with an indica‐
496 tion of whether or not each is enabled. If -s is supplied, the
497 output is restricted to the POSIX special builtins. The return
498 value is 0 unless a name is not a shell builtin or there is an
499 error loading a new builtin from a shared object.
500 eval [arg ...]
502 The args are read and concatenated together into a single com‐
503 mand. This command is then read and executed by the shell, and
504 its exit status is returned as the value of eval. If there are
505 no args, or only null arguments, eval returns 0.
506 exec [-cl] [-a name] [command [arguments]]
508 If command is specified, it replaces the shell. No new process
509 is created. The arguments become the arguments to command. If
510 the -l option is supplied, the shell places a dash at the begin‐
511 ning of the zeroth argument passed to command. This is what
512 login(1) does. The -c option causes command to be executed with
513 an empty environment. If -a is supplied, the shell passes name
514 as the zeroth argument to the executed command. If command can‐
515 not be executed for some reason, a non-interactive shell exits,
516 unless the shell option execfail is enabled, in which case it
517 returns failure. An interactive shell returns failure if the
518 file cannot be executed. If command is not specified, any redi‐
519 rections take effect in the current shell, and the return status
520 is 0. If there is a redirection error, the return status is 1.
521 exit [n]
523 Cause the shell to exit with a status of n. If n is omitted,
524 the exit status is that of the last command executed. A trap on
525 EXIT is executed before the shell terminates.
526 export [-fn] [name[=word]] ...
528 export -p
529 The supplied names are marked for automatic export to the envi‐
530 ronment of subsequently executed commands. If the -f option is
531 given, the names refer to functions. If no names are given, or
532 if the -p option is supplied, a list of all names that are
533 exported in this shell is printed. The -n option causes the
534 export property to be removed from each name. If a variable
535 name is followed by =word, the value of the variable is set to
536 word. export returns an exit status of 0 unless an invalid
537 option is encountered, one of the names is not a valid shell
538 variable name, or -f is supplied with a name that is not a func‐
539 tion.
540 fc [-e ename] [-lnr] [first] [last]
542 fc -s [pat=rep] [cmd]
543 Fix Command. In the first form, a range of commands from first
544 to last is selected from the history list. First and last may
545 be specified as a string (to locate the last command beginning
546 with that string) or as a number (an index into the history
547 list, where a negative number is used as an offset from the cur‐
548 rent command number). If last is not specified it is set to the
549 current command for listing (so that ``fc -l -10'' prints the
550 last 10 commands) and to first otherwise. If first is not spec‐
551 ified it is set to the previous command for editing and -16 for
552 listing.
553 The -n option suppresses the command numbers when listing. The
555 -r option reverses the order of the commands. If the -l option
556 is given, the commands are listed on standard output. Other‐
557 wise, the editor given by ename is invoked on a file containing
558 those commands. If ename is not given, the value of the FCEDIT
559 variable is used, and the value of EDITOR if FCEDIT is not set.
560 If neither variable is set, is used. When editing is complete,
561 the edited commands are echoed and executed.
562 In the second form, command is re-executed after each instance
564 of pat is replaced by rep. A useful alias to use with this is
565 ``r="fc -s"'', so that typing ``r cc'' runs the last command
566 beginning with ``cc'' and typing ``r'' re-executes the last com‐
567 mand.
568 If the first form is used, the return value is 0 unless an
570 invalid option is encountered or first or last specify history
571 lines out of range. If the -e option is supplied, the return
572 value is the value of the last command executed or failure if an
573 error occurs with the temporary file of commands. If the second
574 form is used, the return status is that of the command re-exe‐
575 cuted, unless cmd does not specify a valid history line, in
576 which case fc returns failure.
577 fg [jobspec]
579 Resume jobspec in the foreground, and make it the current job.
580 If jobspec is not present, the shell's notion of the current job
581 is used. The return value is that of the command placed into
582 the foreground, or failure if run when job control is disabled
583 or, when run with job control enabled, if jobspec does not spec‐
584 ify a valid job or jobspec specifies a job that was started
585 without job control.
586 getopts optstring name [args]
588 getopts is used by shell procedures to parse positional parame‐
589 ters. optstring contains the option characters to be recog‐
590 nized; if a character is followed by a colon, the option is
591 expected to have an argument, which should be separated from it
592 by white space. The colon and question mark characters may not
593 be used as option characters. Each time it is invoked, getopts
594 places the next option in the shell variable name, initializing
595 name if it does not exist, and the index of the next argument to
596 be processed into the variable OPTIND. OPTIND is initialized to
597 1 each time the shell or a shell script is invoked. When an
598 option requires an argument, getopts places that argument into
599 the variable OPTARG. The shell does not reset OPTIND automati‐
600 cally; it must be manually reset between multiple calls to
601 getopts within the same shell invocation if a new set of parame‐
602 ters is to be used.
603 When the end of options is encountered, getopts exits with a
605 return value greater than zero. OPTIND is set to the index of
606 the first non-option argument, and name is set to ?.
607 getopts normally parses the positional parameters, but if more
609 arguments are given in args, getopts parses those instead.
610 getopts can report errors in two ways. If the first character
612 of optstring is a colon, silent error reporting is used. In
613 normal operation diagnostic messages are printed when invalid
614 options or missing option arguments are encountered. If the
615 variable OPTERR is set to 0, no error messages will be dis‐
616 played, even if the first character of optstring is not a colon.
617 If an invalid option is seen, getopts places ? into name and, if
619 not silent, prints an error message and unsets OPTARG. If
620 getopts is silent, the option character found is placed in
621 OPTARG and no diagnostic message is printed.
622 If a required argument is not found, and getopts is not silent,
624 a question mark (?) is placed in name, OPTARG is unset, and a
625 diagnostic message is printed. If getopts is silent, then a
626 colon (:) is placed in name and OPTARG is set to the option
627 character found.
628 getopts returns true if an option, specified or unspecified, is
630 found. It returns false if the end of options is encountered or
631 an error occurs.
632 hash [-lr] [-p filename] [-dt] [name]
634 Each time hash is invoked, the full pathname of the command name
635 is determined by searching the directories in $PATH and remem‐
636 bered. Any previously-remembered pathname is discarded. If the
637 -p option is supplied, no path search is performed, and filename
638 is used as the full file name of the command. The -r option
639 causes the shell to forget all remembered locations. The -d
640 option causes the shell to forget the remembered location of
641 each name. If the -t option is supplied, the full pathname to
642 which each name corresponds is printed. If multiple name argu‐
643 ments are supplied with -t, the name is printed before the
644 hashed full pathname. The -l option causes output to be dis‐
645 played in a format that may be reused as input. If no arguments
646 are given, or if only -l is supplied, information about remem‐
647 bered commands is printed. The return status is true unless a
648 name is not found or an invalid option is supplied.
649 help [-dms] [pattern]
651 Display helpful information about builtin commands. If pattern
652 is specified, help gives detailed help on all commands matching
653 pattern; otherwise help for all the builtins and shell control
654 structures is printed.
655 -d Display a short description of each pattern
656 -m Display the description of each pattern in a manpage-like
657 format
658 -s Display only a short usage synopsis for each pattern
659 The return status is 0 unless no command matches pattern.
661 history [n]
663 history -c
664 history -d offset
665 history -anrw [filename]
666 history -p arg [arg ...]
667 history -s arg [arg ...]
668 With no options, display the command history list with line num‐
669 bers. Lines listed with a * have been modified. An argument of
670 n lists only the last n lines. If the shell variable HISTTIME‐
671 FORMAT is set and not null, it is used as a format string for
672 strftime(3) to display the time stamp associated with each dis‐
673 played history entry. No intervening blank is printed between
674 the formatted time stamp and the history line. If filename is
675 supplied, it is used as the name of the history file; if not,
676 the value of HISTFILE is used. Options, if supplied, have the
677 following meanings:
678 -c Clear the history list by deleting all the entries.
679 -d offset
680 Delete the history entry at position offset.
681 -a Append the ``new'' history lines (history lines entered
682 since the beginning of the current bash session) to the
683 history file.
684 -n Read the history lines not already read from the history
685 file into the current history list. These are lines
686 appended to the history file since the beginning of the
687 current bash session.
688 -r Read the contents of the history file and use them as the
689 current history.
690 -w Write the current history to the history file, overwrit‐
691 ing the history file's contents.
692 -p Perform history substitution on the following args and
693 display the result on the standard output. Does not
694 store the results in the history list. Each arg must be
695 quoted to disable normal history expansion.
696 -s Store the args in the history list as a single entry.
697 The last command in the history list is removed before
698 the args are added.
699 If the HISTTIMEFORMAT variable is set, the time stamp informa‐
701 tion associated with each history entry is written to the his‐
702 tory file, marked with the history comment character. When the
703 history file is read, lines beginning with the history comment
704 character followed immediately by a digit are interpreted as
705 timestamps for the previous history line. The return value is 0
706 unless an invalid option is encountered, an error occurs while
707 reading or writing the history file, an invalid offset is sup‐
708 plied as an argument to -d, or the history expansion supplied as
709 an argument to -p fails.
710 jobs [-lnprs] [ jobspec ... ]
712 jobs -x command [ args ... ]
713 The first form lists the active jobs. The options have the fol‐
714 lowing meanings:
715 -l List process IDs in addition to the normal information.
716 -n Display information only about jobs that have changed
717 status since the user was last notified of their status.
718 -p List only the process ID of the job's process group
719 leader.
720 -r Restrict output to running jobs.
721 -s Restrict output to stopped jobs.
722 If jobspec is given, output is restricted to information about
724 that job. The return status is 0 unless an invalid option is
725 encountered or an invalid jobspec is supplied.
726 If the -x option is supplied, jobs replaces any jobspec found in
728 command or args with the corresponding process group ID, and
729 executes command passing it args, returning its exit status.
730 kill [-s sigspec | -n signum | -sigspec] [pid | jobspec] ...
732 kill -l [sigspec | exit_status]
733 Send the signal named by sigspec or signum to the processes
734 named by pid or jobspec. sigspec is either a case-insensitive
735 signal name such as SIGKILL (with or without the SIG prefix) or
736 a signal number; signum is a signal number. If sigspec is not
737 present, then SIGTERM is assumed. An argument of -l lists the
738 signal names. If any arguments are supplied when -l is given,
739 the names of the signals corresponding to the arguments are
740 listed, and the return status is 0. The exit_status argument to
741 -l is a number specifying either a signal number or the exit
742 status of a process terminated by a signal. kill returns true
743 if at least one signal was successfully sent, or false if an
744 error occurs or an invalid option is encountered.
745 let arg [arg ...]
747 Each arg is an arithmetic expression to be evaluated (see ARITH‐
748 METIC EVALUATION above). If the last arg evaluates to 0, let
749 returns 1; 0 is returned otherwise.
750 local [option] [name[=value] ...]
752 For each argument, a local variable named name is created, and
753 assigned value. The option can be any of the options accepted
754 by declare. When local is used within a function, it causes the
755 variable name to have a visible scope restricted to that func‐
756 tion and its children. With no operands, local writes a list of
757 local variables to the standard output. It is an error to use
758 local when not within a function. The return status is 0 unless
759 local is used outside a function, an invalid name is supplied,
760 or name is a readonly variable.
761 logout Exit a login shell.
763 mapfile [-n count] [-O origin] [-s count] [-t] [-u fd] [-C callback]
765 [-c quantum] [array]
766 readarray [-n count] [-O origin] [-s count] [-t] [-u fd] [-C callback]
767 [-c quantum] [array]
768 Read lines from the standard input into the indexed array vari‐
769 able array, or from file descriptor fd if the -u option is sup‐
770 plied. The variable MAPFILE is the default array. Options, if
771 supplied, have the following meanings:
772 -n Copy at most count lines. If count is 0, all lines are
773 copied.
774 -O Begin assigning to array at index origin. The default
775 index is 0.
776 -s Discard the first count lines read.
777 -t Remove a trailing newline from each line read.
778 -u Read lines from file descriptor fd instead of the stan‐
779 dard input.
780 -C Evaluate callback each time quantum lines are read. The
781 -c option specifies quantum.
782 -c Specify the number of lines read between each call to
783 callback.
784 If -C is specified without -c, the default quantum is 5000.
786 When callback is evaluated, it is supplied the index of the next
787 array element to be assigned and the line to be assigned to that
788 element as additional arguments. callback is evaluated after
789 the line is read but before the array element is assigned.
790 If not supplied with an explicit origin, mapfile will clear
792 array before assigning to it.
793 mapfile returns successfully unless an invalid option or option
795 argument is supplied, array is invalid or unassignable, or if
796 array is not an indexed array.
797 popd [-n] [+n] [-n]
799 Removes entries from the directory stack. With no arguments,
800 removes the top directory from the stack, and performs a cd to
801 the new top directory. Arguments, if supplied, have the follow‐
802 ing meanings:
803 -n Suppresses the normal change of directory when removing
804 directories from the stack, so that only the stack is
805 manipulated.
806 +n Removes the nth entry counting from the left of the list
807 shown by dirs, starting with zero. For example: ``popd
808 +0'' removes the first directory, ``popd +1'' the second.
809 -n Removes the nth entry counting from the right of the list
810 shown by dirs, starting with zero. For example: ``popd
811 -0'' removes the last directory, ``popd -1'' the next to
812 last.
813 If the popd command is successful, a dirs is performed as well,
815 and the return status is 0. popd returns false if an invalid
816 option is encountered, the directory stack is empty, a non-exis‐
817 tent directory stack entry is specified, or the directory change
818 fails.
819 printf [-v var] format [arguments]
821 Write the formatted arguments to the standard output under the
822 control of the format. The -v option causes the output to be
823 assigned to the variable var rather than being printed to the
824 standard output.
825 The format is a character string which contains three types of
827 objects: plain characters, which are simply copied to standard
828 output, character escape sequences, which are converted and
829 copied to the standard output, and format specifications, each
830 of which causes printing of the next successive argument. In
831 addition to the standard printf(1) format specifications, printf
832 interprets the following extensions:
833 %b causes printf to expand backslash escape sequences in the
834 corresponding argument (except that \c terminates output,
835 backslashes in \', \", and \? are not removed, and octal
836 escapes beginning with \0 may contain up to four digits).
837 %q causes printf to output the corresponding argument in a
838 format that can be reused as shell input.
839 %(datefmt)T
840 causes printf to output the date-time string resulting
841 from using datefmt as a format string for strftime(3).
842 The corresponding argument is an integer representing the
843 number of seconds since the epoch. Two special argument
844 values may be used: -1 represents the current time, and
845 -2 represents the time the shell was invoked.
846 Arguments to non-string format specifiers are treated as C con‐
848 stants, except that a leading plus or minus sign is allowed, and
849 if the leading character is a single or double quote, the value
850 is the ASCII value of the following character.
851 The format is reused as necessary to consume all of the argu‐
853 ments. If the format requires more arguments than are supplied,
854 the extra format specifications behave as if a zero value or
855 null string, as appropriate, had been supplied. The return
856 value is zero on success, non-zero on failure.
857 pushd [-n] [+n] [-n]
859 pushd [-n] [dir]
860 Adds a directory to the top of the directory stack, or rotates
861 the stack, making the new top of the stack the current working
862 directory. With no arguments, exchanges the top two directories
863 and returns 0, unless the directory stack is empty. Arguments,
864 if supplied, have the following meanings:
865 -n Suppresses the normal change of directory when adding
866 directories to the stack, so that only the stack is
867 manipulated.
868 +n Rotates the stack so that the nth directory (counting
869 from the left of the list shown by dirs, starting with
870 zero) is at the top.
871 -n Rotates the stack so that the nth directory (counting
872 from the right of the list shown by dirs, starting with
873 zero) is at the top.
874 dir Adds dir to the directory stack at the top, making it the
875 new current working directory.
876 If the pushd command is successful, a dirs is performed as well.
878 If the first form is used, pushd returns 0 unless the cd to dir
879 fails. With the second form, pushd returns 0 unless the direc‐
880 tory stack is empty, a non-existent directory stack element is
881 specified, or the directory change to the specified new current
882 directory fails.
883 pwd [-LP]
885 Print the absolute pathname of the current working directory.
886 The pathname printed contains no symbolic links if the -P option
887 is supplied or the -o physical option to the set builtin command
888 is enabled. If the -L option is used, the pathname printed may
889 contain symbolic links. The return status is 0 unless an error
890 occurs while reading the name of the current directory or an
891 invalid option is supplied.
892 read [-ers] [-a aname] [-d delim] [-i text] [-n nchars] [-N nchars] [-p
894 prompt] [-t timeout] [-u fd] [name ...]
895 One line is read from the standard input, or from the file
896 descriptor fd supplied as an argument to the -u option, and the
897 first word is assigned to the first name, the second word to the
898 second name, and so on, with leftover words and their interven‐
899 ing separators assigned to the last name. If there are fewer
900 words read from the input stream than names, the remaining names
901 are assigned empty values. The characters in IFS are used to
902 split the line into words. The backslash character (\) may be
903 used to remove any special meaning for the next character read
904 and for line continuation. Options, if supplied, have the fol‐
905 lowing meanings:
906 -a aname
907 The words are assigned to sequential indices of the array
908 variable aname, starting at 0. aname is unset before any
909 new values are assigned. Other name arguments are
910 ignored.
911 -d delim
912 The first character of delim is used to terminate the
913 input line, rather than newline.
914 -e If the standard input is coming from a terminal, readline
915 (see READLINE above) is used to obtain the line. Read‐
916 line uses the current (or default, if line editing was
917 not previously active) editing settings.
918 -i text
919 If readline is being used to read the line, text is
920 placed into the editing buffer before editing begins.
921 -n nchars
922 read returns after reading nchars characters rather than
923 waiting for a complete line of input, but honor a delim‐
924 iter if fewer than nchars characters are read before the
925 delimiter.
926 -N nchars
927 read returns after reading exactly nchars characters
928 rather than waiting for a complete line of input, unless
929 EOF is encountered or read times out. Delimiter charac‐
930 ters encountered in the input are not treated specially
931 and do not cause read to return until nchars characters
932 are read.
933 -p prompt
934 Display prompt on standard error, without a trailing new‐
935 line, before attempting to read any input. The prompt is
936 displayed only if input is coming from a terminal.
937 -r Backslash does not act as an escape character. The back‐
938 slash is considered to be part of the line. In particu‐
939 lar, a backslash-newline pair may not be used as a line
940 continuation.
941 -s Silent mode. If input is coming from a terminal, charac‐
942 ters are not echoed.
943 -t timeout
944 Cause read to time out and return failure if a complete
945 line of input is not read within timeout seconds. time‐
946 out may be a decimal number with a fractional portion
947 following the decimal point. This option is only effec‐
948 tive if read is reading input from a terminal, pipe, or
949 other special file; it has no effect when reading from
950 regular files. If timeout is 0, read returns success if
951 input is available on the specified file descriptor,
952 failure otherwise. The exit status is greater than 128
953 if the timeout is exceeded.
954 -u fd Read input from file descriptor fd.
955 If no names are supplied, the line read is assigned to the vari‐
957 able REPLY. The return code is zero, unless end-of-file is
958 encountered, read times out (in which case the return code is
959 greater than 128), or an invalid file descriptor is supplied as
960 the argument to -u.
961 readonly [-aAf] [-p] [name[=word] ...]
963 The given names are marked readonly; the values of these names
964 may not be changed by subsequent assignment. If the -f option
965 is supplied, the functions corresponding to the names are so
966 marked. The -a option restricts the variables to indexed
967 arrays; the -A option restricts the variables to associative
968 arrays. If both options are supplied, -A takes precedence. If
969 no name arguments are given, or if the -p option is supplied, a
970 list of all readonly names is printed. The other options may be
971 used to restrict the output to a subset of the set of readonly
972 names. The -p option causes output to be displayed in a format
973 that may be reused as input. If a variable name is followed by
974 =word, the value of the variable is set to word. The return
975 status is 0 unless an invalid option is encountered, one of the
976 names is not a valid shell variable name, or -f is supplied with
977 a name that is not a function.
978 return [n]
980 Causes a function to exit with the return value specified by n.
981 If n is omitted, the return status is that of the last command
982 executed in the function body. If used outside a function, but
983 during execution of a script by the . (source) command, it
984 causes the shell to stop executing that script and return either
985 n or the exit status of the last command executed within the
986 script as the exit status of the script. If used outside a
987 function and not during execution of a script by ., the return
988 status is false. Any command associated with the RETURN trap is
989 executed before execution resumes after the function or script.
990 set [--abefhkmnptuvxBCEHPT] [-o option-name] [arg ...]
992 set [+abefhkmnptuvxBCEHPT] [+o option-name] [arg ...]
993 Without options, the name and value of each shell variable are
994 displayed in a format that can be reused as input for setting or
995 resetting the currently-set variables. Read-only variables can‐
996 not be reset. In posix mode, only shell variables are listed.
997 The output is sorted according to the current locale. When
998 options are specified, they set or unset shell attributes. Any
999 arguments remaining after option processing are treated as val‐
1000 ues for the positional parameters and are assigned, in order, to
1001 $1, $2, ... $n. Options, if specified, have the following
1002 meanings:
1003 -a Automatically mark variables and functions which are
1004 modified or created for export to the environment of
1005 subsequent commands.
1006 -b Report the status of terminated background jobs immedi‐
1007 ately, rather than before the next primary prompt. This
1008 is effective only when job control is enabled.
1009 -e Exit immediately if a pipeline (which may consist of a
1010 single simple command), a subshell command enclosed in
1011 parentheses, or one of the commands executed as part of
1012 a command list enclosed by braces (see SHELL GRAMMAR
1013 above) exits with a non-zero status. The shell does not
1014 exit if the command that fails is part of the command
1015 list immediately following a while or until keyword,
1016 part of the test following the if or elif reserved
1017 words, part of any command executed in a && or || list
1018 except the command following the final && or ||, any
1019 command in a pipeline but the last, or if the command's
1020 return value is being inverted with !. A trap on ERR,
1021 if set, is executed before the shell exits. This option
1022 applies to the shell environment and each subshell envi‐
1023 ronment separately (see COMMAND EXECUTION ENVIRONMENT
1024 above), and may cause subshells to exit before executing
1025 all the commands in the subshell.
1026 -f Disable pathname expansion.
1027 -h Remember the location of commands as they are looked up
1028 for execution. This is enabled by default.
1029 -k All arguments in the form of assignment statements are
1030 placed in the environment for a command, not just those
1031 that precede the command name.
1032 -m Monitor mode. Job control is enabled. This option is
1033 on by default for interactive shells on systems that
1034 support it (see JOB CONTROL above). Background pro‐
1035 cesses run in a separate process group and a line con‐
1036 taining their exit status is printed upon their comple‐
1037 tion.
1038 -n Read commands but do not execute them. This may be used
1039 to check a shell script for syntax errors. This is
1040 ignored by interactive shells.
1041 -o option-name
1042 The option-name can be one of the following:
1043 allexport
1044 Same as -a.
1045 braceexpand
1046 Same as -B.
1047 emacs Use an emacs-style command line editing inter‐
1048 face. This is enabled by default when the shell
1049 is interactive, unless the shell is started with
1050 the --noediting option. This also affects the
1051 editing interface used for read -e.
1052 errexit Same as -e.
1053 errtrace
1054 Same as -E.
1055 functrace
1056 Same as -T.
1057 hashall Same as -h.
1058 histexpand
1059 Same as -H.
1060 history Enable command history, as described above under
1061 HISTORY. This option is on by default in inter‐
1062 active shells.
1063 ignoreeof
1064 The effect is as if the shell command
1065 ``IGNOREEOF=10'' had been executed (see Shell
1066 Variables above).
1067 keyword Same as -k.
1068 monitor Same as -m.
1069 noclobber
1070 Same as -C.
1071 noexec Same as -n.
1072 noglob Same as -f.
1073 nolog Currently ignored.
1074 notify Same as -b.
1075 nounset Same as -u.
1076 onecmd Same as -t.
1077 physical
1078 Same as -P.
1079 pipefail
1080 If set, the return value of a pipeline is the
1081 value of the last (rightmost) command to exit
1082 with a non-zero status, or zero if all commands
1083 in the pipeline exit successfully. This option
1084 is disabled by default.
1085 posix Change the behavior of bash where the default
1086 operation differs from the POSIX standard to
1087 match the standard (posix mode).
1088 privileged
1089 Same as -p.
1090 verbose Same as -v.
1091 vi Use a vi-style command line editing interface.
1092 This also affects the editing interface used for
1093 read -e.
1094 xtrace Same as -x.
1095 If -o is supplied with no option-name, the values of the
1096 current options are printed. If +o is supplied with no
1097 option-name, a series of set commands to recreate the
1098 current option settings is displayed on the standard
1099 output.
1100 -p Turn on privileged mode. In this mode, the $ENV and
1101 $BASH_ENV files are not processed, shell functions are
1102 not inherited from the environment, and the SHELLOPTS,
1103 BASHOPTS, CDPATH, and GLOBIGNORE variables, if they
1104 appear in the environment, are ignored. If the shell is
1105 started with the effective user (group) id not equal to
1106 the real user (group) id, and the -p option is not sup‐
1107 plied, these actions are taken and the effective user id
1108 is set to the real user id. If the -p option is sup‐
1109 plied at startup, the effective user id is not reset.
1110 Turning this option off causes the effective user and
1111 group ids to be set to the real user and group ids.
1112 -t Exit after reading and executing one command.
1113 -u Treat unset variables and parameters other than the spe‐
1114 cial parameters "@" and "*" as an error when performing
1115 parameter expansion. If expansion is attempted on an
1116 unset variable or parameter, the shell prints an error
1117 message, and, if not interactive, exits with a non-zero
1118 status.
1119 -v Print shell input lines as they are read.
1120 -x After expanding each simple command, for command, case
1121 command, select command, or arithmetic for command, dis‐
1122 play the expanded value of PS4, followed by the command
1123 and its expanded arguments or associated word list.
1124 -B The shell performs brace expansion (see Brace Expansion
1125 above). This is on by default.
1126 -C If set, bash does not overwrite an existing file with
1127 the >, >&, and <> redirection operators. This may be
1128 overridden when creating output files by using the redi‐
1129 rection operator >| instead of >.
1130 -E If set, any trap on ERR is inherited by shell functions,
1131 command substitutions, and commands executed in a sub‐
1132 shell environment. The ERR trap is normally not inher‐
1133 ited in such cases.
1134 -H Enable ! style history substitution. This option is on
1135 by default when the shell is interactive.
1136 -P If set, the shell does not follow symbolic links when
1137 executing commands such as cd that change the current
1138 working directory. It uses the physical directory
1139 structure instead. By default, bash follows the logical
1140 chain of directories when performing commands which
1141 change the current directory.
1142 -T If set, any traps on DEBUG and RETURN are inherited by
1143 shell functions, command substitutions, and commands
1144 executed in a subshell environment. The DEBUG and
1145 RETURN traps are normally not inherited in such cases.
1146 -- If no arguments follow this option, then the positional
1147 parameters are unset. Otherwise, the positional parame‐
1148 ters are set to the args, even if some of them begin
1149 with a -.
1150 - Signal the end of options, cause all remaining args to
1151 be assigned to the positional parameters. The -x and -v
1152 options are turned off. If there are no args, the posi‐
1153 tional parameters remain unchanged.
1154 The options are off by default unless otherwise noted. Using +
1156 rather than - causes these options to be turned off. The
1157 options can also be specified as arguments to an invocation of
1158 the shell. The current set of options may be found in $-. The
1159 return status is always true unless an invalid option is encoun‐
1160 tered.
1161 shift [n]
1163 The positional parameters from n+1 ... are renamed to $1 ....
1164 Parameters represented by the numbers $# down to $#-n+1 are
1165 unset. n must be a non-negative number less than or equal to
1166 $#. If n is 0, no parameters are changed. If n is not given,
1167 it is assumed to be 1. If n is greater than $#, the positional
1168 parameters are not changed. The return status is greater than
1169 zero if n is greater than $# or less than zero; otherwise 0.
1170 shopt [-pqsu] [-o] [optname ...]
1172 Toggle the values of variables controlling optional shell behav‐
1173 ior. With no options, or with the -p option, a list of all set‐
1174 table options is displayed, with an indication of whether or not
1175 each is set. The -p option causes output to be displayed in a
1176 form that may be reused as input. Other options have the fol‐
1177 lowing meanings:
1178 -s Enable (set) each optname.
1179 -u Disable (unset) each optname.
1180 -q Suppresses normal output (quiet mode); the return status
1181 indicates whether the optname is set or unset. If multi‐
1182 ple optname arguments are given with -q, the return sta‐
1183 tus is zero if all optnames are enabled; non-zero other‐
1184 wise.
1185 -o Restricts the values of optname to be those defined for
1186 the -o option to the set builtin.
1187 If either -s or -u is used with no optname arguments, the dis‐
1189 play is limited to those options which are set or unset, respec‐
1190 tively. Unless otherwise noted, the shopt options are disabled
1191 (unset) by default.
1192 The return status when listing options is zero if all optnames
1194 are enabled, non-zero otherwise. When setting or unsetting
1195 options, the return status is zero unless an optname is not a
1196 valid shell option.
1197 The list of shopt options is:
1199 autocd If set, a command name that is the name of a directory
1201 is executed as if it were the argument to the cd com‐
1202 mand. This option is only used by interactive shells.
1203 cdable_vars
1204 If set, an argument to the cd builtin command that is
1205 not a directory is assumed to be the name of a variable
1206 whose value is the directory to change to.
1207 cdspell If set, minor errors in the spelling of a directory com‐
1208 ponent in a cd command will be corrected. The errors
1209 checked for are transposed characters, a missing charac‐
1210 ter, and one character too many. If a correction is
1211 found, the corrected file name is printed, and the com‐
1212 mand proceeds. This option is only used by interactive
1213 shells.
1214 checkhash
1215 If set, bash checks that a command found in the hash ta‐
1216 ble exists before trying to execute it. If a hashed
1217 command no longer exists, a normal path search is per‐
1218 formed.
1219 checkjobs
1220 If set, bash lists the status of any stopped and running
1221 jobs before exiting an interactive shell. If any jobs
1222 are running, this causes the exit to be deferred until a
1223 second exit is attempted without an intervening command
1224 (see JOB CONTROL above). The shell always postpones
1225 exiting if any jobs are stopped.
1226 checkwinsize
1227 If set, bash checks the window size after each command
1228 and, if necessary, updates the values of LINES and COL‐
1229 UMNS.
1230 cmdhist If set, bash attempts to save all lines of a multiple-
1231 line command in the same history entry. This allows
1232 easy re-editing of multi-line commands.
1233 compat31
1234 If set, bash changes its behavior to that of version 3.1
1235 with respect to quoted arguments to the [[ conditional
1236 command's =~ operator.
1237 compat32
1238 If set, bash changes its behavior to that of version 3.2
1239 with respect to locale-specific string comparison when
1240 using the [[ conditional command's < and > operators.
1241 Bash versions prior to bash-4.1 use ASCII collation and
1242 strcmp(3); bash-4.1 and later use the current locale's
1243 collation sequence and strcoll(3).
1244 compat40
1245 If set, bash changes its behavior to that of version 4.0
1246 with respect to locale-specific string comparison when
1247 using the [[ conditional command's < and > operators
1248 (see previous item) and the effect of interrupting a
1249 command list.
1250 compat41
1251 If set, bash, when in posix mode, treats a single quote
1252 in a double-quoted parameter expansion as a special
1253 character. The single quotes must match (an even num‐
1254 ber) and the characters between the single quotes are
1255 considered quoted. This is the behavior of posix mode
1256 through version 4.1. The default bash behavior remains
1257 as in previous versions.
1258 direxpand
1259 If set, bash replaces directory names with the results
1260 of word expansion when performing filename completion.
1261 This changes the contents of the readline editing buf‐
1262 fer. If not set, bash attempts to preserve what the
1263 user typed.
1264 dirspell
1265 If set, bash attempts spelling correction on directory
1266 names during word completion if the directory name ini‐
1267 tially supplied does not exist.
1268 dotglob If set, bash includes filenames beginning with a `.' in
1269 the results of pathname expansion.
1270 execfail
1271 If set, a non-interactive shell will not exit if it can‐
1272 not execute the file specified as an argument to the
1273 exec builtin command. An interactive shell does not
1274 exit if exec fails.
1275 expand_aliases
1276 If set, aliases are expanded as described above under
1277 ALIASES. This option is enabled by default for interac‐
1278 tive shells.
1279 extdebug
1280 If set, behavior intended for use by debuggers is
1281 enabled:
1282 1. The -F option to the declare builtin displays the
1283 source file name and line number corresponding to
1284 each function name supplied as an argument.
1285 2. If the command run by the DEBUG trap returns a
1286 non-zero value, the next command is skipped and
1287 not executed.
1288 3. If the command run by the DEBUG trap returns a
1289 value of 2, and the shell is executing in a sub‐
1290 routine (a shell function or a shell script exe‐
1291 cuted by the . or source builtins), a call to
1292 return is simulated.
1293 4. BASH_ARGC and BASH_ARGV are updated as described
1294 in their descriptions above.
1295 5. Function tracing is enabled: command substitu‐
1296 tion, shell functions, and subshells invoked with
1297 ( command ) inherit the DEBUG and RETURN traps.
1298 6. Error tracing is enabled: command substitution,
1299 shell functions, and subshells invoked with (
1300 command ) inherit the ERR trap.
1301 extglob If set, the extended pattern matching features described
1302 above under Pathname Expansion are enabled.
1303 extquote
1304 If set, $'string' and $"string" quoting is performed
1305 within ${parameter} expansions enclosed in double
1306 quotes. This option is enabled by default.
1307 failglob
1308 If set, patterns which fail to match filenames during
1309 pathname expansion result in an expansion error.
1310 force_fignore
1311 If set, the suffixes specified by the FIGNORE shell
1312 variable cause words to be ignored when performing word
1313 completion even if the ignored words are the only possi‐
1314 ble completions. See SHELL VARIABLES above for a
1315 description of FIGNORE. This option is enabled by
1316 default.
1317 globstar
1318 If set, the pattern ** used in a pathname expansion con‐
1319 text will match all files and zero or more directories
1320 and subdirectories. If the pattern is followed by a /,
1321 only directories and subdirectories match.
1322 gnu_errfmt
1323 If set, shell error messages are written in the standard
1324 GNU error message format.
1325 histappend
1326 If set, the history list is appended to the file named
1327 by the value of the HISTFILE variable when the shell
1328 exits, rather than overwriting the file.
1329 histreedit
1330 If set, and readline is being used, a user is given the
1331 opportunity to re-edit a failed history substitution.
1332 histverify
1333 If set, and readline is being used, the results of his‐
1334 tory substitution are not immediately passed to the
1335 shell parser. Instead, the resulting line is loaded
1336 into the readline editing buffer, allowing further modi‐
1337 fication.
1338 hostcomplete
1339 If set, and readline is being used, bash will attempt to
1340 perform hostname completion when a word containing a @
1341 is being completed (see Completing under READLINE
1342 above). This is enabled by default.
1343 huponexit
1344 If set, bash will send SIGHUP to all jobs when an inter‐
1345 active login shell exits.
1346 interactive_comments
1347 If set, allow a word beginning with # to cause that word
1348 and all remaining characters on that line to be ignored
1349 in an interactive shell (see COMMENTS above). This
1350 option is enabled by default.
1351 lastpipe
1352 If set, and job control is not active, the shell runs
1353 the last command of a pipeline not executed in the back‐
1354 ground in the current shell environment.
1355 lithist If set, and the cmdhist option is enabled, multi-line
1356 commands are saved to the history with embedded newlines
1357 rather than using semicolon separators where possible.
1358 login_shell
1359 The shell sets this option if it is started as a login
1360 shell (see INVOCATION above). The value may not be
1361 changed.
1362 mailwarn
1363 If set, and a file that bash is checking for mail has
1364 been accessed since the last time it was checked, the
1365 message ``The mail in mailfile has been read'' is dis‐
1366 played.
1367 no_empty_cmd_completion
1368 If set, and readline is being used, bash will not
1369 attempt to search the PATH for possible completions when
1370 completion is attempted on an empty line.
1371 nocaseglob
1372 If set, bash matches filenames in a case-insensitive
1373 fashion when performing pathname expansion (see Pathname
1374 Expansion above).
1375 nocasematch
1376 If set, bash matches patterns in a case-insensitive
1377 fashion when performing matching while executing case or
1378 [[ conditional commands.
1379 nullglob
1380 If set, bash allows patterns which match no files (see
1381 Pathname Expansion above) to expand to a null string,
1382 rather than themselves.
1383 progcomp
1384 If set, the programmable completion facilities (see Pro‐
1385 grammable Completion above) are enabled. This option is
1386 enabled by default.
1387 promptvars
1388 If set, prompt strings undergo parameter expansion, com‐
1389 mand substitution, arithmetic expansion, and quote
1390 removal after being expanded as described in PROMPTING
1391 above. This option is enabled by default.
1392 restricted_shell
1393 The shell sets this option if it is started in
1394 restricted mode (see RESTRICTED SHELL below). The value
1395 may not be changed. This is not reset when the startup
1396 files are executed, allowing the startup files to dis‐
1397 cover whether or not a shell is restricted.
1398 shift_verbose
1399 If set, the shift builtin prints an error message when
1400 the shift count exceeds the number of positional parame‐
1401 ters.
1402 sourcepath
1403 If set, the source (.) builtin uses the value of PATH to
1404 find the directory containing the file supplied as an
1405 argument. This option is enabled by default.
1406 xpg_echo
1407 If set, the echo builtin expands backslash-escape
1408 sequences by default.
1409 suspend [-f]
1411 Suspend the execution of this shell until it receives a SIGCONT
1412 signal. When the suspended shell is a background process, it can
1413 be restarted by the fg command. For more information, read the
1414 JOB CONTROL section. The suspend command can not suspend the
1415 login shell. However, when -f option is specified, suspend com‐
1416 mand can suspend even login shell. The return status is 0
1417 unless the shell is a login shell and -f is not supplied, or if
1418 job control is not enabled.
1419 test expr
1421 [ expr ]
1422 Return a status of 0 or 1 depending on the evaluation of the
1423 conditional expression expr. Each operator and operand must be
1424 a separate argument. Expressions are composed of the primaries
1425 described above under CONDITIONAL EXPRESSIONS. test does not
1426 accept any options, nor does it accept and ignore an argument of
1427 -- as signifying the end of options.
1428 Expressions may be combined using the following operators,
1430 listed in decreasing order of precedence. The evaluation
1431 depends on the number of arguments; see below. Operator prece‐
1432 dence is used when there are five or more arguments.
1433 ! expr True if expr is false.
1434 ( expr )
1435 Returns the value of expr. This may be used to override
1436 the normal precedence of operators.
1437 expr1 -a expr2
1438 True if both expr1 and expr2 are true.
1439 expr1 -o expr2
1440 True if either expr1 or expr2 is true.
1441 test and [ evaluate conditional expressions using a set of rules
1443 based on the number of arguments.
1444 0 arguments
1446 The expression is false.
1447 1 argument
1448 The expression is true if and only if the argument is not
1449 null.
1450 2 arguments
1451 If the first argument is !, the expression is true if and
1452 only if the second argument is null. If the first argu‐
1453 ment is one of the unary conditional operators listed
1454 above under CONDITIONAL EXPRESSIONS, the expression is
1455 true if the unary test is true. If the first argument is
1456 not a valid unary conditional operator, the expression is
1457 false.
1458 3 arguments
1459 The following conditions are applied in the order listed.
1460 If the second argument is one of the binary conditional
1461 operators listed above under CONDITIONAL EXPRESSIONS, the
1462 result of the expression is the result of the binary test
1463 using the first and third arguments as operands. The -a
1464 and -o operators are considered binary operators when
1465 there are three arguments. If the first argument is !,
1466 the value is the negation of the two-argument test using
1467 the second and third arguments. If the first argument is
1468 exactly ( and the third argument is exactly ), the result
1469 is the one-argument test of the second argument. Other‐
1470 wise, the expression is false.
1471 4 arguments
1472 If the first argument is !, the result is the negation of
1473 the three-argument expression composed of the remaining
1474 arguments. Otherwise, the expression is parsed and eval‐
1475 uated according to precedence using the rules listed
1476 above.
1477 5 or more arguments
1478 The expression is parsed and evaluated according to
1479 precedence using the rules listed above.
1480 When used with test or [, the < and > operators sort lexico‐
1482 graphically using ASCII ordering.
1483 times Print the accumulated user and system times for the shell and
1485 for processes run from the shell. The return status is 0.
1486 trap [-lp] [[arg] sigspec ...]
1488 The command arg is to be read and executed when the shell
1489 receives signal(s) sigspec. If arg is absent (and there is a
1490 single sigspec) or -, each specified signal is reset to its
1491 original disposition (the value it had upon entrance to the
1492 shell). If arg is the null string the signal specified by each
1493 sigspec is ignored by the shell and by the commands it invokes.
1494 If arg is not present and -p has been supplied, then the trap
1495 commands associated with each sigspec are displayed. If no
1496 arguments are supplied or if only -p is given, trap prints the
1497 list of commands associated with each signal. The -l option
1498 causes the shell to print a list of signal names and their cor‐
1499 responding numbers. Each sigspec is either a signal name
1500 defined in <signal.h>, or a signal number. Signal names are
1501 case insensitive and the SIG prefix is optional.
1502 If a sigspec is EXIT (0) the command arg is executed on exit
1504 from the shell. If a sigspec is DEBUG, the command arg is exe‐
1505 cuted before every simple command, for command, case command,
1506 select command, every arithmetic for command, and before the
1507 first command executes in a shell function (see SHELL GRAMMAR
1508 above). Refer to the description of the extdebug option to the
1509 shopt builtin for details of its effect on the DEBUG trap. If a
1510 sigspec is RETURN, the command arg is executed each time a shell
1511 function or a script executed with the . or source builtins fin‐
1512 ishes executing.
1513 If a sigspec is ERR, the command arg is executed whenever a sim‐
1515 ple command has a non-zero exit status, subject to the following
1516 conditions. The ERR trap is not executed if the failed command
1517 is part of the command list immediately following a while or
1518 until keyword, part of the test in an if statement, part of a
1519 command executed in a && or || list, or if the command's return
1520 value is being inverted via !. These are the same conditions
1521 obeyed by the errexit option.
1522 Signals ignored upon entry to the shell cannot be trapped, reset
1524 or listed. Trapped signals that are not being ignored are reset
1525 to their original values in a subshell or subshell environment
1526 when one is created. The return status is false if any sigspec
1527 is invalid; otherwise trap returns true.
1528 type [-aftpP] name [name ...]
1530 With no options, indicate how each name would be interpreted if
1531 used as a command name. If the -t option is used, type prints a
1532 string which is one of alias, keyword, function, builtin, or
1533 file if name is an alias, shell reserved word, function,
1534 builtin, or disk file, respectively. If the name is not found,
1535 then nothing is printed, and an exit status of false is
1536 returned. If the -p option is used, type either returns the
1537 name of the disk file that would be executed if name were speci‐
1538 fied as a command name, or nothing if ``type -t name'' would not
1539 return file. The -P option forces a PATH search for each name,
1540 even if ``type -t name'' would not return file. If a command is
1541 hashed, -p and -P print the hashed value, not necessarily the
1542 file that appears first in PATH. If the -a option is used, type
1543 prints all of the places that contain an executable named name.
1544 This includes aliases and functions, if and only if the -p
1545 option is not also used. The table of hashed commands is not
1546 consulted when using -a. The -f option suppresses shell func‐
1547 tion lookup, as with the command builtin. type returns true if
1548 all of the arguments are found, false if any are not found.
1549 ulimit [-HSTabcdefilmnpqrstuvx [limit]]
1551 Provides control over the resources available to the shell and
1552 to processes started by it, on systems that allow such control.
1553 The -H and -S options specify that the hard or soft limit is set
1554 for the given resource. A hard limit cannot be increased by a
1555 non-root user once it is set; a soft limit may be increased up
1556 to the value of the hard limit. If neither -H nor -S is speci‐
1557 fied, both the soft and hard limits are set. The value of limit
1558 can be a number in the unit specified for the resource or one of
1559 the special values hard, soft, or unlimited, which stand for the
1560 current hard limit, the current soft limit, and no limit,
1561 respectively. If limit is omitted, the current value of the
1562 soft limit of the resource is printed, unless the -H option is
1563 given. When more than one resource is specified, the limit name
1564 and unit are printed before the value. Other options are inter‐
1565 preted as follows:
1566 -a All current limits are reported
1567 -b The maximum socket buffer size
1568 -c The maximum size of core files created
1569 -d The maximum size of a process's data segment
1570 -e The maximum scheduling priority ("nice")
1571 -f The maximum size of files written by the shell and its
1572 children
1573 -i The maximum number of pending signals
1574 -l The maximum size that may be locked into memory
1575 -m The maximum resident set size (many systems do not honor
1576 this limit)
1577 -n The maximum number of open file descriptors (most systems
1578 do not allow this value to be set)
1579 -p The pipe size in 512-byte blocks (this may not be set)
1580 -q The maximum number of bytes in POSIX message queues
1581 -r The maximum real-time scheduling priority
1582 -s The maximum stack size
1583 -t The maximum amount of cpu time in seconds
1584 -u The maximum number of processes available to a single
1585 user
1586 -v The maximum amount of virtual memory available to the
1587 shell and, on some systems, to its children
1588 -x The maximum number of file locks
1589 -T The maximum number of threads
1590 If limit is given, it is the new value of the specified resource
1592 (the -a option is display only). If no option is given, then -f
1593 is assumed. Values are in 1024-byte increments, except for -t,
1594 which is in seconds, -p, which is in units of 512-byte blocks,
1595 and -T, -b, -n, and -u, which are unscaled values. The return
1596 status is 0 unless an invalid option or argument is supplied, or
1597 an error occurs while setting a new limit. In POSIX Mode
1598 512-byte blocks are used for the `-c' and `-f' options.
1599 umask [-p] [-S] [mode]
1601 The user file-creation mask is set to mode. If mode begins with
1602 a digit, it is interpreted as an octal number; otherwise it is
1603 interpreted as a symbolic mode mask similar to that accepted by
1604 chmod(1). If mode is omitted, the current value of the mask is
1605 printed. The -S option causes the mask to be printed in sym‐
1606 bolic form; the default output is an octal number. If the -p
1607 option is supplied, and mode is omitted, the output is in a form
1608 that may be reused as input. The return status is 0 if the mode
1609 was successfully changed or if no mode argument was supplied,
1610 and false otherwise.
1611 unalias [-a] [name ...]
1613 Remove each name from the list of defined aliases. If -a is
1614 supplied, all alias definitions are removed. The return value
1615 is true unless a supplied name is not a defined alias.
1616 unset [-fv] [name ...]
1618 For each name, remove the corresponding variable or function.
1619 If no options are supplied, or the -v option is given, each name
1620 refers to a shell variable. Read-only variables may not be
1621 unset. If -f is specified, each name refers to a shell func‐
1622 tion, and the function definition is removed. Each unset vari‐
1623 able or function is removed from the environment passed to sub‐
1624 sequent commands. If any of COMP_WORDBREAKS, RANDOM, SECONDS,
1625 LINENO, HISTCMD, FUNCNAME, GROUPS, or DIRSTACK are unset, they
1626 lose their special properties, even if they are subsequently
1627 reset. The exit status is true unless a name is readonly.
1628 wait [n ...]
1630 Wait for each specified process and return its termination sta‐
1631 tus. Each n may be a process ID or a job specification; if a
1632 job spec is given, all processes in that job's pipeline are
1633 waited for. If n is not given, all currently active child pro‐
1634 cesses are waited for, and the return status is zero. If n
1635 specifies a non-existent process or job, the return status is
1636 127. Otherwise, the return status is the exit status of the
1637 last process or job waited for.
1638
1640 bash(1), sh(1)
1641GNU Bash-4.0 2004 Apr 20 BASH_BUILTINS(1)