]>
Commit | Line | Data |
---|---|---|
0628567a | 1 | .\" |
726f6388 JA |
2 | .\" MAN PAGE COMMENTS to |
3 | .\" | |
4 | .\" Chet Ramey | |
726f6388 | 5 | .\" Case Western Reserve University |
ac50fbac | 6 | .\" chet.ramey@case.edu |
726f6388 | 7 | .\" |
f250956c | 8 | .\" Last Change: Fri Dec 7 09:48:47 EST 2018 |
726f6388 JA |
9 | .\" |
10 | .\" bash_builtins, strip all but Built-Ins section | |
11 | .if \n(zZ=1 .ig zZ | |
bb70624e | 12 | .if \n(zY=1 .ig zY |
f250956c | 13 | .TH BASH 1 "2018 December 7" "GNU Bash 5.0" |
726f6388 JA |
14 | .\" |
15 | .\" There's some problem with having a `@' | |
16 | .\" in a tagged paragraph with the BSD man macros. | |
17 | .\" It has to do with `@' appearing in the }1 macro. | |
18 | .\" This is a problem on 4.3 BSD and Ultrix, but Sun | |
19 | .\" appears to have fixed it. | |
20 | .\" If you're seeing the characters | |
21 | .\" `@u-3p' appearing before the lines reading | |
22 | .\" `possible-hostname-completions | |
23 | .\" and `complete-hostname' down in READLINE, | |
24 | .\" then uncomment this redefinition. | |
25 | .\" | |
26 | .de }1 | |
27 | .ds ]X \&\\*(]B\\ | |
28 | .nr )E 0 | |
29 | .if !"\\$1"" .nr )I \\$1n | |
30 | .}f | |
31 | .ll \\n(LLu | |
32 | .in \\n()Ru+\\n(INu+\\n()Iu | |
33 | .ti \\n(INu | |
34 | .ie !\\n()Iu+\\n()Ru-\w\a\\*(]X\au-3p \{\\*(]X | |
35 | .br\} | |
36 | .el \\*(]X\h\a|\\n()Iu+\\n()Ru\a\c | |
37 | .}f | |
38 | .. | |
39 | .\" | |
40 | .\" File Name macro. This used to be `.PN', for Path Name, | |
41 | .\" but Sun doesn't seem to like that very much. | |
42 | .\" | |
43 | .de FN | |
44 | \fI\|\\$1\|\fP | |
45 | .. | |
46 | .SH NAME | |
ccc6cda3 | 47 | bash \- GNU Bourne-Again SHell |
726f6388 JA |
48 | .SH SYNOPSIS |
49 | .B bash | |
50 | [options] | |
ac50fbac | 51 | [command_string | file] |
726f6388 | 52 | .SH COPYRIGHT |
9a51695b CR |
53 | .if n Bash is Copyright (C) 1989-2018 by the Free Software Foundation, Inc. |
54 | .if t Bash is Copyright \(co 1989-2018 by the Free Software Foundation, Inc. | |
726f6388 JA |
55 | .SH DESCRIPTION |
56 | .B Bash | |
ccc6cda3 | 57 | is an \fBsh\fR-compatible command language interpreter that |
726f6388 JA |
58 | executes commands read from the standard input or from a file. |
59 | .B Bash | |
60 | also incorporates useful features from the \fIKorn\fP and \fIC\fP | |
61 | shells (\fBksh\fP and \fBcsh\fP). | |
62 | .PP | |
63 | .B Bash | |
0628567a JA |
64 | is intended to be a conformant implementation of the |
65 | Shell and Utilities portion of the IEEE POSIX specification | |
66 | (IEEE Standard 1003.1). | |
95732b49 JA |
67 | .B Bash |
68 | can be configured to be POSIX-conformant by default. | |
726f6388 | 69 | .SH OPTIONS |
a0c0a00f | 70 | All of the single-character shell options documented in the |
9a51695b CR |
71 | description of the \fBset\fR builtin command, including \fB\-o\fP, |
72 | can be used as options when the shell is invoked. | |
495aee44 | 73 | In addition, \fBbash\fR |
cce855bc | 74 | interprets the following options when it is invoked: |
726f6388 JA |
75 | .PP |
76 | .PD 0 | |
77 | .TP 10 | |
ac50fbac | 78 | .B \-c |
ccc6cda3 | 79 | If the |
726f6388 | 80 | .B \-c |
ac50fbac CR |
81 | option is present, then commands are read from the first non-option argument |
82 | .IR command_string . | |
726f6388 | 83 | If there are arguments after the |
ac50fbac | 84 | .IR command_string , |
a0c0a00f CR |
85 | the first argument is assigned to |
86 | .B $0 | |
87 | and any remaining arguments are assigned to the positional parameters. | |
88 | The assignment to | |
89 | .B $0 | |
90 | sets the name of the shell, which is used in warning and error messages. | |
726f6388 | 91 | .TP |
7117c2d2 JA |
92 | .B \-i |
93 | If the | |
94 | .B \-i | |
95 | option is present, the shell is | |
96 | .IR interactive . | |
97 | .TP | |
98 | .B \-l | |
99 | Make | |
100 | .B bash | |
101 | act as if it had been invoked as a login shell (see | |
102 | .SM | |
103 | .B INVOCATION | |
104 | below). | |
105 | .TP | |
ccc6cda3 JA |
106 | .B \-r |
107 | If the | |
108 | .B \-r | |
cce855bc | 109 | option is present, the shell becomes |
ccc6cda3 JA |
110 | .I restricted |
111 | (see | |
112 | .SM | |
113 | .B "RESTRICTED SHELL" | |
114 | below). | |
115 | .TP | |
726f6388 JA |
116 | .B \-s |
117 | If the | |
118 | .B \-s | |
cce855bc | 119 | option is present, or if no arguments remain after option |
726f6388 JA |
120 | processing, then commands are read from the standard input. |
121 | This option allows the positional parameters to be set | |
9a51695b CR |
122 | when invoking an interactive shell or when reading input |
123 | through a pipe. | |
726f6388 | 124 | .TP |
ccc6cda3 JA |
125 | .B \-D |
126 | A list of all double-quoted strings preceded by \fB$\fP | |
95732b49 | 127 | is printed on the standard output. |
ccc6cda3 JA |
128 | These are the strings that |
129 | are subject to language translation when the current locale | |
28ef6c31 | 130 | is not \fBC\fP or \fBPOSIX\fP. |
ccc6cda3 JA |
131 | This implies the \fB\-n\fP option; no commands will be executed. |
132 | .TP | |
f73dda09 JA |
133 | .B [\-+]O [\fIshopt_option\fP] |
134 | \fIshopt_option\fP is one of the shell options accepted by the | |
135 | \fBshopt\fP builtin (see | |
136 | .SM | |
137 | .B SHELL BUILTIN COMMANDS | |
138 | below). | |
139 | If \fIshopt_option\fP is present, \fB\-O\fP sets the value of that option; | |
140 | \fB+O\fP unsets it. | |
141 | If \fIshopt_option\fP is not supplied, the names and values of the shell | |
142 | options accepted by \fBshopt\fP are printed on the standard output. | |
143 | If the invocation option is \fB+O\fP, the output is displayed in a format | |
144 | that may be reused as input. | |
145 | .TP | |
ccc6cda3 JA |
146 | .B \-\- |
147 | A | |
148 | .B \-\- | |
726f6388 JA |
149 | signals the end of options and disables further option processing. |
150 | Any arguments after the | |
726f6388 | 151 | .B \-\- |
ccc6cda3 JA |
152 | are treated as filenames and arguments. An argument of |
153 | .B \- | |
154 | is equivalent to \fB\-\-\fP. | |
726f6388 JA |
155 | .PD |
156 | .PP | |
157 | .B Bash | |
ccc6cda3 JA |
158 | also interprets a number of multi-character options. |
159 | These options must appear on the command line before the | |
7117c2d2 | 160 | single-character options to be recognized. |
726f6388 JA |
161 | .PP |
162 | .PD 0 | |
726f6388 | 163 | .TP |
b80f6443 JA |
164 | .B \-\-debugger |
165 | Arrange for the debugger profile to be executed before the shell | |
95732b49 JA |
166 | starts. |
167 | Turns on extended debugging mode (see the description of the | |
b80f6443 JA |
168 | .B extdebug |
169 | option to the | |
170 | .B shopt | |
b80f6443 JA |
171 | builtin below). |
172 | .TP | |
cce855bc JA |
173 | .B \-\-dump\-po\-strings |
174 | Equivalent to \fB\-D\fP, but the output is in the GNU \fIgettext\fP | |
175 | \fBpo\fP (portable object) file format. | |
176 | .TP | |
ccc6cda3 JA |
177 | .B \-\-dump\-strings |
178 | Equivalent to \fB\-D\fP. | |
179 | .TP | |
180 | .B \-\-help | |
181 | Display a usage message on standard output and exit successfully. | |
182 | .TP | |
28ef6c31 | 183 | \fB\-\-init\-file\fP \fIfile\fP |
7117c2d2 | 184 | .PD 0 |
28ef6c31 JA |
185 | .TP |
186 | \fB\-\-rcfile\fP \fIfile\fP | |
187 | .PD | |
188 | Execute commands from | |
189 | .I file | |
190 | instead of the standard personal initialization file | |
191 | .I ~/.bashrc | |
192 | if the shell is interactive (see | |
193 | .SM | |
194 | .B INVOCATION | |
195 | below). | |
196 | .TP | |
ccc6cda3 | 197 | .B \-\-login |
7117c2d2 | 198 | Equivalent to \fB\-l\fP. |
ccc6cda3 JA |
199 | .TP |
200 | .B \-\-noediting | |
201 | Do not use the GNU | |
202 | .B readline | |
bb70624e | 203 | library to read command lines when the shell is interactive. |
ccc6cda3 JA |
204 | .TP |
205 | .B \-\-noprofile | |
206 | Do not read either the system-wide startup file | |
726f6388 JA |
207 | .FN /etc/profile |
208 | or any of the personal initialization files | |
209 | .IR ~/.bash_profile , | |
210 | .IR ~/.bash_login , | |
211 | or | |
212 | .IR ~/.profile . | |
213 | By default, | |
214 | .B bash | |
ccc6cda3 | 215 | reads these files when it is invoked as a login shell (see |
726f6388 JA |
216 | .SM |
217 | .B INVOCATION | |
218 | below). | |
219 | .TP | |
ccc6cda3 JA |
220 | .B \-\-norc |
221 | Do not read and execute the personal initialization file | |
222 | .I ~/.bashrc | |
223 | if the shell is interactive. | |
224 | This option is on by default if the shell is invoked as | |
225 | .BR sh . | |
226 | .TP | |
227 | .B \-\-posix | |
228 | Change the behavior of \fBbash\fP where the default operation differs | |
0628567a | 229 | from the POSIX standard to match the standard (\fIposix mode\fP). |
ac50fbac CR |
230 | See |
231 | .SM | |
232 | .B "SEE ALSO" | |
233 | below for a reference to a document that details how posix mode affects | |
234 | bash's behavior. | |
726f6388 | 235 | .TP |
ccc6cda3 JA |
236 | .B \-\-restricted |
237 | The shell becomes restricted (see | |
238 | .SM | |
239 | .B "RESTRICTED SHELL" | |
726f6388 JA |
240 | below). |
241 | .TP | |
ccc6cda3 | 242 | .B \-\-verbose |
a0c0a00f | 243 | Equivalent to \fB\-v\fP. |
726f6388 | 244 | .TP |
ccc6cda3 JA |
245 | .B \-\-version |
246 | Show version information for this instance of | |
247 | .B bash | |
248 | on the standard output and exit successfully. | |
726f6388 JA |
249 | .PD |
250 | .SH ARGUMENTS | |
251 | If arguments remain after option processing, and neither the | |
252 | .B \-c | |
253 | nor the | |
254 | .B \-s | |
255 | option has been supplied, the first argument is assumed to | |
ccc6cda3 JA |
256 | be the name of a file containing shell commands. |
257 | If | |
726f6388 | 258 | .B bash |
a0c0a00f | 259 | is invoked in this fashion, |
726f6388 JA |
260 | .B $0 |
261 | is set to the name of the file, and the positional parameters | |
262 | are set to the remaining arguments. | |
263 | .B Bash | |
264 | reads and executes commands from this file, then exits. | |
ccc6cda3 JA |
265 | \fBBash\fP's exit status is the exit status of the last command |
266 | executed in the script. | |
267 | If no commands are executed, the exit status is 0. | |
f73dda09 JA |
268 | An attempt is first made to open the file in the current directory, and, |
269 | if no file is found, then the shell searches the directories in | |
270 | .SM | |
271 | .B PATH | |
272 | for the script. | |
ccc6cda3 JA |
273 | .SH INVOCATION |
274 | A \fIlogin shell\fP is one whose first character of argument zero is a | |
275 | .BR \- , | |
a0c0a00f | 276 | or one started with the |
ccc6cda3 JA |
277 | .B \-\-login |
278 | option. | |
279 | .PP | |
bb70624e | 280 | An \fIinteractive\fP shell is one started without non-option arguments |
a0c0a00f | 281 | (unless \fB\-s\fP is specified) |
bb70624e JA |
282 | and without the |
283 | .B \-c | |
284 | option | |
b80f6443 | 285 | whose standard input and error are |
ccc6cda3 JA |
286 | both connected to terminals (as determined by |
287 | .IR isatty (3)), | |
288 | or one started with the | |
289 | .B \-i | |
290 | option. | |
291 | .SM | |
292 | .B PS1 | |
293 | is set and | |
294 | .B $\- | |
295 | includes | |
296 | .B i | |
297 | if | |
298 | .B bash | |
299 | is interactive, | |
300 | allowing a shell script or a startup file to test this state. | |
301 | .PP | |
302 | The following paragraphs describe how | |
303 | .B bash | |
304 | executes its startup files. | |
305 | If any of the files exist but cannot be read, | |
306 | .B bash | |
307 | reports an error. | |
ac50fbac | 308 | Tildes are expanded in filenames as described below under |
ccc6cda3 JA |
309 | .B "Tilde Expansion" |
310 | in the | |
311 | .SM | |
312 | .B EXPANSION | |
313 | section. | |
314 | .PP | |
315 | When | |
316 | .B bash | |
b72432fd JA |
317 | is invoked as an interactive login shell, or as a non-interactive shell |
318 | with the \fB\-\-login\fP option, it first reads and | |
d166f048 JA |
319 | executes commands from the file \fI/etc/profile\fP, if that |
320 | file exists. | |
ccc6cda3 JA |
321 | After reading that file, it looks for \fI~/.bash_profile\fP, |
322 | \fI~/.bash_login\fP, and \fI~/.profile\fP, in that order, and reads | |
323 | and executes commands from the first one that exists and is readable. | |
324 | The | |
325 | .B \-\-noprofile | |
326 | option may be used when the shell is started to inhibit this behavior. | |
327 | .PP | |
a0c0a00f CR |
328 | When an interactive login shell exits, |
329 | or a non-interactive login shell executes the \fBexit\fP builtin command, | |
ccc6cda3 JA |
330 | .B bash |
331 | reads and executes commands from the file \fI~/.bash_logout\fP, if it | |
332 | exists. | |
333 | .PP | |
334 | When an interactive shell that is not a login shell is started, | |
335 | .B bash | |
336 | reads and executes commands from \fI~/.bashrc\fP, if that file exists. | |
337 | This may be inhibited by using the | |
338 | .B \-\-norc | |
339 | option. | |
340 | The \fB\-\-rcfile\fP \fIfile\fP option will force | |
341 | .B bash | |
342 | to read and execute commands from \fIfile\fP instead of \fI~/.bashrc\fP. | |
343 | .PP | |
344 | When | |
345 | .B bash | |
346 | is started non-interactively, to run a shell script, for example, it | |
347 | looks for the variable | |
348 | .SM | |
349 | .B BASH_ENV | |
350 | in the environment, expands its value if it appears there, and uses the | |
351 | expanded value as the name of a file to read and execute. | |
352 | .B Bash | |
353 | behaves as if the following command were executed: | |
354 | .sp .5 | |
355 | .RS | |
28ef6c31 JA |
356 | .if t \f(CWif [ \-n "$BASH_ENV" ]; then . "$BASH_ENV"; fi\fP |
357 | .if n if [ \-n "$BASH_ENV" ]; then . "$BASH_ENV"; fi | |
ccc6cda3 JA |
358 | .RE |
359 | .sp .5 | |
360 | but the value of the | |
361 | .SM | |
362 | .B PATH | |
ac50fbac | 363 | variable is not used to search for the filename. |
ccc6cda3 JA |
364 | .PP |
365 | If | |
366 | .B bash | |
367 | is invoked with the name | |
368 | .BR sh , | |
369 | it tries to mimic the startup behavior of historical versions of | |
370 | .B sh | |
371 | as closely as possible, | |
372 | while conforming to the POSIX standard as well. | |
b72432fd JA |
373 | When invoked as an interactive login shell, or a non-interactive |
374 | shell with the \fB\-\-login\fP option, it first attempts to | |
cce855bc | 375 | read and execute commands from |
ccc6cda3 JA |
376 | .I /etc/profile |
377 | and | |
378 | .IR ~/.profile , | |
379 | in that order. | |
380 | The | |
381 | .B \-\-noprofile | |
382 | option may be used to inhibit this behavior. | |
383 | When invoked as an interactive shell with the name | |
384 | .BR sh , | |
385 | .B bash | |
386 | looks for the variable | |
387 | .SM | |
388 | .BR ENV , | |
389 | expands its value if it is defined, and uses the | |
390 | expanded value as the name of a file to read and execute. | |
391 | Since a shell invoked as | |
392 | .B sh | |
393 | does not attempt to read and execute commands from any other startup | |
394 | files, the | |
395 | .B \-\-rcfile | |
396 | option has no effect. | |
397 | A non-interactive shell invoked with the name | |
398 | .B sh | |
b72432fd | 399 | does not attempt to read any other startup files. |
ccc6cda3 JA |
400 | When invoked as |
401 | .BR sh , | |
402 | .B bash | |
403 | enters | |
404 | .I posix | |
405 | mode after the startup files are read. | |
406 | .PP | |
407 | When | |
408 | .B bash | |
409 | is started in | |
410 | .I posix | |
411 | mode, as with the | |
412 | .B \-\-posix | |
413 | command line option, it follows the POSIX standard for startup files. | |
cce855bc | 414 | In this mode, interactive shells expand the |
ccc6cda3 JA |
415 | .SM |
416 | .B ENV | |
cce855bc | 417 | variable and commands are read and executed from the file |
ccc6cda3 JA |
418 | whose name is the expanded value. |
419 | No other startup files are read. | |
ccc6cda3 JA |
420 | .PP |
421 | .B Bash | |
3185942a | 422 | attempts to determine when it is being run with its standard input |
495aee44 | 423 | connected to a network connection, as when executed by the remote shell |
3185942a | 424 | daemon, usually \fIrshd\fP, or the secure shell daemon \fIsshd\fP. |
ccc6cda3 JA |
425 | If |
426 | .B bash | |
3185942a | 427 | determines it is being run in this fashion, it reads and executes |
ccc6cda3 JA |
428 | commands from \fI~/.bashrc\fP, if that file exists and is readable. |
429 | It will not do this if invoked as \fBsh\fP. | |
430 | The | |
431 | .B \-\-norc | |
432 | option may be used to inhibit this behavior, and the | |
433 | .B \-\-rcfile | |
ac50fbac CR |
434 | option may be used to force another file to be read, but neither |
435 | \fIrshd\fP nor \fIsshd\fP generally invoke the shell with those options | |
ccc6cda3 | 436 | or allow them to be specified. |
b72432fd JA |
437 | .PP |
438 | If the shell is started with the effective user (group) id not equal to the | |
439 | real user (group) id, and the \fB\-p\fP option is not supplied, no startup | |
f73dda09 JA |
440 | files are read, shell functions are not inherited from the environment, the |
441 | .SM | |
0001803f CR |
442 | .BR SHELLOPTS , |
443 | .SM | |
444 | .BR BASHOPTS , | |
445 | .SM | |
446 | .BR CDPATH , | |
447 | and | |
448 | .SM | |
449 | .B GLOBIGNORE | |
450 | variables, if they appear in the environment, are ignored, | |
b72432fd JA |
451 | and the effective user id is set to the real user id. |
452 | If the \fB\-p\fP option is supplied at invocation, the startup behavior is | |
453 | the same, but the effective user id is not reset. | |
726f6388 | 454 | .SH DEFINITIONS |
ccc6cda3 JA |
455 | .PP |
456 | The following definitions are used throughout the rest of this | |
457 | document. | |
726f6388 JA |
458 | .PD 0 |
459 | .TP | |
a0c0a00f | 460 | .B blank |
726f6388 JA |
461 | A space or tab. |
462 | .TP | |
463 | .B word | |
464 | A sequence of characters considered as a single unit by the shell. | |
465 | Also known as a | |
466 | .BR token . | |
467 | .TP | |
468 | .B name | |
a0c0a00f | 469 | A |
726f6388 JA |
470 | .I word |
471 | consisting only of alphanumeric characters and underscores, and | |
472 | beginning with an alphabetic character or an underscore. Also | |
473 | referred to as an | |
474 | .BR identifier . | |
475 | .TP | |
476 | .B metacharacter | |
477 | A character that, when unquoted, separates words. One of the following: | |
478 | .br | |
479 | .RS | |
480 | .PP | |
a0c0a00f CR |
481 | .if t \fB| & ; ( ) < > space tab newline\fP |
482 | .if n \fB| & ; ( ) < > space tab newline\fP | |
726f6388 JA |
483 | .RE |
484 | .PP | |
485 | .TP | |
486 | .B control operator | |
487 | A \fItoken\fP that performs a control function. It is one of the following | |
488 | symbols: | |
489 | .RS | |
490 | .PP | |
a0c0a00f CR |
491 | .if t \fB|| & && ; ;; ;& ;;& ( ) | |& <newline>\fP |
492 | .if n \fB|| & && ; ;; ;& ;;& ( ) | |& <newline>\fP | |
726f6388 JA |
493 | .RE |
494 | .PD | |
495 | .SH "RESERVED WORDS" | |
496 | \fIReserved words\fP are words that have a special meaning to the shell. | |
497 | The following words are recognized as reserved when unquoted and either | |
498 | the first word of a simple command (see | |
499 | .SM | |
500 | .B SHELL GRAMMAR | |
a0c0a00f CR |
501 | below) or the third word of a |
502 | .B case | |
726f6388 JA |
503 | or |
504 | .B for | |
505 | command: | |
506 | .if t .RS | |
507 | .PP | |
508 | .B | |
ac50fbac CR |
509 | .if n ! case coproc do done elif else esac fi for function if in select then until while { } time [[ ]] |
510 | .if t ! case coproc do done elif else esac fi for function if in select then until while { } time [[ ]] | |
726f6388 | 511 | .if t .RE |
726f6388 JA |
512 | .SH "SHELL GRAMMAR" |
513 | .SS Simple Commands | |
514 | .PP | |
515 | A \fIsimple command\fP is a sequence of optional variable assignments | |
ccc6cda3 | 516 | followed by \fBblank\fP-separated words and redirections, and |
726f6388 | 517 | terminated by a \fIcontrol operator\fP. The first word |
f73dda09 JA |
518 | specifies the command to be executed, and is passed as argument zero. |
519 | The remaining words are passed as arguments to the invoked command. | |
726f6388 JA |
520 | .PP |
521 | The return value of a \fIsimple command\fP is its exit status, or | |
522 | 128+\fIn\^\fP if the command is terminated by signal | |
523 | .IR n . | |
524 | .SS Pipelines | |
525 | .PP | |
526 | A \fIpipeline\fP is a sequence of one or more commands separated by | |
3185942a JA |
527 | one of the control operators |
528 | .B | | |
529 | or \fB|&\fP. | |
726f6388 JA |
530 | The format for a pipeline is: |
531 | .RS | |
532 | .PP | |
3185942a | 533 | [\fBtime\fP [\fB\-p\fP]] [ ! ] \fIcommand\fP [ [\fB|\fP\(bv\fB|&\fP] \fIcommand2\fP ... ] |
726f6388 JA |
534 | .RE |
535 | .PP | |
536 | The standard output of | |
537 | .I command | |
f73dda09 | 538 | is connected via a pipe to the standard input of |
726f6388 JA |
539 | .IR command2 . |
540 | This connection is performed before any redirections specified by the | |
541 | command (see | |
542 | .SM | |
543 | .B REDIRECTION | |
544 | below). | |
ac50fbac CR |
545 | If \fB|&\fP is used, \fIcommand\fP's standard error, in addition to its |
546 | standard output, is connected to | |
547 | \fIcommand2\fP's standard input through the pipe; | |
548 | it is shorthand for \fB2>&1 |\fP. | |
549 | This implicit redirection of the standard error to the standard output is | |
550 | performed after any redirections specified by the command. | |
726f6388 | 551 | .PP |
b80f6443 JA |
552 | The return status of a pipeline is the exit status of the last |
553 | command, unless the \fBpipefail\fP option is enabled. | |
554 | If \fBpipefail\fP is enabled, the pipeline's return status is the | |
555 | value of the last (rightmost) command to exit with a non-zero status, | |
556 | or zero if all commands exit successfully. | |
726f6388 JA |
557 | If the reserved word |
558 | .B ! | |
b80f6443 JA |
559 | precedes a pipeline, the exit status of that pipeline is the logical |
560 | negation of the exit status as described above. | |
ccc6cda3 | 561 | The shell waits for all commands in the pipeline to |
726f6388 JA |
562 | terminate before returning a value. |
563 | .PP | |
ccc6cda3 JA |
564 | If the |
565 | .B time | |
566 | reserved word precedes a pipeline, the elapsed as well as user and | |
567 | system time consumed by its execution are reported when the pipeline | |
568 | terminates. | |
569 | The \fB\-p\fP option changes the output format to that specified by POSIX. | |
495aee44 CR |
570 | When the shell is in \fIposix mode\fP, it does not recognize |
571 | \fBtime\fP as a reserved word if the next token begins with a `-'. | |
ccc6cda3 JA |
572 | The |
573 | .SM | |
574 | .B TIMEFORMAT | |
575 | variable may be set to a format string that specifies how the timing | |
576 | information should be displayed; see the description of | |
577 | .SM | |
578 | .B TIMEFORMAT | |
579 | under | |
580 | .B "Shell Variables" | |
581 | below. | |
582 | .PP | |
495aee44 CR |
583 | When the shell is in \fIposix mode\fP, \fBtime\fP |
584 | may be followed by a newline. In this case, the shell displays the | |
585 | total user and system time consumed by the shell and its children. | |
586 | The | |
587 | .SM | |
588 | .B TIMEFORMAT | |
589 | variable may be used to specify the format of | |
590 | the time information. | |
591 | .PP | |
726f6388 JA |
592 | Each command in a pipeline is executed as a separate process (i.e., in a |
593 | subshell). | |
9a51695b CR |
594 | See |
595 | .SM | |
596 | \fBCOMMAND EXECUTION ENVIRONMENT\fP | |
597 | for a description of a subshell environment. | |
598 | If the \fBlastpipe\fP option is enabled using the \fBshopt\fP builtin | |
599 | (see the description of \fBshopt\fP below), | |
600 | the last element of a pipeline may be run by the shell process. | |
726f6388 JA |
601 | .SS Lists |
602 | .PP | |
603 | A \fIlist\fP is a sequence of one or more pipelines separated by one | |
604 | of the operators | |
605 | .BR ; , | |
606 | .BR & , | |
607 | .BR && , | |
608 | or | |
495aee44 | 609 | .BR || , |
ccc6cda3 | 610 | and optionally terminated by one of |
726f6388 JA |
611 | .BR ; , |
612 | .BR & , | |
613 | or | |
614 | .BR <newline> . | |
615 | .PP | |
616 | Of these list operators, | |
617 | .B && | |
618 | and | |
495aee44 | 619 | .B || |
726f6388 JA |
620 | have equal precedence, followed by |
621 | .B ; | |
622 | and | |
3185942a | 623 | .BR & , |
726f6388 JA |
624 | which have equal precedence. |
625 | .PP | |
7117c2d2 JA |
626 | A sequence of one or more newlines may appear in a \fIlist\fP instead |
627 | of a semicolon to delimit commands. | |
628 | .PP | |
726f6388 JA |
629 | If a command is terminated by the control operator |
630 | .BR & , | |
631 | the shell executes the command in the \fIbackground\fP | |
f250956c CR |
632 | in a subshell. |
633 | The shell does not wait for the command to | |
634 | finish, and the return status is 0. | |
635 | These are referred to as \fIasynchronous\fP commands. | |
636 | Commands separated by a | |
726f6388 JA |
637 | .B ; |
638 | are executed sequentially; the shell waits for each | |
639 | command to terminate in turn. The return status is the | |
640 | exit status of the last command executed. | |
641 | .PP | |
a0c0a00f | 642 | AND and OR lists are sequences of one or more pipelines separated by the |
495aee44 | 643 | \fB&&\fP and \fB||\fP control operators, respectively. |
3185942a | 644 | AND and OR lists are executed with left associativity. |
726f6388 JA |
645 | An AND list has the form |
646 | .RS | |
647 | .PP | |
bb70624e | 648 | \fIcommand1\fP \fB&&\fP \fIcommand2\fP |
726f6388 JA |
649 | .RE |
650 | .PP | |
651 | .I command2 | |
652 | is executed if, and only if, | |
bb70624e | 653 | .I command1 |
9a51695b | 654 | returns an exit status of zero (success). |
726f6388 JA |
655 | .PP |
656 | An OR list has the form | |
657 | .RS | |
658 | .PP | |
495aee44 | 659 | \fIcommand1\fP \fB||\fP \fIcommand2\fP |
726f6388 JA |
660 | .PP |
661 | .RE | |
662 | .PP | |
663 | .I command2 | |
9a51695b | 664 | is executed if, and only if, |
bb70624e | 665 | .I command1 |
3185942a JA |
666 | returns a non-zero exit status. |
667 | The return status of | |
726f6388 JA |
668 | AND and OR lists is the exit status of the last command |
669 | executed in the list. | |
670 | .SS Compound Commands | |
671 | .PP | |
ac50fbac CR |
672 | A \fIcompound command\fP is one of the following. |
673 | In most cases a \fIlist\fP in a command's description may be separated from | |
674 | the rest of the command by one or more newlines, and may be followed by a | |
675 | newline in place of a semicolon. | |
726f6388 JA |
676 | .TP |
677 | (\fIlist\fP) | |
b80f6443 JA |
678 | \fIlist\fP is executed in a subshell environment (see |
679 | .SM | |
680 | \fBCOMMAND EXECUTION ENVIRONMENT\fP | |
681 | below). | |
682 | Variable assignments and builtin | |
726f6388 JA |
683 | commands that affect the shell's environment do not remain in effect |
684 | after the command completes. The return status is the exit status of | |
685 | \fIlist\fP. | |
686 | .TP | |
687 | { \fIlist\fP; } | |
ccc6cda3 JA |
688 | \fIlist\fP is simply executed in the current shell environment. |
689 | \fIlist\fP must be terminated with a newline or semicolon. | |
690 | This is known as a \fIgroup command\fP. | |
691 | The return status is the exit status of | |
726f6388 | 692 | \fIlist\fP. |
b80f6443 | 693 | Note that unlike the metacharacters \fB(\fP and \fB)\fP, \fB{\fP and |
f73dda09 JA |
694 | \fB}\fP are \fIreserved words\fP and must occur where a reserved |
695 | word is permitted to be recognized. Since they do not cause a word | |
3185942a JA |
696 | break, they must be separated from \fIlist\fP by whitespace or another |
697 | shell metacharacter. | |
726f6388 | 698 | .TP |
ccc6cda3 JA |
699 | ((\fIexpression\fP)) |
700 | The \fIexpression\fP is evaluated according to the rules described | |
701 | below under | |
702 | .SM | |
703 | .BR "ARITHMETIC EVALUATION" . | |
704 | If the value of the expression is non-zero, the return status is 0; | |
705 | otherwise the return status is 1. This is exactly equivalent to | |
706 | \fBlet "\fIexpression\fP"\fR. | |
707 | .TP | |
cce855bc JA |
708 | \fB[[\fP \fIexpression\fP \fB]]\fP |
709 | Return a status of 0 or 1 depending on the evaluation of | |
710 | the conditional expression \fIexpression\fP. | |
711 | Expressions are composed of the primaries described below under | |
712 | .SM | |
713 | .BR "CONDITIONAL EXPRESSIONS" . | |
714 | Word splitting and pathname expansion are not performed on the words | |
ac50fbac CR |
715 | between the \fB[[\fP and \fB]]\fP; tilde expansion, |
716 | parameter and variable expansion, | |
717 | arithmetic expansion, command substitution, process | |
cce855bc | 718 | substitution, and quote removal are performed. |
b80f6443 JA |
719 | Conditional operators such as \fB\-f\fP must be unquoted to be recognized |
720 | as primaries. | |
cce855bc JA |
721 | .if t .sp 0.5 |
722 | .if n .sp 1 | |
495aee44 | 723 | When used with \fB[[\fP, the \fB<\fP and \fB>\fP operators sort |
0001803f CR |
724 | lexicographically using the current locale. |
725 | .if t .sp 0.5 | |
726 | .if n .sp 1 | |
cce855bc JA |
727 | When the \fB==\fP and \fB!=\fP operators are used, the string to the |
728 | right of the operator is considered a pattern and matched according | |
ac50fbac CR |
729 | to the rules described below under \fBPattern Matching\fP, |
730 | as if the \fBextglob\fP shell option were enabled. | |
731 | The \fB=\fP operator is equivalent to \fB==\fP. | |
a0c0a00f | 732 | If the |
95732b49 | 733 | .B nocasematch |
a0c0a00f | 734 | shell option is enabled, the match is performed without regard to the case |
95732b49 | 735 | of alphabetic characters. |
0628567a JA |
736 | The return value is 0 if the string matches (\fB==\fP) or does not match |
737 | (\fB!=\fP) the pattern, and 1 otherwise. | |
ac50fbac CR |
738 | Any part of the pattern may be quoted to force the quoted portion |
739 | to be matched as a string. | |
cce855bc JA |
740 | .if t .sp 0.5 |
741 | .if n .sp 1 | |
b80f6443 JA |
742 | An additional binary operator, \fB=~\fP, is available, with the same |
743 | precedence as \fB==\fP and \fB!=\fP. | |
744 | When it is used, the string to the right of the operator is considered | |
2f5dfe5a | 745 | a POSIX extended regular expression and matched accordingly (as in \fIregex\fP(3)). |
b80f6443 JA |
746 | The return value is 0 if the string matches |
747 | the pattern, and 1 otherwise. | |
748 | If the regular expression is syntactically incorrect, the conditional | |
749 | expression's return value is 2. | |
a0c0a00f | 750 | If the |
95732b49 | 751 | .B nocasematch |
a0c0a00f | 752 | shell option is enabled, the match is performed without regard to the case |
b80f6443 | 753 | of alphabetic characters. |
ac50fbac CR |
754 | Any part of the pattern may be quoted to force the quoted portion |
755 | to be matched as a string. | |
756 | Bracket expressions in regular expressions must be treated carefully, | |
757 | since normal quoting characters lose their meanings between brackets. | |
758 | If the pattern is stored in a shell variable, quoting the variable | |
759 | expansion forces the entire pattern to be matched as a string. | |
b80f6443 | 760 | Substrings matched by parenthesized subexpressions within the regular |
0001803f CR |
761 | expression are saved in the array variable |
762 | .SM | |
763 | .BR BASH_REMATCH . | |
764 | The element of | |
765 | .SM | |
766 | .B BASH_REMATCH | |
767 | with index 0 is the portion of the string | |
b80f6443 | 768 | matching the entire regular expression. |
0001803f CR |
769 | The element of |
770 | .SM | |
771 | .B BASH_REMATCH | |
772 | with index \fIn\fP is the portion of the | |
b80f6443 JA |
773 | string matching the \fIn\fPth parenthesized subexpression. |
774 | .if t .sp 0.5 | |
775 | .if n .sp 1 | |
cce855bc JA |
776 | Expressions may be combined using the following operators, listed |
777 | in decreasing order of precedence: | |
778 | .if t .sp 0.5 | |
779 | .if n .sp 1 | |
780 | .RS | |
781 | .PD 0 | |
782 | .TP | |
783 | .B ( \fIexpression\fP ) | |
784 | Returns the value of \fIexpression\fP. | |
785 | This may be used to override the normal precedence of operators. | |
786 | .TP | |
787 | .B ! \fIexpression\fP | |
788 | True if | |
789 | .I expression | |
790 | is false. | |
791 | .TP | |
792 | \fIexpression1\fP \fB&&\fP \fIexpression2\fP | |
793 | True if both | |
794 | .I expression1 | |
795 | and | |
796 | .I expression2 | |
797 | are true. | |
798 | .TP | |
495aee44 | 799 | \fIexpression1\fP \fB||\fP \fIexpression2\fP |
cce855bc JA |
800 | True if either |
801 | .I expression1 | |
802 | or | |
803 | .I expression2 | |
804 | is true. | |
805 | .PD | |
cce855bc | 806 | .LP |
495aee44 | 807 | The \fB&&\fP and \fB||\fP |
7117c2d2 | 808 | operators do not evaluate \fIexpression2\fP if the value of |
cce855bc JA |
809 | \fIexpression1\fP is sufficient to determine the return value of |
810 | the entire conditional expression. | |
f73dda09 | 811 | .RE |
cce855bc | 812 | .TP |
0001803f | 813 | \fBfor\fP \fIname\fP [ [ \fBin\fP [ \fIword ...\fP ] ] ; ] \fBdo\fP \fIlist\fP ; \fBdone\fP |
726f6388 | 814 | The list of words following \fBin\fP is expanded, generating a list |
bb70624e JA |
815 | of items. |
816 | The variable \fIname\fP is set to each element of this list | |
817 | in turn, and \fIlist\fP is executed each time. | |
818 | If the \fBin\fP \fIword\fP is omitted, the \fBfor\fP command executes | |
819 | \fIlist\fP once for each positional parameter that is set (see | |
726f6388 JA |
820 | .SM |
821 | .B PARAMETERS | |
822 | below). | |
cce855bc JA |
823 | The return status is the exit status of the last command that executes. |
824 | If the expansion of the items following \fBin\fP results in an empty | |
825 | list, no commands are executed, and the return status is 0. | |
726f6388 | 826 | .TP |
bb70624e JA |
827 | \fBfor\fP (( \fIexpr1\fP ; \fIexpr2\fP ; \fIexpr3\fP )) ; \fBdo\fP \fIlist\fP ; \fBdone\fP |
828 | First, the arithmetic expression \fIexpr1\fP is evaluated according | |
829 | to the rules described below under | |
830 | .SM | |
831 | .BR "ARITHMETIC EVALUATION" . | |
832 | The arithmetic expression \fIexpr2\fP is then evaluated repeatedly | |
833 | until it evaluates to zero. | |
834 | Each time \fIexpr2\fP evaluates to a non-zero value, \fIlist\fP is | |
835 | executed and the arithmetic expression \fIexpr3\fP is evaluated. | |
836 | If any expression is omitted, it behaves as if it evaluates to 1. | |
837 | The return value is the exit status of the last command in \fIlist\fP | |
838 | that is executed, or false if any of the expressions is invalid. | |
839 | .TP | |
b72432fd | 840 | \fBselect\fP \fIname\fP [ \fBin\fP \fIword\fP ] ; \fBdo\fP \fIlist\fP ; \fBdone\fP |
726f6388 JA |
841 | The list of words following \fBin\fP is expanded, generating a list |
842 | of items. The set of expanded words is printed on the standard | |
843 | error, each preceded by a number. If the \fBin\fP | |
844 | \fIword\fP is omitted, the positional parameters are printed (see | |
845 | .SM | |
846 | .B PARAMETERS | |
847 | below). The | |
0001803f | 848 | .SM |
726f6388 JA |
849 | .B PS3 |
850 | prompt is then displayed and a line read from the standard input. | |
ccc6cda3 | 851 | If the line consists of a number corresponding to one of |
726f6388 JA |
852 | the displayed words, then the value of |
853 | .I name | |
854 | is set to that word. If the line is empty, the words and prompt | |
855 | are displayed again. If EOF is read, the command completes. Any | |
856 | other value read causes | |
857 | .I name | |
858 | to be set to null. The line read is saved in the variable | |
0001803f | 859 | .SM |
726f6388 JA |
860 | .BR REPLY . |
861 | The | |
862 | .I list | |
863 | is executed after each selection until a | |
864 | .B break | |
726f6388 JA |
865 | command is executed. |
866 | The exit status of | |
867 | .B select | |
868 | is the exit status of the last command executed in | |
869 | .IR list , | |
870 | or zero if no commands were executed. | |
871 | .TP | |
bb70624e | 872 | \fBcase\fP \fIword\fP \fBin\fP [ [(] \fIpattern\fP [ \fB|\fP \fIpattern\fP ] \ |
726f6388 JA |
873 | ... ) \fIlist\fP ;; ] ... \fBesac\fP |
874 | A \fBcase\fP command first expands \fIword\fP, and tries to match | |
9a51695b CR |
875 | it against each \fIpattern\fP in turn, using the matching rules |
876 | described under | |
877 | .B Pattern Matching | |
878 | below. | |
0628567a | 879 | The \fIword\fP is expanded using tilde |
a0c0a00f | 880 | expansion, parameter and variable expansion, arithmetic expansion, |
0628567a JA |
881 | command substitution, process substitution and quote removal. |
882 | Each \fIpattern\fP examined is expanded using tilde | |
a0c0a00f | 883 | expansion, parameter and variable expansion, arithmetic expansion, |
0628567a | 884 | command substitution, and process substitution. |
a0c0a00f | 885 | If the |
95732b49 | 886 | .B nocasematch |
a0c0a00f | 887 | shell option is enabled, the match is performed without regard to the case |
95732b49 | 888 | of alphabetic characters. |
3185942a JA |
889 | When a match is found, the corresponding \fIlist\fP is executed. |
890 | If the \fB;;\fP operator is used, no subsequent matches are attempted after | |
891 | the first pattern match. | |
892 | Using \fB;&\fP in place of \fB;;\fP causes execution to continue with | |
893 | the \fIlist\fP associated with the next set of patterns. | |
894 | Using \fB;;&\fP in place of \fB;;\fP causes the shell to test the next | |
895 | pattern list in the statement, if any, and execute any associated \fIlist\fP | |
896 | on a successful match. | |
897 | The exit status is zero if no | |
ccc6cda3 | 898 | pattern matches. Otherwise, it is the exit status of the |
726f6388 JA |
899 | last command executed in \fIlist\fP. |
900 | .TP | |
ac50fbac | 901 | \fBif\fP \fIlist\fP; \fBthen\fP \fIlist\fP; \ |
ccc6cda3 JA |
902 | [ \fBelif\fP \fIlist\fP; \fBthen\fP \fIlist\fP; ] ... \ |
903 | [ \fBelse\fP \fIlist\fP; ] \fBfi\fP | |
726f6388 | 904 | The |
a0c0a00f | 905 | .B if |
726f6388 JA |
906 | .I list |
907 | is executed. If its exit status is zero, the | |
908 | \fBthen\fP \fIlist\fP is executed. Otherwise, each \fBelif\fP | |
909 | \fIlist\fP is executed in turn, and if its exit status is zero, | |
910 | the corresponding \fBthen\fP \fIlist\fP is executed and the | |
911 | command completes. Otherwise, the \fBelse\fP \fIlist\fP is | |
912 | executed, if present. The exit status is the exit status of the | |
913 | last command executed, or zero if no condition tested true. | |
914 | .TP | |
495aee44 | 915 | \fBwhile\fP \fIlist-1\fP; \fBdo\fP \fIlist-2\fP; \fBdone\fP |
7117c2d2 | 916 | .PD 0 |
726f6388 | 917 | .TP |
495aee44 | 918 | \fBuntil\fP \fIlist-1\fP; \fBdo\fP \fIlist-2\fP; \fBdone\fP |
726f6388 | 919 | .PD |
495aee44 CR |
920 | The \fBwhile\fP command continuously executes the list |
921 | \fIlist-2\fP as long as the last command in the list \fIlist-1\fP returns | |
726f6388 | 922 | an exit status of zero. The \fBuntil\fP command is identical |
a0c0a00f | 923 | to the \fBwhile\fP command, except that the test is negated: |
495aee44 | 924 | .I list-2 |
726f6388 | 925 | is executed as long as the last command in |
495aee44 | 926 | .I list-1 |
ccc6cda3 | 927 | returns a non-zero exit status. |
726f6388 JA |
928 | The exit status of the \fBwhile\fP and \fBuntil\fP commands |
929 | is the exit status | |
495aee44 | 930 | of the last command executed in \fIlist-2\fP, or zero if |
726f6388 | 931 | none was executed. |
3185942a JA |
932 | .SS Coprocesses |
933 | .PP | |
934 | A \fIcoprocess\fP is a shell command preceded by the \fBcoproc\fP reserved | |
935 | word. | |
936 | A coprocess is executed asynchronously in a subshell, as if the command | |
937 | had been terminated with the \fB&\fP control operator, with a two-way pipe | |
938 | established between the executing shell and the coprocess. | |
939 | .PP | |
940 | The format for a coprocess is: | |
941 | .RS | |
942 | .PP | |
943 | \fBcoproc\fP [\fINAME\fP] \fIcommand\fP [\fIredirections\fP] | |
944 | .RE | |
945 | .PP | |
946 | This creates a coprocess named \fINAME\fP. | |
ac50fbac | 947 | If \fINAME\fP is not supplied, the default name is \fBCOPROC\fP. |
17345e5a JA |
948 | \fINAME\fP must not be supplied if \fIcommand\fP is a \fIsimple |
949 | command\fP (see above); otherwise, it is interpreted as the first word | |
950 | of the simple command. | |
ac50fbac | 951 | When the coprocess is executed, the shell creates an array variable (see |
3185942a JA |
952 | .B Arrays |
953 | below) named \fINAME\fP in the context of the executing shell. | |
954 | The standard output of | |
955 | .I command | |
956 | is connected via a pipe to a file descriptor in the executing shell, | |
957 | and that file descriptor is assigned to \fINAME\fP[0]. | |
958 | The standard input of | |
959 | .I command | |
960 | is connected via a pipe to a file descriptor in the executing shell, | |
961 | and that file descriptor is assigned to \fINAME\fP[1]. | |
962 | This pipe is established before any redirections specified by the | |
963 | command (see | |
964 | .SM | |
965 | .B REDIRECTION | |
966 | below). | |
967 | The file descriptors can be utilized as arguments to shell commands | |
968 | and redirections using standard word expansions. | |
9a51695b CR |
969 | Other than those created to execute command and process substitutions, |
970 | the file descriptors are not available in subshells. | |
495aee44 | 971 | The process ID of the shell spawned to execute the coprocess is |
3185942a JA |
972 | available as the value of the variable \fINAME\fP_PID. |
973 | The \fBwait\fP | |
974 | builtin command may be used to wait for the coprocess to terminate. | |
975 | .PP | |
ac50fbac CR |
976 | Since the coprocess is created as an asynchronous command, |
977 | the \fBcoproc\fP command always returns success. | |
3185942a | 978 | The return status of a coprocess is the exit status of \fIcommand\fP. |
b80f6443 JA |
979 | .SS Shell Function Definitions |
980 | .PP | |
981 | A shell function is an object that is called like a simple command and | |
982 | executes a compound command with a new set of positional parameters. | |
983 | Shell functions are declared as follows: | |
984 | .TP | |
495aee44 CR |
985 | \fIname\fP () \fIcompound\-command\fP [\fIredirection\fP] |
986 | .PD 0 | |
987 | .TP | |
988 | \fBfunction\fP \fIname\fP [()] \fIcompound\-command\fP [\fIredirection\fP] | |
989 | .PD | |
b80f6443 JA |
990 | This defines a function named \fIname\fP. |
991 | The reserved word \fBfunction\fP is optional. | |
992 | If the \fBfunction\fP reserved word is supplied, the parentheses are optional. | |
993 | The \fIbody\fP of the function is the compound command | |
a0c0a00f | 994 | .I compound\-command |
b80f6443 JA |
995 | (see \fBCompound Commands\fP above). |
996 | That command is usually a \fIlist\fP of commands between { and }, but | |
a0c0a00f CR |
997 | may be any command listed under \fBCompound Commands\fP above, |
998 | with one exception: If the \fBfunction\fP reserved word is used, but the | |
999 | parentheses are not supplied, the braces are required. | |
b80f6443 JA |
1000 | \fIcompound\-command\fP is executed whenever \fIname\fP is specified as the |
1001 | name of a simple command. | |
ac50fbac CR |
1002 | When in \fIposix mode\fP, \fIname\fP may not be the name of one of the |
1003 | POSIX \fIspecial builtins\fP. | |
b80f6443 JA |
1004 | Any redirections (see |
1005 | .SM | |
1006 | .B REDIRECTION | |
1007 | below) specified when a function is defined are performed | |
1008 | when the function is executed. | |
1009 | The exit status of a function definition is zero unless a syntax error | |
1010 | occurs or a readonly function with the same name already exists. | |
1011 | When executed, the exit status of a function is the exit status of the | |
1012 | last command executed in the body. (See | |
726f6388 JA |
1013 | .SM |
1014 | .B FUNCTIONS | |
1015 | below.) | |
1016 | .SH COMMENTS | |
ccc6cda3 JA |
1017 | In a non-interactive shell, or an interactive shell in which the |
1018 | .B interactive_comments | |
1019 | option to the | |
1020 | .B shopt | |
1021 | builtin is enabled (see | |
1022 | .SM | |
1023 | .B "SHELL BUILTIN COMMANDS" | |
1024 | below), a word beginning with | |
726f6388 JA |
1025 | .B # |
1026 | causes that word and all remaining characters on that line to | |
1027 | be ignored. An interactive shell without the | |
ccc6cda3 | 1028 | .B interactive_comments |
ccc6cda3 JA |
1029 | option enabled does not allow comments. The |
1030 | .B interactive_comments | |
1031 | option is on by default in interactive shells. | |
726f6388 JA |
1032 | .SH QUOTING |
1033 | \fIQuoting\fP is used to remove the special meaning of certain | |
a0c0a00f | 1034 | characters or words to the shell. Quoting can be used to |
726f6388 JA |
1035 | disable special treatment for special characters, to prevent |
1036 | reserved words from being recognized as such, and to prevent | |
1037 | parameter expansion. | |
1038 | .PP | |
1039 | Each of the \fImetacharacters\fP listed above under | |
1040 | .SM | |
1041 | .B DEFINITIONS | |
bb70624e JA |
1042 | has special meaning to the shell and must be quoted if it is to |
1043 | represent itself. | |
1044 | .PP | |
95732b49 JA |
1045 | When the command history expansion facilities are being used |
1046 | (see | |
1047 | .SM | |
1048 | .B HISTORY EXPANSION | |
1049 | below), the | |
bb70624e JA |
1050 | \fIhistory expansion\fP character, usually \fB!\fP, must be quoted |
1051 | to prevent history expansion. | |
1052 | .PP | |
1053 | There are three quoting mechanisms: the | |
726f6388 JA |
1054 | .IR "escape character" , |
1055 | single quotes, and double quotes. | |
1056 | .PP | |
1057 | A non-quoted backslash (\fB\e\fP) is the | |
1058 | .IR "escape character" . | |
1059 | It preserves the literal value of the next character that follows, | |
1060 | with the exception of <newline>. If a \fB\e\fP<newline> pair | |
cce855bc JA |
1061 | appears, and the backslash is not itself quoted, the \fB\e\fP<newline> |
1062 | is treated as a line continuation (that is, it is removed from the | |
1063 | input stream and effectively ignored). | |
726f6388 JA |
1064 | .PP |
1065 | Enclosing characters in single quotes preserves the literal value | |
1066 | of each character within the quotes. A single quote may not occur | |
1067 | between single quotes, even when preceded by a backslash. | |
1068 | .PP | |
1069 | Enclosing characters in double quotes preserves the literal value | |
1070 | of all characters within the quotes, with the exception of | |
1071 | .BR $ , | |
3185942a | 1072 | .BR \` , |
95732b49 JA |
1073 | .BR \e , |
1074 | and, when history expansion is enabled, | |
1075 | .BR ! . | |
a0c0a00f CR |
1076 | When the shell is in \fIposix mode\fP, the \fB!\fP has no special meaning |
1077 | within double quotes, even when history expansion is enabled. | |
726f6388 JA |
1078 | The characters |
1079 | .B $ | |
1080 | and | |
3185942a | 1081 | .B \` |
726f6388 JA |
1082 | retain their special meaning within double quotes. The backslash |
1083 | retains its special meaning only when followed by one of the following | |
1084 | characters: | |
1085 | .BR $ , | |
3185942a | 1086 | .BR \` , |
726f6388 JA |
1087 | \^\fB"\fP\^, |
1088 | .BR \e , | |
1089 | or | |
1090 | .BR <newline> . | |
1091 | A double quote may be quoted within double quotes by preceding it with | |
1092 | a backslash. | |
95732b49 JA |
1093 | If enabled, history expansion will be performed unless an |
1094 | .B ! | |
1095 | appearing in double quotes is escaped using a backslash. | |
1096 | The backslash preceding the | |
1097 | .B ! | |
1098 | is not removed. | |
726f6388 JA |
1099 | .PP |
1100 | The special parameters | |
1101 | .B * | |
1102 | and | |
1103 | .B @ | |
1104 | have special meaning when in double | |
1105 | quotes (see | |
1106 | .SM | |
1107 | .B PARAMETERS | |
1108 | below). | |
ccc6cda3 | 1109 | .PP |
0628567a | 1110 | Words of the form \fB$\fP\(aq\fIstring\fP\(aq are treated specially. The |
ccc6cda3 | 1111 | word expands to \fIstring\fP, with backslash-escaped characters replaced |
95732b49 | 1112 | as specified by the ANSI C standard. Backslash escape sequences, if |
ccc6cda3 JA |
1113 | present, are decoded as follows: |
1114 | .RS | |
1115 | .PD 0 | |
1116 | .TP | |
1117 | .B \ea | |
1118 | alert (bell) | |
1119 | .TP | |
1120 | .B \eb | |
1121 | backspace | |
1122 | .TP | |
1123 | .B \ee | |
0001803f CR |
1124 | .TP |
1125 | .B \eE | |
ccc6cda3 | 1126 | an escape character |
a0c0a00f | 1127 | .TP |
ccc6cda3 JA |
1128 | .B \ef |
1129 | form feed | |
a0c0a00f | 1130 | .TP |
ccc6cda3 JA |
1131 | .B \en |
1132 | new line | |
a0c0a00f | 1133 | .TP |
ccc6cda3 JA |
1134 | .B \er |
1135 | carriage return | |
1136 | .TP | |
1137 | .B \et | |
1138 | horizontal tab | |
a0c0a00f | 1139 | .TP |
ccc6cda3 JA |
1140 | .B \ev |
1141 | vertical tab | |
1142 | .TP | |
1143 | .B \e\e | |
1144 | backslash | |
bb70624e | 1145 | .TP |
0628567a | 1146 | .B \e\(aq |
bb70624e | 1147 | single quote |
0001803f CR |
1148 | .TP |
1149 | .B \e\(dq | |
1150 | double quote | |
a0c0a00f CR |
1151 | .TP |
1152 | .B \e? | |
1153 | question mark | |
1154 | .TP | |
ccc6cda3 | 1155 | .B \e\fInnn\fP |
f73dda09 | 1156 | the eight-bit character whose value is the octal value \fInnn\fP |
9a51695b | 1157 | (one to three octal digits) |
cce855bc | 1158 | .TP |
f73dda09 JA |
1159 | .B \ex\fIHH\fP |
1160 | the eight-bit character whose value is the hexadecimal value \fIHH\fP | |
1161 | (one or two hex digits) | |
7117c2d2 | 1162 | .TP |
495aee44 CR |
1163 | .B \eu\fIHHHH\fP |
1164 | the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value | |
1165 | \fIHHHH\fP (one to four hex digits) | |
1166 | .TP | |
1167 | .B \eU\fIHHHHHHHH\fP | |
1168 | the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value | |
1169 | \fIHHHHHHHH\fP (one to eight hex digits) | |
1170 | .TP | |
7117c2d2 JA |
1171 | .B \ec\fIx\fP |
1172 | a control-\fIx\fP character | |
ccc6cda3 JA |
1173 | .PD |
1174 | .RE | |
1175 | .LP | |
bb70624e | 1176 | The expanded result is single-quoted, as if the dollar sign had |
ccc6cda3 JA |
1177 | not been present. |
1178 | .PP | |
0001803f CR |
1179 | A double-quoted string preceded by a dollar sign (\fB$\fP\(dq\fIstring\fP\(dq) |
1180 | will cause the string to be translated according to the current locale. | |
ccc6cda3 JA |
1181 | If the current locale is \fBC\fP or \fBPOSIX\fP, the dollar sign |
1182 | is ignored. | |
1183 | If the string is translated and replaced, the replacement is | |
1184 | double-quoted. | |
726f6388 JA |
1185 | .SH PARAMETERS |
1186 | A | |
1187 | .I parameter | |
ccc6cda3 JA |
1188 | is an entity that stores values. |
1189 | It can be a | |
726f6388 JA |
1190 | .IR name , |
1191 | a number, or one of the special characters listed below under | |
1192 | .BR "Special Parameters" . | |
b80f6443 | 1193 | A |
726f6388 JA |
1194 | .I variable |
1195 | is a parameter denoted by a | |
1196 | .IR name . | |
f73dda09 JA |
1197 | A variable has a \fIvalue\fP and zero or more \fIattributes\fP. |
1198 | Attributes are assigned using the | |
1199 | .B declare | |
1200 | builtin command (see | |
1201 | .B declare | |
1202 | below in | |
1203 | .SM | |
1204 | .BR "SHELL BUILTIN COMMANDS" ). | |
726f6388 JA |
1205 | .PP |
1206 | A parameter is set if it has been assigned a value. The null string is | |
1207 | a valid value. Once a variable is set, it may be unset only by using | |
1208 | the | |
1209 | .B unset | |
1210 | builtin command (see | |
1211 | .SM | |
1212 | .B SHELL BUILTIN COMMANDS | |
1213 | below). | |
1214 | .PP | |
1215 | A | |
1216 | .I variable | |
1217 | may be assigned to by a statement of the form | |
1218 | .RS | |
1219 | .PP | |
1220 | \fIname\fP=[\fIvalue\fP] | |
1221 | .RE | |
1222 | .PP | |
1223 | If | |
1224 | .I value | |
1225 | is not given, the variable is assigned the null string. All | |
1226 | .I values | |
bb70624e JA |
1227 | undergo tilde expansion, parameter and variable expansion, |
1228 | command substitution, arithmetic expansion, and quote | |
ccc6cda3 JA |
1229 | removal (see |
1230 | .SM | |
1231 | .B EXPANSION | |
1232 | below). If the variable has its | |
cce855bc | 1233 | .B integer |
f73dda09 | 1234 | attribute set, then |
726f6388 | 1235 | .I value |
b80f6443 | 1236 | is evaluated as an arithmetic expression even if the $((...)) expansion is |
cce855bc | 1237 | not used (see |
ccc6cda3 JA |
1238 | .B "Arithmetic Expansion" |
1239 | below). | |
1240 | Word splitting is not performed, with the exception | |
726f6388 JA |
1241 | of \fB"$@"\fP as explained below under |
1242 | .BR "Special Parameters" . | |
1243 | Pathname expansion is not performed. | |
f73dda09 | 1244 | Assignment statements may also appear as arguments to the |
b80f6443 | 1245 | .BR alias , |
f73dda09 JA |
1246 | .BR declare , |
1247 | .BR typeset , | |
1248 | .BR export , | |
1249 | .BR readonly , | |
1250 | and | |
1251 | .B local | |
a0c0a00f | 1252 | builtin commands (\fIdeclaration\fP commands). |
ac50fbac CR |
1253 | When in \fIposix mode\fP, these builtins may appear in a command after |
1254 | one or more instances of the \fBcommand\fP builtin and retain these | |
1255 | assignment statement properties. | |
95732b49 JA |
1256 | .PP |
1257 | In the context where an assignment statement is assigning a value | |
1258 | to a shell variable or array index, the += operator can be used to | |
1259 | append to or add to the variable's previous value. | |
a0c0a00f CR |
1260 | This includes arguments to builtin commands such as \fBdeclare\fP that |
1261 | accept assignment statements (\fIdeclaration\fP commands). | |
495aee44 | 1262 | When += is applied to a variable for which the \fIinteger\fP attribute has been |
95732b49 JA |
1263 | set, \fIvalue\fP is evaluated as an arithmetic expression and added to the |
1264 | variable's current value, which is also evaluated. | |
1265 | When += is applied to an array variable using compound assignment (see | |
1266 | .B Arrays | |
1267 | below), the | |
1268 | variable's value is not unset (as it is when using =), and new values are | |
3185942a JA |
1269 | appended to the array beginning at one greater than the array's maximum index |
1270 | (for indexed arrays) or added as additional key\-value pairs in an | |
1271 | associative array. | |
95732b49 JA |
1272 | When applied to a string-valued variable, \fIvalue\fP is expanded and |
1273 | appended to the variable's value. | |
ac50fbac CR |
1274 | .PP |
1275 | A variable can be assigned the \fInameref\fP attribute using the | |
1276 | \fB\-n\fP option to the \fBdeclare\fP or \fBlocal\fP builtin commands | |
1277 | (see the descriptions of \fBdeclare\fP and \fBlocal\fP below) | |
1278 | to create a \fInameref\fP, or a reference to another variable. | |
1279 | This allows variables to be manipulated indirectly. | |
a0c0a00f CR |
1280 | Whenever the nameref variable is referenced, assigned to, unset, or has |
1281 | its attributes modified (other than using or changing the \fInameref\fP | |
1282 | attribute itself), the | |
1283 | operation is actually performed on the variable specified by the nameref | |
1284 | variable's value. | |
ac50fbac CR |
1285 | A nameref is commonly used within shell functions to refer to a variable |
1286 | whose name is passed as an argument to the function. | |
1287 | For instance, if a variable name is passed to a shell function as its first | |
1288 | argument, running | |
1289 | .sp .5 | |
1290 | .RS | |
1291 | .if t \f(CWdeclare -n ref=$1\fP | |
1292 | .if n declare -n ref=$1 | |
1293 | .RE | |
1294 | .sp .5 | |
1295 | inside the function creates a nameref variable \fBref\fP whose value is | |
1296 | the variable name passed as the first argument. | |
a0c0a00f CR |
1297 | References and assignments to \fBref\fP, and changes to its attributes, |
1298 | are treated as references, assignments, and attribute modifications | |
1299 | to the variable whose name was passed as \fB$1\fP. | |
ac50fbac CR |
1300 | If the control variable in a \fBfor\fP loop has the nameref attribute, |
1301 | the list of words can be a list of shell variables, and a name reference | |
1302 | will be established for each word in the list, in turn, when the loop is | |
1303 | executed. | |
a0c0a00f | 1304 | Array variables cannot be given the \fBnameref\fP attribute. |
ac50fbac CR |
1305 | However, nameref variables can reference array variables and subscripted |
1306 | array variables. | |
1307 | Namerefs can be unset using the \fB\-n\fP option to the \fBunset\fP builtin. | |
1308 | Otherwise, if \fBunset\fP is executed with the name of a nameref variable | |
1309 | as an argument, the variable referenced by the nameref variable will be unset. | |
726f6388 JA |
1310 | .SS Positional Parameters |
1311 | .PP | |
1312 | A | |
1313 | .I positional parameter | |
1314 | is a parameter denoted by one or more | |
1315 | digits, other than the single digit 0. Positional parameters are | |
1316 | assigned from the shell's arguments when it is invoked, | |
1317 | and may be reassigned using the | |
1318 | .B set | |
1319 | builtin command. Positional parameters may not be assigned to | |
1320 | with assignment statements. The positional parameters are | |
1321 | temporarily replaced when a shell function is executed (see | |
1322 | .SM | |
1323 | .B FUNCTIONS | |
1324 | below). | |
1325 | .PP | |
1326 | When a positional parameter consisting of more than a single | |
1327 | digit is expanded, it must be enclosed in braces (see | |
1328 | .SM | |
1329 | .B EXPANSION | |
1330 | below). | |
1331 | .SS Special Parameters | |
1332 | .PP | |
1333 | The shell treats several parameters specially. These parameters may | |
1334 | only be referenced; assignment to them is not allowed. | |
1335 | .PD 0 | |
1336 | .TP | |
1337 | .B * | |
ac50fbac CR |
1338 | Expands to the positional parameters, starting from one. |
1339 | When the expansion is not within double quotes, each positional parameter | |
1340 | expands to a separate word. | |
1341 | In contexts where it is performed, those words | |
1342 | are subject to further word splitting and pathname expansion. | |
1343 | When the expansion occurs within double quotes, it expands to a single word | |
a0c0a00f | 1344 | with the value of each parameter separated by the first character of the |
726f6388 JA |
1345 | .SM |
1346 | .B IFS | |
cce855bc JA |
1347 | special variable. That is, "\fB$*\fP" is equivalent |
1348 | to "\fB$1\fP\fIc\fP\fB$2\fP\fIc\fP\fB...\fP", where | |
726f6388 JA |
1349 | .I c |
1350 | is the first character of the value of the | |
1351 | .SM | |
1352 | .B IFS | |
1353 | variable. If | |
1354 | .SM | |
1355 | .B IFS | |
d166f048 JA |
1356 | is unset, the parameters are separated by spaces. |
1357 | If | |
1358 | .SM | |
1359 | .B IFS | |
1360 | is null, the parameters are joined without intervening separators. | |
726f6388 JA |
1361 | .TP |
1362 | .B @ | |
2f5dfe5a CR |
1363 | Expands to the positional parameters, starting from one. |
1364 | In contexts where word splitting is performed, this expands each | |
1365 | positional parameter to a separate word; if not within double | |
1366 | quotes, these words are subject to word splitting. | |
1367 | In contexts where word splitting is not performed, | |
1368 | this expands to a single word | |
1369 | with each positional parameter separated by a space. | |
1370 | When the | |
cce855bc JA |
1371 | expansion occurs within double quotes, each parameter expands to a |
1372 | separate word. That is, "\fB$@\fP" is equivalent to | |
1373 | "\fB$1\fP" "\fB$2\fP" ... | |
95732b49 JA |
1374 | If the double-quoted expansion occurs within a word, the expansion of |
1375 | the first parameter is joined with the beginning part of the original | |
1376 | word, and the expansion of the last parameter is joined with the last | |
1377 | part of the original word. | |
a0c0a00f | 1378 | When there are no positional parameters, "\fB$@\fP" and |
726f6388 JA |
1379 | .B $@ |
1380 | expand to nothing (i.e., they are removed). | |
1381 | .TP | |
1382 | .B # | |
1383 | Expands to the number of positional parameters in decimal. | |
1384 | .TP | |
1385 | .B ? | |
3185942a | 1386 | Expands to the exit status of the most recently executed foreground |
726f6388 JA |
1387 | pipeline. |
1388 | .TP | |
1389 | .B \- | |
1390 | Expands to the current option flags as specified upon invocation, | |
1391 | by the | |
1392 | .B set | |
1393 | builtin command, or those set by the shell itself | |
1394 | (such as the | |
1395 | .B \-i | |
cce855bc | 1396 | option). |
726f6388 JA |
1397 | .TP |
1398 | .B $ | |
1399 | Expands to the process ID of the shell. In a () subshell, it | |
1400 | expands to the process ID of the current shell, not the | |
1401 | subshell. | |
1402 | .TP | |
1403 | .B ! | |
ac50fbac CR |
1404 | Expands to the process ID of the job most recently placed into the |
1405 | background, whether executed as an asynchronous command or using | |
1406 | the \fBbg\fP builtin (see | |
1407 | .SM | |
1408 | .B "JOB CONTROL" | |
1409 | below). | |
726f6388 JA |
1410 | .TP |
1411 | .B 0 | |
1412 | Expands to the name of the shell or shell script. This is set at | |
1413 | shell initialization. If | |
1414 | .B bash | |
1415 | is invoked with a file of commands, | |
1416 | .B $0 | |
1417 | is set to the name of that file. If | |
1418 | .B bash | |
1419 | is started with the | |
1420 | .B \-c | |
1421 | option, then | |
1422 | .B $0 | |
1423 | is set to the first argument after the string to be | |
1424 | executed, if one is present. Otherwise, it is set | |
ac50fbac | 1425 | to the filename used to invoke |
726f6388 JA |
1426 | .BR bash , |
1427 | as given by argument zero. | |
1428 | .TP | |
1429 | .B _ | |
95732b49 JA |
1430 | At shell startup, set to the absolute pathname used to invoke the |
1431 | shell or shell script being executed as passed in the environment | |
1432 | or argument list. | |
2ae59c11 CR |
1433 | Subsequently, expands to the last argument to the previous simple |
1434 | command executed in the foreground, after expansion. | |
95732b49 JA |
1435 | Also set to the full pathname used to invoke each command executed |
1436 | and placed in the environment exported to that command. | |
ccc6cda3 JA |
1437 | When checking mail, this parameter holds the name of the mail file |
1438 | currently being checked. | |
726f6388 JA |
1439 | .PD |
1440 | .SS Shell Variables | |
1441 | .PP | |
1442 | The following variables are set by the shell: | |
1443 | .PP | |
1444 | .PD 0 | |
1445 | .TP | |
726f6388 | 1446 | .B BASH |
ac50fbac | 1447 | Expands to the full filename used to invoke this instance of |
726f6388 JA |
1448 | .BR bash . |
1449 | .TP | |
0001803f CR |
1450 | .B BASHOPTS |
1451 | A colon-separated list of enabled shell options. Each word in | |
1452 | the list is a valid argument for the | |
1453 | .B \-s | |
1454 | option to the | |
1455 | .B shopt | |
1456 | builtin command (see | |
1457 | .SM | |
1458 | .B "SHELL BUILTIN COMMANDS" | |
1459 | below). The options appearing in | |
1460 | .SM | |
1461 | .B BASHOPTS | |
1462 | are those reported as | |
1463 | .I on | |
1464 | by \fBshopt\fP. | |
1465 | If this variable is in the environment when | |
1466 | .B bash | |
1467 | starts up, each shell option in the list will be enabled before | |
1468 | reading any startup files. | |
1469 | This variable is read-only. | |
1470 | .TP | |
3185942a | 1471 | .B BASHPID |
495aee44 | 1472 | Expands to the process ID of the current \fBbash\fP process. |
3185942a JA |
1473 | This differs from \fB$$\fP under certain circumstances, such as subshells |
1474 | that do not require \fBbash\fP to be re-initialized. | |
9a51695b CR |
1475 | Assignments to |
1476 | .SM | |
1477 | .B BASHPID | |
1478 | have no effect. | |
1479 | If | |
1480 | .B BASHPID | |
1481 | is unset, it loses its special properties, even if it is | |
1482 | subsequently reset. | |
3185942a JA |
1483 | .TP |
1484 | .B BASH_ALIASES | |
1485 | An associative array variable whose members correspond to the internal | |
495aee44 | 1486 | list of aliases as maintained by the \fBalias\fP builtin. |
a0c0a00f CR |
1487 | Elements added to this array appear in the alias list; however, |
1488 | unsetting array elements currently does not cause aliases to be removed | |
1489 | from the alias list. | |
1490 | If | |
1491 | .B BASH_ALIASES | |
1492 | is unset, it loses its special properties, even if it is | |
1493 | subsequently reset. | |
3185942a | 1494 | .TP |
b80f6443 JA |
1495 | .B BASH_ARGC |
1496 | An array variable whose values are the number of parameters in each | |
3185942a | 1497 | frame of the current \fBbash\fP execution call stack. |
95732b49 | 1498 | The number of |
b80f6443 | 1499 | parameters to the current subroutine (shell function or script executed |
95732b49 JA |
1500 | with \fB.\fP or \fBsource\fP) is at the top of the stack. |
1501 | When a subroutine is executed, the number of parameters passed is pushed onto | |
0001803f CR |
1502 | .SM |
1503 | .BR BASH_ARGC . | |
1504 | The shell sets | |
1505 | .SM | |
1506 | .B BASH_ARGC | |
1507 | only when in extended debugging mode (see the description of the | |
95732b49 JA |
1508 | .B extdebug |
1509 | option to the | |
1510 | .B shopt | |
9a51695b | 1511 | builtin below). |
2f5dfe5a CR |
1512 | Setting \fBextdebug\fP after the shell has started to execute a script, |
1513 | or referencing this variable when \fBextdebug\fP is not set, | |
9a51695b | 1514 | may result in inconsistent values. |
b80f6443 JA |
1515 | .TP |
1516 | .B BASH_ARGV | |
3185942a | 1517 | An array variable containing all of the parameters in the current \fBbash\fP |
b80f6443 JA |
1518 | execution call stack. The final parameter of the last subroutine call |
1519 | is at the top of the stack; the first parameter of the initial call is | |
1520 | at the bottom. When a subroutine is executed, the parameters supplied | |
0001803f CR |
1521 | are pushed onto |
1522 | .SM | |
1523 | .BR BASH_ARGV . | |
1524 | The shell sets | |
1525 | .SM | |
1526 | .B BASH_ARGV | |
1527 | only when in extended debugging mode | |
95732b49 JA |
1528 | (see the description of the |
1529 | .B extdebug | |
1530 | option to the | |
1531 | .B shopt | |
9a51695b | 1532 | builtin below). |
2f5dfe5a CR |
1533 | Setting \fBextdebug\fP after the shell has started to execute a script, |
1534 | or referencing this variable when \fBextdebug\fP is not set, | |
9a51695b CR |
1535 | may result in inconsistent values. |
1536 | .TP | |
1537 | .B BASH_ARGV0 | |
1538 | When referenced, this variable expands to the name of the shell or shell | |
1539 | script (identical to | |
1540 | .BR $0 ; | |
1541 | see the description of special parameter 0 above). | |
1542 | Assignment to | |
1543 | .B BASH_ARGV0 | |
1544 | causes the value assigned to also be assigned to \fB$0\fP. | |
1545 | If | |
1546 | .B BASH_ARGV0 | |
1547 | is unset, it loses its special properties, even if it is | |
1548 | subsequently reset. | |
b80f6443 | 1549 | .TP |
3185942a JA |
1550 | .B BASH_CMDS |
1551 | An associative array variable whose members correspond to the internal | |
1552 | hash table of commands as maintained by the \fBhash\fP builtin. | |
a0c0a00f CR |
1553 | Elements added to this array appear in the hash table; however, |
1554 | unsetting array elements currently does not cause command names to be removed | |
1555 | from the hash table. | |
1556 | If | |
1557 | .B BASH_CMDS | |
1558 | is unset, it loses its special properties, even if it is | |
1559 | subsequently reset. | |
3185942a | 1560 | .TP |
b80f6443 JA |
1561 | .B BASH_COMMAND |
1562 | The command currently being executed or about to be executed, unless the | |
1563 | shell is executing a command as the result of a trap, | |
1564 | in which case it is the command executing at the time of the trap. | |
1565 | .TP | |
1566 | .B BASH_EXECUTION_STRING | |
1567 | The command argument to the \fB\-c\fP invocation option. | |
1568 | .TP | |
1569 | .B BASH_LINENO | |
1570 | An array variable whose members are the line numbers in source files | |
495aee44 | 1571 | where each corresponding member of |
0001803f | 1572 | .SM |
495aee44 CR |
1573 | .B FUNCNAME |
1574 | was invoked. | |
b80f6443 | 1575 | \fB${BASH_LINENO[\fP\fI$i\fP\fB]}\fP is the line number in the source |
495aee44 CR |
1576 | file (\fB${BASH_SOURCE[\fP\fI$i+1\fP\fB]}\fP) where |
1577 | \fB${FUNCNAME[\fP\fI$i\fP\fB]}\fP was called | |
3185942a JA |
1578 | (or \fB${BASH_LINENO[\fP\fI$i-1\fP\fB]}\fP if referenced within another |
1579 | shell function). | |
0001803f CR |
1580 | Use |
1581 | .SM | |
1582 | .B LINENO | |
1583 | to obtain the current line number. | |
b80f6443 | 1584 | .TP |
a0c0a00f CR |
1585 | .B BASH_LOADABLES_PATH |
1586 | A colon-separated list of directories in which the shell looks for | |
1587 | dynamically loadable builtins specified by the | |
1588 | .B enable | |
1589 | command. | |
1590 | .TP | |
b80f6443 JA |
1591 | .B BASH_REMATCH |
1592 | An array variable whose members are assigned by the \fB=~\fP binary | |
1593 | operator to the \fB[[\fP conditional command. | |
1594 | The element with index 0 is the portion of the string | |
1595 | matching the entire regular expression. | |
1596 | The element with index \fIn\fP is the portion of the | |
1597 | string matching the \fIn\fPth parenthesized subexpression. | |
1598 | This variable is read-only. | |
1599 | .TP | |
1600 | .B BASH_SOURCE | |
495aee44 CR |
1601 | An array variable whose members are the source filenames |
1602 | where the corresponding shell function names in the | |
0001803f CR |
1603 | .SM |
1604 | .B FUNCNAME | |
495aee44 CR |
1605 | array variable are defined. |
1606 | The shell function | |
1607 | \fB${FUNCNAME[\fP\fI$i\fP\fB]}\fP is defined in the file | |
1608 | \fB${BASH_SOURCE[\fP\fI$i\fP\fB]}\fP and called from | |
1609 | \fB${BASH_SOURCE[\fP\fI$i+1\fP\fB]}\fP. | |
b80f6443 JA |
1610 | .TP |
1611 | .B BASH_SUBSHELL | |
ac50fbac CR |
1612 | Incremented by one within each subshell or subshell environment when |
1613 | the shell begins executing in that environment. | |
b80f6443 JA |
1614 | The initial value is 0. |
1615 | .TP | |
ccc6cda3 | 1616 | .B BASH_VERSINFO |
cce855bc JA |
1617 | A readonly array variable whose members hold version information for |
1618 | this instance of | |
ccc6cda3 JA |
1619 | .BR bash . |
1620 | The values assigned to the array members are as follows: | |
1621 | .sp .5 | |
1622 | .RS | |
ccc6cda3 JA |
1623 | .TP 24 |
1624 | .B BASH_VERSINFO[\fR0\fP] | |
1625 | The major version number (the \fIrelease\fP). | |
1626 | .TP | |
1627 | .B BASH_VERSINFO[\fR1\fP] | |
1628 | The minor version number (the \fIversion\fP). | |
1629 | .TP | |
1630 | .B BASH_VERSINFO[\fR2\fP] | |
1631 | The patch level. | |
1632 | .TP | |
1633 | .B BASH_VERSINFO[\fR3\fP] | |
1634 | The build version. | |
1635 | .TP | |
1636 | .B BASH_VERSINFO[\fR4\fP] | |
1637 | The release status (e.g., \fIbeta1\fP). | |
1638 | .TP | |
1639 | .B BASH_VERSINFO[\fR5\fP] | |
0001803f CR |
1640 | The value of |
1641 | .SM | |
1642 | .BR MACHTYPE . | |
ccc6cda3 JA |
1643 | .RE |
1644 | .TP | |
f73dda09 JA |
1645 | .B BASH_VERSION |
1646 | Expands to a string describing the version of this instance of | |
1647 | .BR bash . | |
726f6388 | 1648 | .TP |
f73dda09 JA |
1649 | .B COMP_CWORD |
1650 | An index into \fB${COMP_WORDS}\fP of the word containing the current | |
1651 | cursor position. | |
1652 | This variable is available only in shell functions invoked by the | |
1653 | programmable completion facilities (see \fBProgrammable Completion\fP | |
1654 | below). | |
1655 | .TP | |
3185942a JA |
1656 | .B COMP_KEY |
1657 | The key (or final key of a key sequence) used to invoke the current | |
1658 | completion function. | |
1659 | .TP | |
f73dda09 JA |
1660 | .B COMP_LINE |
1661 | The current command line. | |
1662 | This variable is available only in shell functions and external | |
1663 | commands invoked by the | |
1664 | programmable completion facilities (see \fBProgrammable Completion\fP | |
1665 | below). | |
1666 | .TP | |
1667 | .B COMP_POINT | |
1668 | The index of the current cursor position relative to the beginning of | |
1669 | the current command. | |
1670 | If the current cursor position is at the end of the current command, | |
1671 | the value of this variable is equal to \fB${#COMP_LINE}\fP. | |
1672 | This variable is available only in shell functions and external | |
1673 | commands invoked by the | |
1674 | programmable completion facilities (see \fBProgrammable Completion\fP | |
1675 | below). | |
1676 | .TP | |
3185942a JA |
1677 | .B COMP_TYPE |
1678 | Set to an integer value corresponding to the type of completion attempted | |
1679 | that caused a completion function to be called: | |
1680 | \fITAB\fP, for normal completion, | |
1681 | \fI?\fP, for listing completions after successive tabs, | |
1682 | \fI!\fP, for listing alternatives on partial word completion, | |
1683 | \fI@\fP, to list completions if the word is not unmodified, | |
1684 | or | |
1685 | \fI%\fP, for menu completion. | |
1686 | This variable is available only in shell functions and external | |
1687 | commands invoked by the | |
1688 | programmable completion facilities (see \fBProgrammable Completion\fP | |
1689 | below). | |
1690 | .TP | |
b80f6443 | 1691 | .B COMP_WORDBREAKS |
17345e5a | 1692 | The set of characters that the \fBreadline\fP library treats as word |
b80f6443 JA |
1693 | separators when performing word completion. |
1694 | If | |
1695 | .SM | |
1696 | .B COMP_WORDBREAKS | |
1697 | is unset, it loses its special properties, even if it is | |
1698 | subsequently reset. | |
1699 | .TP | |
f73dda09 JA |
1700 | .B COMP_WORDS |
1701 | An array variable (see \fBArrays\fP below) consisting of the individual | |
1702 | words in the current command line. | |
17345e5a | 1703 | The line is split into words as \fBreadline\fP would split it, using |
0001803f CR |
1704 | .SM |
1705 | .B COMP_WORDBREAKS | |
1706 | as described above. | |
f73dda09 JA |
1707 | This variable is available only in shell functions invoked by the |
1708 | programmable completion facilities (see \fBProgrammable Completion\fP | |
1709 | below). | |
1710 | .TP | |
495aee44 CR |
1711 | .B COPROC |
1712 | An array variable (see \fBArrays\fP below) created to hold the file descriptors | |
1713 | for output from and input to an unnamed coprocess (see \fBCoprocesses\fP | |
1714 | above). | |
1715 | .TP | |
f73dda09 JA |
1716 | .B DIRSTACK |
1717 | An array variable (see | |
1718 | .B Arrays | |
1719 | below) containing the current contents of the directory stack. | |
1720 | Directories appear in the stack in the order they are displayed by the | |
1721 | .B dirs | |
1722 | builtin. | |
1723 | Assigning to members of this array variable may be used to modify | |
1724 | directories already in the stack, but the | |
1725 | .B pushd | |
1726 | and | |
1727 | .B popd | |
1728 | builtins must be used to add and remove directories. | |
1729 | Assignment to this variable will not change the current directory. | |
726f6388 JA |
1730 | If |
1731 | .SM | |
f73dda09 | 1732 | .B DIRSTACK |
726f6388 JA |
1733 | is unset, it loses its special properties, even if it is |
1734 | subsequently reset. | |
1735 | .TP | |
9a51695b CR |
1736 | .B EPOCHREALTIME |
1737 | Each time this parameter is referenced, it expands to the number of seconds | |
1738 | since the Unix Epoch (see \fItime\fP\fR(3)\fP) as a floating point value | |
1739 | with micro-second granularity. | |
1740 | Assignments to | |
1741 | .SM | |
1742 | .B EPOCHREALTIME | |
1743 | are ignored. | |
1744 | If | |
1745 | .SM | |
1746 | .B EPOCHREALTIME | |
1747 | is unset, it loses its special properties, even if it is | |
1748 | subsequently reset. | |
1749 | .TP | |
1750 | .B EPOCHSECONDS | |
1751 | Each time this parameter is referenced, it expands to the number of seconds | |
1752 | since the Unix Epoch (see \fItime\fP\fR(3)\fP). | |
1753 | Assignments to | |
1754 | .SM | |
1755 | .B EPOCHSECONDS | |
1756 | are ignored. | |
1757 | If | |
1758 | .SM | |
1759 | .B EPOCHSECONDS | |
1760 | is unset, it loses its special properties, even if it is | |
1761 | subsequently reset. | |
1762 | .TP | |
f73dda09 JA |
1763 | .B EUID |
1764 | Expands to the effective user ID of the current user, initialized at | |
1765 | shell startup. This variable is readonly. | |
1766 | .TP | |
1767 | .B FUNCNAME | |
b80f6443 JA |
1768 | An array variable containing the names of all shell functions |
1769 | currently in the execution call stack. | |
1770 | The element with index 0 is the name of any currently-executing | |
1771 | shell function. | |
495aee44 | 1772 | The bottom-most element (the one with the highest index) is |
3185942a JA |
1773 | .if t \f(CW"main"\fP. |
1774 | .if n "main". | |
f73dda09 JA |
1775 | This variable exists only when a shell function is executing. |
1776 | Assignments to | |
726f6388 | 1777 | .SM |
f73dda09 | 1778 | .B FUNCNAME |
a0c0a00f | 1779 | have no effect. |
726f6388 JA |
1780 | If |
1781 | .SM | |
f73dda09 | 1782 | .B FUNCNAME |
726f6388 JA |
1783 | is unset, it loses its special properties, even if it is |
1784 | subsequently reset. | |
495aee44 CR |
1785 | .if t .sp 0.5 |
1786 | .if n .sp 1 | |
1787 | This variable can be used with \fBBASH_LINENO\fP and \fBBASH_SOURCE\fP. | |
1788 | Each element of \fBFUNCNAME\fP has corresponding elements in | |
1789 | \fBBASH_LINENO\fP and \fBBASH_SOURCE\fP to describe the call stack. | |
1790 | For instance, \fB${FUNCNAME[\fP\fI$i\fP\fB]}\fP was called from the file | |
1791 | \fB${BASH_SOURCE[\fP\fI$i+1\fP\fB]}\fP at line number | |
1792 | \fB${BASH_LINENO[\fP\fI$i\fP\fB]}\fP. | |
1793 | The \fBcaller\fP builtin displays the current call stack using this | |
1794 | information. | |
726f6388 | 1795 | .TP |
f73dda09 JA |
1796 | .B GROUPS |
1797 | An array variable containing the list of groups of which the current | |
1798 | user is a member. | |
a0c0a00f | 1799 | Assignments to |
f73dda09 JA |
1800 | .SM |
1801 | .B GROUPS | |
a0c0a00f | 1802 | have no effect. |
726f6388 JA |
1803 | If |
1804 | .SM | |
f73dda09 | 1805 | .B GROUPS |
726f6388 JA |
1806 | is unset, it loses its special properties, even if it is |
1807 | subsequently reset. | |
1808 | .TP | |
1809 | .B HISTCMD | |
1810 | The history number, or index in the history list, of the current | |
ccc6cda3 JA |
1811 | command. |
1812 | If | |
726f6388 JA |
1813 | .SM |
1814 | .B HISTCMD | |
1815 | is unset, it loses its special properties, even if it is | |
1816 | subsequently reset. | |
1817 | .TP | |
f73dda09 JA |
1818 | .B HOSTNAME |
1819 | Automatically set to the name of the current host. | |
bb70624e | 1820 | .TP |
f73dda09 JA |
1821 | .B HOSTTYPE |
1822 | Automatically set to a string that uniquely | |
1823 | describes the type of machine on which | |
1824 | .B bash | |
1825 | is executing. | |
1826 | The default is system-dependent. | |
1827 | .TP | |
1828 | .B LINENO | |
1829 | Each time this parameter is referenced, the shell substitutes | |
1830 | a decimal number representing the current sequential line number | |
1831 | (starting with 1) within a script or function. When not in a | |
1832 | script or function, the value substituted is not guaranteed to | |
1833 | be meaningful. | |
ccc6cda3 JA |
1834 | If |
1835 | .SM | |
f73dda09 | 1836 | .B LINENO |
ccc6cda3 JA |
1837 | is unset, it loses its special properties, even if it is |
1838 | subsequently reset. | |
1839 | .TP | |
f73dda09 JA |
1840 | .B MACHTYPE |
1841 | Automatically set to a string that fully describes the system | |
1842 | type on which | |
1843 | .B bash | |
1844 | is executing, in the standard GNU \fIcpu-company-system\fP format. | |
1845 | The default is system-dependent. | |
1846 | .TP | |
495aee44 CR |
1847 | .B MAPFILE |
1848 | An array variable (see \fBArrays\fP below) created to hold the text | |
1849 | read by the \fBmapfile\fP builtin when no variable name is supplied. | |
1850 | .TP | |
f73dda09 JA |
1851 | .B OLDPWD |
1852 | The previous working directory as set by the | |
1853 | .B cd | |
1854 | command. | |
ccc6cda3 | 1855 | .TP |
726f6388 JA |
1856 | .B OPTARG |
1857 | The value of the last option argument processed by the | |
1858 | .B getopts | |
1859 | builtin command (see | |
1860 | .SM | |
1861 | .B SHELL BUILTIN COMMANDS | |
1862 | below). | |
1863 | .TP | |
1864 | .B OPTIND | |
1865 | The index of the next argument to be processed by the | |
1866 | .B getopts | |
1867 | builtin command (see | |
1868 | .SM | |
1869 | .B SHELL BUILTIN COMMANDS | |
1870 | below). | |
1871 | .TP | |
726f6388 JA |
1872 | .B OSTYPE |
1873 | Automatically set to a string that | |
1874 | describes the operating system on which | |
1875 | .B bash | |
ccc6cda3 JA |
1876 | is executing. |
1877 | The default is system-dependent. | |
1878 | .TP | |
f73dda09 JA |
1879 | .B PIPESTATUS |
1880 | An array variable (see | |
1881 | .B Arrays | |
1882 | below) containing a list of exit status values from the processes | |
1883 | in the most-recently-executed foreground pipeline (which may | |
1884 | contain only a single command). | |
ccc6cda3 | 1885 | .TP |
f73dda09 JA |
1886 | .B PPID |
1887 | The process ID of the shell's parent. This variable is readonly. | |
1888 | .TP | |
1889 | .B PWD | |
1890 | The current working directory as set by the | |
1891 | .B cd | |
1892 | command. | |
1893 | .TP | |
1894 | .B RANDOM | |
1895 | Each time this parameter is referenced, a random integer between | |
1896 | 0 and 32767 is | |
1897 | generated. The sequence of random numbers may be initialized by assigning | |
1898 | a value to | |
1899 | .SM | |
1900 | .BR RANDOM . | |
1901 | If | |
1902 | .SM | |
1903 | .B RANDOM | |
1904 | is unset, it loses its special properties, even if it is | |
1905 | subsequently reset. | |
1906 | .TP | |
495aee44 CR |
1907 | .B READLINE_LINE |
1908 | The contents of the | |
1909 | .B readline | |
1910 | line buffer, for use with | |
1911 | .if t \f(CWbind -x\fP | |
1912 | .if n "bind -x" | |
1913 | (see | |
1914 | .SM | |
1915 | .B "SHELL BUILTIN COMMANDS" | |
1916 | below). | |
1917 | .TP | |
1918 | .B READLINE_POINT | |
1919 | The position of the insertion point in the | |
1920 | .B readline | |
1921 | line buffer, for use with | |
1922 | .if t \f(CWbind -x\fP | |
1923 | .if n "bind -x" | |
1924 | (see | |
1925 | .SM | |
1926 | .B "SHELL BUILTIN COMMANDS" | |
1927 | below). | |
1928 | .TP | |
f73dda09 JA |
1929 | .B REPLY |
1930 | Set to the line of input read by the | |
1931 | .B read | |
1932 | builtin command when no arguments are supplied. | |
1933 | .TP | |
1934 | .B SECONDS | |
1935 | Each time this parameter is | |
1936 | referenced, the number of seconds since shell invocation is returned. If a | |
a0c0a00f | 1937 | value is assigned to |
f73dda09 JA |
1938 | .SM |
1939 | .BR SECONDS , | |
1940 | the value returned upon subsequent | |
1941 | references is | |
1942 | the number of seconds since the assignment plus the value assigned. | |
1943 | If | |
1944 | .SM | |
1945 | .B SECONDS | |
1946 | is unset, it loses its special properties, even if it is | |
1947 | subsequently reset. | |
1948 | .TP | |
1949 | .B SHELLOPTS | |
1950 | A colon-separated list of enabled shell options. Each word in | |
1951 | the list is a valid argument for the | |
1952 | .B \-o | |
1953 | option to the | |
1954 | .B set | |
1955 | builtin command (see | |
1956 | .SM | |
1957 | .B "SHELL BUILTIN COMMANDS" | |
1958 | below). The options appearing in | |
ccc6cda3 JA |
1959 | .SM |
1960 | .B SHELLOPTS | |
1961 | are those reported as | |
1962 | .I on | |
1963 | by \fBset \-o\fP. | |
1964 | If this variable is in the environment when | |
1965 | .B bash | |
1966 | starts up, each shell option in the list will be enabled before | |
1967 | reading any startup files. | |
1968 | This variable is read-only. | |
bb70624e | 1969 | .TP |
f73dda09 JA |
1970 | .B SHLVL |
1971 | Incremented by one each time an instance of | |
1972 | .B bash | |
1973 | is started. | |
bb70624e | 1974 | .TP |
f73dda09 JA |
1975 | .B UID |
1976 | Expands to the user ID of the current user, initialized at shell startup. | |
1977 | This variable is readonly. | |
726f6388 JA |
1978 | .PD |
1979 | .PP | |
1980 | The following variables are used by the shell. In some cases, | |
1981 | .B bash | |
1982 | assigns a default value to a variable; these cases are noted | |
1983 | below. | |
1984 | .PP | |
1985 | .PD 0 | |
1986 | .TP | |
ac50fbac CR |
1987 | .B BASH_COMPAT |
1988 | The value is used to set the shell's compatibility level. | |
1989 | See the description of the \fBshopt\fP builtin below under | |
1990 | \fBSHELL BUILTIN COMMANDS\fP | |
1991 | for a description of the various compatibility | |
1992 | levels and their effects. | |
1993 | The value may be a decimal number (e.g., 4.2) or an integer (e.g., 42) | |
1994 | corresponding to the desired compatibility level. | |
1995 | If \fBBASH_COMPAT\fP is unset or set to the empty string, the compatibility | |
1996 | level is set to the default for the current version. | |
1997 | If \fBBASH_COMPAT\fP is set to a value that is not one of the valid | |
1998 | compatibility levels, the shell prints an error message and sets the | |
1999 | compatibility level to the default for the current version. | |
2000 | The valid compatibility levels correspond to the compatibility options | |
2001 | accepted by the \fBshopt\fP builtin described below (for example, | |
2002 | \fBcompat42\fP means that 4.2 and 42 are valid values). | |
2003 | The current version is also a valid value. | |
2004 | .TP | |
d166f048 | 2005 | .B BASH_ENV |
726f6388 JA |
2006 | If this parameter is set when \fBbash\fP is executing a shell script, |
2007 | its value is interpreted as a filename containing commands to | |
2008 | initialize the shell, as in | |
cce855bc | 2009 | .IR ~/.bashrc . |
726f6388 JA |
2010 | The value of |
2011 | .SM | |
d166f048 | 2012 | .B BASH_ENV |
726f6388 | 2013 | is subjected to parameter expansion, command substitution, and arithmetic |
ac50fbac | 2014 | expansion before being interpreted as a filename. |
726f6388 JA |
2015 | .SM |
2016 | .B PATH | |
ac50fbac | 2017 | is not used to search for the resultant filename. |
726f6388 | 2018 | .TP |
0001803f CR |
2019 | .B BASH_XTRACEFD |
2020 | If set to an integer corresponding to a valid file descriptor, \fBbash\fP | |
2021 | will write the trace output generated when | |
2022 | .if t \f(CWset -x\fP | |
2023 | .if n \fIset -x\fP | |
2024 | is enabled to that file descriptor. | |
2025 | The file descriptor is closed when | |
2026 | .SM | |
2027 | .B BASH_XTRACEFD | |
2028 | is unset or assigned a new value. | |
2029 | Unsetting | |
2030 | .SM | |
2031 | .B BASH_XTRACEFD | |
2032 | or assigning it the empty string causes the | |
2033 | trace output to be sent to the standard error. | |
2034 | Note that setting | |
2035 | .SM | |
2036 | .B BASH_XTRACEFD | |
2037 | to 2 (the standard error file | |
2038 | descriptor) and then unsetting it will result in the standard error | |
2039 | being closed. | |
2040 | .TP | |
495aee44 CR |
2041 | .B CDPATH |
2042 | The search path for the | |
2043 | .B cd | |
2044 | command. | |
2045 | This is a colon-separated list of directories in which the shell looks | |
2046 | for destination directories specified by the | |
2047 | .B cd | |
2048 | command. | |
2049 | A sample value is | |
2050 | .if t \f(CW".:~:/usr"\fP. | |
2051 | .if n ".:~:/usr". | |
2052 | .TP | |
ac50fbac CR |
2053 | .B CHILD_MAX |
2054 | Set the number of exited child status values for the shell to remember. | |
2055 | Bash will not allow this value to be decreased below a POSIX-mandated | |
2056 | minimum, and there is a maximum value (currently 8192) that this may | |
2057 | not exceed. | |
2058 | The minimum value is system-dependent. | |
2059 | .TP | |
f73dda09 | 2060 | .B COLUMNS |
495aee44 | 2061 | Used by the \fBselect\fP compound command to determine the terminal width |
ac50fbac CR |
2062 | when printing selection lists. |
2063 | Automatically set if the | |
2064 | .B checkwinsize | |
2065 | option is enabled or in an interactive shell upon receipt of a | |
495aee44 CR |
2066 | .SM |
2067 | .BR SIGWINCH . | |
726f6388 | 2068 | .TP |
f73dda09 JA |
2069 | .B COMPREPLY |
2070 | An array variable from which \fBbash\fP reads the possible completions | |
2071 | generated by a shell function invoked by the programmable completion | |
2072 | facility (see \fBProgrammable Completion\fP below). | |
ac50fbac | 2073 | Each array element contains one possible completion. |
726f6388 | 2074 | .TP |
b80f6443 JA |
2075 | .B EMACS |
2076 | If \fBbash\fP finds this variable in the environment when the shell starts | |
2077 | with value | |
2078 | .if t \f(CWt\fP, | |
2079 | .if n "t", | |
495aee44 | 2080 | it assumes that the shell is running in an Emacs shell buffer and disables |
b80f6443 JA |
2081 | line editing. |
2082 | .TP | |
495aee44 CR |
2083 | .B ENV |
2084 | Similar to | |
2085 | .SM | |
2086 | .BR BASH_ENV ; | |
2f5dfe5a | 2087 | used when the shell is invoked in \fIposix mode\fP. |
495aee44 | 2088 | .TP |
a0c0a00f CR |
2089 | .B EXECIGNORE |
2090 | A colon-separated list of shell patterns (see \fBPattern Matching\fP) | |
2091 | defining the list of filenames to be ignored by command search using | |
2092 | \fBPATH\fP. | |
2093 | Files whose full pathnames match one of these patterns are not considered | |
2094 | executable files for the purposes of completion and command execution | |
2095 | via \fBPATH\fP lookup. | |
2096 | This does not affect the behavior of the \fB[\fP, \fBtest\fP, and \fB[[\fP | |
2097 | commands. | |
2098 | Full pathnames in the command hash table are not subject to \fBEXECIGNORE\fP. | |
2099 | Use this variable to ignore shared library files that have the executable | |
2100 | bit set, but are not executable files. | |
2101 | The pattern matching honors the setting of the \fBextglob\fP shell | |
2102 | option. | |
2103 | .TP | |
f73dda09 JA |
2104 | .B FCEDIT |
2105 | The default editor for the | |
2106 | .B fc | |
2107 | builtin command. | |
726f6388 | 2108 | .TP |
f73dda09 JA |
2109 | .B FIGNORE |
2110 | A colon-separated list of suffixes to ignore when performing | |
2111 | filename completion (see | |
726f6388 | 2112 | .SM |
f73dda09 JA |
2113 | .B READLINE |
2114 | below). | |
2115 | A filename whose suffix matches one of the entries in | |
726f6388 | 2116 | .SM |
f73dda09 JA |
2117 | .B FIGNORE |
2118 | is excluded from the list of matched filenames. | |
7117c2d2 JA |
2119 | A sample value is |
2120 | .if t \f(CW".o:~"\fP. | |
2121 | .if n ".o:~". | |
ccc6cda3 | 2122 | .TP |
495aee44 CR |
2123 | .B FUNCNEST |
2124 | If set to a numeric value greater than 0, defines a maximum function | |
2125 | nesting level. Function invocations that exceed this nesting level | |
2126 | will cause the current command to abort. | |
2127 | .TP | |
f73dda09 | 2128 | .B GLOBIGNORE |
9a51695b | 2129 | A colon-separated list of patterns defining the set of file names to |
f73dda09 | 2130 | be ignored by pathname expansion. |
9a51695b | 2131 | If a file name matched by a pathname expansion pattern also matches one |
f73dda09 | 2132 | of the patterns in |
726f6388 | 2133 | .SM |
f73dda09 JA |
2134 | .BR GLOBIGNORE , |
2135 | it is removed from the list of matches. | |
2136 | .TP | |
2137 | .B HISTCONTROL | |
b80f6443 JA |
2138 | A colon-separated list of values controlling how commands are saved on |
2139 | the history list. | |
2140 | If the list of values includes | |
f73dda09 JA |
2141 | .IR ignorespace , |
2142 | lines which begin with a | |
2143 | .B space | |
b80f6443 | 2144 | character are not saved in the history list. |
a0c0a00f | 2145 | A value of |
b80f6443 JA |
2146 | .I ignoredups |
2147 | causes lines matching the previous history entry to not be saved. | |
f73dda09 JA |
2148 | A value of |
2149 | .I ignoreboth | |
b80f6443 JA |
2150 | is shorthand for \fIignorespace\fP and \fIignoredups\fP. |
2151 | A value of | |
9a51695b | 2152 | .I erasedups |
b80f6443 JA |
2153 | causes all previous lines matching the current line to be removed from |
2154 | the history list before that line is saved. | |
2155 | Any value not in the above list is ignored. | |
0001803f CR |
2156 | If |
2157 | .SM | |
2158 | .B HISTCONTROL | |
2159 | is unset, or does not include a valid value, | |
b80f6443 JA |
2160 | all lines read by the shell parser are saved on the history list, |
2161 | subject to the value of | |
0001803f | 2162 | .SM |
f73dda09 JA |
2163 | .BR HISTIGNORE . |
2164 | The second and subsequent lines of a multi-line compound command are | |
2165 | not tested, and are added to the history regardless of the value of | |
0001803f | 2166 | .SM |
f73dda09 | 2167 | .BR HISTCONTROL . |
726f6388 JA |
2168 | .TP |
2169 | .B HISTFILE | |
ccc6cda3 | 2170 | The name of the file in which command history is saved (see |
726f6388 JA |
2171 | .SM |
2172 | .B HISTORY | |
ccc6cda3 | 2173 | below). The default value is \fI~/.bash_history\fP. If unset, the |
ac50fbac | 2174 | command history is not saved when a shell exits. |
726f6388 JA |
2175 | .TP |
2176 | .B HISTFILESIZE | |
2177 | The maximum number of lines contained in the history file. When this | |
2178 | variable is assigned a value, the history file is truncated, if | |
ac50fbac CR |
2179 | necessary, |
2180 | to contain no more than that number of lines by removing the oldest entries. | |
2181 | The history file is also truncated to this size after | |
2182 | writing it when a shell exits. | |
2183 | If the value is 0, the history file is truncated to zero size. | |
2184 | Non-numeric values and numeric values less than zero inhibit truncation. | |
2185 | The shell sets the default value to the value of \fBHISTSIZE\fP | |
2186 | after reading any startup files. | |
726f6388 | 2187 | .TP |
f73dda09 JA |
2188 | .B HISTIGNORE |
2189 | A colon-separated list of patterns used to decide which command lines | |
2190 | should be saved on the history list. Each pattern is anchored at the | |
2191 | beginning of the line and must match the complete line (no implicit | |
2192 | `\fB*\fP' is appended). Each pattern is tested against the line | |
2193 | after the checks specified by | |
0001803f | 2194 | .SM |
f73dda09 JA |
2195 | .B HISTCONTROL |
2196 | are applied. | |
2197 | In addition to the normal shell pattern matching characters, `\fB&\fP' | |
2198 | matches the previous history line. `\fB&\fP' may be escaped using a | |
2199 | backslash; the backslash is removed before attempting a match. | |
2200 | The second and subsequent lines of a multi-line compound command are | |
2201 | not tested, and are added to the history regardless of the value of | |
0001803f | 2202 | .SM |
f73dda09 | 2203 | .BR HISTIGNORE . |
a0c0a00f CR |
2204 | The pattern matching honors the setting of the \fBextglob\fP shell |
2205 | option. | |
f73dda09 JA |
2206 | .TP |
2207 | .B HISTSIZE | |
2208 | The number of commands to remember in the command history (see | |
2209 | .SM | |
2210 | .B HISTORY | |
ac50fbac CR |
2211 | below). |
2212 | If the value is 0, commands are not saved in the history list. | |
2213 | Numeric values less than zero result in every command being saved | |
2214 | on the history list (there is no limit). | |
2215 | The shell sets the default value to 500 after reading any startup files. | |
f73dda09 | 2216 | .TP |
b80f6443 JA |
2217 | .B HISTTIMEFORMAT |
2218 | If this variable is set and not null, its value is used as a format string | |
2219 | for \fIstrftime\fP(3) to print the time stamp associated with each history | |
2220 | entry displayed by the \fBhistory\fP builtin. | |
2221 | If this variable is set, time stamps are written to the history file so | |
2222 | they may be preserved across shell sessions. | |
3185942a JA |
2223 | This uses the history comment character to distinguish timestamps from |
2224 | other history lines. | |
b80f6443 | 2225 | .TP |
f73dda09 JA |
2226 | .B HOME |
2227 | The home directory of the current user; the default argument for the | |
2228 | \fBcd\fP builtin command. | |
2229 | The value of this variable is also used when performing tilde expansion. | |
2230 | .TP | |
2231 | .B HOSTFILE | |
2232 | Contains the name of a file in the same format as | |
2233 | .FN /etc/hosts | |
2234 | that should be read when the shell needs to complete a | |
2235 | hostname. | |
2236 | The list of possible hostname completions may be changed while the | |
2237 | shell is running; | |
2238 | the next time hostname completion is attempted after the | |
2239 | value is changed, | |
726f6388 | 2240 | .B bash |
f73dda09 JA |
2241 | adds the contents of the new file to the existing list. |
2242 | If | |
726f6388 | 2243 | .SM |
f73dda09 | 2244 | .B HOSTFILE |
0001803f CR |
2245 | is set, but has no value, or does not name a readable file, |
2246 | \fBbash\fP attempts to read | |
f73dda09 JA |
2247 | .FN /etc/hosts |
2248 | to obtain the list of possible hostname completions. | |
2249 | When | |
726f6388 | 2250 | .SM |
f73dda09 JA |
2251 | .B HOSTFILE |
2252 | is unset, the hostname list is cleared. | |
2253 | .TP | |
2254 | .B IFS | |
2255 | The | |
2256 | .I Internal Field Separator | |
2257 | that is used | |
2258 | for word splitting after expansion and to | |
2259 | split lines into words with the | |
2260 | .B read | |
2261 | builtin command. The default value is | |
2262 | ``<space><tab><newline>''. | |
2263 | .TP | |
2264 | .B IGNOREEOF | |
2265 | Controls the | |
2266 | action of an interactive shell on receipt of an | |
2267 | .SM | |
2268 | .B EOF | |
2269 | character as the sole input. If set, the value is the number of | |
2270 | consecutive | |
2271 | .SM | |
2272 | .B EOF | |
2273 | characters which must be | |
2274 | typed as the first characters on an input line before | |
2275 | .B bash | |
2276 | exits. If the variable exists but does not have a numeric value, or | |
2277 | has no value, the default value is 10. If it does not exist, | |
2278 | .SM | |
2279 | .B EOF | |
2280 | signifies the end of input to the shell. | |
2281 | .TP | |
2282 | .B INPUTRC | |
2283 | The filename for the | |
2284 | .B readline | |
2285 | startup file, overriding the default of | |
2286 | .FN ~/.inputrc | |
2287 | (see | |
2288 | .SM | |
2289 | .B READLINE | |
2290 | below). | |
726f6388 | 2291 | .TP |
2f5dfe5a CR |
2292 | .B INSIDE_EMACS |
2293 | If this variable appears in the environment when the shell starts, | |
2294 | \fBbash\fP assumes that it is running inside an Emacs shell buffer | |
2295 | and may disable line editing, depending on the value of \fBTERM\fP. | |
2296 | .TP | |
ccc6cda3 JA |
2297 | .B LANG |
2298 | Used to determine the locale category for any category not specifically | |
2299 | selected with a variable starting with \fBLC_\fP. | |
2300 | .TP | |
2301 | .B LC_ALL | |
0001803f CR |
2302 | This variable overrides the value of |
2303 | .SM | |
2304 | .B LANG | |
2305 | and any other | |
ccc6cda3 JA |
2306 | \fBLC_\fP variable specifying a locale category. |
2307 | .TP | |
2308 | .B LC_COLLATE | |
2309 | This variable determines the collation order used when sorting the | |
cce855bc JA |
2310 | results of pathname expansion, and determines the behavior of range |
2311 | expressions, equivalence classes, and collating sequences within | |
2312 | pathname expansion and pattern matching. | |
2313 | .TP | |
2314 | .B LC_CTYPE | |
2315 | This variable determines the interpretation of characters and the | |
2316 | behavior of character classes within pathname expansion and pattern | |
2317 | matching. | |
ccc6cda3 JA |
2318 | .TP |
2319 | .B LC_MESSAGES | |
2320 | This variable determines the locale used to translate double-quoted | |
2321 | strings preceded by a \fB$\fP. | |
2322 | .TP | |
bb70624e JA |
2323 | .B LC_NUMERIC |
2324 | This variable determines the locale category used for number formatting. | |
2325 | .TP | |
a0c0a00f CR |
2326 | .B LC_TIME |
2327 | This variable determines the locale category used for data and time | |
2328 | formatting. | |
2329 | .TP | |
28ef6c31 | 2330 | .B LINES |
495aee44 | 2331 | Used by the \fBselect\fP compound command to determine the column length |
ac50fbac CR |
2332 | for printing selection lists. |
2333 | Automatically set if the | |
2334 | .B checkwinsize | |
2335 | option is enabled or in an interactive shell upon receipt of a | |
0001803f CR |
2336 | .SM |
2337 | .BR SIGWINCH . | |
28ef6c31 | 2338 | .TP |
f73dda09 | 2339 | .B MAIL |
495aee44 | 2340 | If this parameter is set to a file or directory name and the |
726f6388 | 2341 | .SM |
f73dda09 JA |
2342 | .B MAILPATH |
2343 | variable is not set, | |
726f6388 | 2344 | .B bash |
495aee44 CR |
2345 | informs the user of the arrival of mail in the specified file or |
2346 | Maildir-format directory. | |
726f6388 | 2347 | .TP |
f73dda09 JA |
2348 | .B MAILCHECK |
2349 | Specifies how | |
2350 | often (in seconds) | |
2351 | .B bash | |
2352 | checks for mail. The default is 60 seconds. When it is time to check | |
2353 | for mail, the shell does so before displaying the primary prompt. | |
2354 | If this variable is unset, or set to a value that is not a number | |
2355 | greater than or equal to zero, the shell disables mail checking. | |
726f6388 | 2356 | .TP |
f73dda09 | 2357 | .B MAILPATH |
a0c0a00f | 2358 | A colon-separated list of filenames to be checked for mail. |
f73dda09 | 2359 | The message to be printed when mail arrives in a particular file |
ac50fbac | 2360 | may be specified by separating the filename from the message with a `?'. |
f73dda09 | 2361 | When used in the text of the message, \fB$_\fP expands to the name of |
a0c0a00f | 2362 | the current mailfile. |
f73dda09 JA |
2363 | Example: |
2364 | .RS | |
2365 | .PP | |
0628567a | 2366 | \fBMAILPATH\fP=\(aq/var/mail/bfox?"You have mail":~/shell\-mail?"$_ has mail!"\(aq |
f73dda09 JA |
2367 | .PP |
2368 | .B Bash | |
a0c0a00f CR |
2369 | can be configured to supply |
2370 | a default value for this variable (there is no value by default), | |
2371 | but the location of the user | |
f73dda09 JA |
2372 | mail files that it uses is system dependent (e.g., /var/mail/\fB$USER\fP). |
2373 | .RE | |
726f6388 | 2374 | .TP |
f73dda09 JA |
2375 | .B OPTERR |
2376 | If set to the value 1, | |
2377 | .B bash | |
2378 | displays error messages generated by the | |
2379 | .B getopts | |
2380 | builtin command (see | |
726f6388 | 2381 | .SM |
f73dda09 | 2382 | .B SHELL BUILTIN COMMANDS |
ccc6cda3 | 2383 | below). |
726f6388 | 2384 | .SM |
f73dda09 JA |
2385 | .B OPTERR |
2386 | is initialized to 1 each time the shell is invoked or a shell | |
2387 | script is executed. | |
ccc6cda3 | 2388 | .TP |
f73dda09 JA |
2389 | .B PATH |
2390 | The search path for commands. It | |
2391 | is a colon-separated list of directories in which | |
2392 | the shell looks for commands (see | |
ccc6cda3 | 2393 | .SM |
f73dda09 | 2394 | .B COMMAND EXECUTION |
b80f6443 | 2395 | below). |
0001803f CR |
2396 | A zero-length (null) directory name in the value of |
2397 | .SM | |
2398 | .B PATH | |
2399 | indicates the current directory. | |
b80f6443 JA |
2400 | A null directory name may appear as two adjacent colons, or as an initial |
2401 | or trailing colon. | |
2402 | The default path is system-dependent, | |
f73dda09 JA |
2403 | and is set by the administrator who installs |
2404 | .BR bash . | |
2405 | A common value is | |
a0c0a00f | 2406 | .na |
ac50fbac CR |
2407 | .if t \f(CW/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin\fP. |
2408 | .if n ``/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin''. | |
a0c0a00f | 2409 | .ad |
726f6388 | 2410 | .TP |
f73dda09 JA |
2411 | .B POSIXLY_CORRECT |
2412 | If this variable is in the environment when \fBbash\fP starts, the shell | |
2413 | enters \fIposix mode\fP before reading the startup files, as if the | |
2414 | .B \-\-posix | |
2415 | invocation option had been supplied. If it is set while the shell is | |
2416 | running, \fBbash\fP enables \fIposix mode\fP, as if the command | |
2417 | .if t \f(CWset -o posix\fP | |
2418 | .if n \fIset -o posix\fP | |
2419 | had been executed. | |
2f5dfe5a CR |
2420 | When the shell enters \fIposix mode\fP, it sets this variable if it was |
2421 | not already set. | |
726f6388 | 2422 | .TP |
f73dda09 JA |
2423 | .B PROMPT_COMMAND |
2424 | If set, the value is executed as a command prior to issuing each primary | |
2425 | prompt. | |
ccc6cda3 | 2426 | .TP |
3185942a JA |
2427 | .B PROMPT_DIRTRIM |
2428 | If set to a number greater than zero, the value is used as the number of | |
0001803f | 2429 | trailing directory components to retain when expanding the \fB\ew\fP and |
3185942a JA |
2430 | \fB\eW\fP prompt string escapes (see |
2431 | .SM | |
2432 | .B PROMPTING | |
2433 | below). Characters removed are replaced with an ellipsis. | |
2434 | .TP | |
a0c0a00f CR |
2435 | .B PS0 |
2436 | The value of this parameter is expanded (see | |
2437 | .SM | |
2438 | .B PROMPTING | |
2439 | below) and displayed by interactive shells after reading a command | |
2440 | and before the command is executed. | |
2441 | .TP | |
f73dda09 JA |
2442 | .B PS1 |
2443 | The value of this parameter is expanded (see | |
2444 | .SM | |
2445 | .B PROMPTING | |
2446 | below) and used as the primary prompt string. The default value is | |
2447 | ``\fB\es\-\ev\e$ \fP''. | |
726f6388 | 2448 | .TP |
f73dda09 JA |
2449 | .B PS2 |
2450 | The value of this parameter is expanded as with | |
0001803f | 2451 | .SM |
f73dda09 JA |
2452 | .B PS1 |
2453 | and used as the secondary prompt string. The default is | |
2454 | ``\fB> \fP''. | |
2455 | .TP | |
2456 | .B PS3 | |
2457 | The value of this parameter is used as the prompt for the | |
2458 | .B select | |
2459 | command (see | |
726f6388 | 2460 | .SM |
f73dda09 JA |
2461 | .B SHELL GRAMMAR |
2462 | above). | |
726f6388 | 2463 | .TP |
f73dda09 JA |
2464 | .B PS4 |
2465 | The value of this parameter is expanded as with | |
0001803f | 2466 | .SM |
f73dda09 JA |
2467 | .B PS1 |
2468 | and the value is printed before each command | |
726f6388 | 2469 | .B bash |
f73dda09 | 2470 | displays during an execution trace. The first character of |
9a51695b | 2471 | the expanded value of |
bb70624e | 2472 | .SM |
f73dda09 JA |
2473 | .B PS4 |
2474 | is replicated multiple times, as necessary, to indicate multiple | |
2475 | levels of indirection. The default is ``\fB+ \fP''. | |
2476 | .TP | |
b80f6443 JA |
2477 | .B SHELL |
2478 | The full pathname to the shell is kept in this environment variable. | |
2479 | If it is not set when the shell starts, | |
2480 | .B bash | |
2481 | assigns to it the full pathname of the current user's login shell. | |
2482 | .TP | |
f73dda09 JA |
2483 | .B TIMEFORMAT |
2484 | The value of this parameter is used as a format string specifying | |
2485 | how the timing information for pipelines prefixed with the | |
2486 | .B time | |
2487 | reserved word should be displayed. | |
2488 | The \fB%\fP character introduces an escape sequence that is | |
2489 | expanded to a time value or other information. | |
2490 | The escape sequences and their meanings are as follows; the | |
2491 | braces denote optional portions. | |
2492 | .sp .5 | |
2493 | .RS | |
2494 | .PD 0 | |
2495 | .TP 10 | |
2496 | .B %% | |
2497 | A literal \fB%\fP. | |
2498 | .TP | |
2499 | .B %[\fIp\fP][l]R | |
2500 | The elapsed time in seconds. | |
2501 | .TP | |
2502 | .B %[\fIp\fP][l]U | |
2503 | The number of CPU seconds spent in user mode. | |
2504 | .TP | |
2505 | .B %[\fIp\fP][l]S | |
2506 | The number of CPU seconds spent in system mode. | |
2507 | .TP | |
2508 | .B %P | |
2509 | The CPU percentage, computed as (%U + %S) / %R. | |
2510 | .PD | |
2511 | .RE | |
2512 | .IP | |
2513 | The optional \fIp\fP is a digit specifying the \fIprecision\fP, | |
2514 | the number of fractional digits after a decimal point. | |
2515 | A value of 0 causes no decimal point or fraction to be output. | |
2516 | At most three places after the decimal point may be specified; | |
2517 | values of \fIp\fP greater than 3 are changed to 3. | |
2518 | If \fIp\fP is not specified, the value 3 is used. | |
2519 | .IP | |
2520 | The optional \fBl\fP specifies a longer format, including | |
2521 | minutes, of the form \fIMM\fPm\fISS\fP.\fIFF\fPs. | |
2522 | The value of \fIp\fP determines whether or not the fraction is | |
2523 | included. | |
2524 | .IP | |
2525 | If this variable is not set, \fBbash\fP acts as if it had the | |
ac50fbac | 2526 | value \fB$\(aq\enreal\et%3lR\enuser\et%3lU\ensys\et%3lS\(aq\fP. |
f73dda09 JA |
2527 | If the value is null, no timing information is displayed. |
2528 | A trailing newline is added when the format string is displayed. | |
495aee44 | 2529 | .PD 0 |
f73dda09 JA |
2530 | .TP |
2531 | .B TMOUT | |
0001803f CR |
2532 | If set to a value greater than zero, |
2533 | .SM | |
2534 | .B TMOUT | |
2535 | is treated as the | |
7117c2d2 JA |
2536 | default timeout for the \fBread\fP builtin. |
2537 | The \fBselect\fP command terminates if input does not arrive | |
0001803f CR |
2538 | after |
2539 | .SM | |
2540 | .B TMOUT | |
2541 | seconds when input is coming from a terminal. | |
7117c2d2 | 2542 | In an interactive shell, the value is interpreted as the |
ac50fbac CR |
2543 | number of seconds to wait for a line of input after issuing the |
2544 | primary prompt. | |
f73dda09 | 2545 | .B Bash |
ac50fbac CR |
2546 | terminates after waiting for that number of seconds if a complete |
2547 | line of input does not arrive. | |
726f6388 | 2548 | .TP |
95732b49 | 2549 | .B TMPDIR |
495aee44 CR |
2550 | If set, \fBbash\fP uses its value as the name of a directory in which |
2551 | \fBbash\fP creates temporary files for the shell's use. | |
95732b49 | 2552 | .TP |
726f6388 JA |
2553 | .B auto_resume |
2554 | This variable controls how the shell interacts with the user and | |
2555 | job control. If this variable is set, single word simple | |
2556 | commands without redirections are treated as candidates for resumption | |
2557 | of an existing stopped job. There is no ambiguity allowed; if there is | |
2558 | more than one job beginning with the string typed, the job most recently | |
2559 | accessed is selected. The | |
2560 | .I name | |
2561 | of a stopped job, in this context, is the command line used to | |
2562 | start it. | |
2563 | If set to the value | |
2564 | .IR exact , | |
2565 | the string supplied must match the name of a stopped job exactly; | |
2566 | if set to | |
2567 | .IR substring , | |
2568 | the string supplied needs to match a substring of the name of a | |
2569 | stopped job. The | |
2570 | .I substring | |
2571 | value provides functionality analogous to the | |
2572 | .B %? | |
ccc6cda3 | 2573 | job identifier (see |
726f6388 JA |
2574 | .SM |
2575 | .B JOB CONTROL | |
2576 | below). If set to any other value, the supplied string must | |
2577 | be a prefix of a stopped job's name; this provides functionality | |
95732b49 | 2578 | analogous to the \fB%\fP\fIstring\fP job identifier. |
bb70624e | 2579 | .TP |
f73dda09 JA |
2580 | .B histchars |
2581 | The two or three characters which control history expansion | |
2582 | and tokenization (see | |
2583 | .SM | |
2584 | .B HISTORY EXPANSION | |
2585 | below). The first character is the \fIhistory expansion\fP character, | |
2586 | the character which signals the start of a history | |
2587 | expansion, normally `\fB!\fP'. | |
2588 | The second character is the \fIquick substitution\fP | |
2589 | character, which is used as shorthand for re-running the previous | |
2590 | command entered, substituting one string for another in the command. | |
2591 | The default is `\fB^\fP'. | |
2592 | The optional third character is the character | |
2593 | which indicates that the remainder of the line is a comment when found | |
2594 | as the first character of a word, normally `\fB#\fP'. The history | |
2595 | comment character causes history substitution to be skipped for the | |
2596 | remaining words on the line. It does not necessarily cause the shell | |
2597 | parser to treat the rest of the line as a comment. | |
726f6388 | 2598 | .PD |
ccc6cda3 JA |
2599 | .SS Arrays |
2600 | .B Bash | |
3185942a JA |
2601 | provides one-dimensional indexed and associative array variables. |
2602 | Any variable may be used as an indexed array; the | |
ccc6cda3 | 2603 | .B declare |
3185942a JA |
2604 | builtin will explicitly declare an array. |
2605 | There is no maximum | |
ccc6cda3 | 2606 | limit on the size of an array, nor any requirement that members |
3185942a JA |
2607 | be indexed or assigned contiguously. |
2608 | Indexed arrays are referenced using integers (including arithmetic | |
a0c0a00f | 2609 | expressions) and are zero-based; associative arrays are referenced |
3185942a | 2610 | using arbitrary strings. |
ac50fbac | 2611 | Unless otherwise noted, indexed array indices must be non-negative integers. |
ccc6cda3 | 2612 | .PP |
3185942a JA |
2613 | An indexed array is created automatically if any variable is assigned to |
2614 | using the syntax \fIname\fP[\fIsubscript\fP]=\fIvalue\fP. The | |
ccc6cda3 | 2615 | .I subscript |
495aee44 | 2616 | is treated as an arithmetic expression that must evaluate to a number. |
495aee44 | 2617 | To explicitly declare an indexed array, use |
ccc6cda3 JA |
2618 | .B declare \-a \fIname\fP |
2619 | (see | |
2620 | .SM | |
2621 | .B SHELL BUILTIN COMMANDS | |
2622 | below). | |
2623 | .B declare \-a \fIname\fP[\fIsubscript\fP] | |
3185942a JA |
2624 | is also accepted; the \fIsubscript\fP is ignored. |
2625 | .PP | |
2626 | Associative arrays are created using | |
2627 | .BR "declare \-A \fIname\fP" . | |
2628 | .PP | |
2629 | Attributes may be | |
ccc6cda3 JA |
2630 | specified for an array variable using the |
2631 | .B declare | |
2632 | and | |
2633 | .B readonly | |
2634 | builtins. Each attribute applies to all members of an array. | |
2635 | .PP | |
2636 | Arrays are assigned to using compound assignments of the form | |
2637 | \fIname\fP=\fB(\fPvalue\fI1\fP ... value\fIn\fP\fB)\fP, where each | |
3185942a | 2638 | \fIvalue\fP is of the form [\fIsubscript\fP]=\fIstring\fP. |
ac50fbac | 2639 | Indexed array assignments do not require anything but \fIstring\fP. |
3185942a JA |
2640 | When assigning to indexed arrays, if the optional brackets and subscript |
2641 | are supplied, that index is assigned to; | |
ccc6cda3 JA |
2642 | otherwise the index of the element assigned is the last index assigned |
2643 | to by the statement plus one. Indexing starts at zero. | |
3185942a JA |
2644 | .PP |
2645 | When assigning to an associative array, the subscript is required. | |
2646 | .PP | |
ccc6cda3 JA |
2647 | This syntax is also accepted by the |
2648 | .B declare | |
2649 | builtin. Individual array elements may be assigned to using the | |
2650 | \fIname\fP[\fIsubscript\fP]=\fIvalue\fP syntax introduced above. | |
ac50fbac CR |
2651 | When assigning to an indexed array, if |
2652 | .I name | |
2653 | is subscripted by a negative number, that number is | |
2654 | interpreted as relative to one greater than the maximum index of | |
2655 | \fIname\fP, so negative indices count back from the end of the | |
2656 | array, and an index of \-1 references the last element. | |
ccc6cda3 JA |
2657 | .PP |
2658 | Any element of an array may be referenced using | |
2659 | ${\fIname\fP[\fIsubscript\fP]}. The braces are required to avoid | |
2660 | conflicts with pathname expansion. If | |
2661 | \fIsubscript\fP is \fB@\fP or \fB*\fP, the word expands to | |
2662 | all members of \fIname\fP. These subscripts differ only when the | |
2663 | word appears within double quotes. If the word is double-quoted, | |
2664 | ${\fIname\fP[*]} expands to a single | |
2665 | word with the value of each array member separated by the first | |
2666 | character of the | |
2667 | .SM | |
2668 | .B IFS | |
2669 | special variable, and ${\fIname\fP[@]} expands each element of | |
2670 | \fIname\fP to a separate word. When there are no array members, | |
95732b49 JA |
2671 | ${\fIname\fP[@]} expands to nothing. |
2672 | If the double-quoted expansion occurs within a word, the expansion of | |
2673 | the first parameter is joined with the beginning part of the original | |
2674 | word, and the expansion of the last parameter is joined with the last | |
2675 | part of the original word. | |
2676 | This is analogous to the expansion | |
ccc6cda3 JA |
2677 | of the special parameters \fB*\fP and \fB@\fP (see |
2678 | .B Special Parameters | |
2679 | above). ${#\fIname\fP[\fIsubscript\fP]} expands to the length of | |
2680 | ${\fIname\fP[\fIsubscript\fP]}. If \fIsubscript\fP is \fB*\fP or | |
2681 | \fB@\fP, the expansion is the number of elements in the array. | |
ac50fbac CR |
2682 | If the |
2683 | .I subscript | |
2684 | used to reference an element of an indexed array | |
a0c0a00f | 2685 | evaluates to a number less than zero, it is |
ac50fbac CR |
2686 | interpreted as relative to one greater than the maximum index of the array, |
2687 | so negative indices count back from the end of the | |
2688 | array, and an index of \-1 references the last element. | |
ccc6cda3 | 2689 | .PP |
a0c0a00f CR |
2690 | Referencing an array variable without a subscript is equivalent to |
2691 | referencing the array with a subscript of 0. | |
2692 | Any reference to a variable using a valid subscript is legal, and | |
2693 | .B bash | |
2694 | will create an array if necessary. | |
2695 | .PP | |
0001803f CR |
2696 | An array variable is considered set if a subscript has been assigned a |
2697 | value. The null string is a valid value. | |
2698 | .PP | |
ac50fbac CR |
2699 | It is possible to obtain the keys (indices) of an array as well as the values. |
2700 | ${\fB!\fP\fIname\fP[\fI@\fP]} and ${\fB!\fP\fIname\fP[\fI*\fP]} | |
2701 | expand to the indices assigned in array variable \fIname\fP. | |
2702 | The treatment when in double quotes is similar to the expansion of the | |
2703 | special parameters \fI@\fP and \fI*\fP within double quotes. | |
2704 | .PP | |
ccc6cda3 JA |
2705 | The |
2706 | .B unset | |
bb70624e | 2707 | builtin is used to destroy arrays. \fBunset\fP \fIname\fP[\fIsubscript\fP] |
9a51695b CR |
2708 | destroys the array element at index \fIsubscript\fP, |
2709 | for both indexed and associative arrays. | |
ac50fbac | 2710 | Negative subscripts to indexed arrays are interpreted as described above. |
9a51695b | 2711 | Unsetting the last element of an array variable does not unset the variable. |
ccc6cda3 JA |
2712 | \fBunset\fP \fIname\fP, where \fIname\fP is an array, or |
2713 | \fBunset\fP \fIname\fP[\fIsubscript\fP], where | |
2714 | \fIsubscript\fP is \fB*\fP or \fB@\fP, removes the entire array. | |
2715 | .PP | |
9a51695b CR |
2716 | When using a variable name with a subscript as an argument to a command, |
2717 | such as with \fBunset\fP, without using the word expansion syntax | |
2718 | described above, the argument is subject to pathname expansion. | |
2719 | If pathname expansion is not desired, the argument should be quoted. | |
2720 | .PP | |
ccc6cda3 JA |
2721 | The |
2722 | .BR declare , | |
2723 | .BR local , | |
2724 | and | |
2725 | .B readonly | |
2726 | builtins each accept a | |
2727 | .B \-a | |
3185942a JA |
2728 | option to specify an indexed array and a |
2729 | .B \-A | |
2730 | option to specify an associative array. | |
a0c0a00f | 2731 | If both options are supplied, |
495aee44 CR |
2732 | .B \-A |
2733 | takes precedence. | |
3185942a | 2734 | The |
ccc6cda3 JA |
2735 | .B read |
2736 | builtin accepts a | |
2737 | .B \-a | |
2738 | option to assign a list of words read from the standard input | |
2739 | to an array. The | |
2740 | .B set | |
2741 | and | |
2742 | .B declare | |
2743 | builtins display array values in a way that allows them to be | |
2744 | reused as assignments. | |
726f6388 JA |
2745 | .SH EXPANSION |
2746 | Expansion is performed on the command line after it has been split into | |
2747 | words. There are seven kinds of expansion performed: | |
2748 | .IR "brace expansion" , | |
2749 | .IR "tilde expansion" , | |
2750 | .IR "parameter and variable expansion" , | |
2751 | .IR "command substitution" , | |
2752 | .IR "arithmetic expansion" , | |
2753 | .IR "word splitting" , | |
2754 | and | |
2755 | .IR "pathname expansion" . | |
2756 | .PP | |
ac50fbac CR |
2757 | The order of expansions is: |
2758 | brace expansion; | |
2759 | tilde expansion, parameter and variable expansion, arithmetic expansion, | |
2760 | and command substitution (done in a left-to-right fashion); | |
2761 | word splitting; | |
2762 | and pathname expansion. | |
726f6388 JA |
2763 | .PP |
2764 | On systems that can support it, there is an additional expansion | |
2765 | available: \fIprocess substitution\fP. | |
ac50fbac CR |
2766 | This is performed at the |
2767 | same time as tilde, parameter, variable, and arithmetic expansion and | |
2768 | command substitution. | |
726f6388 | 2769 | .PP |
a0c0a00f CR |
2770 | After these expansions are performed, quote characters present in the |
2771 | original word are removed unless they have been quoted themselves | |
2772 | (\fIquote removal\fP). | |
2773 | .PP | |
726f6388 | 2774 | Only brace expansion, word splitting, and pathname expansion |
9a51695b | 2775 | can increase the number of words of the expansion; other expansions |
726f6388 | 2776 | expand a single word to a single word. |
ccc6cda3 | 2777 | The only exceptions to this are the expansions of |
9a51695b CR |
2778 | "\fB$@\fP" and "\fB${\fP\fIname\fP\fB[@]}\fP", |
2779 | and, in most cases, \fB$*\fP and \fB${\fP\fIname\fP\fB[*]}\fP | |
ccc6cda3 | 2780 | as explained above (see |
726f6388 JA |
2781 | .SM |
2782 | .BR PARAMETERS ). | |
2783 | .SS Brace Expansion | |
2784 | .PP | |
2785 | .I "Brace expansion" | |
2786 | is a mechanism by which arbitrary strings | |
2787 | may be generated. This mechanism is similar to | |
2788 | \fIpathname expansion\fP, but the filenames generated | |
2789 | need not exist. Patterns to be brace expanded take | |
2790 | the form of an optional | |
2791 | .IR preamble , | |
b80f6443 JA |
2792 | followed by either a series of comma-separated strings or |
2793 | a sequence expression between a pair of braces, followed by | |
2794 | an optional | |
cce855bc | 2795 | .IR postscript . |
ccc6cda3 | 2796 | The preamble is prefixed to each string contained |
cce855bc | 2797 | within the braces, and the postscript is then appended |
726f6388 JA |
2798 | to each resulting string, expanding left to right. |
2799 | .PP | |
2800 | Brace expansions may be nested. The results of each expanded | |
2801 | string are not sorted; left to right order is preserved. | |
2802 | For example, a\fB{\fPd,c,b\fB}\fPe expands into `ade ace abe'. | |
2803 | .PP | |
3185942a JA |
2804 | A sequence expression takes the form |
2805 | \fB{\fP\fIx\fP\fB..\fP\fIy\fP\fB[..\fP\fIincr\fP\fB]}\fP, | |
2806 | where \fIx\fP and \fIy\fP are either integers or single characters, | |
2807 | and \fIincr\fP, an optional increment, is an integer. | |
b80f6443 JA |
2808 | When integers are supplied, the expression expands to each number between |
2809 | \fIx\fP and \fIy\fP, inclusive. | |
3185942a | 2810 | Supplied integers may be prefixed with \fI0\fP to force each term to have the |
ac50fbac CR |
2811 | same width. |
2812 | When either \fIx\fP or \fPy\fP begins with a zero, the shell | |
3185942a JA |
2813 | attempts to force all generated terms to contain the same number of digits, |
2814 | zero-padding where necessary. | |
b80f6443 | 2815 | When characters are supplied, the expression expands to each character |
ac50fbac CR |
2816 | lexicographically between \fIx\fP and \fIy\fP, inclusive, |
2817 | using the default C locale. | |
2818 | Note that both \fIx\fP and \fIy\fP must be of the same type. | |
3185942a | 2819 | When the increment is supplied, it is used as the difference between |
9a51695b | 2820 | each term. The default increment is 1 or \-1 as appropriate. |
b80f6443 | 2821 | .PP |
726f6388 JA |
2822 | Brace expansion is performed before any other expansions, |
2823 | and any characters special to other expansions are preserved | |
2824 | in the result. It is strictly textual. | |
2825 | .B Bash | |
2826 | does not apply any syntactic interpretation to the context of the | |
2827 | expansion or the text between the braces. | |
2828 | .PP | |
2829 | A correctly-formed brace expansion must contain unquoted opening | |
b80f6443 JA |
2830 | and closing braces, and at least one unquoted comma or a valid |
2831 | sequence expression. | |
726f6388 | 2832 | Any incorrectly formed brace expansion is left unchanged. |
ccc6cda3 JA |
2833 | A \fB{\fP or \fB,\fP may be quoted with a backslash to prevent its |
2834 | being considered part of a brace expression. | |
bb70624e | 2835 | To avoid conflicts with parameter expansion, the string \fB${\fP |
9a51695b CR |
2836 | is not considered eligible for brace expansion, and inhibits brace |
2837 | expansion until the closing \fB}\fP. | |
726f6388 JA |
2838 | .PP |
2839 | This construct is typically used as shorthand when the common | |
2840 | prefix of the strings to be generated is longer than in the | |
2841 | above example: | |
2842 | .RS | |
2843 | .PP | |
2844 | mkdir /usr/local/src/bash/{old,new,dist,bugs} | |
2845 | .RE | |
2846 | or | |
2847 | .RS | |
2848 | chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}} | |
2849 | .RE | |
2850 | .PP | |
2851 | Brace expansion introduces a slight incompatibility with | |
ccc6cda3 JA |
2852 | historical versions of |
2853 | .BR sh . | |
726f6388 JA |
2854 | .B sh |
2855 | does not treat opening or closing braces specially when they | |
2856 | appear as part of a word, and preserves them in the output. | |
2857 | .B Bash | |
2858 | removes braces from words as a consequence of brace | |
2859 | expansion. For example, a word entered to | |
2860 | .B sh | |
2861 | as \fIfile{1,2}\fP | |
2862 | appears identically in the output. The same word is | |
2863 | output as | |
2864 | .I file1 file2 | |
2865 | after expansion by | |
2866 | .BR bash . | |
2867 | If strict compatibility with | |
2868 | .B sh | |
2869 | is desired, start | |
2870 | .B bash | |
2871 | with the | |
a0c0a00f | 2872 | .B +B |
ccc6cda3 JA |
2873 | option or disable brace expansion with the |
2874 | .B +B | |
726f6388 JA |
2875 | option to the |
2876 | .B set | |
2877 | command (see | |
2878 | .SM | |
2879 | .B SHELL BUILTIN COMMANDS | |
2880 | below). | |
2881 | .SS Tilde Expansion | |
2882 | .PP | |
cce855bc JA |
2883 | If a word begins with an unquoted tilde character (`\fB~\fP'), all of |
2884 | the characters preceding the first unquoted slash (or all characters, | |
2885 | if there is no unquoted slash) are considered a \fItilde-prefix\fP. | |
2886 | If none of the characters in the tilde-prefix are quoted, the | |
2887 | characters in the tilde-prefix following the tilde are treated as a | |
2888 | possible \fIlogin name\fP. | |
2889 | If this login name is the null string, the tilde is replaced with the | |
2890 | value of the shell parameter | |
726f6388 JA |
2891 | .SM |
2892 | .BR HOME . | |
2893 | If | |
2894 | .SM | |
2895 | .B HOME | |
cce855bc JA |
2896 | is unset, the home directory of the user executing the shell is |
2897 | substituted instead. | |
2898 | Otherwise, the tilde-prefix is replaced with the home directory | |
2899 | associated with the specified login name. | |
726f6388 | 2900 | .PP |
cce855bc | 2901 | If the tilde-prefix is a `~+', the value of the shell variable |
726f6388 JA |
2902 | .SM |
2903 | .B PWD | |
cce855bc JA |
2904 | replaces the tilde-prefix. |
2905 | If the tilde-prefix is a `~\-', the value of the shell variable | |
2906 | .SM | |
2907 | .BR OLDPWD , | |
2908 | if it is set, is substituted. | |
2909 | If the characters following the tilde in the tilde-prefix consist | |
2910 | of a number \fIN\fP, optionally prefixed | |
2911 | by a `+' or a `\-', the tilde-prefix is replaced with the corresponding | |
2912 | element from the directory stack, as it would be displayed by the | |
2913 | .B dirs | |
2914 | builtin invoked with the tilde-prefix as an argument. | |
2915 | If the characters following the tilde in the tilde-prefix consist of a | |
2916 | number without a leading `+' or `\-', `+' is assumed. | |
2917 | .PP | |
2918 | If the login name is invalid, or the tilde expansion fails, the word | |
2919 | is unchanged. | |
726f6388 | 2920 | .PP |
cce855bc JA |
2921 | Each variable assignment is checked for unquoted tilde-prefixes immediately |
2922 | following a | |
726f6388 | 2923 | .B : |
95732b49 | 2924 | or the first |
726f6388 | 2925 | .BR = . |
cce855bc | 2926 | In these cases, tilde expansion is also performed. |
ac50fbac | 2927 | Consequently, one may use filenames with tildes in assignments to |
726f6388 JA |
2928 | .SM |
2929 | .BR PATH , | |
2930 | .SM | |
2931 | .BR MAILPATH , | |
2932 | and | |
2933 | .SM | |
2934 | .BR CDPATH , | |
2935 | and the shell assigns the expanded value. | |
2f5dfe5a CR |
2936 | .PP |
2937 | Bash also performs tilde expansion on words satisfying the conditions of | |
2938 | variable assignments (as described above under | |
2939 | .SM | |
2940 | .BR PARAMETERS ) | |
2941 | when they appear as arguments to simple commands. | |
2942 | Bash does not do this, except for the \fIdeclaration\fP commands listed | |
2943 | above, when in \fIposix mode\fP. | |
726f6388 JA |
2944 | .SS Parameter Expansion |
2945 | .PP | |
2946 | The `\fB$\fP' character introduces parameter expansion, | |
2947 | command substitution, or arithmetic expansion. The parameter name | |
2948 | or symbol to be expanded may be enclosed in braces, which | |
2949 | are optional but serve to protect the variable to be expanded from | |
2950 | characters immediately following it which could be | |
2951 | interpreted as part of the name. | |
2952 | .PP | |
cce855bc JA |
2953 | When braces are used, the matching ending brace is the first `\fB}\fP' |
2954 | not escaped by a backslash or within a quoted string, and not within an | |
95732b49 | 2955 | embedded arithmetic expansion, command substitution, or parameter |
cce855bc JA |
2956 | expansion. |
2957 | .PP | |
726f6388 JA |
2958 | .PD 0 |
2959 | .TP | |
2960 | ${\fIparameter\fP} | |
2961 | The value of \fIparameter\fP is substituted. The braces are required | |
2962 | when | |
2963 | .I parameter | |
2964 | is a positional parameter with more than one digit, | |
2965 | or when | |
2966 | .I parameter | |
2967 | is followed by a character which is not to be | |
2968 | interpreted as part of its name. | |
ac50fbac CR |
2969 | The \fIparameter\fP is a shell parameter as described above |
2970 | \fBPARAMETERS\fP) or an array reference (\fBArrays\fP). | |
726f6388 JA |
2971 | .PD |
2972 | .PP | |
0001803f | 2973 | If the first character of \fIparameter\fP is an exclamation point (\fB!\fP), |
a0c0a00f | 2974 | and \fIparameter\fP is not a \fInameref\fP, |
2f5dfe5a CR |
2975 | it introduces a level of indirection. |
2976 | \fBBash\fP uses the value formed by expanding the rest of | |
2977 | \fIparameter\fP as the new \fIparameter\fP; this is then | |
2978 | expanded and that value is used in the rest of the expansion, rather | |
2979 | than the expansion of the original \fIparameter\fP. | |
ccc6cda3 | 2980 | This is known as \fIindirect expansion\fP. |
9a51695b CR |
2981 | The value is subject to tilde expansion, |
2982 | parameter expansion, command substitution, and arithmetic expansion. | |
a0c0a00f | 2983 | If \fIparameter\fP is a nameref, this expands to the name of the |
2f5dfe5a | 2984 | parameter referenced by \fIparameter\fP instead of performing the |
a0c0a00f | 2985 | complete indirect expansion. |
495aee44 | 2986 | The exceptions to this are the expansions of ${\fB!\fP\fIprefix\fP\fB*\fP} and |
b80f6443 JA |
2987 | ${\fB!\fP\fIname\fP[\fI@\fP]} described below. |
2988 | The exclamation point must immediately follow the left brace in order to | |
2989 | introduce indirection. | |
ccc6cda3 | 2990 | .PP |
726f6388 JA |
2991 | In each of the cases below, \fIword\fP is subject to tilde expansion, |
2992 | parameter expansion, command substitution, and arithmetic expansion. | |
17345e5a | 2993 | .PP |
ac50fbac CR |
2994 | When not performing substring expansion, using the forms documented below |
2995 | (e.g., \fB:-\fP), | |
17345e5a JA |
2996 | \fBbash\fP tests for a parameter that is unset or null. Omitting the colon |
2997 | results in a test only for a parameter that is unset. | |
726f6388 JA |
2998 | .PP |
2999 | .PD 0 | |
3000 | .TP | |
3001 | ${\fIparameter\fP\fB:\-\fP\fIword\fP} | |
3002 | \fBUse Default Values\fP. If | |
3003 | .I parameter | |
3004 | is unset or null, the expansion of | |
3005 | .I word | |
3006 | is substituted. Otherwise, the value of | |
3007 | .I parameter | |
3008 | is substituted. | |
3009 | .TP | |
3010 | ${\fIparameter\fP\fB:=\fP\fIword\fP} | |
3011 | \fBAssign Default Values\fP. | |
3012 | If | |
3013 | .I parameter | |
3014 | is unset or null, the expansion of | |
3015 | .I word | |
3016 | is assigned to | |
3017 | .IR parameter . | |
3018 | The value of | |
3019 | .I parameter | |
3020 | is then substituted. Positional parameters and special parameters may | |
3021 | not be assigned to in this way. | |
3022 | .TP | |
3023 | ${\fIparameter\fP\fB:?\fP\fIword\fP} | |
3024 | \fBDisplay Error if Null or Unset\fP. | |
3025 | If | |
3026 | .I parameter | |
3027 | is null or unset, the expansion of \fIword\fP (or a message to that effect | |
3028 | if | |
3029 | .I word | |
3030 | is not present) is written to the standard error and the shell, if it | |
3031 | is not interactive, exits. Otherwise, the value of \fIparameter\fP is | |
3032 | substituted. | |
3033 | .TP | |
3034 | ${\fIparameter\fP\fB:+\fP\fIword\fP} | |
3035 | \fBUse Alternate Value\fP. | |
3036 | If | |
3037 | .I parameter | |
3038 | is null or unset, nothing is substituted, otherwise the expansion of | |
3039 | .I word | |
3040 | is substituted. | |
3041 | .TP | |
ccc6cda3 | 3042 | ${\fIparameter\fP\fB:\fP\fIoffset\fP} |
7117c2d2 | 3043 | .PD 0 |
ccc6cda3 JA |
3044 | .TP |
3045 | ${\fIparameter\fP\fB:\fP\fIoffset\fP\fB:\fP\fIlength\fP} | |
3046 | .PD | |
495aee44 | 3047 | \fBSubstring Expansion\fP. |
ac50fbac | 3048 | Expands to up to \fIlength\fP characters of the value of \fIparameter\fP |
bb70624e | 3049 | starting at the character specified by \fIoffset\fP. |
ac50fbac CR |
3050 | If \fIparameter\fP is \fB@\fP, an indexed array subscripted by |
3051 | \fB@\fP or \fB*\fP, or an associative array name, the results differ as | |
3052 | described below. | |
3053 | If \fIlength\fP is omitted, expands to the substring of the value of | |
3054 | \fIparameter\fP starting at the character specified by \fIoffset\fP | |
3055 | and extending to the end of the value. | |
ccc6cda3 JA |
3056 | \fIlength\fP and \fIoffset\fP are arithmetic expressions (see |
3057 | .SM | |
3058 | .B | |
3059 | ARITHMETIC EVALUATION | |
3060 | below). | |
ac50fbac | 3061 | .sp 1 |
ccc6cda3 | 3062 | If \fIoffset\fP evaluates to a number less than zero, the value |
ac50fbac CR |
3063 | is used as an offset in characters |
3064 | from the end of the value of \fIparameter\fP. | |
3065 | If \fIlength\fP evaluates to a number less than zero, | |
3066 | it is interpreted as an offset in characters | |
3067 | from the end of the value of \fIparameter\fP rather than | |
3068 | a number of characters, and the expansion is the characters between | |
3069 | \fIoffset\fP and that result. | |
3070 | Note that a negative offset must be separated from the colon by at least | |
3071 | one space to avoid being confused with the \fB:-\fP expansion. | |
3072 | .sp 1 | |
ccc6cda3 JA |
3073 | If \fIparameter\fP is \fB@\fP, the result is \fIlength\fP positional |
3074 | parameters beginning at \fIoffset\fP. | |
ac50fbac | 3075 | A negative \fIoffset\fP is taken relative to one greater than the greatest |
9a51695b | 3076 | positional parameter, so an offset of \-1 evaluates to the last positional |
ac50fbac CR |
3077 | parameter. |
3078 | It is an expansion error if \fIlength\fP evaluates to a number less than | |
3079 | zero. | |
3080 | .sp 1 | |
3185942a | 3081 | If \fIparameter\fP is an indexed array name subscripted by @ or *, |
ccc6cda3 JA |
3082 | the result is the \fIlength\fP |
3083 | members of the array beginning with ${\fIparameter\fP[\fIoffset\fP]}. | |
95732b49 JA |
3084 | A negative \fIoffset\fP is taken relative to one greater than the maximum |
3085 | index of the specified array. | |
ac50fbac CR |
3086 | It is an expansion error if \fIlength\fP evaluates to a number less than |
3087 | zero. | |
3088 | .sp 1 | |
3185942a JA |
3089 | Substring expansion applied to an associative array produces undefined |
3090 | results. | |
ac50fbac | 3091 | .sp 1 |
a0c0a00f | 3092 | Substring indexing is zero-based unless the positional parameters |
3185942a JA |
3093 | are used, in which case the indexing starts at 1 by default. |
3094 | If \fIoffset\fP is 0, and the positional parameters are used, \fB$0\fP is | |
3095 | prefixed to the list. | |
ccc6cda3 | 3096 | .TP |
bb70624e | 3097 | ${\fB!\fP\fIprefix\fP\fB*\fP} |
b80f6443 JA |
3098 | .PD 0 |
3099 | .TP | |
3100 | ${\fB!\fP\fIprefix\fP\fB@\fP} | |
3101 | .PD | |
495aee44 | 3102 | \fBNames matching prefix\fP. |
bb70624e JA |
3103 | Expands to the names of variables whose names begin with \fIprefix\fP, |
3104 | separated by the first character of the | |
3105 | .SM | |
3106 | .B IFS | |
3107 | special variable. | |
3185942a JA |
3108 | When \fI@\fP is used and the expansion appears within double quotes, each |
3109 | variable name expands to a separate word. | |
bb70624e | 3110 | .TP |
b80f6443 JA |
3111 | ${\fB!\fP\fIname\fP[\fI@\fP]} |
3112 | .PD 0 | |
3113 | .TP | |
3114 | ${\fB!\fP\fIname\fP[\fI*\fP]} | |
3115 | .PD | |
495aee44 | 3116 | \fBList of array keys\fP. |
b80f6443 JA |
3117 | If \fIname\fP is an array variable, expands to the list of array indices |
3118 | (keys) assigned in \fIname\fP. | |
3119 | If \fIname\fP is not an array, expands to 0 if \fIname\fP is set and null | |
3120 | otherwise. | |
3121 | When \fI@\fP is used and the expansion appears within double quotes, each | |
3122 | key expands to a separate word. | |
3123 | .TP | |
726f6388 | 3124 | ${\fB#\fP\fIparameter\fP} |
495aee44 | 3125 | \fBParameter length\fP. |
726f6388 | 3126 | The length in characters of the value of \fIparameter\fP is substituted. |
ccc6cda3 JA |
3127 | If |
3128 | .I parameter | |
3129 | is | |
726f6388 | 3130 | .B * |
a0c0a00f | 3131 | or |
726f6388 | 3132 | .BR @ , |
cce855bc | 3133 | the value substituted is the number of positional parameters. |
ccc6cda3 JA |
3134 | If |
3135 | .I parameter | |
3136 | is an array name subscripted by | |
726f6388 | 3137 | .B * |
ccc6cda3 JA |
3138 | or |
3139 | .BR @ , | |
cce855bc | 3140 | the value substituted is the number of elements in the array. |
ac50fbac CR |
3141 | If |
3142 | .I parameter | |
3143 | is an indexed array name subscripted by a negative number, that number is | |
3144 | interpreted as relative to one greater than the maximum index of | |
3145 | \fIparameter\fP, so negative indices count back from the end of the | |
3146 | array, and an index of \-1 references the last element. | |
726f6388 | 3147 | .TP |
726f6388 | 3148 | ${\fIparameter\fP\fB#\fP\fIword\fP} |
7117c2d2 | 3149 | .PD 0 |
726f6388 JA |
3150 | .TP |
3151 | ${\fIparameter\fP\fB##\fP\fIword\fP} | |
3152 | .PD | |
495aee44 | 3153 | \fBRemove matching prefix pattern\fP. |
a0c0a00f | 3154 | The |
726f6388 JA |
3155 | .I word |
3156 | is expanded to produce a pattern just as in pathname | |
9a51695b CR |
3157 | expansion, and matched against the expanded value of |
3158 | .I parameter | |
3159 | using the rules described under | |
3160 | .B Pattern Matching | |
3161 | below. | |
3162 | If the pattern matches the beginning of | |
726f6388 JA |
3163 | the value of |
3164 | .IR parameter , | |
cce855bc | 3165 | then the result of the expansion is the expanded value of |
726f6388 | 3166 | .I parameter |
ccc6cda3 JA |
3167 | with the shortest matching pattern (the ``\fB#\fP'' case) or the |
3168 | longest matching pattern (the ``\fB##\fP'' case) deleted. | |
3169 | If | |
3170 | .I parameter | |
3171 | is | |
3172 | .B @ | |
3173 | or | |
3174 | .BR * , | |
3175 | the pattern removal operation is applied to each positional | |
3176 | parameter in turn, and the expansion is the resultant list. | |
3177 | If | |
3178 | .I parameter | |
3179 | is an array variable subscripted with | |
3180 | .B @ | |
3181 | or | |
3182 | .BR * , | |
3183 | the pattern removal operation is applied to each member of the | |
3184 | array in turn, and the expansion is the resultant list. | |
726f6388 | 3185 | .TP |
726f6388 | 3186 | ${\fIparameter\fP\fB%\fP\fIword\fP} |
7117c2d2 | 3187 | .PD 0 |
726f6388 JA |
3188 | .TP |
3189 | ${\fIparameter\fP\fB%%\fP\fIword\fP} | |
3190 | .PD | |
495aee44 | 3191 | \fBRemove matching suffix pattern\fP. |
726f6388 | 3192 | The \fIword\fP is expanded to produce a pattern just as in |
9a51695b CR |
3193 | pathname expansion, and matched against the expanded value of |
3194 | .I parameter | |
3195 | using the rules described under | |
3196 | .B Pattern Matching | |
3197 | below. | |
cce855bc | 3198 | If the pattern matches a trailing portion of the expanded value of |
726f6388 | 3199 | .IR parameter , |
cce855bc | 3200 | then the result of the expansion is the expanded value of |
726f6388 | 3201 | .I parameter |
ccc6cda3 JA |
3202 | with the shortest matching pattern (the ``\fB%\fP'' case) or the |
3203 | longest matching pattern (the ``\fB%%\fP'' case) deleted. | |
3204 | If | |
3205 | .I parameter | |
3206 | is | |
3207 | .B @ | |
3208 | or | |
3209 | .BR * , | |
3210 | the pattern removal operation is applied to each positional | |
3211 | parameter in turn, and the expansion is the resultant list. | |
3212 | If | |
3213 | .I parameter | |
3214 | is an array variable subscripted with | |
3215 | .B @ | |
3216 | or | |
3217 | .BR * , | |
3218 | the pattern removal operation is applied to each member of the | |
3219 | array in turn, and the expansion is the resultant list. | |
3220 | .TP | |
ccc6cda3 | 3221 | ${\fIparameter\fP\fB/\fP\fIpattern\fP\fB/\fP\fIstring\fP} |
495aee44 | 3222 | \fBPattern substitution\fP. |
ccc6cda3 | 3223 | The \fIpattern\fP is expanded to produce a pattern just as in |
9a51695b | 3224 | pathname expansion, |
ccc6cda3 JA |
3225 | \fIParameter\fP is expanded and the longest match of \fIpattern\fP |
3226 | against its value is replaced with \fIstring\fP. | |
9a51695b CR |
3227 | The match is performed using the rules described under |
3228 | .B Pattern Matching | |
3229 | below. | |
3185942a | 3230 | If \fIpattern\fP begins with \fB/\fP, all matches of \fIpattern\fP are |
0628567a | 3231 | replaced with \fIstring\fP. Normally only the first match is replaced. |
ccc6cda3 | 3232 | If \fIpattern\fP begins with \fB#\fP, it must match at the beginning |
b72432fd | 3233 | of the expanded value of \fIparameter\fP. |
ccc6cda3 | 3234 | If \fIpattern\fP begins with \fB%\fP, it must match at the end |
b72432fd | 3235 | of the expanded value of \fIparameter\fP. |
ccc6cda3 JA |
3236 | If \fIstring\fP is null, matches of \fIpattern\fP are deleted |
3237 | and the \fB/\fP following \fIpattern\fP may be omitted. | |
a0c0a00f CR |
3238 | If the |
3239 | .B nocasematch | |
3240 | shell option is enabled, the match is performed without regard to the case | |
3241 | of alphabetic characters. | |
ccc6cda3 JA |
3242 | If |
3243 | .I parameter | |
3244 | is | |
3245 | .B @ | |
3246 | or | |
3247 | .BR * , | |
3248 | the substitution operation is applied to each positional | |
3249 | parameter in turn, and the expansion is the resultant list. | |
3250 | If | |
3251 | .I parameter | |
3252 | is an array variable subscripted with | |
3253 | .B @ | |
3254 | or | |
3255 | .BR * , | |
3256 | the substitution operation is applied to each member of the | |
3257 | array in turn, and the expansion is the resultant list. | |
3185942a JA |
3258 | .TP |
3259 | ${\fIparameter\fP\fB^\fP\fIpattern\fP} | |
3260 | .PD 0 | |
3261 | .TP | |
3262 | ${\fIparameter\fP\fB^^\fP\fIpattern\fP} | |
3263 | .TP | |
3264 | ${\fIparameter\fP\fB,\fP\fIpattern\fP} | |
3265 | .TP | |
3266 | ${\fIparameter\fP\fB,,\fP\fIpattern\fP} | |
3267 | .PD | |
495aee44 | 3268 | \fBCase modification\fP. |
3185942a JA |
3269 | This expansion modifies the case of alphabetic characters in \fIparameter\fP. |
3270 | The \fIpattern\fP is expanded to produce a pattern just as in | |
3271 | pathname expansion. | |
ac50fbac CR |
3272 | Each character in the expanded value of \fIparameter\fP is tested against |
3273 | \fIpattern\fP, and, if it matches the pattern, its case is converted. | |
3274 | The pattern should not attempt to match more than one character. | |
3185942a JA |
3275 | The \fB^\fP operator converts lowercase letters matching \fIpattern\fP |
3276 | to uppercase; the \fB,\fP operator converts matching uppercase letters | |
3277 | to lowercase. | |
3278 | The \fB^^\fP and \fB,,\fP expansions convert each matched character in the | |
3279 | expanded value; the \fB^\fP and \fB,\fP expansions match and convert only | |
495aee44 | 3280 | the first character in the expanded value. |
3185942a JA |
3281 | If \fIpattern\fP is omitted, it is treated like a \fB?\fP, which matches |
3282 | every character. | |
3283 | If | |
3284 | .I parameter | |
3285 | is | |
3286 | .B @ | |
3287 | or | |
3288 | .BR * , | |
3289 | the case modification operation is applied to each positional | |
3290 | parameter in turn, and the expansion is the resultant list. | |
3291 | If | |
3292 | .I parameter | |
3293 | is an array variable subscripted with | |
3294 | .B @ | |
3295 | or | |
3296 | .BR * , | |
3297 | the case modification operation is applied to each member of the | |
3298 | array in turn, and the expansion is the resultant list. | |
a0c0a00f CR |
3299 | .TP |
3300 | ${\fIparameter\fP\fB@\fP\fIoperator\fP} | |
3301 | \fBParameter transformation\fP. | |
3302 | The expansion is either a transformation of the value of \fIparameter\fP | |
3303 | or information about \fIparameter\fP itself, depending on the value of | |
3304 | \fIoperator\fP. Each \fIoperator\fP is a single letter: | |
3305 | .sp 1 | |
3306 | .RS | |
3307 | .PD 0 | |
3308 | .TP | |
3309 | .B Q | |
3310 | The expansion is a string that is the value of \fIparameter\fP quoted in a | |
3311 | format that can be reused as input. | |
3312 | .TP | |
3313 | .B E | |
3314 | The expansion is a string that is the value of \fIparameter\fP with backslash | |
9a51695b | 3315 | escape sequences expanded as with the \fB$'...'\fP quoting mechanism. |
a0c0a00f CR |
3316 | .TP |
3317 | .B P | |
3318 | The expansion is a string that is the result of expanding the value of | |
3319 | \fIparameter\fP as if it were a prompt string (see \fBPROMPTING\fP below). | |
3320 | .TP | |
3321 | .B A | |
3322 | The expansion is a string in the form of | |
3323 | an assignment statement or \fBdeclare\fP command that, if | |
3324 | evaluated, will recreate \fIparameter\fP with its attributes and value. | |
3325 | .TP | |
3326 | .B a | |
3327 | The expansion is a string consisting of flag values representing | |
3328 | \fIparameter\fP's attributes. | |
3329 | .PD | |
3330 | .PP | |
3331 | If | |
3332 | .I parameter | |
3333 | is | |
3334 | .B @ | |
3335 | or | |
3336 | .BR * , | |
3337 | the operation is applied to each positional | |
3338 | parameter in turn, and the expansion is the resultant list. | |
3339 | If | |
3340 | .I parameter | |
3341 | is an array variable subscripted with | |
3342 | .B @ | |
3343 | or | |
3344 | .BR * , | |
9a51695b | 3345 | the operation is applied to each member of the |
a0c0a00f CR |
3346 | array in turn, and the expansion is the resultant list. |
3347 | .sp 1 | |
3348 | The result of the expansion is subject to word splitting and pathname | |
3349 | expansion as described below. | |
3350 | .RE | |
726f6388 JA |
3351 | .SS Command Substitution |
3352 | .PP | |
cce855bc | 3353 | \fICommand substitution\fP allows the output of a command to replace |
726f6388 | 3354 | the command name. There are two forms: |
726f6388 JA |
3355 | .RS |
3356 | .PP | |
3357 | \fB$(\fP\fIcommand\fP\|\fB)\fP | |
3358 | .RE | |
3359 | or | |
3360 | .RS | |
3185942a | 3361 | \fB\`\fP\fIcommand\fP\fB\`\fP |
726f6388 JA |
3362 | .RE |
3363 | .PP | |
ccc6cda3 | 3364 | .B Bash |
a0c0a00f CR |
3365 | performs the expansion by executing \fIcommand\fP in a subshell environment |
3366 | and replacing the command substitution with the standard output of the | |
726f6388 | 3367 | command, with any trailing newlines deleted. |
cce855bc JA |
3368 | Embedded newlines are not deleted, but they may be removed during |
3369 | word splitting. | |
3370 | The command substitution \fB$(cat \fIfile\fP)\fR can be replaced by | |
3371 | the equivalent but faster \fB$(< \fIfile\fP)\fR. | |
726f6388 | 3372 | .PP |
ccc6cda3 | 3373 | When the old-style backquote form of substitution is used, |
726f6388 JA |
3374 | backslash retains its literal meaning except when followed by |
3375 | .BR $ , | |
3185942a | 3376 | .BR \` , |
726f6388 JA |
3377 | or |
3378 | .BR \e . | |
cce855bc JA |
3379 | The first backquote not preceded by a backslash terminates the |
3380 | command substitution. | |
726f6388 JA |
3381 | When using the $(\^\fIcommand\fP\|) form, all characters between the |
3382 | parentheses make up the command; none are treated specially. | |
3383 | .PP | |
cce855bc | 3384 | Command substitutions may be nested. To nest when using the backquoted form, |
726f6388 JA |
3385 | escape the inner backquotes with backslashes. |
3386 | .PP | |
3387 | If the substitution appears within double quotes, word splitting and | |
3388 | pathname expansion are not performed on the results. | |
3389 | .SS Arithmetic Expansion | |
3390 | .PP | |
3391 | Arithmetic expansion allows the evaluation of an arithmetic expression | |
ccc6cda3 | 3392 | and the substitution of the result. The format for arithmetic expansion is: |
726f6388 JA |
3393 | .RS |
3394 | .PP | |
726f6388 JA |
3395 | \fB$((\fP\fIexpression\fP\fB))\fP |
3396 | .RE | |
3397 | .PP | |
3398 | The | |
3399 | .I expression | |
3400 | is treated as if it were within double quotes, but a double quote | |
ccc6cda3 | 3401 | inside the parentheses is not treated specially. |
ac50fbac CR |
3402 | All tokens in the expression undergo parameter and variable expansion, |
3403 | command substitution, and quote removal. | |
3404 | The result is treated as the arithmetic expression to be evaluated. | |
b80f6443 | 3405 | Arithmetic expansions may be nested. |
726f6388 JA |
3406 | .PP |
3407 | The evaluation is performed according to the rules listed below under | |
3408 | .SM | |
3409 | .BR "ARITHMETIC EVALUATION" . | |
3410 | If | |
3411 | .I expression | |
3412 | is invalid, | |
3413 | .B bash | |
3414 | prints a message indicating failure and no substitution occurs. | |
3415 | .SS Process Substitution | |
3416 | .PP | |
a0c0a00f CR |
3417 | \fIProcess substitution\fP allows a process's input or output to be |
3418 | referred to using a filename. | |
726f6388 JA |
3419 | It takes the form of |
3420 | \fB<(\fP\fIlist\^\fP\fB)\fP | |
3421 | or | |
3422 | \fB>(\fP\fIlist\^\fP\fB)\fP. | |
a0c0a00f CR |
3423 | The process \fIlist\fP is run asynchronously, and its input or output |
3424 | appears as a filename. | |
3425 | This filename is | |
726f6388 | 3426 | passed as an argument to the current command as the result of the |
a0c0a00f CR |
3427 | expansion. |
3428 | If the \fB>(\fP\fIlist\^\fP\fB)\fP form is used, writing to | |
726f6388 JA |
3429 | the file will provide input for \fIlist\fP. If the |
3430 | \fB<(\fP\fIlist\^\fP\fB)\fP form is used, the file passed as an | |
3431 | argument should be read to obtain the output of \fIlist\fP. | |
a0c0a00f CR |
3432 | Process substitution is supported on systems that support named |
3433 | pipes (\fIFIFOs\fP) or the \fB/dev/fd\fP method of naming open files. | |
726f6388 | 3434 | .PP |
bb70624e | 3435 | When available, process substitution is performed |
a0c0a00f | 3436 | simultaneously with parameter and variable expansion, |
ccc6cda3 JA |
3437 | command substitution, |
3438 | and arithmetic expansion. | |
726f6388 JA |
3439 | .SS Word Splitting |
3440 | .PP | |
3441 | The shell scans the results of | |
3442 | parameter expansion, | |
3443 | command substitution, | |
3444 | and | |
3445 | arithmetic expansion | |
3446 | that did not occur within double quotes for | |
3447 | .IR "word splitting" . | |
3448 | .PP | |
3449 | The shell treats each character of | |
3450 | .SM | |
3451 | .B IFS | |
3452 | as a delimiter, and splits the results of the other | |
ac50fbac CR |
3453 | expansions into words using these characters as field terminators. |
3454 | If | |
726f6388 JA |
3455 | .SM |
3456 | .B IFS | |
ccc6cda3 JA |
3457 | is unset, or its |
3458 | value is exactly | |
726f6388 JA |
3459 | .BR <space><tab><newline> , |
3460 | the default, then | |
3185942a JA |
3461 | sequences of |
3462 | .BR <space> , | |
3463 | .BR <tab> , | |
3464 | and | |
3465 | .B <newline> | |
3466 | at the beginning and end of the results of the previous | |
3467 | expansions are ignored, and | |
726f6388 JA |
3468 | any sequence of |
3469 | .SM | |
3470 | .B IFS | |
3185942a JA |
3471 | characters not at the beginning or end serves to delimit words. |
3472 | If | |
726f6388 JA |
3473 | .SM |
3474 | .B IFS | |
3475 | has a value other than the default, then sequences of | |
3476 | the whitespace characters | |
a0c0a00f CR |
3477 | .BR space , |
3478 | .BR tab , | |
726f6388 | 3479 | and |
a0c0a00f | 3480 | .B newline |
726f6388 JA |
3481 | are ignored at the beginning and end of the |
3482 | word, as long as the whitespace character is in the | |
3483 | value of | |
3484 | .SM | |
9a51695b | 3485 | .B IFS |
726f6388 JA |
3486 | (an |
3487 | .SM | |
3488 | .B IFS | |
3489 | whitespace character). | |
3490 | Any character in | |
3491 | .SM | |
3492 | .B IFS | |
3493 | that is not | |
3494 | .SM | |
3495 | .B IFS | |
3496 | whitespace, along with any adjacent | |
3497 | .SM | |
3498 | .B IFS | |
3499 | whitespace characters, delimits a field. | |
3500 | A sequence of | |
3501 | .SM | |
3502 | .B IFS | |
3503 | whitespace characters is also treated as a delimiter. | |
3504 | If the value of | |
3505 | .SM | |
3506 | .B IFS | |
3507 | is null, no word splitting occurs. | |
726f6388 | 3508 | .PP |
a0c0a00f CR |
3509 | Explicit null arguments (\^\f3"\^"\fP or \^\f3\(aq\^\(aq\fP\^) are retained |
3510 | and passed to commands as empty strings. | |
ccc6cda3 | 3511 | Unquoted implicit null arguments, resulting from the expansion of |
bb70624e | 3512 | parameters that have no values, are removed. |
ccc6cda3 | 3513 | If a parameter with no value is expanded within double quotes, a |
a0c0a00f CR |
3514 | null argument results and is retained |
3515 | and passed to a command as an empty string. | |
3516 | When a quoted null argument appears as part of a word whose expansion is | |
3517 | non-null, the null argument is removed. | |
3518 | That is, the word | |
3519 | \f(CW\-d\(aq\^\(aq\fP becomes \f(CW\-d\fP after word splitting and | |
3520 | null argument removal. | |
726f6388 JA |
3521 | .PP |
3522 | Note that if no expansion occurs, no splitting | |
3523 | is performed. | |
3524 | .SS Pathname Expansion | |
3525 | .PP | |
3526 | After word splitting, | |
3527 | unless the | |
3528 | .B \-f | |
3529 | option has been set, | |
3530 | .B bash | |
ccc6cda3 | 3531 | scans each word for the characters |
726f6388 JA |
3532 | .BR * , |
3533 | .BR ? , | |
3534 | and | |
3535 | .BR [ . | |
3536 | If one of these characters appears, then the word is | |
3537 | regarded as a | |
3538 | .IR pattern , | |
3539 | and replaced with an alphabetically sorted list of | |
ac50fbac CR |
3540 | filenames matching the pattern |
3541 | (see | |
3542 | .SM | |
3543 | .B "Pattern Matching" | |
3544 | below). | |
3545 | If no matching filenames are found, | |
ccc6cda3 JA |
3546 | and the shell option |
3547 | .B nullglob | |
3185942a | 3548 | is not enabled, the word is left unchanged. |
a0c0a00f | 3549 | If the |
cce855bc JA |
3550 | .B nullglob |
3551 | option is set, and no matches are found, | |
726f6388 | 3552 | the word is removed. |
b80f6443 JA |
3553 | If the |
3554 | .B failglob | |
3555 | shell option is set, and no matches are found, an error message | |
3556 | is printed and the command is not executed. | |
cce855bc JA |
3557 | If the shell option |
3558 | .B nocaseglob | |
3559 | is enabled, the match is performed without regard to the case | |
3560 | of alphabetic characters. | |
ccc6cda3 | 3561 | When a pattern is used for pathname expansion, |
726f6388 JA |
3562 | the character |
3563 | .B ``.'' | |
3564 | at the start of a name or immediately following a slash | |
ccc6cda3 JA |
3565 | must be matched explicitly, unless the shell option |
3566 | .B dotglob | |
3567 | is set. | |
9a51695b CR |
3568 | The filenames |
3569 | .B ``.'' | |
3570 | and | |
3571 | .B ``..'' | |
3572 | must always be matched explicitly, even if | |
3573 | .B dotglob | |
3574 | is set. | |
ccc6cda3 | 3575 | In other cases, the |
726f6388 JA |
3576 | .B ``.'' |
3577 | character is not treated specially. | |
9a51695b CR |
3578 | When matching a pathname, the slash character must always be |
3579 | matched explicitly by a slash in the pattern, but in other matching | |
3580 | contexts it can be matched by a special pattern character as described | |
3581 | below under | |
3582 | .SM | |
3583 | .BR "Pattern Matching" . | |
ccc6cda3 JA |
3584 | See the description of |
3585 | .B shopt | |
3586 | below under | |
3587 | .SM | |
3588 | .B SHELL BUILTIN COMMANDS | |
3589 | for a description of the | |
cce855bc JA |
3590 | .BR nocaseglob , |
3591 | .BR nullglob , | |
b80f6443 | 3592 | .BR failglob , |
ccc6cda3 JA |
3593 | and |
3594 | .B dotglob | |
3595 | shell options. | |
3596 | .PP | |
3597 | The | |
3598 | .SM | |
3599 | .B GLOBIGNORE | |
9a51695b | 3600 | shell variable may be used to restrict the set of file names matching a |
ccc6cda3 JA |
3601 | .IR pattern . |
3602 | If | |
3603 | .SM | |
3604 | .B GLOBIGNORE | |
9a51695b | 3605 | is set, each matching file name that also matches one of the patterns in |
ccc6cda3 JA |
3606 | .SM |
3607 | .B GLOBIGNORE | |
3608 | is removed from the list of matches. | |
a0c0a00f CR |
3609 | If the \fBnocaseglob\fP option is set, the matching against the patterns in |
3610 | .SM | |
3611 | .B GLOBIGNORE | |
3612 | is performed without regard to case. | |
ac50fbac | 3613 | The filenames |
ccc6cda3 JA |
3614 | .B ``.'' |
3615 | and | |
3616 | .B ``..'' | |
b80f6443 | 3617 | are always ignored when |
ccc6cda3 JA |
3618 | .SM |
3619 | .B GLOBIGNORE | |
b80f6443 | 3620 | is set and not null. However, setting |
ccc6cda3 JA |
3621 | .SM |
3622 | .B GLOBIGNORE | |
b80f6443 | 3623 | to a non-null value has the effect of enabling the |
ccc6cda3 | 3624 | .B dotglob |
ac50fbac | 3625 | shell option, so all other filenames beginning with a |
ccc6cda3 JA |
3626 | .B ``.'' |
3627 | will match. | |
ac50fbac | 3628 | To get the old behavior of ignoring filenames beginning with a |
ccc6cda3 JA |
3629 | .BR ``.'' , |
3630 | make | |
3631 | .B ``.*'' | |
3632 | one of the patterns in | |
3633 | .SM | |
3634 | .BR GLOBIGNORE . | |
3635 | The | |
3636 | .B dotglob | |
3637 | option is disabled when | |
3638 | .SM | |
3639 | .B GLOBIGNORE | |
3640 | is unset. | |
a0c0a00f CR |
3641 | The pattern matching honors the setting of the \fBextglob\fP shell |
3642 | option. | |
726f6388 | 3643 | .PP |
cce855bc JA |
3644 | \fBPattern Matching\fP |
3645 | .PP | |
3646 | Any character that appears in a pattern, other than the special pattern | |
3647 | characters described below, matches itself. The NUL character may not | |
b80f6443 JA |
3648 | occur in a pattern. A backslash escapes the following character; the |
3649 | escaping backslash is discarded when matching. | |
3650 | The special pattern characters must be quoted if | |
cce855bc JA |
3651 | they are to be matched literally. |
3652 | .PP | |
726f6388 JA |
3653 | The special pattern characters have the following meanings: |
3654 | .PP | |
3655 | .PD 0 | |
495aee44 | 3656 | .RS |
726f6388 JA |
3657 | .TP |
3658 | .B * | |
3659 | Matches any string, including the null string. | |
3185942a | 3660 | When the \fBglobstar\fP shell option is enabled, and \fB*\fP is used in |
0001803f | 3661 | a pathname expansion context, two adjacent \fB*\fPs used as a single |
3185942a JA |
3662 | pattern will match all files and zero or more directories and |
3663 | subdirectories. | |
3664 | If followed by a \fB/\fP, two adjacent \fB*\fPs will match only directories | |
3665 | and subdirectories. | |
726f6388 JA |
3666 | .TP |
3667 | .B ? | |
3668 | Matches any single character. | |
3669 | .TP | |
3670 | .B [...] | |
3671 | Matches any one of the enclosed characters. A pair of characters | |
28ef6c31 JA |
3672 | separated by a hyphen denotes a |
3673 | \fIrange expression\fP; | |
ac50fbac | 3674 | any character that falls between those two characters, inclusive, |
28ef6c31 | 3675 | using the current locale's collating sequence and character set, |
726f6388 JA |
3676 | is matched. If the first character following the |
3677 | .B [ | |
3678 | is a | |
3679 | .B ! | |
3680 | or a | |
3681 | .B ^ | |
ccc6cda3 | 3682 | then any character not enclosed is matched. |
28ef6c31 | 3683 | The sorting order of characters in range expressions is determined by |
ac50fbac | 3684 | the current locale and the values of the |
0001803f CR |
3685 | .SM |
3686 | .B LC_COLLATE | |
ac50fbac CR |
3687 | or |
3688 | .SM | |
3689 | .B LC_ALL | |
3690 | shell variables, if set. | |
3691 | To obtain the traditional interpretation of range expressions, where | |
3692 | .B [a\-d] | |
3693 | is equivalent to | |
3694 | .BR [abcd] , | |
3695 | set value of the | |
3696 | .B LC_ALL | |
3697 | shell variable to | |
3698 | .BR C , | |
3699 | or enable the | |
3700 | .B globasciiranges | |
3701 | shell option. | |
a0c0a00f | 3702 | A |
726f6388 | 3703 | .B \- |
726f6388 JA |
3704 | may be matched by including it as the first or last character |
3705 | in the set. | |
ccc6cda3 JA |
3706 | A |
3707 | .B ] | |
3708 | may be matched by including it as the first character | |
3709 | in the set. | |
cce855bc JA |
3710 | .br |
3711 | .if t .sp 0.5 | |
3712 | .if n .sp 1 | |
3713 | Within | |
3714 | .B [ | |
3715 | and | |
3716 | .BR ] , | |
3717 | \fIcharacter classes\fP can be specified using the syntax | |
3718 | \fB[:\fP\fIclass\fP\fB:]\fP, where \fIclass\fP is one of the | |
0628567a | 3719 | following classes defined in the POSIX standard: |
cce855bc JA |
3720 | .PP |
3721 | .RS | |
3722 | .B | |
7117c2d2 JA |
3723 | .if n alnum alpha ascii blank cntrl digit graph lower print punct space upper word xdigit |
3724 | .if t alnum alpha ascii blank cntrl digit graph lower print punct space upper word xdigit | |
cce855bc JA |
3725 | .br |
3726 | A character class matches any character belonging to that class. | |
7117c2d2 | 3727 | The \fBword\fP character class matches letters, digits, and the character _. |
cce855bc JA |
3728 | .br |
3729 | .if t .sp 0.5 | |
3730 | .if n .sp 1 | |
3731 | Within | |
3732 | .B [ | |
a0c0a00f | 3733 | and |
cce855bc JA |
3734 | .BR ] , |
3735 | an \fIequivalence class\fP can be specified using the syntax | |
3736 | \fB[=\fP\fIc\fP\fB=]\fP, which matches all characters with the | |
3737 | same collation weight (as defined by the current locale) as | |
3738 | the character \fIc\fP. | |
3739 | .br | |
3740 | .if t .sp 0.5 | |
3741 | .if n .sp 1 | |
3742 | Within | |
3743 | .B [ | |
a0c0a00f | 3744 | and |
cce855bc JA |
3745 | .BR ] , |
3746 | the syntax \fB[.\fP\fIsymbol\fP\fB.]\fP matches the collating symbol | |
3747 | \fIsymbol\fP. | |
3748 | .RE | |
495aee44 | 3749 | .RE |
cce855bc JA |
3750 | .PD |
3751 | .PP | |
3752 | If the \fBextglob\fP shell option is enabled using the \fBshopt\fP | |
3753 | builtin, several extended pattern matching operators are recognized. | |
bb70624e | 3754 | In the following description, a \fIpattern-list\fP is a list of one |
cce855bc JA |
3755 | or more patterns separated by a \fB|\fP. |
3756 | Composite patterns may be formed using one or more of the following | |
3757 | sub-patterns: | |
3758 | .sp 1 | |
3759 | .PD 0 | |
3760 | .RS | |
3761 | .TP | |
3762 | \fB?(\fP\^\fIpattern-list\^\fP\fB)\fP | |
3763 | Matches zero or one occurrence of the given patterns | |
3764 | .TP | |
3765 | \fB*(\fP\^\fIpattern-list\^\fP\fB)\fP | |
3766 | Matches zero or more occurrences of the given patterns | |
3767 | .TP | |
3768 | \fB+(\fP\^\fIpattern-list\^\fP\fB)\fP | |
3769 | Matches one or more occurrences of the given patterns | |
3770 | .TP | |
3771 | \fB@(\fP\^\fIpattern-list\^\fP\fB)\fP | |
95732b49 | 3772 | Matches one of the given patterns |
cce855bc JA |
3773 | .TP |
3774 | \fB!(\fP\^\fIpattern-list\^\fP\fB)\fP | |
3775 | Matches anything except one of the given patterns | |
3776 | .RE | |
726f6388 | 3777 | .PD |
9a51695b CR |
3778 | .PP |
3779 | Complicated extended pattern matching against long strings is slow, | |
3780 | especially when the patterns contain alternations and the strings | |
3781 | contain multiple matches. | |
3782 | Using separate matches against shorter strings, or using arrays of | |
3783 | strings instead of a single long string, may be faster. | |
726f6388 JA |
3784 | .SS Quote Removal |
3785 | .PP | |
3786 | After the preceding expansions, all unquoted occurrences of the | |
3787 | characters | |
3788 | .BR \e , | |
0628567a | 3789 | .BR \(aq , |
ccc6cda3 JA |
3790 | and \^\f3"\fP\^ that did not result from one of the above |
3791 | expansions are removed. | |
726f6388 JA |
3792 | .SH REDIRECTION |
3793 | Before a command is executed, its input and output | |
3794 | may be | |
3795 | .I redirected | |
3796 | using a special notation interpreted by the shell. | |
ac50fbac CR |
3797 | Redirection allows commands' file handles to be |
3798 | duplicated, opened, closed, | |
3799 | made to refer to different files, | |
3800 | and can change the files the command reads from and writes to. | |
3801 | Redirection may also be used to modify file handles in the | |
3802 | current shell execution environment. | |
3803 | The following redirection | |
726f6388 JA |
3804 | operators may precede or appear anywhere within a |
3805 | .I simple command | |
3806 | or may follow a | |
3807 | .IR command . | |
3808 | Redirections are processed in the order they appear, from | |
3809 | left to right. | |
3810 | .PP | |
0001803f CR |
3811 | Each redirection that may be preceded by a file descriptor number |
3812 | may instead be preceded by a word of the form {\fIvarname\fP}. | |
3813 | In this case, for each redirection operator except | |
3814 | >&- and <&-, the shell will allocate a file descriptor greater | |
ac50fbac CR |
3815 | than or equal to 10 and assign it to \fIvarname\fP. |
3816 | If >&- or <&- is preceded | |
0001803f CR |
3817 | by {\fIvarname\fP}, the value of \fIvarname\fP defines the file |
3818 | descriptor to close. | |
9a51695b CR |
3819 | If {\fIvarname\fP} is supplied, the redirection persists beyond |
3820 | the scope of the command, allowing the shell programmer to manage | |
3821 | the file descriptor himself. | |
0001803f | 3822 | .PP |
726f6388 JA |
3823 | In the following descriptions, if the file descriptor number is |
3824 | omitted, and the first character of the redirection operator is | |
3825 | .BR < , | |
3826 | the redirection refers to the standard input (file descriptor | |
3827 | 0). If the first character of the redirection operator is | |
3828 | .BR > , | |
3829 | the redirection refers to the standard output (file descriptor | |
3830 | 1). | |
3831 | .PP | |
cce855bc | 3832 | The word following the redirection operator in the following |
ac50fbac CR |
3833 | descriptions, unless otherwise noted, is subjected to |
3834 | brace expansion, tilde expansion, parameter and variable expansion, | |
3835 | command substitution, arithmetic expansion, quote removal, | |
3836 | pathname expansion, and word splitting. | |
cce855bc | 3837 | If it expands to more than one word, |
726f6388 JA |
3838 | .B bash |
3839 | reports an error. | |
3840 | .PP | |
a0c0a00f | 3841 | Note that the order of redirections is significant. For example, |
726f6388 JA |
3842 | the command |
3843 | .RS | |
3844 | .PP | |
3845 | ls \fB>\fP dirlist 2\fB>&\fP1 | |
3846 | .RE | |
3847 | .PP | |
a0c0a00f | 3848 | directs both standard output and standard error to the file |
726f6388 JA |
3849 | .IR dirlist , |
3850 | while the command | |
3851 | .RS | |
3852 | .PP | |
3853 | ls 2\fB>&\fP1 \fB>\fP dirlist | |
3854 | .RE | |
3855 | .PP | |
3856 | directs only the standard output to file | |
3857 | .IR dirlist , | |
17345e5a | 3858 | because the standard error was duplicated from the standard output |
726f6388 JA |
3859 | before the standard output was redirected to |
3860 | .IR dirlist . | |
cce855bc | 3861 | .PP |
bb70624e | 3862 | \fBBash\fP handles several filenames specially when they are used in |
a0c0a00f CR |
3863 | redirections, as described in the following table. |
3864 | If the operating system on which \fBbash\fP is running provides these | |
3865 | special files, bash will use them; otherwise it will emulate them | |
3866 | internally with the behavior described below. | |
bb70624e JA |
3867 | .RS |
3868 | .PP | |
3869 | .PD 0 | |
3870 | .TP | |
3871 | .B /dev/fd/\fIfd\fP | |
3872 | If \fIfd\fP is a valid integer, file descriptor \fIfd\fP is duplicated. | |
3873 | .TP | |
3874 | .B /dev/stdin | |
3875 | File descriptor 0 is duplicated. | |
3876 | .TP | |
3877 | .B /dev/stdout | |
3878 | File descriptor 1 is duplicated. | |
3879 | .TP | |
3880 | .B /dev/stderr | |
3881 | File descriptor 2 is duplicated. | |
3882 | .TP | |
3883 | .B /dev/tcp/\fIhost\fP/\fIport\fP | |
3884 | If \fIhost\fP is a valid hostname or Internet address, and \fIport\fP | |
f73dda09 | 3885 | is an integer port number or service name, \fBbash\fP attempts to open |
ac50fbac | 3886 | the corresponding TCP socket. |
bb70624e JA |
3887 | .TP |
3888 | .B /dev/udp/\fIhost\fP/\fIport\fP | |
3889 | If \fIhost\fP is a valid hostname or Internet address, and \fIport\fP | |
f73dda09 | 3890 | is an integer port number or service name, \fBbash\fP attempts to open |
ac50fbac | 3891 | the corresponding UDP socket. |
bb70624e JA |
3892 | .PD |
3893 | .RE | |
3894 | .PP | |
cce855bc | 3895 | A failure to open or create a file causes the redirection to fail. |
95732b49 JA |
3896 | .PP |
3897 | Redirections using file descriptors greater than 9 should be used with | |
3898 | care, as they may conflict with file descriptors the shell uses | |
3899 | internally. | |
726f6388 JA |
3900 | .SS Redirecting Input |
3901 | .PP | |
3902 | Redirection of input causes the file whose name results from | |
3903 | the expansion of | |
3904 | .I word | |
3905 | to be opened for reading on file descriptor | |
3906 | .IR n , | |
3907 | or the standard input (file descriptor 0) if | |
3908 | .I n | |
3909 | is not specified. | |
3910 | .PP | |
3911 | The general format for redirecting input is: | |
3912 | .RS | |
3913 | .PP | |
3914 | [\fIn\fP]\fB<\fP\fIword\fP | |
3915 | .RE | |
3916 | .SS Redirecting Output | |
3917 | .PP | |
3918 | Redirection of output causes the file whose name results from | |
3919 | the expansion of | |
3920 | .I word | |
3921 | to be opened for writing on file descriptor | |
3922 | .IR n , | |
3923 | or the standard output (file descriptor 1) if | |
3924 | .I n | |
3925 | is not specified. If the file does not exist it is created; | |
3926 | if it does exist it is truncated to zero size. | |
3927 | .PP | |
3928 | The general format for redirecting output is: | |
3929 | .RS | |
3930 | .PP | |
3931 | [\fIn\fP]\fB>\fP\fIword\fP | |
3932 | .RE | |
3933 | .PP | |
3934 | If the redirection operator is | |
ccc6cda3 JA |
3935 | .BR > , |
3936 | and the | |
cce855bc | 3937 | .B noclobber |
ccc6cda3 JA |
3938 | option to the |
3939 | .B set | |
bb70624e | 3940 | builtin has been enabled, the redirection will fail if the file |
cce855bc JA |
3941 | whose name results from the expansion of \fIword\fP exists and is |
3942 | a regular file. | |
ccc6cda3 | 3943 | If the redirection operator is |
726f6388 | 3944 | .BR >| , |
cce855bc JA |
3945 | or the redirection operator is |
3946 | .B > | |
3947 | and the | |
3948 | .B noclobber | |
726f6388 JA |
3949 | option to the |
3950 | .B set | |
cce855bc | 3951 | builtin command is not enabled, the redirection is attempted even |
ccc6cda3 | 3952 | if the file named by \fIword\fP exists. |
726f6388 JA |
3953 | .SS Appending Redirected Output |
3954 | .PP | |
3955 | Redirection of output in this fashion | |
3956 | causes the file whose name results from | |
3957 | the expansion of | |
3958 | .I word | |
3959 | to be opened for appending on file descriptor | |
3960 | .IR n , | |
3961 | or the standard output (file descriptor 1) if | |
3962 | .I n | |
3963 | is not specified. If the file does not exist it is created. | |
3964 | .PP | |
3965 | The general format for appending output is: | |
3966 | .RS | |
3967 | .PP | |
3968 | [\fIn\fP]\fB>>\fP\fIword\fP | |
3969 | .RE | |
3970 | .PP | |
3971 | .SS Redirecting Standard Output and Standard Error | |
3972 | .PP | |
3185942a | 3973 | This construct allows both the |
726f6388 JA |
3974 | standard output (file descriptor 1) and |
3975 | the standard error output (file descriptor 2) | |
3976 | to be redirected to the file whose name is the | |
3977 | expansion of | |
3185942a | 3978 | .IR word . |
726f6388 JA |
3979 | .PP |
3980 | There are two formats for redirecting standard output and | |
3981 | standard error: | |
3982 | .RS | |
3983 | .PP | |
3984 | \fB&>\fP\fIword\fP | |
3985 | .RE | |
3986 | and | |
3987 | .RS | |
3988 | \fB>&\fP\fIword\fP | |
3989 | .RE | |
3990 | .PP | |
3991 | Of the two forms, the first is preferred. | |
3992 | This is semantically equivalent to | |
3993 | .RS | |
3994 | .PP | |
3995 | \fB>\fP\fIword\fP 2\fB>&\fP1 | |
3996 | .RE | |
3185942a | 3997 | .PP |
ac50fbac CR |
3998 | When using the second form, \fIword\fP may not expand to a number or |
3999 | \fB\-\fP. If it does, other redirection operators apply | |
4000 | (see \fBDuplicating File Descriptors\fP below) for compatibility | |
4001 | reasons. | |
3185942a JA |
4002 | .SS Appending Standard Output and Standard Error |
4003 | .PP | |
4004 | This construct allows both the | |
4005 | standard output (file descriptor 1) and | |
4006 | the standard error output (file descriptor 2) | |
4007 | to be appended to the file whose name is the | |
4008 | expansion of | |
4009 | .IR word . | |
4010 | .PP | |
4011 | The format for appending standard output and standard error is: | |
4012 | .RS | |
4013 | .PP | |
4014 | \fB&>>\fP\fIword\fP | |
4015 | .RE | |
4016 | .PP | |
4017 | This is semantically equivalent to | |
4018 | .RS | |
4019 | .PP | |
4020 | \fB>>\fP\fIword\fP 2\fB>&\fP1 | |
4021 | .RE | |
ac50fbac CR |
4022 | .PP |
4023 | (see \fBDuplicating File Descriptors\fP below). | |
726f6388 JA |
4024 | .SS Here Documents |
4025 | .PP | |
4026 | This type of redirection instructs the shell to read input from the | |
4027 | current source until a line containing only | |
3185942a | 4028 | .I delimiter |
726f6388 JA |
4029 | (with no trailing blanks) |
4030 | is seen. All of | |
4031 | the lines read up to that point are then used as the standard | |
a0c0a00f | 4032 | input (or file descriptor \fIn\fP if \fIn\fP is specified) for a command. |
726f6388 | 4033 | .PP |
7117c2d2 | 4034 | The format of here-documents is: |
726f6388 JA |
4035 | .RS |
4036 | .PP | |
4037 | .nf | |
a0c0a00f | 4038 | [\fIn\fP]\fB<<\fP[\fB\-\fP]\fIword\fP |
f73dda09 | 4039 | \fIhere-document\fP |
726f6388 JA |
4040 | \fIdelimiter\fP |
4041 | .fi | |
4042 | .RE | |
4043 | .PP | |
ac50fbac CR |
4044 | No parameter and variable expansion, command substitution, |
4045 | arithmetic expansion, or pathname expansion is performed on | |
726f6388 | 4046 | .IR word . |
a0c0a00f | 4047 | If any part of |
726f6388 | 4048 | .I word |
a0c0a00f | 4049 | is quoted, the |
726f6388 JA |
4050 | .I delimiter |
4051 | is the result of quote removal on | |
4052 | .IR word , | |
cce855bc JA |
4053 | and the lines in the here-document are not expanded. |
4054 | If \fIword\fP is unquoted, | |
ac50fbac CR |
4055 | all lines of the here-document are subjected to |
4056 | parameter expansion, command substitution, and arithmetic expansion, | |
4057 | the character sequence | |
726f6388 JA |
4058 | .B \e<newline> |
4059 | is ignored, and | |
4060 | .B \e | |
4061 | must be used to quote the characters | |
4062 | .BR \e , | |
4063 | .BR $ , | |
4064 | and | |
3185942a | 4065 | .BR \` . |
726f6388 JA |
4066 | .PP |
4067 | If the redirection operator is | |
4068 | .BR <<\- , | |
4069 | then all leading tab characters are stripped from input lines and the | |
4070 | line containing | |
4071 | .IR delimiter . | |
4072 | This allows | |
4073 | here-documents within shell scripts to be indented in a | |
4074 | natural fashion. | |
7117c2d2 JA |
4075 | .SS "Here Strings" |
4076 | A variant of here documents, the format is: | |
4077 | .RS | |
4078 | .PP | |
4079 | .nf | |
a0c0a00f | 4080 | [\fIn\fP]\fB<<<\fP\fIword\fP |
7117c2d2 JA |
4081 | .fi |
4082 | .RE | |
4083 | .PP | |
ac50fbac | 4084 | The \fIword\fP undergoes |
9a51695b | 4085 | tilde expansion, parameter and variable expansion, |
ac50fbac CR |
4086 | command substitution, arithmetic expansion, and quote removal. |
4087 | Pathname expansion and word splitting are not performed. | |
a0c0a00f CR |
4088 | The result is supplied as a single string, with a newline appended, |
4089 | to the command on its | |
4090 | standard input (or file descriptor \fIn\fP if \fIn\fP is specified). | |
726f6388 JA |
4091 | .SS "Duplicating File Descriptors" |
4092 | .PP | |
4093 | The redirection operator | |
4094 | .RS | |
4095 | .PP | |
4096 | [\fIn\fP]\fB<&\fP\fIword\fP | |
4097 | .RE | |
4098 | .PP | |
4099 | is used to duplicate input file descriptors. | |
4100 | If | |
4101 | .I word | |
4102 | expands to one or more digits, the file descriptor denoted by | |
4103 | .I n | |
cce855bc JA |
4104 | is made to be a copy of that file descriptor. |
4105 | If the digits in | |
4106 | .I word | |
4107 | do not specify a file descriptor open for input, a redirection error occurs. | |
4108 | If | |
726f6388 JA |
4109 | .I word |
4110 | evaluates to | |
4111 | .BR \- , | |
4112 | file descriptor | |
4113 | .I n | |
4114 | is closed. If | |
4115 | .I n | |
4116 | is not specified, the standard input (file descriptor 0) is used. | |
4117 | .PP | |
4118 | The operator | |
4119 | .RS | |
4120 | .PP | |
4121 | [\fIn\fP]\fB>&\fP\fIword\fP | |
4122 | .RE | |
4123 | .PP | |
4124 | is used similarly to duplicate output file descriptors. If | |
4125 | .I n | |
4126 | is not specified, the standard output (file descriptor 1) is used. | |
cce855bc JA |
4127 | If the digits in |
4128 | .I word | |
4129 | do not specify a file descriptor open for output, a redirection error occurs. | |
ac50fbac CR |
4130 | If |
4131 | .I word | |
4132 | evaluates to | |
4133 | .BR \- , | |
4134 | file descriptor | |
4135 | .I n | |
4136 | is closed. | |
726f6388 | 4137 | As a special case, if \fIn\fP is omitted, and \fIword\fP does not |
ac50fbac | 4138 | expand to one or more digits or \fB\-\fP, the standard output and standard |
726f6388 | 4139 | error are redirected as described previously. |
7117c2d2 JA |
4140 | .SS "Moving File Descriptors" |
4141 | .PP | |
4142 | The redirection operator | |
4143 | .RS | |
4144 | .PP | |
4145 | [\fIn\fP]\fB<&\fP\fIdigit\fP\fB\-\fP | |
4146 | .RE | |
4147 | .PP | |
4148 | moves the file descriptor \fIdigit\fP to file descriptor | |
4149 | .IR n , | |
4150 | or the standard input (file descriptor 0) if \fIn\fP is not specified. | |
4151 | \fIdigit\fP is closed after being duplicated to \fIn\fP. | |
4152 | .PP | |
4153 | Similarly, the redirection operator | |
4154 | .RS | |
4155 | .PP | |
4156 | [\fIn\fP]\fB>&\fP\fIdigit\fP\fB\-\fP | |
4157 | .RE | |
4158 | .PP | |
4159 | moves the file descriptor \fIdigit\fP to file descriptor | |
4160 | .IR n , | |
4161 | or the standard output (file descriptor 1) if \fIn\fP is not specified. | |
726f6388 JA |
4162 | .SS "Opening File Descriptors for Reading and Writing" |
4163 | .PP | |
4164 | The redirection operator | |
4165 | .RS | |
4166 | .PP | |
4167 | [\fIn\fP]\fB<>\fP\fIword\fP | |
4168 | .RE | |
4169 | .PP | |
4170 | causes the file whose name is the expansion of | |
4171 | .I word | |
4172 | to be opened for both reading and writing on file descriptor | |
4173 | .IR n , | |
ccc6cda3 | 4174 | or on file descriptor 0 if |
726f6388 JA |
4175 | .I n |
4176 | is not specified. If the file does not exist, it is created. | |
726f6388 | 4177 | .SH ALIASES |
bb70624e | 4178 | \fIAliases\fP allow a string to be substituted for a word when it is used |
cce855bc | 4179 | as the first word of a simple command. |
bb70624e | 4180 | The shell maintains a list of aliases that may be set and unset with the |
726f6388 JA |
4181 | .B alias |
4182 | and | |
4183 | .B unalias | |
4184 | builtin commands (see | |
4185 | .SM | |
4186 | .B SHELL BUILTIN COMMANDS | |
4187 | below). | |
b80f6443 | 4188 | The first word of each simple command, if unquoted, |
726f6388 JA |
4189 | is checked to see if it has an |
4190 | alias. If so, that word is replaced by the text of the alias. | |
3185942a | 4191 | The characters \fB/\fP, \fB$\fP, \fB\`\fP, and \fB=\fP and |
b80f6443 JA |
4192 | any of the shell \fImetacharacters\fP or quoting characters |
4193 | listed above may not appear in an alias name. | |
4194 | The replacement text may contain any valid shell input, | |
4195 | including shell metacharacters. | |
4196 | The first word of the replacement text is tested | |
726f6388 | 4197 | for aliases, but a word that is identical to an alias being expanded |
b80f6443 JA |
4198 | is not expanded a second time. |
4199 | This means that one may alias | |
726f6388 JA |
4200 | .B ls |
4201 | to | |
4202 | .BR "ls \-F" , | |
4203 | for instance, and | |
4204 | .B bash | |
4205 | does not try to recursively expand the replacement text. | |
4206 | If the last character of the alias value is a | |
4207 | .IR blank , | |
4208 | then the next command | |
4209 | word following the alias is also checked for alias expansion. | |
4210 | .PP | |
4211 | Aliases are created and listed with the | |
4212 | .B alias | |
4213 | command, and removed with the | |
4214 | .B unalias | |
4215 | command. | |
4216 | .PP | |
ccc6cda3 | 4217 | There is no mechanism for using arguments in the replacement text. |
bb70624e JA |
4218 | If arguments are needed, a shell function should be used (see |
4219 | .SM | |
4220 | .B FUNCTIONS | |
4221 | below). | |
726f6388 | 4222 | .PP |
ccc6cda3 JA |
4223 | Aliases are not expanded when the shell is not interactive, unless |
4224 | the | |
4225 | .B expand_aliases | |
4226 | shell option is set using | |
4227 | .B shopt | |
4228 | (see the description of | |
4229 | .B shopt | |
4230 | under | |
4231 | .SM | |
4232 | \fBSHELL BUILTIN COMMANDS\fP | |
4233 | below). | |
726f6388 JA |
4234 | .PP |
4235 | The rules concerning the definition and use of aliases are | |
4236 | somewhat confusing. | |
4237 | .B Bash | |
2ae59c11 CR |
4238 | always reads at least one complete line of input, |
4239 | and all lines that make up a compound command, | |
4240 | before executing any of the commands on that line or the compound command. | |
4241 | Aliases are expanded when a | |
726f6388 JA |
4242 | command is read, not when it is executed. Therefore, an |
4243 | alias definition appearing on the same line as another | |
4244 | command does not take effect until the next line of input is read. | |
ccc6cda3 | 4245 | The commands following the alias definition |
726f6388 JA |
4246 | on that line are not affected by the new alias. |
4247 | This behavior is also an issue when functions are executed. | |
cce855bc | 4248 | Aliases are expanded when a function definition is read, |
726f6388 | 4249 | not when the function is executed, because a function definition |
a0c0a00f | 4250 | is itself a command. As a consequence, aliases |
726f6388 JA |
4251 | defined in a function are not available until after that |
4252 | function is executed. To be safe, always put | |
4253 | alias definitions on a separate line, and do not use | |
4254 | .B alias | |
4255 | in compound commands. | |
4256 | .PP | |
cce855bc | 4257 | For almost every purpose, aliases are superseded by |
726f6388 | 4258 | shell functions. |
ccc6cda3 JA |
4259 | .SH FUNCTIONS |
4260 | A shell function, defined as described above under | |
4261 | .SM | |
4262 | .BR "SHELL GRAMMAR" , | |
4263 | stores a series of commands for later execution. | |
bb70624e JA |
4264 | When the name of a shell function is used as a simple command name, |
4265 | the list of commands associated with that function name is executed. | |
ccc6cda3 JA |
4266 | Functions are executed in the context of the |
4267 | current shell; no new process is created to interpret | |
4268 | them (contrast this with the execution of a shell script). | |
4269 | When a function is executed, the arguments to the | |
4270 | function become the positional parameters | |
bb70624e JA |
4271 | during its execution. |
4272 | The special parameter | |
ccc6cda3 | 4273 | .B # |
495aee44 | 4274 | is updated to reflect the change. Special parameter \fB0\fP |
bb70624e | 4275 | is unchanged. |
b80f6443 | 4276 | The first element of the |
bb70624e JA |
4277 | .SM |
4278 | .B FUNCNAME | |
4279 | variable is set to the name of the function while the function | |
4280 | is executing. | |
0001803f | 4281 | .PP |
bb70624e | 4282 | All other aspects of the shell execution |
ccc6cda3 | 4283 | environment are identical between a function and its caller |
a0c0a00f | 4284 | with these exceptions: the |
ccc6cda3 JA |
4285 | .SM |
4286 | .B DEBUG | |
95732b49 JA |
4287 | and |
4288 | .B RETURN | |
4289 | traps (see the description of the | |
ccc6cda3 JA |
4290 | .B trap |
4291 | builtin under | |
4292 | .SM | |
4293 | .B SHELL BUILTIN COMMANDS | |
95732b49 | 4294 | below) are not inherited unless the function has been given the |
7117c2d2 JA |
4295 | \fBtrace\fP attribute (see the description of the |
4296 | .SM | |
4297 | .B declare | |
b80f6443 JA |
4298 | builtin below) or the |
4299 | \fB\-o functrace\fP shell option has been enabled with | |
4300 | the \fBset\fP builtin | |
0001803f CR |
4301 | (in which case all functions inherit the \fBDEBUG\fP and \fBRETURN\fP traps), |
4302 | and the | |
4303 | .SM | |
4304 | .B ERR | |
4305 | trap is not inherited unless the \fB\-o errtrace\fP shell option has | |
4306 | been enabled. | |
726f6388 | 4307 | .PP |
ccc6cda3 JA |
4308 | Variables local to the function may be declared with the |
4309 | .B local | |
4310 | builtin command. Ordinarily, variables and their values | |
4311 | are shared between the function and its caller. | |
9a51695b CR |
4312 | If a variable is declared \fBlocal\fP, the variable's visible scope |
4313 | is restricted to that function and its children (including the functions | |
4314 | it calls). | |
4315 | Local variables "shadow" variables with the same name declared at | |
4316 | previous scopes. | |
4317 | For instance, a local variable declared in a function | |
4318 | hides a global variable of the same name: references and assignments | |
4319 | refer to the local variable, leaving the global variable unmodified. | |
4320 | When the function returns, the global variable is once again visible. | |
4321 | .PP | |
4322 | The shell uses \fIdynamic scoping\fP to control a variable's visibility | |
4323 | within functions. | |
4324 | With dynamic scoping, visible variables and their values | |
4325 | are a result of the sequence of function calls that caused execution | |
4326 | to reach the current function. | |
4327 | The value of a variable that a function sees depends | |
4328 | on its value within its caller, if any, whether that caller is | |
4329 | the "global" scope or another shell function. | |
4330 | This is also the value that a local variable | |
4331 | declaration "shadows", and the value that is restored when the function | |
4332 | returns. | |
4333 | .PP | |
4334 | For example, if a variable \fIvar\fP is declared as local in function | |
4335 | \fIfunc1\fP, and \fIfunc1\fP calls another function \fIfunc2\fP, | |
4336 | references to \fIvar\fP made from within \fIfunc2\fP will resolve to the | |
4337 | local variable \fIvar\fP from \fIfunc1\fP, shadowing any global variable | |
4338 | named \fIvar\fP. | |
4339 | .PP | |
4340 | The \fBunset\fP builtin also acts using the same dynamic scope: if a | |
4341 | variable is local to the current scope, \fBunset\fP will unset it; | |
4342 | otherwise the unset will refer to the variable found in any calling scope | |
4343 | as described above. | |
4344 | If a variable at the current local scope is unset, it will remain so | |
4345 | until it is reset in that scope or until the function returns. | |
4346 | Once the function returns, any instance of the variable at a previous | |
4347 | scope will become visible. | |
4348 | If the unset acts on a variable at a previous scope, any instance of a | |
4349 | variable with that name that had been shadowed will become visible. | |
726f6388 | 4350 | .PP |
495aee44 CR |
4351 | The \fBFUNCNEST\fP variable, if set to a numeric value greater |
4352 | than 0, defines a maximum function nesting level. Function | |
4353 | invocations that exceed the limit cause the entire command to | |
4354 | abort. | |
4355 | .PP | |
ccc6cda3 JA |
4356 | If the builtin command |
4357 | .B return | |
4358 | is executed in a function, the function completes and | |
4359 | execution resumes with the next command after the function | |
b80f6443 JA |
4360 | call. |
4361 | Any command associated with the \fBRETURN\fP trap is executed | |
4362 | before execution resumes. | |
4363 | When a function completes, the values of the | |
ccc6cda3 JA |
4364 | positional parameters and the special parameter |
4365 | .B # | |
cce855bc | 4366 | are restored to the values they had prior to the function's |
ccc6cda3 | 4367 | execution. |
726f6388 | 4368 | .PP |
ccc6cda3 JA |
4369 | Function names and definitions may be listed with the |
4370 | .B \-f | |
726f6388 | 4371 | option to the |
ccc6cda3 JA |
4372 | .B declare |
4373 | or | |
4374 | .B typeset | |
4375 | builtin commands. The | |
4376 | .B \-F | |
4377 | option to | |
4378 | .B declare | |
4379 | or | |
4380 | .B typeset | |
b80f6443 JA |
4381 | will list the function names only |
4382 | (and optionally the source file and line number, if the \fBextdebug\fP | |
4383 | shell option is enabled). | |
ccc6cda3 JA |
4384 | Functions may be exported so that subshells |
4385 | automatically have them defined with the | |
4386 | .B \-f | |
4387 | option to the | |
4388 | .B export | |
4389 | builtin. | |
0628567a JA |
4390 | A function definition may be deleted using the \fB\-f\fP option to |
4391 | the | |
4392 | .B unset | |
4393 | builtin. | |
726f6388 | 4394 | .PP |
495aee44 CR |
4395 | Functions may be recursive. |
4396 | The \fBFUNCNEST\fP variable may be used to limit the depth of the | |
4397 | function call stack and restrict the number of function invocations. | |
4398 | By default, no limit is imposed on the number of recursive calls. | |
cce855bc JA |
4399 | .SH "ARITHMETIC EVALUATION" |
4400 | The shell allows arithmetic expressions to be evaluated, under | |
b80f6443 | 4401 | certain circumstances (see the \fBlet\fP and \fBdeclare\fP builtin |
a0c0a00f | 4402 | commands, the \fB((\fP compound command, and \fBArithmetic Expansion\fP). |
7117c2d2 | 4403 | Evaluation is done in fixed-width integers with no check for overflow, |
cce855bc | 4404 | though division by 0 is trapped and flagged as an error. |
b80f6443 JA |
4405 | The operators and their precedence, associativity, and values |
4406 | are the same as in the C language. | |
cce855bc JA |
4407 | The following list of operators is grouped into levels of |
4408 | equal-precedence operators. | |
4409 | The levels are listed in order of decreasing precedence. | |
726f6388 | 4410 | .PP |
cce855bc JA |
4411 | .PD 0 |
4412 | .TP | |
bb70624e JA |
4413 | .B \fIid\fP++ \fIid\fP\-\- |
4414 | variable post-increment and post-decrement | |
4415 | .TP | |
cce855bc JA |
4416 | .B \- + |
4417 | unary minus and plus | |
4418 | .TP | |
2ae59c11 CR |
4419 | .B ++\fIid\fP \-\-\fIid\fP |
4420 | variable pre-increment and pre-decrement | |
4421 | .TP | |
cce855bc JA |
4422 | .B ! ~ |
4423 | logical and bitwise negation | |
4424 | .TP | |
4425 | .B ** | |
4426 | exponentiation | |
4427 | .TP | |
4428 | .B * / % | |
4429 | multiplication, division, remainder | |
4430 | .TP | |
4431 | .B + \- | |
4432 | addition, subtraction | |
4433 | .TP | |
4434 | .B << >> | |
4435 | left and right bitwise shifts | |
4436 | .TP | |
4437 | .B <= >= < > | |
4438 | comparison | |
4439 | .TP | |
4440 | .B == != | |
4441 | equality and inequality | |
4442 | .TP | |
4443 | .B & | |
4444 | bitwise AND | |
4445 | .TP | |
4446 | .B ^ | |
4447 | bitwise exclusive OR | |
4448 | .TP | |
4449 | .B | | |
4450 | bitwise OR | |
4451 | .TP | |
4452 | .B && | |
4453 | logical AND | |
4454 | .TP | |
4455 | .B || | |
4456 | logical OR | |
4457 | .TP | |
4458 | .B \fIexpr\fP?\fIexpr\fP:\fIexpr\fP | |
b80f6443 | 4459 | conditional operator |
cce855bc JA |
4460 | .TP |
4461 | .B = *= /= %= += \-= <<= >>= &= ^= |= | |
4462 | assignment | |
bb70624e JA |
4463 | .TP |
4464 | .B \fIexpr1\fP , \fIexpr2\fP | |
4465 | comma | |
cce855bc | 4466 | .PD |
ccc6cda3 | 4467 | .PP |
cce855bc | 4468 | Shell variables are allowed as operands; parameter expansion is |
bb70624e JA |
4469 | performed before the expression is evaluated. |
4470 | Within an expression, shell variables may also be referenced by name | |
4471 | without using the parameter expansion syntax. | |
b80f6443 JA |
4472 | A shell variable that is null or unset evaluates to 0 when referenced |
4473 | by name without using the parameter expansion syntax. | |
bb70624e | 4474 | The value of a variable is evaluated as an arithmetic expression |
b80f6443 | 4475 | when it is referenced, or when a variable which has been given the |
9a51695b | 4476 | \fIinteger\fP attribute using \fBdeclare \-i\fP is assigned a value. |
b80f6443 | 4477 | A null value evaluates to 0. |
495aee44 | 4478 | A shell variable need not have its \fIinteger\fP attribute |
cce855bc | 4479 | turned on to be used in an expression. |
ccc6cda3 | 4480 | .PP |
cce855bc JA |
4481 | Constants with a leading 0 are interpreted as octal numbers. |
4482 | A leading 0x or 0X denotes hexadecimal. | |
495aee44 | 4483 | Otherwise, numbers take the form [\fIbase#\fP]n, where the optional \fIbase\fP |
cce855bc JA |
4484 | is a decimal number between 2 and 64 representing the arithmetic |
4485 | base, and \fIn\fP is a number in that base. | |
bb70624e | 4486 | If \fIbase#\fP is omitted, then base 10 is used. |
ac50fbac | 4487 | When specifying \fIn\fP, |
a0c0a00f | 4488 | the digits greater than 9 are represented by the lowercase letters, |
f73dda09 | 4489 | the uppercase letters, @, and _, in that order. |
cce855bc | 4490 | If \fIbase\fP is less than or equal to 36, lowercase and uppercase |
95732b49 | 4491 | letters may be used interchangeably to represent numbers between 10 |
cce855bc | 4492 | and 35. |
ccc6cda3 | 4493 | .PP |
cce855bc JA |
4494 | Operators are evaluated in order of precedence. Sub-expressions in |
4495 | parentheses are evaluated first and may override the precedence | |
4496 | rules above. | |
4497 | .SH "CONDITIONAL EXPRESSIONS" | |
4498 | Conditional expressions are used by the \fB[[\fP compound command and | |
4499 | the \fBtest\fP and \fB[\fP builtin commands to test file attributes | |
4500 | and perform string and arithmetic comparisons. | |
2ae59c11 CR |
4501 | The \fBtest\fP abd \fB[\fP commands determine their behavior based on |
4502 | the number of arguments; see the descriptions of those commands for any | |
4503 | other command-specific actions. | |
4504 | .PP | |
cce855bc | 4505 | Expressions are formed from the following unary or binary primaries. |
a0c0a00f CR |
4506 | \fBBash\fP handles several filenames specially when they are used in |
4507 | expressions. | |
4508 | If the operating system on which \fBbash\fP is running provides these | |
4509 | special files, bash will use them; otherwise it will emulate them | |
4510 | internally with this behavior: | |
cce855bc | 4511 | If any \fIfile\fP argument to one of the primaries is of the form |
bb70624e JA |
4512 | \fI/dev/fd/n\fP, then file descriptor \fIn\fP is checked. |
4513 | If the \fIfile\fP argument to one of the primaries is one of | |
4514 | \fI/dev/stdin\fP, \fI/dev/stdout\fP, or \fI/dev/stderr\fP, file | |
4515 | descriptor 0, 1, or 2, respectively, is checked. | |
95732b49 JA |
4516 | .PP |
4517 | Unless otherwise specified, primaries that operate on files follow symbolic | |
4518 | links and operate on the target of the link, rather than the link itself. | |
0001803f CR |
4519 | .if t .sp 0.5 |
4520 | .if n .sp 1 | |
495aee44 | 4521 | When used with \fB[[\fP, the \fB<\fP and \fB>\fP operators sort |
0001803f | 4522 | lexicographically using the current locale. |
495aee44 | 4523 | The \fBtest\fP command sorts using ASCII ordering. |
cce855bc JA |
4524 | .sp 1 |
4525 | .PD 0 | |
4526 | .TP | |
4527 | .B \-a \fIfile\fP | |
4528 | True if \fIfile\fP exists. | |
4529 | .TP | |
4530 | .B \-b \fIfile\fP | |
4531 | True if \fIfile\fP exists and is a block special file. | |
4532 | .TP | |
4533 | .B \-c \fIfile\fP | |
4534 | True if \fIfile\fP exists and is a character special file. | |
4535 | .TP | |
4536 | .B \-d \fIfile\fP | |
4537 | True if \fIfile\fP exists and is a directory. | |
4538 | .TP | |
4539 | .B \-e \fIfile\fP | |
4540 | True if \fIfile\fP exists. | |
4541 | .TP | |
4542 | .B \-f \fIfile\fP | |
4543 | True if \fIfile\fP exists and is a regular file. | |
4544 | .TP | |
4545 | .B \-g \fIfile\fP | |
4546 | True if \fIfile\fP exists and is set-group-id. | |
4547 | .TP | |
b72432fd JA |
4548 | .B \-h \fIfile\fP |
4549 | True if \fIfile\fP exists and is a symbolic link. | |
4550 | .TP | |
cce855bc JA |
4551 | .B \-k \fIfile\fP |
4552 | True if \fIfile\fP exists and its ``sticky'' bit is set. | |
4553 | .TP | |
4554 | .B \-p \fIfile\fP | |
4555 | True if \fIfile\fP exists and is a named pipe (FIFO). | |
4556 | .TP | |
4557 | .B \-r \fIfile\fP | |
4558 | True if \fIfile\fP exists and is readable. | |
4559 | .TP | |
4560 | .B \-s \fIfile\fP | |
4561 | True if \fIfile\fP exists and has a size greater than zero. | |
4562 | .TP | |
4563 | .B \-t \fIfd\fP | |
4564 | True if file descriptor | |
4565 | .I fd | |
4566 | is open and refers to a terminal. | |
4567 | .TP | |
4568 | .B \-u \fIfile\fP | |
4569 | True if \fIfile\fP exists and its set-user-id bit is set. | |
4570 | .TP | |
4571 | .B \-w \fIfile\fP | |
4572 | True if \fIfile\fP exists and is writable. | |
4573 | .TP | |
4574 | .B \-x \fIfile\fP | |
4575 | True if \fIfile\fP exists and is executable. | |
4576 | .TP | |
cce855bc JA |
4577 | .B \-G \fIfile\fP |
4578 | True if \fIfile\fP exists and is owned by the effective group id. | |
4579 | .TP | |
4580 | .B \-L \fIfile\fP | |
4581 | True if \fIfile\fP exists and is a symbolic link. | |
4582 | .TP | |
495aee44 CR |
4583 | .B \-N \fIfile\fP |
4584 | True if \fIfile\fP exists and has been modified since it was last read. | |
4585 | .TP | |
4586 | .B \-O \fIfile\fP | |
4587 | True if \fIfile\fP exists and is owned by the effective user id. | |
4588 | .TP | |
cce855bc JA |
4589 | .B \-S \fIfile\fP |
4590 | True if \fIfile\fP exists and is a socket. | |
4591 | .TP | |
495aee44 CR |
4592 | \fIfile1\fP \fB\-ef\fP \fIfile2\fP |
4593 | True if \fIfile1\fP and \fIfile2\fP refer to the same device and | |
4594 | inode numbers. | |
cce855bc JA |
4595 | .TP |
4596 | \fIfile1\fP \-\fBnt\fP \fIfile2\fP | |
7117c2d2 JA |
4597 | True if \fIfile1\fP is newer (according to modification date) than \fIfile2\fP, |
4598 | or if \fIfile1\fP exists and \fPfile2\fP does not. | |
cce855bc JA |
4599 | .TP |
4600 | \fIfile1\fP \-\fBot\fP \fIfile2\fP | |
7117c2d2 JA |
4601 | True if \fIfile1\fP is older than \fIfile2\fP, or if \fIfile2\fP exists |
4602 | and \fIfile1\fP does not. | |
cce855bc | 4603 | .TP |
cce855bc | 4604 | .B \-o \fIoptname\fP |
495aee44 | 4605 | True if the shell option |
cce855bc JA |
4606 | .I optname |
4607 | is enabled. | |
4608 | See the list of options under the description of the | |
4609 | .B \-o | |
4610 | option to the | |
4611 | .B set | |
4612 | builtin below. | |
4613 | .TP | |
495aee44 CR |
4614 | .B \-v \fIvarname\fP |
4615 | True if the shell variable | |
4616 | .I varname | |
4617 | is set (has been assigned a value). | |
4618 | .TP | |
ac50fbac CR |
4619 | .B \-R \fIvarname\fP |
4620 | True if the shell variable | |
4621 | .I varname | |
4622 | is set and is a name reference. | |
4623 | .TP | |
cce855bc JA |
4624 | .B \-z \fIstring\fP |
4625 | True if the length of \fIstring\fP is zero. | |
4626 | .TP | |
cce855bc | 4627 | \fIstring\fP |
b80f6443 JA |
4628 | .PD 0 |
4629 | .TP | |
4630 | .B \-n \fIstring\fP | |
4631 | .PD | |
cce855bc JA |
4632 | True if the length of |
4633 | .I string | |
4634 | is non-zero. | |
4635 | .TP | |
4636 | \fIstring1\fP \fB==\fP \fIstring2\fP | |
0001803f CR |
4637 | .PD 0 |
4638 | .TP | |
4639 | \fIstring1\fP \fB=\fP \fIstring2\fP | |
4640 | .PD | |
4641 | True if the strings are equal. \fB=\fP should be used | |
4642 | with the \fBtest\fP command for POSIX conformance. | |
ac50fbac CR |
4643 | When used with the \fB[[\fP command, this performs pattern matching as |
4644 | described above (\fBCompound Commands\fP). | |
cce855bc JA |
4645 | .TP |
4646 | \fIstring1\fP \fB!=\fP \fIstring2\fP | |
4647 | True if the strings are not equal. | |
4648 | .TP | |
4649 | \fIstring1\fP \fB<\fP \fIstring2\fP | |
0001803f | 4650 | True if \fIstring1\fP sorts before \fIstring2\fP lexicographically. |
cce855bc JA |
4651 | .TP |
4652 | \fIstring1\fP \fB>\fP \fIstring2\fP | |
0001803f | 4653 | True if \fIstring1\fP sorts after \fIstring2\fP lexicographically. |
cce855bc JA |
4654 | .TP |
4655 | .I \fIarg1\fP \fBOP\fP \fIarg2\fP | |
4656 | .SM | |
4657 | .B OP | |
4658 | is one of | |
4659 | .BR \-eq , | |
4660 | .BR \-ne , | |
4661 | .BR \-lt , | |
4662 | .BR \-le , | |
4663 | .BR \-gt , | |
4664 | or | |
4665 | .BR \-ge . | |
4666 | These arithmetic binary operators return true if \fIarg1\fP | |
4667 | is equal to, not equal to, less than, less than or equal to, | |
4668 | greater than, or greater than or equal to \fIarg2\fP, respectively. | |
4669 | .I Arg1 | |
4670 | and | |
4671 | .I arg2 | |
4672 | may be positive or negative integers. | |
9a51695b CR |
4673 | When used with the \fB[[\fP command, |
4674 | .I Arg1 | |
4675 | and | |
4676 | .I Arg2 | |
4677 | are evaluated as arithmetic expressions (see | |
4678 | .SM | |
4679 | .B "ARITHMETIC EVALUATION" | |
4680 | above). | |
cce855bc JA |
4681 | .PD |
4682 | .SH "SIMPLE COMMAND EXPANSION" | |
4683 | When a simple command is executed, the shell performs the following | |
4684 | expansions, assignments, and redirections, from left to right. | |
4685 | .IP 1. | |
4686 | The words that the parser has marked as variable assignments (those | |
4687 | preceding the command name) and redirections are saved for later | |
4688 | processing. | |
4689 | .IP 2. | |
4690 | The words that are not variable assignments or redirections are | |
4691 | expanded. If any words remain after expansion, the first word | |
4692 | is taken to be the name of the command and the remaining words are | |
4693 | the arguments. | |
4694 | .IP 3. | |
4695 | Redirections are performed as described above under | |
4696 | .SM | |
4697 | .BR REDIRECTION . | |
4698 | .IP 4. | |
4699 | The text after the \fB=\fP in each variable assignment undergoes tilde | |
4700 | expansion, parameter expansion, command substitution, arithmetic expansion, | |
4701 | and quote removal before being assigned to the variable. | |
4702 | .PP | |
4703 | If no command name results, the variable assignments affect the current | |
4704 | shell environment. Otherwise, the variables are added to the environment | |
4705 | of the executed command and do not affect the current shell environment. | |
4706 | If any of the assignments attempts to assign a value to a readonly variable, | |
4707 | an error occurs, and the command exits with a non-zero status. | |
4708 | .PP | |
4709 | If no command name results, redirections are performed, but do not | |
4710 | affect the current shell environment. A redirection error causes the | |
4711 | command to exit with a non-zero status. | |
4712 | .PP | |
4713 | If there is a command name left after expansion, execution proceeds as | |
4714 | described below. Otherwise, the command exits. If one of the expansions | |
4715 | contained a command substitution, the exit status of the command is | |
4716 | the exit status of the last command substitution performed. If there | |
4717 | were no command substitutions, the command exits with a status of zero. | |
4718 | .SH "COMMAND EXECUTION" | |
4719 | After a command has been split into words, if it results in a | |
4720 | simple command and an optional list of arguments, the following | |
4721 | actions are taken. | |
4722 | .PP | |
4723 | If the command name contains no slashes, the shell attempts to | |
4724 | locate it. If there exists a shell function by that name, that | |
4725 | function is invoked as described above in | |
4726 | .SM | |
4727 | .BR FUNCTIONS . | |
4728 | If the name does not match a function, the shell searches for | |
4729 | it in the list of shell builtins. If a match is found, that | |
4730 | builtin is invoked. | |
4731 | .PP | |
4732 | If the name is neither a shell function nor a builtin, | |
4733 | and contains no slashes, | |
4734 | .B bash | |
4735 | searches each element of the | |
4736 | .SM | |
4737 | .B PATH | |
4738 | for a directory containing an executable file by that name. | |
4739 | .B Bash | |
bb70624e | 4740 | uses a hash table to remember the full pathnames of executable |
cce855bc JA |
4741 | files (see |
4742 | .B hash | |
4743 | under | |
4744 | .SM | |
4745 | .B "SHELL BUILTIN COMMANDS" | |
4746 | below). | |
4747 | A full search of the directories in | |
4748 | .SM | |
4749 | .B PATH | |
4750 | is performed only if the command is not found in the hash table. | |
3185942a JA |
4751 | If the search is unsuccessful, the shell searches for a defined shell |
4752 | function named \fBcommand_not_found_handle\fP. | |
9a51695b CR |
4753 | If that function exists, it is invoked in a separate execution environment |
4754 | with the original command and | |
3185942a | 4755 | the original command's arguments as its arguments, and the function's |
9a51695b | 4756 | exit status becomes the exit status of that subshell. |
3185942a | 4757 | If that function is not defined, the shell prints an error |
cce855bc JA |
4758 | message and returns an exit status of 127. |
4759 | .PP | |
4760 | If the search is successful, or if the command name contains | |
4761 | one or more slashes, the shell executes the named program in a | |
4762 | separate execution environment. | |
4763 | Argument 0 is set to the name given, and the remaining arguments | |
4764 | to the command are set to the arguments given, if any. | |
4765 | .PP | |
4766 | If this execution fails because the file is not in executable | |
4767 | format, and the file is not a directory, it is assumed to be | |
4768 | a \fIshell script\fP, a file | |
4769 | containing shell commands. A subshell is spawned to execute | |
4770 | it. This subshell reinitializes itself, so | |
4771 | that the effect is as if a new shell had been invoked | |
4772 | to handle the script, with the exception that the locations of | |
4773 | commands remembered by the parent (see | |
4774 | .B hash | |
4775 | below under | |
4776 | .SM | |
4777 | \fBSHELL BUILTIN COMMANDS\fP) | |
4778 | are retained by the child. | |
4779 | .PP | |
4780 | If the program is a file beginning with | |
4781 | .BR #! , | |
4782 | the remainder of the first line specifies an interpreter | |
4783 | for the program. The shell executes the | |
4784 | specified interpreter on operating systems that do not | |
a0c0a00f | 4785 | handle this executable format themselves. The arguments to the |
cce855bc JA |
4786 | interpreter consist of a single optional argument following the |
4787 | interpreter name on the first line of the program, followed | |
4788 | by the name of the program, followed by the command | |
4789 | arguments, if any. | |
4790 | .SH COMMAND EXECUTION ENVIRONMENT | |
4791 | The shell has an \fIexecution environment\fP, which consists of the | |
4792 | following: | |
cce855bc JA |
4793 | .IP \(bu |
4794 | open files inherited by the shell at invocation, as modified by | |
4795 | redirections supplied to the \fBexec\fP builtin | |
4796 | .IP \(bu | |
4797 | the current working directory as set by \fBcd\fP, \fBpushd\fP, or | |
4798 | \fBpopd\fP, or inherited by the shell at invocation | |
4799 | .IP \(bu | |
4800 | the file creation mode mask as set by \fBumask\fP or inherited from | |
4801 | the shell's parent | |
4802 | .IP \(bu | |
4803 | current traps set by \fBtrap\fP | |
4804 | .IP \(bu | |
4805 | shell parameters that are set by variable assignment or with \fBset\fP | |
4806 | or inherited from the shell's parent in the environment | |
4807 | .IP \(bu | |
4808 | shell functions defined during execution or inherited from the shell's | |
4809 | parent in the environment | |
4810 | .IP \(bu | |
4811 | options enabled at invocation (either by default or with command-line | |
4812 | arguments) or by \fBset\fP | |
4813 | .IP \(bu | |
4814 | options enabled by \fBshopt\fP | |
4815 | .IP \(bu | |
4816 | shell aliases defined with \fBalias\fP | |
4817 | .IP \(bu | |
4818 | various process IDs, including those of background jobs, the value | |
0001803f CR |
4819 | of \fB$$\fP, and the value of |
4820 | .SM | |
4821 | .B PPID | |
cce855bc JA |
4822 | .PP |
4823 | When a simple command other than a builtin or shell function | |
4824 | is to be executed, it | |
4825 | is invoked in a separate execution environment that consists of | |
4826 | the following. Unless otherwise noted, the values are inherited | |
4827 | from the shell. | |
0001803f | 4828 | .if n .sp 1 |
cce855bc JA |
4829 | .IP \(bu |
4830 | the shell's open files, plus any modifications and additions specified | |
4831 | by redirections to the command | |
4832 | .IP \(bu | |
4833 | the current working directory | |
4834 | .IP \(bu | |
4835 | the file creation mode mask | |
4836 | .IP \(bu | |
b80f6443 JA |
4837 | shell variables and functions marked for export, along with variables |
4838 | exported for the command, passed in the environment | |
cce855bc | 4839 | .IP \(bu |
b80f6443 JA |
4840 | traps caught by the shell are reset to the values inherited from the |
4841 | shell's parent, and traps ignored by the shell are ignored | |
cce855bc JA |
4842 | .PP |
4843 | A command invoked in this separate environment cannot affect the | |
a0c0a00f | 4844 | shell's execution environment. |
cce855bc | 4845 | .PP |
b80f6443 JA |
4846 | Command substitution, commands grouped with parentheses, |
4847 | and asynchronous commands are invoked in a | |
cce855bc JA |
4848 | subshell environment that is a duplicate of the shell environment, |
4849 | except that traps caught by the shell are reset to the values | |
4850 | that the shell inherited from its parent at invocation. Builtin | |
4851 | commands that are invoked as part of a pipeline are also executed in a | |
4852 | subshell environment. Changes made to the subshell environment | |
4853 | cannot affect the shell's execution environment. | |
f73dda09 | 4854 | .PP |
3185942a | 4855 | Subshells spawned to execute command substitutions inherit the value of |
2f5dfe5a | 4856 | the \fB\-e\fP option from the parent shell. When not in \fIposix mode\fP, |
495aee44 | 4857 | \fBbash\fP clears the \fB\-e\fP option in such subshells. |
3185942a | 4858 | .PP |
f73dda09 JA |
4859 | If a command is followed by a \fB&\fP and job control is not active, the |
4860 | default standard input for the command is the empty file \fI/dev/null\fP. | |
4861 | Otherwise, the invoked command inherits the file descriptors of the calling | |
4862 | shell as modified by redirections. | |
cce855bc JA |
4863 | .SH ENVIRONMENT |
4864 | When a program is invoked it is given an array of strings | |
4865 | called the | |
4866 | .IR environment . | |
a0c0a00f | 4867 | This is a list of |
cce855bc JA |
4868 | \fIname\fP\-\fIvalue\fP pairs, of the form |
4869 | .IR "name\fR=\fPvalue" . | |
4870 | .PP | |
bb70624e JA |
4871 | The shell provides several ways to manipulate the environment. |
4872 | On invocation, the shell scans its own environment and | |
cce855bc JA |
4873 | creates a parameter for each name found, automatically marking |
4874 | it for | |
4875 | .I export | |
4876 | to child processes. Executed commands inherit the environment. | |
4877 | The | |
4878 | .B export | |
4879 | and | |
4880 | .B declare \-x | |
4881 | commands allow parameters and functions to be added to and | |
4882 | deleted from the environment. If the value of a parameter | |
4883 | in the environment is modified, the new value becomes part | |
4884 | of the environment, replacing the old. The environment | |
4885 | inherited by any executed command consists of the shell's | |
4886 | initial environment, whose values may be modified in the shell, | |
4887 | less any pairs removed by the | |
4888 | .B unset | |
4889 | command, plus any additions via the | |
4890 | .B export | |
4891 | and | |
4892 | .B declare \-x | |
4893 | commands. | |
4894 | .PP | |
4895 | The environment for any | |
4896 | .I simple command | |
4897 | or function may be augmented temporarily by prefixing it with | |
4898 | parameter assignments, as described above in | |
4899 | .SM | |
4900 | .BR PARAMETERS . | |
4901 | These assignment statements affect only the environment seen | |
4902 | by that command. | |
4903 | .PP | |
a0c0a00f | 4904 | If the |
cce855bc JA |
4905 | .B \-k |
4906 | option is set (see the | |
4907 | .B set | |
4908 | builtin command below), then | |
4909 | .I all | |
4910 | parameter assignments are placed in the environment for a command, | |
4911 | not just those that precede the command name. | |
4912 | .PP | |
4913 | When | |
4914 | .B bash | |
4915 | invokes an external command, the variable | |
4916 | .B _ | |
ac50fbac | 4917 | is set to the full filename of the command and passed to that |
ccc6cda3 JA |
4918 | command in its environment. |
4919 | .SH "EXIT STATUS" | |
3185942a JA |
4920 | .PP |
4921 | The exit status of an executed command is the value returned by the | |
4922 | \fIwaitpid\fP system call or equivalent function. Exit statuses | |
4923 | fall between 0 and 255, though, as explained below, the shell may | |
4924 | use values above 125 specially. Exit statuses from shell builtins and | |
a0c0a00f | 4925 | compound commands are also limited to this range. Under certain |
3185942a JA |
4926 | circumstances, the shell will use special values to indicate specific |
4927 | failure modes. | |
4928 | .PP | |
a0c0a00f | 4929 | For the shell's purposes, a command which exits with a |
ccc6cda3 JA |
4930 | zero exit status has succeeded. An exit status of zero |
4931 | indicates success. A non-zero exit status indicates failure. | |
bb70624e JA |
4932 | When a command terminates on a fatal signal \fIN\fP, \fBbash\fP uses |
4933 | the value of 128+\fIN\fP as the exit status. | |
ccc6cda3 JA |
4934 | .PP |
4935 | If a command is not found, the child process created to | |
4936 | execute it returns a status of 127. If a command is found | |
4937 | but is not executable, the return status is 126. | |
4938 | .PP | |
cce855bc JA |
4939 | If a command fails because of an error during expansion or redirection, |
4940 | the exit status is greater than zero. | |
4941 | .PP | |
ccc6cda3 JA |
4942 | Shell builtin commands return a status of 0 (\fItrue\fP) if |
4943 | successful, and non-zero (\fIfalse\fP) if an error occurs | |
a0c0a00f CR |
4944 | while they execute. |
4945 | All builtins return an exit status of 2 to indicate incorrect usage, | |
4946 | generally invalid options or missing arguments. | |
ccc6cda3 JA |
4947 | .PP |
4948 | \fBBash\fP itself returns the exit status of the last command | |
4949 | executed, unless a syntax error occurs, in which case it exits | |
4950 | with a non-zero value. See also the \fBexit\fP builtin | |
4951 | command below. | |
4952 | .SH SIGNALS | |
cce855bc | 4953 | When \fBbash\fP is interactive, in the absence of any traps, it ignores |
ccc6cda3 JA |
4954 | .SM |
4955 | .B SIGTERM | |
4956 | (so that \fBkill 0\fP does not kill an interactive shell), | |
4957 | and | |
4958 | .SM | |
4959 | .B SIGINT | |
4960 | is caught and handled (so that the \fBwait\fP builtin is interruptible). | |
4961 | In all cases, \fBbash\fP ignores | |
4962 | .SM | |
4963 | .BR SIGQUIT . | |
4964 | If job control is in effect, | |
4965 | .B bash | |
4966 | ignores | |
4967 | .SM | |
4968 | .BR SIGTTIN , | |
4969 | .SM | |
4970 | .BR SIGTTOU , | |
4971 | and | |
4972 | .SM | |
4973 | .BR SIGTSTP . | |
4974 | .PP | |
b80f6443 | 4975 | Non-builtin commands run by \fBbash\fP have signal handlers |
cce855bc JA |
4976 | set to the values inherited by the shell from its parent. |
4977 | When job control is not in effect, asynchronous commands | |
ccc6cda3 JA |
4978 | ignore |
4979 | .SM | |
4980 | .B SIGINT | |
4981 | and | |
4982 | .SM | |
cce855bc | 4983 | .B SIGQUIT |
b80f6443 | 4984 | in addition to these inherited handlers. |
ccc6cda3 JA |
4985 | Commands run as a result of command substitution ignore the |
4986 | keyboard-generated job control signals | |
4987 | .SM | |
4988 | .BR SIGTTIN , | |
4989 | .SM | |
4990 | .BR SIGTTOU , | |
4991 | and | |
4992 | .SM | |
4993 | .BR SIGTSTP . | |
4994 | .PP | |
4995 | The shell exits by default upon receipt of a | |
4996 | .SM | |
4997 | .BR SIGHUP . | |
f73dda09 | 4998 | Before exiting, an interactive shell resends the |
ccc6cda3 JA |
4999 | .SM |
5000 | .B SIGHUP | |
cce855bc JA |
5001 | to all jobs, running or stopped. |
5002 | Stopped jobs are sent | |
5003 | .SM | |
5004 | .B SIGCONT | |
5005 | to ensure that they receive the | |
5006 | .SM | |
5007 | .BR SIGHUP . | |
5008 | To prevent the shell from | |
5009 | sending the signal to a particular job, it should be removed from the | |
a0c0a00f | 5010 | jobs table with the |
ccc6cda3 JA |
5011 | .B disown |
5012 | builtin (see | |
5013 | .SM | |
5014 | .B "SHELL BUILTIN COMMANDS" | |
a0c0a00f | 5015 | below) or marked |
cce855bc | 5016 | to not receive |
ccc6cda3 | 5017 | .SM |
cce855bc JA |
5018 | .B SIGHUP |
5019 | using | |
5020 | .BR "disown \-h" . | |
5021 | .PP | |
5022 | If the | |
5023 | .B huponexit | |
5024 | shell option has been set with | |
5025 | .BR shopt , | |
5026 | .B bash | |
a0c0a00f | 5027 | sends a |
cce855bc JA |
5028 | .SM |
5029 | .B SIGHUP | |
5030 | to all jobs when an interactive login shell exits. | |
5031 | .PP | |
95732b49 | 5032 | If \fBbash\fP is waiting for a command to complete and receives a signal |
b80f6443 | 5033 | for which a trap has been set, the trap will not be executed until |
a0c0a00f | 5034 | the command completes. |
cce855bc JA |
5035 | When \fBbash\fP is waiting for an asynchronous command via the \fBwait\fP |
5036 | builtin, the reception of a signal for which a trap has been set will | |
5037 | cause the \fBwait\fP builtin to return immediately with an exit status | |
5038 | greater than 128, immediately after which the trap is executed. | |
ccc6cda3 JA |
5039 | .SH "JOB CONTROL" |
5040 | .I Job control | |
5041 | refers to the ability to selectively stop (\fIsuspend\fP) | |
5042 | the execution of processes and continue (\fIresume\fP) | |
5043 | their execution at a later point. A user typically employs | |
5044 | this facility via an interactive interface supplied jointly | |
0001803f | 5045 | by the operating system kernel's terminal driver and |
ccc6cda3 JA |
5046 | .BR bash . |
5047 | .PP | |
5048 | The shell associates a | |
5049 | .I job | |
5050 | with each pipeline. It keeps a table of currently executing | |
5051 | jobs, which may be listed with the | |
5052 | .B jobs | |
5053 | command. When | |
5054 | .B bash | |
5055 | starts a job asynchronously (in the | |
5056 | .IR background ), | |
5057 | it prints a line that looks like: | |
5058 | .RS | |
5059 | .PP | |
5060 | [1] 25647 | |
5061 | .RE | |
5062 | .PP | |
5063 | indicating that this job is job number 1 and that the process ID | |
5064 | of the last process in the pipeline associated with this job is 25647. | |
5065 | All of the processes in a single pipeline are members of the same job. | |
5066 | .B Bash | |
5067 | uses the | |
5068 | .I job | |
5069 | abstraction as the basis for job control. | |
5070 | .PP | |
5071 | To facilitate the implementation of the user interface to job | |
bb70624e | 5072 | control, the operating system maintains the notion of a \fIcurrent terminal |
ccc6cda3 JA |
5073 | process group ID\fP. Members of this process group (processes whose |
5074 | process group ID is equal to the current terminal process group ID) | |
5075 | receive keyboard-generated signals such as | |
5076 | .SM | |
5077 | .BR SIGINT . | |
5078 | These processes are said to be in the | |
5079 | .IR foreground . | |
5080 | .I Background | |
5081 | processes are those whose process group ID differs from the terminal's; | |
5082 | such processes are immune to keyboard-generated signals. | |
0001803f CR |
5083 | Only foreground processes are allowed to read from or, if the |
5084 | user so specifies with \f(CWstty tostop\fP, write to the | |
5085 | terminal. | |
5086 | Background processes which attempt to read from (write to when | |
5087 | \f(CWstty tostop\fP is in effect) the | |
a0c0a00f | 5088 | terminal are sent a |
ccc6cda3 JA |
5089 | .SM |
5090 | .B SIGTTIN (SIGTTOU) | |
0001803f | 5091 | signal by the kernel's terminal driver, |
ccc6cda3 JA |
5092 | which, unless caught, suspends the process. |
5093 | .PP | |
5094 | If the operating system on which | |
5095 | .B bash | |
5096 | is running supports | |
5097 | job control, | |
5098 | .B bash | |
bb70624e | 5099 | contains facilities to use it. |
ccc6cda3 JA |
5100 | Typing the |
5101 | .I suspend | |
5102 | character (typically | |
5103 | .BR ^Z , | |
5104 | Control-Z) while a process is running | |
a0c0a00f | 5105 | causes that process to be stopped and returns control to |
ccc6cda3 JA |
5106 | .BR bash . |
5107 | Typing the | |
5108 | .I "delayed suspend" | |
5109 | character (typically | |
5110 | .BR ^Y , | |
5111 | Control-Y) causes the process to be stopped when it | |
5112 | attempts to read input from the terminal, and control to | |
5113 | be returned to | |
5114 | .BR bash . | |
cce855bc | 5115 | The user may then manipulate the state of this job, using the |
ccc6cda3 JA |
5116 | .B bg |
5117 | command to continue it in the background, the | |
5118 | .B fg | |
5119 | command to continue it in the foreground, or | |
5120 | the | |
5121 | .B kill | |
5122 | command to kill it. A \fB^Z\fP takes effect immediately, | |
5123 | and has the additional side effect of causing pending output | |
5124 | and typeahead to be discarded. | |
5125 | .PP | |
5126 | There are a number of ways to refer to a job in the shell. | |
5127 | The character | |
5128 | .B % | |
3185942a | 5129 | introduces a job specification (\fIjobspec\fP). Job number |
ccc6cda3 JA |
5130 | .I n |
5131 | may be referred to as | |
5132 | .BR %n . | |
5133 | A job may also be referred to using a prefix of the name used to | |
5134 | start it, or using a substring that appears in its command line. | |
5135 | For example, | |
5136 | .B %ce | |
5137 | refers to a stopped | |
5138 | .B ce | |
5139 | job. If a prefix matches more than one job, | |
5140 | .B bash | |
5141 | reports an error. Using | |
5142 | .BR %?ce , | |
5143 | on the other hand, refers to any job containing the string | |
5144 | .B ce | |
5145 | in its command line. If the substring matches more than one job, | |
5146 | .B bash | |
5147 | reports an error. The symbols | |
5148 | .B %% | |
5149 | and | |
5150 | .B %+ | |
5151 | refer to the shell's notion of the | |
5152 | .IR "current job" , | |
5153 | which is the last job stopped while it was in | |
cce855bc | 5154 | the foreground or started in the background. |
a0c0a00f | 5155 | The |
ccc6cda3 JA |
5156 | .I "previous job" |
5157 | may be referenced using | |
5158 | .BR %\- . | |
3185942a JA |
5159 | If there is only a single job, \fB%+\fP and \fB%\-\fP can both be used |
5160 | to refer to that job. | |
ccc6cda3 JA |
5161 | In output pertaining to jobs (e.g., the output of the |
5162 | .B jobs | |
5163 | command), the current job is always flagged with a | |
5164 | .BR + , | |
5165 | and the previous job with a | |
5166 | .BR \- . | |
95732b49 JA |
5167 | A single % (with no accompanying job specification) also refers to the |
5168 | current job. | |
726f6388 | 5169 | .PP |
ccc6cda3 JA |
5170 | Simply naming a job can be used to bring it into the |
5171 | foreground: | |
5172 | .B %1 | |
5173 | is a synonym for | |
5174 | \fB``fg %1''\fP, | |
5175 | bringing job 1 from the background into the foreground. | |
5176 | Similarly, | |
5177 | .B ``%1 &'' | |
5178 | resumes job 1 in the background, equivalent to | |
5179 | \fB``bg %1''\fP. | |
726f6388 | 5180 | .PP |
ccc6cda3 JA |
5181 | The shell learns immediately whenever a job changes state. |
5182 | Normally, | |
5183 | .B bash | |
5184 | waits until it is about to print a prompt before reporting | |
5185 | changes in a job's status so as to not interrupt | |
a0c0a00f | 5186 | any other output. If the |
ccc6cda3 JA |
5187 | .B \-b |
5188 | option to the | |
726f6388 | 5189 | .B set |
ccc6cda3 | 5190 | builtin command |
cce855bc | 5191 | is enabled, |
726f6388 | 5192 | .B bash |
ccc6cda3 | 5193 | reports such changes immediately. |
f73dda09 JA |
5194 | Any trap on |
5195 | .SM | |
5196 | .B SIGCHLD | |
5197 | is executed for each child that exits. | |
726f6388 | 5198 | .PP |
ccc6cda3 JA |
5199 | If an attempt to exit |
5200 | .B bash | |
3185942a JA |
5201 | is made while jobs are stopped (or, if the \fBcheckjobs\fP shell option has |
5202 | been enabled using the \fBshopt\fP builtin, running), the shell prints a | |
5203 | warning message, and, if the \fBcheckjobs\fP option is enabled, lists the | |
5204 | jobs and their statuses. | |
5205 | The | |
ccc6cda3 | 5206 | .B jobs |
a0c0a00f | 5207 | command may then be used to inspect their status. |
ccc6cda3 | 5208 | If a second attempt to exit is made without an intervening command, |
3185942a | 5209 | the shell does not print another warning, and any stopped |
ccc6cda3 | 5210 | jobs are terminated. |
9a51695b CR |
5211 | .PP |
5212 | When the shell is waiting for a job or process using the \fBwait\fP | |
5213 | builtin, and job control is enabled, \fBwait\fP will return when the | |
5214 | job changes state. The \fB\-f\fP option will force \fBwait\fP to wait | |
5215 | until the job or process terminates before returning. | |
726f6388 | 5216 | .SH PROMPTING |
a0c0a00f | 5217 | When executing interactively, |
726f6388 JA |
5218 | .B bash |
5219 | displays the primary prompt | |
5220 | .SM | |
5221 | .B PS1 | |
5222 | when it is ready to read a command, and the secondary prompt | |
5223 | .SM | |
5224 | .B PS2 | |
5225 | when it needs more input to complete a command. | |
5226 | .B Bash | |
a0c0a00f | 5227 | displays |
9a51695b | 5228 | .SM |
a0c0a00f CR |
5229 | .B PS0 |
5230 | after it reads a command but before executing it. | |
5231 | .B Bash | |
9a51695b CR |
5232 | displays |
5233 | .SM | |
5234 | .B PS4 | |
5235 | as described above | |
5236 | before tracing each command when the \fB\-x\fP option is enabled. | |
5237 | .B Bash | |
726f6388 JA |
5238 | allows these prompt strings to be customized by inserting a number of |
5239 | backslash-escaped special characters that are decoded as follows: | |
5240 | .RS | |
5241 | .PD 0 | |
5242 | .TP | |
ccc6cda3 JA |
5243 | .B \ea |
5244 | an ASCII bell character (07) | |
726f6388 JA |
5245 | .TP |
5246 | .B \ed | |
5247 | the date in "Weekday Month Date" format (e.g., "Tue May 26") | |
5248 | .TP | |
7117c2d2 JA |
5249 | .B \eD{\fIformat\fP} |
5250 | the \fIformat\fP is passed to \fIstrftime\fP(3) and the result is inserted | |
5251 | into the prompt string; an empty \fIformat\fP results in a locale-specific | |
5252 | time representation. The braces are required | |
5253 | .TP | |
ccc6cda3 JA |
5254 | .B \ee |
5255 | an ASCII escape character (033) | |
5256 | .TP | |
5257 | .B \eh | |
5258 | the hostname up to the first `.' | |
5259 | .TP | |
5260 | .B \eH | |
5261 | the hostname | |
5262 | .TP | |
bb70624e JA |
5263 | .B \ej |
5264 | the number of jobs currently managed by the shell | |
5265 | .TP | |
5266 | .B \el | |
5267 | the basename of the shell's terminal device name | |
5268 | .TP | |
726f6388 JA |
5269 | .B \en |
5270 | newline | |
5271 | .TP | |
cce855bc JA |
5272 | .B \er |
5273 | carriage return | |
5274 | .TP | |
726f6388 JA |
5275 | .B \es |
5276 | the name of the shell, the basename of | |
5277 | .B $0 | |
5278 | (the portion following the final slash) | |
5279 | .TP | |
ccc6cda3 JA |
5280 | .B \et |
5281 | the current time in 24-hour HH:MM:SS format | |
726f6388 | 5282 | .TP |
ccc6cda3 JA |
5283 | .B \eT |
5284 | the current time in 12-hour HH:MM:SS format | |
5285 | .TP | |
5286 | .B \e@ | |
5287 | the current time in 12-hour am/pm format | |
726f6388 | 5288 | .TP |
f73dda09 JA |
5289 | .B \eA |
5290 | the current time in 24-hour HH:MM format | |
5291 | .TP | |
726f6388 JA |
5292 | .B \eu |
5293 | the username of the current user | |
5294 | .TP | |
ccc6cda3 JA |
5295 | .B \ev |
5296 | the version of \fBbash\fP (e.g., 2.00) | |
726f6388 | 5297 | .TP |
ccc6cda3 | 5298 | .B \eV |
b80f6443 | 5299 | the release of \fBbash\fP, version + patch level (e.g., 2.00.0) |
ccc6cda3 JA |
5300 | .TP |
5301 | .B \ew | |
0001803f CR |
5302 | the current working directory, with |
5303 | .SM | |
5304 | .B $HOME | |
5305 | abbreviated with a tilde | |
5306 | (uses the value of the | |
5307 | .SM | |
5308 | .B PROMPT_DIRTRIM | |
5309 | variable) | |
ccc6cda3 JA |
5310 | .TP |
5311 | .B \eW | |
0001803f CR |
5312 | the basename of the current working directory, with |
5313 | .SM | |
5314 | .B $HOME | |
b80f6443 | 5315 | abbreviated with a tilde |
726f6388 JA |
5316 | .TP |
5317 | .B \e! | |
5318 | the history number of this command | |
5319 | .TP | |
ccc6cda3 JA |
5320 | .B \e# |
5321 | the command number of this command | |
5322 | .TP | |
726f6388 JA |
5323 | .B \e$ |
5324 | if the effective UID is 0, a | |
5325 | .BR # , | |
5326 | otherwise a | |
5327 | .B $ | |
5328 | .TP | |
ccc6cda3 JA |
5329 | .B \e\fInnn\fP |
5330 | the character corresponding to the octal number \fInnn\fP | |
726f6388 JA |
5331 | .TP |
5332 | .B \e\e | |
5333 | a backslash | |
5334 | .TP | |
5335 | .B \e[ | |
5336 | begin a sequence of non-printing characters, which could be used to | |
5337 | embed a terminal control sequence into the prompt | |
5338 | .TP | |
5339 | .B \e] | |
5340 | end a sequence of non-printing characters | |
5341 | .PD | |
5342 | .RE | |
5343 | .PP | |
5344 | The command number and the history number are usually different: | |
5345 | the history number of a command is its position in the history | |
5346 | list, which may include commands restored from the history file | |
5347 | (see | |
5348 | .SM | |
5349 | .B HISTORY | |
5350 | below), while the command number is the position in the sequence | |
5351 | of commands executed during the current shell session. | |
5352 | After the string is decoded, it is expanded via | |
bb70624e JA |
5353 | parameter expansion, command substitution, arithmetic |
5354 | expansion, and quote removal, subject to the value of the | |
ccc6cda3 JA |
5355 | .B promptvars |
5356 | shell option (see the description of the | |
5357 | .B shopt | |
5358 | command under | |
5359 | .SM | |
5360 | .B "SHELL BUILTIN COMMANDS" | |
5361 | below). | |
726f6388 JA |
5362 | .SH READLINE |
5363 | This is the library that handles reading input when using an interactive | |
5364 | shell, unless the | |
d166f048 | 5365 | .B \-\-noediting |
ccc6cda3 | 5366 | option is given at shell invocation. |
3185942a JA |
5367 | Line editing is also used when using the \fB\-e\fP option to the |
5368 | \fBread\fP builtin. | |
495aee44 | 5369 | By default, the line editing commands are similar to those of Emacs. |
726f6388 | 5370 | A vi-style line editing interface is also available. |
3185942a JA |
5371 | Line editing can be enabled at any time using the |
5372 | .B \-o emacs | |
ccc6cda3 | 5373 | or |
3185942a | 5374 | .B \-o vi |
ccc6cda3 JA |
5375 | options to the |
5376 | .B set | |
5377 | builtin (see | |
5378 | .SM | |
5379 | .B SHELL BUILTIN COMMANDS | |
5380 | below). | |
3185942a JA |
5381 | To turn off line editing after the shell is running, use the |
5382 | .B +o emacs | |
5383 | or | |
5384 | .B +o vi | |
5385 | options to the | |
5386 | .B set | |
5387 | builtin. | |
ccc6cda3 | 5388 | .SS "Readline Notation" |
726f6388 | 5389 | .PP |
495aee44 | 5390 | In this section, the Emacs-style notation is used to denote |
726f6388 | 5391 | keystrokes. Control keys are denoted by C\-\fIkey\fR, e.g., C\-n |
a0c0a00f | 5392 | means Control\-N. Similarly, |
726f6388 JA |
5393 | .I meta |
5394 | keys are denoted by M\-\fIkey\fR, so M\-x means Meta\-X. (On keyboards | |
a0c0a00f | 5395 | without a |
726f6388 JA |
5396 | .I meta |
5397 | key, M\-\fIx\fP means ESC \fIx\fP, i.e., press the Escape key | |
5398 | then the | |
5399 | .I x | |
5400 | key. This makes ESC the \fImeta prefix\fP. | |
5401 | The combination M\-C\-\fIx\fP means ESC\-Control\-\fIx\fP, | |
5402 | or press the Escape key | |
5403 | then hold the Control key while pressing the | |
5404 | .I x | |
5405 | key.) | |
5406 | .PP | |
ccc6cda3 JA |
5407 | Readline commands may be given numeric |
5408 | .IR arguments , | |
5409 | which normally act as a repeat count. | |
5410 | Sometimes, however, it is the sign of the argument that is significant. | |
5411 | Passing a negative argument to a command that acts in the forward | |
5412 | direction (e.g., \fBkill\-line\fP) causes that command to act in a | |
a0c0a00f | 5413 | backward direction. |
ccc6cda3 JA |
5414 | Commands whose behavior with arguments deviates from this are noted |
5415 | below. | |
5416 | .PP | |
5417 | When a command is described as \fIkilling\fP text, the text | |
5418 | deleted is saved for possible future retrieval | |
5419 | (\fIyanking\fP). The killed text is saved in a | |
5420 | \fIkill ring\fP. Consecutive kills cause the text to be | |
a0c0a00f | 5421 | accumulated into one unit, which can be yanked all at once. |
ccc6cda3 JA |
5422 | Commands which do not kill text separate the chunks of text |
5423 | on the kill ring. | |
5424 | .SS "Readline Initialization" | |
5425 | .PP | |
5426 | Readline is customized by putting commands in an initialization | |
5427 | file (the \fIinputrc\fP file). | |
5428 | The name of this file is taken from the value of the | |
726f6388 | 5429 | .SM |
ccc6cda3 JA |
5430 | .B INPUTRC |
5431 | variable. If that variable is unset, the default is | |
726f6388 | 5432 | .IR ~/.inputrc . |
ccc6cda3 JA |
5433 | When a program which uses the readline library starts up, the |
5434 | initialization file is read, and the key bindings and variables | |
5435 | are set. | |
5436 | There are only a few basic constructs allowed in the | |
5437 | readline initialization file. | |
5438 | Blank lines are ignored. | |
5439 | Lines beginning with a \fB#\fP are comments. | |
5440 | Lines beginning with a \fB$\fP indicate conditional constructs. | |
5441 | Other lines denote key bindings and variable settings. | |
5442 | .PP | |
5443 | The default key-bindings may be changed with an | |
a0c0a00f | 5444 | .I inputrc |
ccc6cda3 | 5445 | file. |
726f6388 JA |
5446 | Other programs that use this library may add their own commands |
5447 | and bindings. | |
5448 | .PP | |
5449 | For example, placing | |
5450 | .RS | |
5451 | .PP | |
5452 | M\-Control\-u: universal\-argument | |
5453 | .RE | |
5454 | or | |
5455 | .RS | |
5456 | C\-Meta\-u: universal\-argument | |
5457 | .RE | |
a0c0a00f | 5458 | into the |
ccc6cda3 | 5459 | .I inputrc |
726f6388 JA |
5460 | would make M\-C\-u execute the readline command |
5461 | .IR universal\-argument . | |
5462 | .PP | |
5463 | The following symbolic character names are recognized: | |
5464 | .IR RUBOUT , | |
5465 | .IR DEL , | |
5466 | .IR ESC , | |
5467 | .IR LFD , | |
5468 | .IR NEWLINE , | |
5469 | .IR RET , | |
5470 | .IR RETURN , | |
5471 | .IR SPC , | |
5472 | .IR SPACE , | |
5473 | and | |
5474 | .IR TAB . | |
bb70624e | 5475 | .PP |
726f6388 JA |
5476 | In addition to command names, readline allows keys to be bound |
5477 | to a string that is inserted when the key is pressed (a \fImacro\fP). | |
ccc6cda3 | 5478 | .SS "Readline Key Bindings" |
726f6388 JA |
5479 | .PP |
5480 | The syntax for controlling key bindings in the | |
cce855bc | 5481 | .I inputrc |
726f6388 JA |
5482 | file is simple. All that is required is the name of the |
5483 | command or the text of a macro and a key sequence to which | |
a0c0a00f | 5484 | it should be bound. The name may be specified in one of two ways: |
ccc6cda3 | 5485 | as a symbolic key name, possibly with \fIMeta\-\fP or \fIControl\-\fP |
726f6388 | 5486 | prefixes, or as a key sequence. |
28ef6c31 | 5487 | .PP |
cce855bc | 5488 | When using the form \fBkeyname\fP:\^\fIfunction\-name\fP or \fImacro\fP, |
726f6388 JA |
5489 | .I keyname |
5490 | is the name of a key spelled out in English. For example: | |
5491 | .sp | |
5492 | .RS | |
5493 | Control-u: universal\-argument | |
5494 | .br | |
5495 | Meta-Rubout: backward-kill-word | |
5496 | .br | |
ccc6cda3 | 5497 | Control-o: "> output" |
726f6388 JA |
5498 | .RE |
5499 | .LP | |
5500 | In the above example, | |
ccc6cda3 | 5501 | .I C\-u |
726f6388 JA |
5502 | is bound to the function |
5503 | .BR universal\-argument , | |
ccc6cda3 | 5504 | .I M\-DEL |
726f6388 JA |
5505 | is bound to the function |
5506 | .BR backward\-kill\-word , | |
5507 | and | |
ccc6cda3 | 5508 | .I C\-o |
726f6388 JA |
5509 | is bound to run the macro |
5510 | expressed on the right hand side (that is, to insert the text | |
28ef6c31 JA |
5511 | .if t \f(CW> output\fP |
5512 | .if n ``> output'' | |
726f6388 JA |
5513 | into the line). |
5514 | .PP | |
cce855bc | 5515 | In the second form, \fB"keyseq"\fP:\^\fIfunction\-name\fP or \fImacro\fP, |
726f6388 JA |
5516 | .B keyseq |
5517 | differs from | |
5518 | .B keyname | |
5519 | above in that strings denoting | |
5520 | an entire key sequence may be specified by placing the sequence | |
5521 | within double quotes. Some GNU Emacs style key escapes can be | |
28ef6c31 JA |
5522 | used, as in the following example, but the symbolic character names |
5523 | are not recognized. | |
726f6388 JA |
5524 | .sp |
5525 | .RS | |
ccc6cda3 | 5526 | "\eC\-u": universal\-argument |
726f6388 | 5527 | .br |
ccc6cda3 | 5528 | "\eC\-x\eC\-r": re\-read\-init\-file |
726f6388 JA |
5529 | .br |
5530 | "\ee[11~": "Function Key 1" | |
5531 | .RE | |
5532 | .PP | |
5533 | In this example, | |
ccc6cda3 | 5534 | .I C\-u |
726f6388 JA |
5535 | is again bound to the function |
5536 | .BR universal\-argument . | |
ccc6cda3 | 5537 | .I "C\-x C\-r" |
726f6388 JA |
5538 | is bound to the function |
5539 | .BR re\-read\-init\-file , | |
a0c0a00f | 5540 | and |
726f6388 JA |
5541 | .I "ESC [ 1 1 ~" |
5542 | is bound to insert the text | |
28ef6c31 JA |
5543 | .if t \f(CWFunction Key 1\fP. |
5544 | .if n ``Function Key 1''. | |
5545 | .PP | |
cce855bc | 5546 | The full set of GNU Emacs style escape sequences is |
726f6388 | 5547 | .RS |
cce855bc | 5548 | .PD 0 |
726f6388 JA |
5549 | .TP |
5550 | .B \eC\- | |
5551 | control prefix | |
5552 | .TP | |
ccc6cda3 | 5553 | .B \eM\- |
726f6388 JA |
5554 | meta prefix |
5555 | .TP | |
5556 | .B \ee | |
5557 | an escape character | |
5558 | .TP | |
5559 | .B \e\e | |
5560 | backslash | |
5561 | .TP | |
5562 | .B \e" | |
5563 | literal " | |
5564 | .TP | |
0628567a JA |
5565 | .B \e\(aq |
5566 | literal \(aq | |
726f6388 | 5567 | .RE |
cce855bc JA |
5568 | .PD |
5569 | .PP | |
5570 | In addition to the GNU Emacs style escape sequences, a second | |
5571 | set of backslash escapes is available: | |
5572 | .RS | |
5573 | .PD 0 | |
5574 | .TP | |
5575 | .B \ea | |
5576 | alert (bell) | |
5577 | .TP | |
5578 | .B \eb | |
5579 | backspace | |
5580 | .TP | |
5581 | .B \ed | |
5582 | delete | |
5583 | .TP | |
5584 | .B \ef | |
5585 | form feed | |
5586 | .TP | |
5587 | .B \en | |
5588 | newline | |
5589 | .TP | |
5590 | .B \er | |
5591 | carriage return | |
5592 | .TP | |
5593 | .B \et | |
5594 | horizontal tab | |
5595 | .TP | |
5596 | .B \ev | |
5597 | vertical tab | |
5598 | .TP | |
5599 | .B \e\fInnn\fP | |
f73dda09 | 5600 | the eight-bit character whose value is the octal value \fInnn\fP |
cce855bc JA |
5601 | (one to three digits) |
5602 | .TP | |
f73dda09 JA |
5603 | .B \ex\fIHH\fP |
5604 | the eight-bit character whose value is the hexadecimal value \fIHH\fP | |
5605 | (one or two hex digits) | |
cce855bc JA |
5606 | .RE |
5607 | .PD | |
726f6388 | 5608 | .PP |
cce855bc JA |
5609 | When entering the text of a macro, single or double quotes must |
5610 | be used to indicate a macro definition. | |
5611 | Unquoted text is assumed to be a function name. | |
5612 | In the macro body, the backslash escapes described above are expanded. | |
5613 | Backslash will quote any other character in the macro text, | |
0628567a | 5614 | including " and \(aq. |
726f6388 JA |
5615 | .PP |
5616 | .B Bash | |
5617 | allows the current readline key bindings to be displayed or modified | |
5618 | with the | |
5619 | .B bind | |
5620 | builtin command. The editing mode may be switched during interactive | |
5621 | use by using the | |
5622 | .B \-o | |
5623 | option to the | |
5624 | .B set | |
5625 | builtin command (see | |
5626 | .SM | |
5627 | .B SHELL BUILTIN COMMANDS | |
5628 | below). | |
ccc6cda3 | 5629 | .SS "Readline Variables" |
726f6388 JA |
5630 | .PP |
5631 | Readline has variables that can be used to further customize its | |
5632 | behavior. A variable may be set in the | |
5633 | .I inputrc | |
5634 | file with a statement of the form | |
5635 | .RS | |
5636 | .PP | |
5637 | \fBset\fP \fIvariable\-name\fP \fIvalue\fP | |
5638 | .RE | |
5639 | .PP | |
5640 | Except where noted, readline variables can take the values | |
5641 | .B On | |
5642 | or | |
95732b49 JA |
5643 | .B Off |
5644 | (without regard to case). | |
5645 | Unrecognized variable names are ignored. | |
5646 | When a variable value is read, empty or null values, "on" (case-insensitive), | |
5647 | and "1" are equivalent to \fBOn\fP. All other values are equivalent to | |
5648 | \fBOff\fP. | |
726f6388 JA |
5649 | The variables and their default values are: |
5650 | .PP | |
5651 | .PD 0 | |
5652 | .TP | |
726f6388 JA |
5653 | .B bell\-style (audible) |
5654 | Controls what happens when readline wants to ring the terminal bell. | |
5655 | If set to \fBnone\fP, readline never rings the bell. If set to | |
5656 | \fBvisible\fP, readline uses a visible bell if one is available. | |
5657 | If set to \fBaudible\fP, readline attempts to ring the terminal's bell. | |
5658 | .TP | |
95732b49 JA |
5659 | .B bind\-tty\-special\-chars (On) |
5660 | If set to \fBOn\fP, readline attempts to bind the control characters | |
5661 | treated specially by the kernel's terminal driver to their readline | |
5662 | equivalents. | |
5663 | .TP | |
a0c0a00f CR |
5664 | .B blink\-matching\-paren (Off) |
5665 | If set to \fBOn\fP, readline attempts to briefly move the cursor to an | |
5666 | opening parenthesis when a closing parenthesis is inserted. | |
5667 | .TP | |
5668 | .B colored\-completion\-prefix (Off) | |
5669 | If set to \fBOn\fP, when listing completions, readline displays the | |
5670 | common prefix of the set of possible completions using a different color. | |
5671 | The color definitions are taken from the value of the \fBLS_COLORS\fP | |
5672 | environment variable. | |
5673 | .TP | |
ac50fbac CR |
5674 | .B colored\-stats (Off) |
5675 | If set to \fBOn\fP, readline displays possible completions using different | |
a0c0a00f | 5676 | colors to indicate their file type. |
ac50fbac CR |
5677 | The color definitions are taken from the value of the \fBLS_COLORS\fP |
5678 | environment variable. | |
5679 | .TP | |
726f6388 | 5680 | .B comment\-begin (``#'') |
bb70624e | 5681 | The string that is inserted when the readline |
ccc6cda3 | 5682 | .B insert\-comment |
726f6388 | 5683 | command is executed. |
ccc6cda3 JA |
5684 | This command is bound to |
5685 | .B M\-# | |
5686 | in emacs mode and to | |
5687 | .B # | |
5688 | in vi command mode. | |
726f6388 | 5689 | .TP |
9a51695b | 5690 | .B completion\-display\-width (\-1) |
a0c0a00f CR |
5691 | The number of screen columns used to display possible matches |
5692 | when performing completion. | |
5693 | The value is ignored if it is less than 0 or greater than the terminal | |
5694 | screen width. | |
5695 | A value of 0 will cause matches to be displayed one per line. | |
9a51695b | 5696 | The default value is \-1. |
a0c0a00f | 5697 | .TP |
cce855bc JA |
5698 | .B completion\-ignore\-case (Off) |
5699 | If set to \fBOn\fP, readline performs filename matching and completion | |
5700 | in a case\-insensitive fashion. | |
5701 | .TP | |
a0c0a00f CR |
5702 | .B completion\-map\-case (Off) |
5703 | If set to \fBOn\fP, and \fBcompletion\-ignore\-case\fP is enabled, readline | |
5704 | treats hyphens (\fI\-\fP) and underscores (\fI_\fP) as equivalent when | |
5705 | performing case\-insensitive filename matching and completion. | |
5706 | .TP | |
3185942a JA |
5707 | .B completion\-prefix\-display\-length (0) |
5708 | The length in characters of the common prefix of a list of possible | |
5709 | completions that is displayed without modification. When set to a | |
5710 | value greater than zero, common prefixes longer than this value are | |
5711 | replaced with an ellipsis when displaying possible completions. | |
5712 | .TP | |
726f6388 JA |
5713 | .B completion\-query\-items (100) |
5714 | This determines when the user is queried about viewing | |
5715 | the number of possible completions | |
5716 | generated by the \fBpossible\-completions\fP command. | |
5717 | It may be set to any integer value greater than or equal to | |
5718 | zero. If the number of possible completions is greater than | |
5719 | or equal to the value of this variable, the user is asked whether | |
5720 | or not he wishes to view them; otherwise they are simply listed | |
5721 | on the terminal. | |
5722 | .TP | |
ccc6cda3 JA |
5723 | .B convert\-meta (On) |
5724 | If set to \fBOn\fP, readline will convert characters with the | |
5725 | eighth bit set to an ASCII key sequence | |
bb70624e | 5726 | by stripping the eighth bit and prefixing an |
ccc6cda3 | 5727 | escape character (in effect, using escape as the \fImeta prefix\fP). |
a0c0a00f CR |
5728 | The default is \fIOn\fP, but readline will set it to \fIOff\fP if the |
5729 | locale contains eight-bit characters. | |
ccc6cda3 JA |
5730 | .TP |
5731 | .B disable\-completion (Off) | |
5732 | If set to \fBOn\fP, readline will inhibit word completion. Completion | |
5733 | characters will be inserted into the line as if they had been | |
5734 | mapped to \fBself-insert\fP. | |
5735 | .TP | |
a0c0a00f CR |
5736 | .B echo\-control\-characters (On) |
5737 | When set to \fBOn\fP, on operating systems that indicate they support it, | |
5738 | readline echoes a character corresponding to a signal generated from the | |
5739 | keyboard. | |
5740 | .TP | |
ccc6cda3 JA |
5741 | .B editing\-mode (emacs) |
5742 | Controls whether readline begins with a set of key bindings similar | |
495aee44 | 5743 | to \fIEmacs\fP or \fIvi\fP. |
ccc6cda3 JA |
5744 | .B editing\-mode |
5745 | can be set to either | |
5746 | .B emacs | |
5747 | or | |
5748 | .BR vi . | |
5749 | .TP | |
9a51695b CR |
5750 | .B emacs\-mode\-string (@) |
5751 | If the \fIshow\-mode\-in\-prompt\fP variable is enabled, | |
5752 | this string is displayed immediately before the last line of the primary | |
5753 | prompt when emacs editing mode is active. The value is expanded like a | |
5754 | key binding, so the standard set of meta- and control prefixes and | |
5755 | backslash escape sequences is available. | |
5756 | Use the \e1 and \e2 escapes to begin and end sequences of | |
5757 | non-printing characters, which can be used to embed a terminal control | |
5758 | sequence into the mode string. | |
5759 | .TP | |
a0c0a00f CR |
5760 | .B enable\-bracketed\-paste (Off) |
5761 | When set to \fBOn\fP, readline will configure the terminal in a way | |
5762 | that will enable it to insert each paste into the editing buffer as a | |
5763 | single string of characters, instead of treating each character as if | |
5764 | it had been read from the keyboard. This can prevent pasted characters | |
5765 | from being interpreted as editing commands. | |
0001803f | 5766 | .TP |
ccc6cda3 JA |
5767 | .B enable\-keypad (Off) |
5768 | When set to \fBOn\fP, readline will try to enable the application | |
5769 | keypad when it is called. Some systems need this to enable the | |
5770 | arrow keys. | |
5771 | .TP | |
0001803f CR |
5772 | .B enable\-meta\-key (On) |
5773 | When set to \fBOn\fP, readline will try to enable any meta modifier | |
5774 | key the terminal claims to support when it is called. On many terminals, | |
5775 | the meta key is used to send eight-bit characters. | |
5776 | .TP | |
ccc6cda3 | 5777 | .B expand\-tilde (Off) |
495aee44 | 5778 | If set to \fBOn\fP, tilde expansion is performed when readline |
ccc6cda3 JA |
5779 | attempts word completion. |
5780 | .TP | |
95732b49 | 5781 | .B history\-preserve\-point (Off) |
495aee44 | 5782 | If set to \fBOn\fP, the history code attempts to place point at the |
95732b49 | 5783 | same location on each history line retrieved with \fBprevious-history\fP |
f73dda09 JA |
5784 | or \fBnext-history\fP. |
5785 | .TP | |
a0c0a00f | 5786 | .B history\-size (unset) |
ac50fbac CR |
5787 | Set the maximum number of history entries saved in the history list. |
5788 | If set to zero, any existing history entries are deleted and no new entries | |
5789 | are saved. | |
5790 | If set to a value less than zero, the number of history entries is not | |
5791 | limited. | |
a0c0a00f CR |
5792 | By default, the number of history entries is set to the value of the |
5793 | \fBHISTSIZE\fP shell variable. | |
5794 | If an attempt is made to set \fIhistory\-size\fP to a non-numeric value, | |
5795 | the maximum number of history entries will be set to 500. | |
3185942a | 5796 | .TP |
ccc6cda3 JA |
5797 | .B horizontal\-scroll\-mode (Off) |
5798 | When set to \fBOn\fP, makes readline use a single line for display, | |
5799 | scrolling the input horizontally on a single screen line when it | |
5800 | becomes longer than the screen width rather than wrapping to a new line. | |
5801 | .TP | |
5802 | .B input\-meta (Off) | |
5803 | If set to \fBOn\fP, readline will enable eight-bit input (that is, | |
a0c0a00f | 5804 | it will not strip the eighth bit from the characters it reads), |
ccc6cda3 JA |
5805 | regardless of what the terminal claims it can support. The name |
5806 | .B meta\-flag | |
5807 | is a synonym for this variable. | |
a0c0a00f CR |
5808 | The default is \fIOff\fP, but readline will set it to \fIOn\fP if the |
5809 | locale contains eight-bit characters. | |
ccc6cda3 | 5810 | .TP |
b72432fd JA |
5811 | .B isearch\-terminators (``C\-[C\-J'') |
5812 | The string of characters that should terminate an incremental | |
5813 | search without subsequently executing the character as a command. | |
5814 | If this variable has not been given a value, the characters | |
5815 | \fIESC\fP and \fIC\-J\fP will terminate an incremental search. | |
5816 | .TP | |
726f6388 | 5817 | .B keymap (emacs) |
cce855bc | 5818 | Set the current readline keymap. The set of valid keymap names is |
ccc6cda3 JA |
5819 | \fIemacs, emacs\-standard, emacs\-meta, emacs\-ctlx, vi, |
5820 | vi\-command\fP, and | |
5821 | .IR vi\-insert . | |
5822 | \fIvi\fP is equivalent to \fIvi\-command\fP; \fIemacs\fP is | |
5823 | equivalent to \fIemacs\-standard\fP. The default value is | |
726f6388 JA |
5824 | .IR emacs ; |
5825 | the value of | |
5826 | .B editing\-mode | |
5827 | also affects the default keymap. | |
5828 | .TP | |
ac50fbac CR |
5829 | .B keyseq\-timeout (500) |
5830 | Specifies the duration \fIreadline\fP will wait for a character when reading an | |
5831 | ambiguous key sequence (one that can form a complete key sequence using | |
5832 | the input read so far, or can take additional input to complete a longer | |
5833 | key sequence). | |
5834 | If no input is received within the timeout, \fIreadline\fP will use the shorter | |
5835 | but complete key sequence. | |
5836 | The value is specified in milliseconds, so a value of 1000 means that | |
5837 | \fIreadline\fP will wait one second for additional input. | |
5838 | If this variable is set to a value less than or equal to zero, or to a | |
5839 | non-numeric value, \fIreadline\fP will wait until another key is pressed to | |
5840 | decide which key sequence to complete. | |
5841 | .TP | |
ccc6cda3 JA |
5842 | .B mark\-directories (On) |
5843 | If set to \fBOn\fP, completed directory names have a slash | |
5844 | appended. | |
5845 | .TP | |
5846 | .B mark\-modified\-lines (Off) | |
5847 | If set to \fBOn\fP, history lines that have been modified are displayed | |
5848 | with a preceding asterisk (\fB*\fP). | |
5849 | .TP | |
7117c2d2 JA |
5850 | .B mark\-symlinked\-directories (Off) |
5851 | If set to \fBOn\fP, completed names which are symbolic links to directories | |
5852 | have a slash appended (subject to the value of | |
5853 | \fBmark\-directories\fP). | |
5854 | .TP | |
f73dda09 JA |
5855 | .B match\-hidden\-files (On) |
5856 | This variable, when set to \fBOn\fP, causes readline to match files whose | |
a0c0a00f | 5857 | names begin with a `.' (hidden files) when performing filename |
495aee44 CR |
5858 | completion. |
5859 | If set to \fBOff\fP, the leading `.' must be | |
f73dda09 JA |
5860 | supplied by the user in the filename to be completed. |
5861 | .TP | |
495aee44 CR |
5862 | .B menu\-complete\-display\-prefix (Off) |
5863 | If set to \fBOn\fP, menu completion displays the common prefix of the | |
5864 | list of possible completions (which may be empty) before cycling through | |
5865 | the list. | |
5866 | .TP | |
ccc6cda3 JA |
5867 | .B output\-meta (Off) |
5868 | If set to \fBOn\fP, readline will display characters with the | |
5869 | eighth bit set directly rather than as a meta-prefixed escape | |
5870 | sequence. | |
a0c0a00f CR |
5871 | The default is \fIOff\fP, but readline will set it to \fIOn\fP if the |
5872 | locale contains eight-bit characters. | |
ccc6cda3 | 5873 | .TP |
7117c2d2 JA |
5874 | .B page\-completions (On) |
5875 | If set to \fBOn\fP, readline uses an internal \fImore\fP-like pager | |
5876 | to display a screenful of possible completions at a time. | |
5877 | .TP | |
cce855bc JA |
5878 | .B print\-completions\-horizontally (Off) |
5879 | If set to \fBOn\fP, readline will display completions with matches | |
5880 | sorted horizontally in alphabetical order, rather than down the screen. | |
a0c0a00f | 5881 | .TP |
3185942a | 5882 | .B revert\-all\-at\-newline (Off) |
a0c0a00f | 5883 | If set to \fBOn\fP, readline will undo all changes to history lines |
3185942a JA |
5884 | before returning when \fBaccept\-line\fP is executed. By default, |
5885 | history lines may be modified and retain individual undo lists across | |
5886 | calls to \fBreadline\fP. | |
cce855bc | 5887 | .TP |
726f6388 JA |
5888 | .B show\-all\-if\-ambiguous (Off) |
5889 | This alters the default behavior of the completion functions. If | |
5890 | set to | |
495aee44 | 5891 | .BR On , |
726f6388 JA |
5892 | words which have more than one possible completion cause the |
5893 | matches to be listed immediately instead of ringing the bell. | |
5894 | .TP | |
b80f6443 JA |
5895 | .B show\-all\-if\-unmodified (Off) |
5896 | This alters the default behavior of the completion functions in | |
5897 | a fashion similar to \fBshow\-all\-if\-ambiguous\fP. | |
5898 | If set to | |
495aee44 | 5899 | .BR On , |
b80f6443 JA |
5900 | words which have more than one possible completion without any |
5901 | possible partial completion (the possible completions don't share | |
5902 | a common prefix) cause the matches to be listed immediately instead | |
5903 | of ringing the bell. | |
5904 | .TP | |
ac50fbac | 5905 | .B show\-mode\-in\-prompt (Off) |
9a51695b CR |
5906 | If set to \fBOn\fP, add a string to the beginning of the prompt |
5907 | indicating the editing mode: emacs, vi command, or vi insertion. | |
5908 | The mode strings are user-settable (e.g., \fIemacs\-mode\-string\fP). | |
ac50fbac | 5909 | .TP |
0001803f CR |
5910 | .B skip\-completed\-text (Off) |
5911 | If set to \fBOn\fP, this alters the default completion behavior when | |
5912 | inserting a single match into the line. It's only active when | |
5913 | performing completion in the middle of a word. If enabled, readline | |
5914 | does not insert characters from the completion that match characters | |
5915 | after point in the word being completed, so portions of the word | |
5916 | following the cursor are not duplicated. | |
5917 | .TP | |
a0c0a00f | 5918 | .B vi\-cmd\-mode\-string ((cmd)) |
9a51695b CR |
5919 | If the \fIshow\-mode\-in\-prompt\fP variable is enabled, |
5920 | this string is displayed immediately before the last line of the primary | |
a0c0a00f CR |
5921 | prompt when vi editing mode is active and in command mode. |
5922 | The value is expanded like a | |
5923 | key binding, so the standard set of meta- and control prefixes and | |
5924 | backslash escape sequences is available. | |
5925 | Use the \e1 and \e2 escapes to begin and end sequences of | |
5926 | non-printing characters, which can be used to embed a terminal control | |
5927 | sequence into the mode string. | |
5928 | .TP | |
5929 | .B vi\-ins\-mode\-string ((ins)) | |
9a51695b CR |
5930 | If the \fIshow\-mode\-in\-prompt\fP variable is enabled, |
5931 | this string is displayed immediately before the last line of the primary | |
a0c0a00f CR |
5932 | prompt when vi editing mode is active and in insertion mode. |
5933 | The value is expanded like a | |
5934 | key binding, so the standard set of meta- and control prefixes and | |
5935 | backslash escape sequences is available. | |
5936 | Use the \e1 and \e2 escapes to begin and end sequences of | |
5937 | non-printing characters, which can be used to embed a terminal control | |
5938 | sequence into the mode string. | |
5939 | .TP | |
ccc6cda3 JA |
5940 | .B visible\-stats (Off) |
5941 | If set to \fBOn\fP, a character denoting a file's type as reported | |
5942 | by \fIstat\fP(2) is appended to the filename when listing possible | |
5943 | completions. | |
726f6388 | 5944 | .PD |
ccc6cda3 | 5945 | .SS "Readline Conditional Constructs" |
726f6388 JA |
5946 | .PP |
5947 | Readline implements a facility similar in spirit to the conditional | |
5948 | compilation features of the C preprocessor which allows key | |
5949 | bindings and variable settings to be performed as the result | |
cce855bc | 5950 | of tests. There are four parser directives used. |
726f6388 | 5951 | .IP \fB$if\fP |
a0c0a00f | 5952 | The |
726f6388 JA |
5953 | .B $if |
5954 | construct allows bindings to be made based on the | |
5955 | editing mode, the terminal being used, or the application using | |
9a51695b CR |
5956 | readline. The text of the test, after any comparison operator, |
5957 | extends to the end of the line; | |
5958 | unless otherwise noted, no characters are required to isolate it. | |
726f6388 JA |
5959 | .RS |
5960 | .IP \fBmode\fP | |
5961 | The \fBmode=\fP form of the \fB$if\fP directive is used to test | |
5962 | whether readline is in emacs or vi mode. | |
5963 | This may be used in conjunction | |
5964 | with the \fBset keymap\fP command, for instance, to set bindings in | |
ccc6cda3 | 5965 | the \fIemacs\-standard\fP and \fIemacs\-ctlx\fP keymaps only if |
726f6388 JA |
5966 | readline is starting out in emacs mode. |
5967 | .IP \fBterm\fP | |
5968 | The \fBterm=\fP form may be used to include terminal-specific | |
5969 | key bindings, perhaps to bind the key sequences output by the | |
5970 | terminal's function keys. The word on the right side of the | |
5971 | .B = | |
a0c0a00f | 5972 | is tested against both the full name of the terminal and the portion |
726f6388 JA |
5973 | of the terminal name before the first \fB\-\fP. This allows |
5974 | .I sun | |
5975 | to match both | |
5976 | .I sun | |
5977 | and | |
5978 | .IR sun\-cmd , | |
5979 | for instance. | |
9a51695b CR |
5980 | .IP \fBversion\fP |
5981 | The \fBversion\fP test may be used to perform comparisons against | |
5982 | specific readline versions. | |
5983 | The \fBversion\fP expands to the current readline version. | |
5984 | The set of comparison operators includes | |
5985 | .BR = , | |
5986 | (and | |
5987 | .BR == ), | |
5988 | .BR != , | |
5989 | .BR <= , | |
5990 | .BR >= , | |
5991 | .BR < , | |
5992 | and | |
5993 | .BR > . | |
5994 | The version number supplied on the right side of the operator consists | |
5995 | of a major version number, an optional decimal point, and an optional | |
5996 | minor version (e.g., \fB7.1\fP). If the minor version is omitted, it | |
5997 | is assumed to be \fB0\fP. | |
5998 | The operator may be separated from the string \fBversion\fP | |
5999 | and from the version number argument by whitespace. | |
726f6388 JA |
6000 | .IP \fBapplication\fP |
6001 | The \fBapplication\fP construct is used to include | |
ccc6cda3 | 6002 | application-specific settings. Each program using the readline |
726f6388 JA |
6003 | library sets the \fIapplication name\fP, and an initialization |
6004 | file can test for a particular value. | |
6005 | This could be used to bind key sequences to functions useful for | |
6006 | a specific program. For instance, the following command adds a | |
495aee44 | 6007 | key sequence that quotes the current or previous word in \fBbash\fP: |
cce855bc | 6008 | .sp 1 |
726f6388 JA |
6009 | .RS |
6010 | .nf | |
6011 | \fB$if\fP Bash | |
6012 | # Quote the current or previous word | |
ccc6cda3 | 6013 | "\eC\-xq": "\eeb\e"\eef\e"" |
726f6388 JA |
6014 | \fB$endif\fP |
6015 | .fi | |
6016 | .RE | |
9a51695b CR |
6017 | .IP \fIvariable\fP |
6018 | The \fIvariable\fP construct provides simple equality tests for readline | |
6019 | variables and values. | |
6020 | The permitted comparison operators are \fI=\fP, \fI==\fP, and \fI!=\fP. | |
6021 | The variable name must be separated from the comparison operator by | |
6022 | whitespace; the operator may be separated from the value on the right hand | |
6023 | side by whitespace. | |
6024 | Both string and boolean variables may be tested. Boolean variables must be | |
6025 | tested against the values \fIon\fP and \fIoff\fP. | |
726f6388 JA |
6026 | .RE |
6027 | .IP \fB$endif\fP | |
cce855bc | 6028 | This command, as seen in the previous example, terminates an |
726f6388 JA |
6029 | \fB$if\fP command. |
6030 | .IP \fB$else\fP | |
6031 | Commands in this branch of the \fB$if\fP directive are executed if | |
6032 | the test fails. | |
cce855bc JA |
6033 | .IP \fB$include\fP |
6034 | This directive takes a single filename as an argument and reads commands | |
6035 | and bindings from that file. For example, the following directive | |
6036 | would read \fI/etc/inputrc\fP: | |
6037 | .sp 1 | |
6038 | .RS | |
6039 | .nf | |
6040 | \fB$include\fP \^ \fI/etc/inputrc\fP | |
6041 | .fi | |
6042 | .RE | |
ccc6cda3 | 6043 | .SS Searching |
726f6388 | 6044 | .PP |
ccc6cda3 JA |
6045 | Readline provides commands for searching through the command history |
6046 | (see | |
6047 | .SM | |
6048 | .B HISTORY | |
6049 | below) for lines containing a specified string. | |
6050 | There are two search modes: | |
6051 | .I incremental | |
6052 | and | |
6053 | .IR non-incremental . | |
6054 | .PP | |
6055 | Incremental searches begin before the user has finished typing the | |
6056 | search string. | |
6057 | As each character of the search string is typed, readline displays | |
6058 | the next entry from the history matching the string typed so far. | |
6059 | An incremental search requires only as many characters as needed to | |
6060 | find the desired history entry. | |
bb70624e | 6061 | The characters present in the value of the \fBisearch-terminators\fP |
b72432fd JA |
6062 | variable are used to terminate an incremental search. |
6063 | If that variable has not been assigned a value the Escape and | |
6064 | Control-J characters will terminate an incremental search. | |
ccc6cda3 JA |
6065 | Control-G will abort an incremental search and restore the original |
6066 | line. | |
6067 | When the search is terminated, the history entry containing the | |
6068 | search string becomes the current line. | |
bb70624e | 6069 | .PP |
ccc6cda3 JA |
6070 | To find other matching entries in the history list, type Control-S or |
6071 | Control-R as appropriate. | |
6072 | This will search backward or forward in the history for the next | |
6073 | entry matching the search string typed so far. | |
6074 | Any other key sequence bound to a readline command will terminate | |
6075 | the search and execute that command. | |
6076 | For instance, a \fInewline\fP will terminate the search and accept | |
6077 | the line, thereby executing the command from the history list. | |
6078 | .PP | |
f73dda09 JA |
6079 | Readline remembers the last incremental search string. If two |
6080 | Control-Rs are typed without any intervening characters defining a | |
6081 | new search string, any remembered search string is used. | |
6082 | .PP | |
ccc6cda3 JA |
6083 | Non-incremental searches read the entire search string before starting |
6084 | to search for matching history lines. The search string may be | |
cce855bc | 6085 | typed by the user or be part of the contents of the current line. |
ccc6cda3 | 6086 | .SS "Readline Command Names" |
726f6388 JA |
6087 | .PP |
6088 | The following is a list of the names of the commands and the default | |
6089 | key sequences to which they are bound. | |
ccc6cda3 | 6090 | Command names without an accompanying key sequence are unbound by default. |
bb70624e JA |
6091 | In the following descriptions, \fIpoint\fP refers to the current cursor |
6092 | position, and \fImark\fP refers to a cursor position saved by the | |
6093 | \fBset\-mark\fP command. | |
6094 | The text between the point and mark is referred to as the \fIregion\fP. | |
726f6388 JA |
6095 | .SS Commands for Moving |
6096 | .PP | |
6097 | .PD 0 | |
6098 | .TP | |
6099 | .B beginning\-of\-line (C\-a) | |
6100 | Move to the start of the current line. | |
6101 | .TP | |
6102 | .B end\-of\-line (C\-e) | |
6103 | Move to the end of the line. | |
6104 | .TP | |
6105 | .B forward\-char (C\-f) | |
6106 | Move forward a character. | |
6107 | .TP | |
6108 | .B backward\-char (C\-b) | |
6109 | Move back a character. | |
6110 | .TP | |
6111 | .B forward\-word (M\-f) | |
6112 | Move forward to the end of the next word. Words are composed of | |
6113 | alphanumeric characters (letters and digits). | |
6114 | .TP | |
6115 | .B backward\-word (M\-b) | |
3185942a JA |
6116 | Move back to the start of the current or previous word. |
6117 | Words are composed of alphanumeric characters (letters and digits). | |
6118 | .TP | |
6119 | .B shell\-forward\-word | |
6120 | Move forward to the end of the next word. | |
6121 | Words are delimited by non-quoted shell metacharacters. | |
6122 | .TP | |
6123 | .B shell\-backward\-word | |
6124 | Move back to the start of the current or previous word. | |
6125 | Words are delimited by non-quoted shell metacharacters. | |
726f6388 | 6126 | .TP |
9a51695b CR |
6127 | .B previous\-screen\-line |
6128 | Attempt to move point to the same physical screen column on the previous | |
6129 | physical screen line. This will not have the desired effect if the current | |
6130 | Readline line does not take up more than one physical line or if point is not | |
6131 | greater than the length of the prompt plus the screen width. | |
6132 | .TP | |
6133 | .B next\-screen\-line | |
6134 | Attempt to move point to the same physical screen column on the next | |
6135 | physical screen line. This will not have the desired effect if the current | |
6136 | Readline line does not take up more than one physical line or if the length | |
6137 | of the current Readline line is not greater than the length of the prompt | |
6138 | plus the screen width. | |
6139 | .TP | |
726f6388 JA |
6140 | .B clear\-screen (C\-l) |
6141 | Clear the screen leaving the current line at the top of the screen. | |
6142 | With an argument, refresh the current line without clearing the | |
6143 | screen. | |
6144 | .TP | |
6145 | .B redraw\-current\-line | |
ccc6cda3 | 6146 | Refresh the current line. |
726f6388 JA |
6147 | .PD |
6148 | .SS Commands for Manipulating the History | |
6149 | .PP | |
6150 | .PD 0 | |
6151 | .TP | |
6152 | .B accept\-line (Newline, Return) | |
6153 | Accept the line regardless of where the cursor is. If this line is | |
ccc6cda3 | 6154 | non-empty, add it to the history list according to the state of the |
726f6388 JA |
6155 | .SM |
6156 | .B HISTCONTROL | |
6157 | variable. If the line is a modified history | |
6158 | line, then restore the history line to its original state. | |
6159 | .TP | |
6160 | .B previous\-history (C\-p) | |
6161 | Fetch the previous command from the history list, moving back in | |
6162 | the list. | |
6163 | .TP | |
6164 | .B next\-history (C\-n) | |
6165 | Fetch the next command from the history list, moving forward in the | |
6166 | list. | |
6167 | .TP | |
6168 | .B beginning\-of\-history (M\-<) | |
6169 | Move to the first line in the history. | |
6170 | .TP | |
6171 | .B end\-of\-history (M\->) | |
6172 | Move to the end of the input history, i.e., the line currently being | |
6173 | entered. | |
6174 | .TP | |
6175 | .B reverse\-search\-history (C\-r) | |
6176 | Search backward starting at the current line and moving `up' through | |
6177 | the history as necessary. This is an incremental search. | |
6178 | .TP | |
6179 | .B forward\-search\-history (C\-s) | |
6180 | Search forward starting at the current line and moving `down' through | |
6181 | the history as necessary. This is an incremental search. | |
6182 | .TP | |
6183 | .B non\-incremental\-reverse\-search\-history (M\-p) | |
6184 | Search backward through the history starting at the current line | |
ccc6cda3 | 6185 | using a non-incremental search for a string supplied by the user. |
726f6388 JA |
6186 | .TP |
6187 | .B non\-incremental\-forward\-search\-history (M\-n) | |
ccc6cda3 | 6188 | Search forward through the history using a non-incremental search for |
726f6388 JA |
6189 | a string supplied by the user. |
6190 | .TP | |
6191 | .B history\-search\-forward | |
6192 | Search forward through the history for the string of characters | |
bb70624e | 6193 | between the start of the current line and the point. |
ccc6cda3 | 6194 | This is a non-incremental search. |
726f6388 JA |
6195 | .TP |
6196 | .B history\-search\-backward | |
6197 | Search backward through the history for the string of characters | |
ccc6cda3 JA |
6198 | between the start of the current line and the point. |
6199 | This is a non-incremental search. | |
726f6388 | 6200 | .TP |
9a51695b CR |
6201 | .B history\-substring\-search\-backward |
6202 | Search backward through the history for the string of characters | |
6203 | between the start of the current line and the current cursor | |
6204 | position (the \fIpoint\fP). | |
6205 | The search string may match anywhere in a history line. | |
6206 | This is a non-incremental search. | |
6207 | .TP | |
6208 | .B history\-substring\-search\-forward | |
6209 | Search forward through the history for the string of characters | |
6210 | between the start of the current line and the point. | |
6211 | The search string may match anywhere in a history line. | |
6212 | This is a non-incremental search. | |
6213 | .TP | |
726f6388 JA |
6214 | .B yank\-nth\-arg (M\-C\-y) |
6215 | Insert the first argument to the previous command (usually | |
28ef6c31 JA |
6216 | the second word on the previous line) at point. |
6217 | With an argument | |
726f6388 JA |
6218 | .IR n , |
6219 | insert the \fIn\fPth word from the previous command (the words | |
6220 | in the previous command begin with word 0). A negative argument | |
6221 | inserts the \fIn\fPth word from the end of the previous command. | |
95732b49 JA |
6222 | Once the argument \fIn\fP is computed, the argument is extracted |
6223 | as if the "!\fIn\fP" history expansion had been specified. | |
726f6388 JA |
6224 | .TP |
6225 | .B | |
6226 | yank\-last\-arg (M\-.\^, M\-_\^) | |
ccc6cda3 | 6227 | Insert the last argument to the previous command (the last word of |
495aee44 CR |
6228 | the previous history entry). |
6229 | With a numeric argument, behave exactly like \fByank\-nth\-arg\fP. | |
cce855bc | 6230 | Successive calls to \fByank\-last\-arg\fP move back through the history |
495aee44 CR |
6231 | list, inserting the last word (or the word specified by the argument to |
6232 | the first call) of each line in turn. | |
6233 | Any numeric argument supplied to these successive calls determines | |
6234 | the direction to move through the history. A negative argument switches | |
6235 | the direction through the history (back or forward). | |
ac50fbac | 6236 | The history expansion facilities are used to extract the last word, |
95732b49 | 6237 | as if the "!$" history expansion had been specified. |
726f6388 JA |
6238 | .TP |
6239 | .B shell\-expand\-line (M\-C\-e) | |
cce855bc | 6240 | Expand the line as the shell does. This |
726f6388 JA |
6241 | performs alias and history expansion as well as all of the shell |
6242 | word expansions. See | |
6243 | .SM | |
6244 | .B HISTORY EXPANSION | |
6245 | below for a description of history expansion. | |
6246 | .TP | |
6247 | .B history\-expand\-line (M\-^) | |
d166f048 JA |
6248 | Perform history expansion on the current line. |
6249 | See | |
726f6388 JA |
6250 | .SM |
6251 | .B HISTORY EXPANSION | |
6252 | below for a description of history expansion. | |
6253 | .TP | |
cce855bc JA |
6254 | .B magic\-space |
6255 | Perform history expansion on the current line and insert a space. | |
6256 | See | |
6257 | .SM | |
6258 | .B HISTORY EXPANSION | |
6259 | below for a description of history expansion. | |
6260 | .TP | |
d166f048 JA |
6261 | .B alias\-expand\-line |
6262 | Perform alias expansion on the current line. | |
6263 | See | |
6264 | .SM | |
6265 | .B ALIASES | |
6266 | above for a description of alias expansion. | |
6267 | .TP | |
6268 | .B history\-and\-alias\-expand\-line | |
6269 | Perform history and alias expansion on the current line. | |
6270 | .TP | |
726f6388 JA |
6271 | .B insert\-last\-argument (M\-.\^, M\-_\^) |
6272 | A synonym for \fByank\-last\-arg\fP. | |
6273 | .TP | |
ccc6cda3 | 6274 | .B operate\-and\-get\-next (C\-o) |
726f6388 | 6275 | Accept the current line for execution and fetch the next line |
9a51695b CR |
6276 | relative to the current line from the history for editing. |
6277 | A numeric argument, if supplied, specifies the history entry to use instead | |
6278 | of the current line. | |
7117c2d2 | 6279 | .TP |
9a51695b | 6280 | .B edit\-and\-execute\-command (C\-x C\-e) |
7117c2d2 JA |
6281 | Invoke an editor on the current command line, and execute the result as shell |
6282 | commands. | |
6283 | \fBBash\fP attempts to invoke | |
6284 | .SM | |
3185942a | 6285 | .BR $VISUAL , |
7117c2d2 JA |
6286 | .SM |
6287 | .BR $EDITOR , | |
6288 | and \fIemacs\fP as the editor, in that order. | |
726f6388 JA |
6289 | .PD |
6290 | .SS Commands for Changing Text | |
6291 | .PP | |
6292 | .PD 0 | |
6293 | .TP | |
ac50fbac CR |
6294 | .B \fIend\-of\-file\fP (usually C\-d) |
6295 | The character indicating end-of-file as set, for example, by | |
6296 | .if t \f(CWstty\fP. | |
6297 | .if n ``stty''. | |
6298 | If this character is read when there are no characters | |
6299 | on the line, and point is at the beginning of the line, Readline | |
6300 | interprets it as the end of input and returns | |
726f6388 JA |
6301 | .SM |
6302 | .BR EOF . | |
6303 | .TP | |
ac50fbac CR |
6304 | .B delete\-char (C\-d) |
6305 | Delete the character at point. | |
6306 | If this function is bound to the | |
6307 | same character as the tty \fBEOF\fP character, as \fBC\-d\fP | |
6308 | commonly is, see above for the effects. | |
6309 | .TP | |
726f6388 JA |
6310 | .B backward\-delete\-char (Rubout) |
6311 | Delete the character behind the cursor. When given a numeric argument, | |
ccc6cda3 | 6312 | save the deleted text on the kill ring. |
726f6388 | 6313 | .TP |
b72432fd JA |
6314 | .B forward\-backward\-delete\-char |
6315 | Delete the character under the cursor, unless the cursor is at the | |
6316 | end of the line, in which case the character behind the cursor is | |
f73dda09 | 6317 | deleted. |
b72432fd | 6318 | .TP |
726f6388 | 6319 | .B quoted\-insert (C\-q, C\-v) |
cce855bc | 6320 | Add the next character typed to the line verbatim. This is |
726f6388 JA |
6321 | how to insert characters like \fBC\-q\fP, for example. |
6322 | .TP | |
ccc6cda3 | 6323 | .B tab\-insert (C\-v TAB) |
726f6388 JA |
6324 | Insert a tab character. |
6325 | .TP | |
6326 | .B self\-insert (a,\ b,\ A,\ 1,\ !,\ ...) | |
6327 | Insert the character typed. | |
6328 | .TP | |
6329 | .B transpose\-chars (C\-t) | |
28ef6c31 JA |
6330 | Drag the character before point forward over the character at point, |
6331 | moving point forward as well. | |
6332 | If point is at the end of the line, then this transposes | |
6333 | the two characters before point. | |
bb70624e | 6334 | Negative arguments have no effect. |
726f6388 JA |
6335 | .TP |
6336 | .B transpose\-words (M\-t) | |
bb70624e | 6337 | Drag the word before point past the word after point, |
28ef6c31 | 6338 | moving point over that word as well. |
f73dda09 | 6339 | If point is at the end of the line, this transposes |
a0c0a00f | 6340 | the last two words on the line. |
726f6388 JA |
6341 | .TP |
6342 | .B upcase\-word (M\-u) | |
6343 | Uppercase the current (or following) word. With a negative argument, | |
cce855bc | 6344 | uppercase the previous word, but do not move point. |
726f6388 JA |
6345 | .TP |
6346 | .B downcase\-word (M\-l) | |
6347 | Lowercase the current (or following) word. With a negative argument, | |
cce855bc | 6348 | lowercase the previous word, but do not move point. |
726f6388 JA |
6349 | .TP |
6350 | .B capitalize\-word (M\-c) | |
6351 | Capitalize the current (or following) word. With a negative argument, | |
cce855bc | 6352 | capitalize the previous word, but do not move point. |
7117c2d2 JA |
6353 | .TP |
6354 | .B overwrite\-mode | |
6355 | Toggle overwrite mode. With an explicit positive numeric argument, | |
6356 | switches to overwrite mode. With an explicit non-positive numeric | |
6357 | argument, switches to insert mode. This command affects only | |
6358 | \fBemacs\fP mode; \fBvi\fP mode does overwrite differently. | |
6359 | Each call to \fIreadline()\fP starts in insert mode. | |
a0c0a00f | 6360 | In overwrite mode, characters bound to \fBself\-insert\fP replace |
7117c2d2 JA |
6361 | the text at point rather than pushing the text to the right. |
6362 | Characters bound to \fBbackward\-delete\-char\fP replace the character | |
6363 | before point with a space. By default, this command is unbound. | |
726f6388 JA |
6364 | .PD |
6365 | .SS Killing and Yanking | |
6366 | .PP | |
6367 | .PD 0 | |
6368 | .TP | |
6369 | .B kill\-line (C\-k) | |
bb70624e | 6370 | Kill the text from point to the end of the line. |
726f6388 | 6371 | .TP |
ccc6cda3 | 6372 | .B backward\-kill\-line (C\-x Rubout) |
726f6388 JA |
6373 | Kill backward to the beginning of the line. |
6374 | .TP | |
6375 | .B unix\-line\-discard (C\-u) | |
6376 | Kill backward from point to the beginning of the line. | |
cce855bc | 6377 | The killed text is saved on the kill-ring. |
bb70624e | 6378 | .\" There is no real difference between this and backward-kill-line |
726f6388 JA |
6379 | .TP |
6380 | .B kill\-whole\-line | |
bb70624e | 6381 | Kill all characters on the current line, no matter where point is. |
726f6388 | 6382 | .TP |
a0c0a00f | 6383 | .B kill\-word (M\-d) |
bb70624e JA |
6384 | Kill from point to the end of the current word, or if between |
6385 | words, to the end of the next word. | |
6386 | Word boundaries are the same as those used by \fBforward\-word\fP. | |
726f6388 JA |
6387 | .TP |
6388 | .B backward\-kill\-word (M\-Rubout) | |
bb70624e JA |
6389 | Kill the word behind point. |
6390 | Word boundaries are the same as those used by \fBbackward\-word\fP. | |
726f6388 | 6391 | .TP |
a0c0a00f | 6392 | .B shell\-kill\-word |
3185942a JA |
6393 | Kill from point to the end of the current word, or if between |
6394 | words, to the end of the next word. | |
6395 | Word boundaries are the same as those used by \fBshell\-forward\-word\fP. | |
6396 | .TP | |
a0c0a00f | 6397 | .B shell\-backward\-kill\-word |
3185942a JA |
6398 | Kill the word behind point. |
6399 | Word boundaries are the same as those used by \fBshell\-backward\-word\fP. | |
6400 | .TP | |
726f6388 | 6401 | .B unix\-word\-rubout (C\-w) |
bb70624e | 6402 | Kill the word behind point, using white space as a word boundary. |
bb70624e | 6403 | The killed text is saved on the kill-ring. |
ccc6cda3 | 6404 | .TP |
b80f6443 JA |
6405 | .B unix\-filename\-rubout |
6406 | Kill the word behind point, using white space and the slash character | |
6407 | as the word boundaries. | |
6408 | The killed text is saved on the kill-ring. | |
6409 | .TP | |
ccc6cda3 JA |
6410 | .B delete\-horizontal\-space (M\-\e) |
6411 | Delete all spaces and tabs around point. | |
6412 | .TP | |
6413 | .B kill\-region | |
bb70624e | 6414 | Kill the text in the current region. |
ccc6cda3 JA |
6415 | .TP |
6416 | .B copy\-region\-as\-kill | |
6417 | Copy the text in the region to the kill buffer. | |
726f6388 | 6418 | .TP |
ccc6cda3 JA |
6419 | .B copy\-backward\-word |
6420 | Copy the word before point to the kill buffer. | |
cce855bc | 6421 | The word boundaries are the same as \fBbackward\-word\fP. |
ccc6cda3 JA |
6422 | .TP |
6423 | .B copy\-forward\-word | |
6424 | Copy the word following point to the kill buffer. | |
cce855bc | 6425 | The word boundaries are the same as \fBforward\-word\fP. |
726f6388 JA |
6426 | .TP |
6427 | .B yank (C\-y) | |
28ef6c31 | 6428 | Yank the top of the kill ring into the buffer at point. |
726f6388 JA |
6429 | .TP |
6430 | .B yank\-pop (M\-y) | |
ccc6cda3 | 6431 | Rotate the kill ring, and yank the new top. Only works following |
726f6388 JA |
6432 | .B yank |
6433 | or | |
6434 | .BR yank\-pop . | |
6435 | .PD | |
6436 | .SS Numeric Arguments | |
6437 | .PP | |
6438 | .PD 0 | |
6439 | .TP | |
6440 | .B digit\-argument (M\-0, M\-1, ..., M\-\-) | |
6441 | Add this digit to the argument already accumulating, or start a new | |
6442 | argument. M\-\- starts a negative argument. | |
6443 | .TP | |
6444 | .B universal\-argument | |
d166f048 JA |
6445 | This is another way to specify an argument. |
6446 | If this command is followed by one or more digits, optionally with a | |
6447 | leading minus sign, those digits define the argument. | |
6448 | If the command is followed by digits, executing | |
6449 | .B universal\-argument | |
6450 | again ends the numeric argument, but is otherwise ignored. | |
6451 | As a special case, if this command is immediately followed by a | |
a0c0a00f | 6452 | character that is neither a digit nor minus sign, the argument count |
d166f048 | 6453 | for the next command is multiplied by four. |
726f6388 | 6454 | The argument count is initially one, so executing this function the |
d166f048 JA |
6455 | first time makes the argument count four, a second time makes the |
6456 | argument count sixteen, and so on. | |
726f6388 JA |
6457 | .PD |
6458 | .SS Completing | |
6459 | .PP | |
6460 | .PD 0 | |
6461 | .TP | |
6462 | .B complete (TAB) | |
6463 | Attempt to perform completion on the text before point. | |
6464 | .B Bash | |
6465 | attempts completion treating the text as a variable (if the | |
6466 | text begins with \fB$\fP), username (if the text begins with | |
6467 | \fB~\fP), hostname (if the text begins with \fB@\fP), or | |
6468 | command (including aliases and functions) in turn. If none | |
6469 | of these produces a match, filename completion is attempted. | |
6470 | .TP | |
ccc6cda3 | 6471 | .B possible\-completions (M\-?) |
726f6388 JA |
6472 | List the possible completions of the text before point. |
6473 | .TP | |
ccc6cda3 | 6474 | .B insert\-completions (M\-*) |
726f6388 JA |
6475 | Insert all completions of the text before point |
6476 | that would have been generated by | |
ccc6cda3 | 6477 | \fBpossible\-completions\fP. |
726f6388 | 6478 | .TP |
cce855bc JA |
6479 | .B menu\-complete |
6480 | Similar to \fBcomplete\fP, but replaces the word to be completed | |
6481 | with a single match from the list of possible completions. | |
6482 | Repeated execution of \fBmenu\-complete\fP steps through the list | |
6483 | of possible completions, inserting each match in turn. | |
28ef6c31 | 6484 | At the end of the list of completions, the bell is rung |
f73dda09 | 6485 | (subject to the setting of \fBbell\-style\fP) |
28ef6c31 | 6486 | and the original text is restored. |
cce855bc JA |
6487 | An argument of \fIn\fP moves \fIn\fP positions forward in the list |
6488 | of matches; a negative argument may be used to move backward | |
6489 | through the list. | |
6490 | This command is intended to be bound to \fBTAB\fP, but is unbound | |
6491 | by default. | |
6492 | .TP | |
495aee44 | 6493 | .B menu\-complete\-backward |
0001803f CR |
6494 | Identical to \fBmenu\-complete\fP, but moves backward through the list |
6495 | of possible completions, as if \fBmenu\-complete\fP had been given a | |
6496 | negative argument. This command is unbound by default. | |
6497 | .TP | |
b72432fd JA |
6498 | .B delete\-char\-or\-list |
6499 | Deletes the character under the cursor if not at the beginning or | |
bb70624e | 6500 | end of the line (like \fBdelete\-char\fP). |
b72432fd | 6501 | If at the end of the line, behaves identically to |
bb70624e | 6502 | \fBpossible\-completions\fP. |
b72432fd JA |
6503 | This command is unbound by default. |
6504 | .TP | |
726f6388 JA |
6505 | .B complete\-filename (M\-/) |
6506 | Attempt filename completion on the text before point. | |
6507 | .TP | |
6508 | .B possible\-filename\-completions (C\-x /) | |
6509 | List the possible completions of the text before point, | |
6510 | treating it as a filename. | |
6511 | .TP | |
6512 | .B complete\-username (M\-~) | |
6513 | Attempt completion on the text before point, treating | |
6514 | it as a username. | |
6515 | .TP | |
6516 | .B possible\-username\-completions (C\-x ~) | |
6517 | List the possible completions of the text before point, | |
6518 | treating it as a username. | |
6519 | .TP | |
6520 | .B complete\-variable (M\-$) | |
6521 | Attempt completion on the text before point, treating | |
6522 | it as a shell variable. | |
6523 | .TP | |
6524 | .B possible\-variable\-completions (C\-x $) | |
6525 | List the possible completions of the text before point, | |
6526 | treating it as a shell variable. | |
6527 | .TP | |
6528 | .B complete\-hostname (M\-@) | |
6529 | Attempt completion on the text before point, treating | |
6530 | it as a hostname. | |
6531 | .TP | |
6532 | .B possible\-hostname\-completions (C\-x @) | |
6533 | List the possible completions of the text before point, | |
6534 | treating it as a hostname. | |
6535 | .TP | |
6536 | .B complete\-command (M\-!) | |
6537 | Attempt completion on the text before point, treating | |
6538 | it as a command name. Command completion attempts to | |
6539 | match the text against aliases, reserved words, shell | |
cce855bc | 6540 | functions, shell builtins, and finally executable filenames, |
726f6388 JA |
6541 | in that order. |
6542 | .TP | |
6543 | .B possible\-command\-completions (C\-x !) | |
6544 | List the possible completions of the text before point, | |
6545 | treating it as a command name. | |
6546 | .TP | |
ccc6cda3 | 6547 | .B dynamic\-complete\-history (M\-TAB) |
726f6388 JA |
6548 | Attempt completion on the text before point, comparing |
6549 | the text against lines from the history list for possible | |
6550 | completion matches. | |
6551 | .TP | |
3185942a JA |
6552 | .B dabbrev\-expand |
6553 | Attempt menu completion on the text before point, comparing | |
6554 | the text against lines from the history list for possible | |
6555 | completion matches. | |
6556 | .TP | |
726f6388 | 6557 | .B complete\-into\-braces (M\-{) |
bb70624e | 6558 | Perform filename completion and insert the list of possible completions |
726f6388 JA |
6559 | enclosed within braces so the list is available to the shell (see |
6560 | .B Brace Expansion | |
6561 | above). | |
6562 | .PD | |
6563 | .SS Keyboard Macros | |
6564 | .PP | |
6565 | .PD 0 | |
6566 | .TP | |
ccc6cda3 | 6567 | .B start\-kbd\-macro (C\-x (\^) |
726f6388 JA |
6568 | Begin saving the characters typed into the current keyboard macro. |
6569 | .TP | |
ccc6cda3 | 6570 | .B end\-kbd\-macro (C\-x )\^) |
726f6388 | 6571 | Stop saving the characters typed into the current keyboard macro |
ccc6cda3 | 6572 | and store the definition. |
726f6388 | 6573 | .TP |
ccc6cda3 | 6574 | .B call\-last\-kbd\-macro (C\-x e) |
726f6388 JA |
6575 | Re-execute the last keyboard macro defined, by making the characters |
6576 | in the macro appear as if typed at the keyboard. | |
ac50fbac CR |
6577 | .TP |
6578 | .B print\-last\-kbd\-macro () | |
6579 | Print the last keyboard macro defined in a format suitable for the | |
6580 | \fIinputrc\fP file. | |
726f6388 JA |
6581 | .PD |
6582 | .SS Miscellaneous | |
6583 | .PP | |
6584 | .PD 0 | |
6585 | .TP | |
6586 | .B re\-read\-init\-file (C\-x C\-r) | |
ccc6cda3 | 6587 | Read in the contents of the \fIinputrc\fP file, and incorporate |
726f6388 JA |
6588 | any bindings or variable assignments found there. |
6589 | .TP | |
6590 | .B abort (C\-g) | |
6591 | Abort the current editing command and | |
6592 | ring the terminal's bell (subject to the setting of | |
6593 | .BR bell\-style ). | |
6594 | .TP | |
9a51695b CR |
6595 | .B do\-lowercase\-version (M\-A, M\-B, M\-\fIx\fP, ...) |
6596 | If the metafied character \fIx\fP is uppercase, run the command | |
6597 | that is bound to the corresponding metafied lowercase character. | |
6598 | The behavior is undefined if \fIx\fP is already lowercase. | |
726f6388 JA |
6599 | .TP |
6600 | .B prefix\-meta (ESC) | |
6601 | Metafy the next character typed. | |
6602 | .SM | |
6603 | .B ESC | |
6604 | .B f | |
6605 | is equivalent to | |
6606 | .BR Meta\-f . | |
6607 | .TP | |
6608 | .B undo (C\-_, C\-x C\-u) | |
6609 | Incremental undo, separately remembered for each line. | |
6610 | .TP | |
6611 | .B revert\-line (M\-r) | |
cce855bc | 6612 | Undo all changes made to this line. This is like executing the |
726f6388 JA |
6613 | .B undo |
6614 | command enough times to return the line to its initial state. | |
6615 | .TP | |
b72432fd | 6616 | .B tilde\-expand (M\-&) |
726f6388 JA |
6617 | Perform tilde expansion on the current word. |
6618 | .TP | |
ccc6cda3 | 6619 | .B set\-mark (C\-@, M\-<space>) |
28ef6c31 | 6620 | Set the mark to the point. If a |
ccc6cda3 JA |
6621 | numeric argument is supplied, the mark is set to that position. |
6622 | .TP | |
6623 | .B exchange\-point\-and\-mark (C\-x C\-x) | |
6624 | Swap the point with the mark. The current cursor position is set to | |
6625 | the saved position, and the old cursor position is saved as the mark. | |
6626 | .TP | |
6627 | .B character\-search (C\-]) | |
6628 | A character is read and point is moved to the next occurrence of that | |
6629 | character. A negative count searches for previous occurrences. | |
6630 | .TP | |
6631 | .B character\-search\-backward (M\-C\-]) | |
6632 | A character is read and point is moved to the previous occurrence of that | |
6633 | character. A negative count searches for subsequent occurrences. | |
6634 | .TP | |
495aee44 | 6635 | .B skip\-csi\-sequence |
0001803f CR |
6636 | Read enough characters to consume a multi-key sequence such as those |
6637 | defined for keys like Home and End. Such sequences begin with a | |
6638 | Control Sequence Indicator (CSI), usually ESC\-[. If this sequence is | |
6639 | bound to "\e[", keys producing such sequences will have no effect | |
6640 | unless explicitly bound to a readline command, instead of inserting | |
6641 | stray characters into the editing buffer. This is unbound by default, | |
6642 | but usually bound to ESC\-[. | |
6643 | .TP | |
ccc6cda3 | 6644 | .B insert\-comment (M\-#) |
7117c2d2 | 6645 | Without a numeric argument, the value of the readline |
ccc6cda3 | 6646 | .B comment\-begin |
7117c2d2 | 6647 | variable is inserted at the beginning of the current line. |
a0c0a00f | 6648 | If a numeric argument is supplied, this command acts as a toggle: if |
7117c2d2 JA |
6649 | the characters at the beginning of the line do not match the value |
6650 | of \fBcomment\-begin\fP, the value is inserted, otherwise | |
a0c0a00f | 6651 | the characters in \fBcomment\-begin\fP are deleted from the beginning of |
7117c2d2 JA |
6652 | the line. |
6653 | In either case, the line is accepted as if a newline had been typed. | |
6654 | The default value of | |
bb70624e | 6655 | \fBcomment\-begin\fP causes this command to make the current line |
ccc6cda3 | 6656 | a shell comment. |
7117c2d2 JA |
6657 | If a numeric argument causes the comment character to be removed, the line |
6658 | will be executed by the shell. | |
6659 | .TP | |
6660 | .B glob\-complete\-word (M\-g) | |
6661 | The word before point is treated as a pattern for pathname expansion, | |
6662 | with an asterisk implicitly appended. This pattern is used to | |
ac50fbac | 6663 | generate a list of matching filenames for possible completions. |
ccc6cda3 JA |
6664 | .TP |
6665 | .B glob\-expand\-word (C\-x *) | |
6666 | The word before point is treated as a pattern for pathname expansion, | |
ac50fbac | 6667 | and the list of matching filenames is inserted, replacing the word. |
7117c2d2 JA |
6668 | If a numeric argument is supplied, an asterisk is appended before |
6669 | pathname expansion. | |
ccc6cda3 JA |
6670 | .TP |
6671 | .B glob\-list\-expansions (C\-x g) | |
6672 | The list of expansions that would have been generated by | |
6673 | .B glob\-expand\-word | |
6674 | is displayed, and the line is redrawn. | |
7117c2d2 JA |
6675 | If a numeric argument is supplied, an asterisk is appended before |
6676 | pathname expansion. | |
ccc6cda3 | 6677 | .TP |
726f6388 JA |
6678 | .B dump\-functions |
6679 | Print all of the functions and their key bindings to the | |
6680 | readline output stream. If a numeric argument is supplied, | |
6681 | the output is formatted in such a way that it can be made part | |
6682 | of an \fIinputrc\fP file. | |
6683 | .TP | |
ccc6cda3 JA |
6684 | .B dump\-variables |
6685 | Print all of the settable readline variables and their values to the | |
6686 | readline output stream. If a numeric argument is supplied, | |
6687 | the output is formatted in such a way that it can be made part | |
6688 | of an \fIinputrc\fP file. | |
6689 | .TP | |
6690 | .B dump\-macros | |
6691 | Print all of the readline key sequences bound to macros and the | |
95732b49 | 6692 | strings they output. If a numeric argument is supplied, |
ccc6cda3 JA |
6693 | the output is formatted in such a way that it can be made part |
6694 | of an \fIinputrc\fP file. | |
6695 | .TP | |
726f6388 JA |
6696 | .B display\-shell\-version (C\-x C\-v) |
6697 | Display version information about the current instance of | |
6698 | .BR bash . | |
6699 | .PD | |
bb70624e JA |
6700 | .SS Programmable Completion |
6701 | .PP | |
6702 | When word completion is attempted for an argument to a command for | |
6703 | which a completion specification (a \fIcompspec\fP) has been defined | |
6704 | using the \fBcomplete\fP builtin (see | |
6705 | .SM | |
6706 | .B "SHELL BUILTIN COMMANDS" | |
6707 | below), the programmable completion facilities are invoked. | |
6708 | .PP | |
6709 | First, the command name is identified. | |
0001803f CR |
6710 | If the command word is the empty string (completion attempted at the |
6711 | beginning of an empty line), any compspec defined with | |
6712 | the \fB\-E\fP option to \fBcomplete\fP is used. | |
bb70624e JA |
6713 | If a compspec has been defined for that command, the |
6714 | compspec is used to generate the list of possible completions for the word. | |
6715 | If the command word is a full pathname, a compspec for the full | |
6716 | pathname is searched for first. | |
6717 | If no compspec is found for the full pathname, an attempt is made to | |
6718 | find a compspec for the portion following the final slash. | |
495aee44 | 6719 | If those searches do not result in a compspec, any compspec defined with |
0001803f | 6720 | the \fB\-D\fP option to \fBcomplete\fP is used as the default. |
2ae59c11 CR |
6721 | If there is no default compspec, \fBbash\fP attempts alias expansion |
6722 | on the command word as a final resort, and attempts to find a compspec | |
6723 | for the command word from any successful expansion. | |
bb70624e JA |
6724 | .PP |
6725 | Once a compspec has been found, it is used to generate the list of | |
6726 | matching words. | |
6727 | If a compspec is not found, the default \fBbash\fP completion as | |
6728 | described above under \fBCompleting\fP is performed. | |
6729 | .PP | |
6730 | First, the actions specified by the compspec are used. | |
6731 | Only matches which are prefixed by the word being completed are | |
6732 | returned. | |
6733 | When the | |
6734 | .B \-f | |
6735 | or | |
6736 | .B \-d | |
6737 | option is used for filename or directory name completion, the shell | |
6738 | variable | |
6739 | .SM | |
6740 | .B FIGNORE | |
6741 | is used to filter the matches. | |
6742 | .PP | |
0001803f | 6743 | Any completions specified by a pathname expansion pattern to the |
bb70624e JA |
6744 | \fB\-G\fP option are generated next. |
6745 | The words generated by the pattern need not match the word | |
6746 | being completed. | |
6747 | The | |
6748 | .SM | |
6749 | .B GLOBIGNORE | |
6750 | shell variable is not used to filter the matches, but the | |
6751 | .SM | |
6752 | .B FIGNORE | |
6753 | variable is used. | |
6754 | .PP | |
6755 | Next, the string specified as the argument to the \fB\-W\fP option | |
6756 | is considered. | |
6757 | The string is first split using the characters in the | |
6758 | .SM | |
6759 | .B IFS | |
6760 | special variable as delimiters. | |
6761 | Shell quoting is honored. | |
6762 | Each word is then expanded using | |
6763 | brace expansion, tilde expansion, parameter and variable expansion, | |
95732b49 | 6764 | command substitution, and arithmetic expansion, |
a0c0a00f | 6765 | as described above under |
bb70624e JA |
6766 | .SM |
6767 | .BR EXPANSION . | |
6768 | The results are split using the rules described above under | |
6769 | \fBWord Splitting\fP. | |
6770 | The results of the expansion are prefix-matched against the word being | |
6771 | completed, and the matching words become the possible completions. | |
6772 | .PP | |
6773 | After these matches have been generated, any shell function or command | |
6774 | specified with the \fB\-F\fP and \fB\-C\fP options is invoked. | |
6775 | When the command or function is invoked, the | |
6776 | .SM | |
3185942a JA |
6777 | .BR COMP_LINE , |
6778 | .SM | |
6779 | .BR COMP_POINT , | |
6780 | .SM | |
6781 | .BR COMP_KEY , | |
bb70624e JA |
6782 | and |
6783 | .SM | |
3185942a | 6784 | .B COMP_TYPE |
bb70624e JA |
6785 | variables are assigned values as described above under |
6786 | \fBShell Variables\fP. | |
a0c0a00f | 6787 | If a shell function is being invoked, the |
bb70624e JA |
6788 | .SM |
6789 | .B COMP_WORDS | |
6790 | and | |
6791 | .SM | |
6792 | .B COMP_CWORD | |
6793 | variables are also set. | |
ac50fbac CR |
6794 | When the function or command is invoked, |
6795 | the first argument (\fB$1\fP) is the name of the command whose arguments are | |
6796 | being completed, | |
6797 | the second argument (\fB$2\fP) is the word being completed, | |
6798 | and the third argument (\fB$3\fP) is the word preceding the word being | |
6799 | completed on the current command line. | |
bb70624e JA |
6800 | No filtering of the generated completions against the word being completed |
6801 | is performed; the function or command has complete freedom in generating | |
6802 | the matches. | |
6803 | .PP | |
6804 | Any function specified with \fB\-F\fP is invoked first. | |
6805 | The function may use any of the shell facilities, including the | |
6806 | \fBcompgen\fP builtin described below, to generate the matches. | |
6807 | It must put the possible completions in the | |
6808 | .SM | |
6809 | .B COMPREPLY | |
ac50fbac | 6810 | array variable, one per array element. |
bb70624e JA |
6811 | .PP |
6812 | Next, any command specified with the \fB\-C\fP option is invoked | |
6813 | in an environment equivalent to command substitution. | |
6814 | It should print a list of completions, one per line, to the | |
6815 | standard output. | |
6816 | Backslash may be used to escape a newline, if necessary. | |
6817 | .PP | |
6818 | After all of the possible completions are generated, any filter | |
6819 | specified with the \fB\-X\fP option is applied to the list. | |
6820 | The filter is a pattern as used for pathname expansion; a \fB&\fP | |
6821 | in the pattern is replaced with the text of the word being completed. | |
6822 | A literal \fB&\fP may be escaped with a backslash; the backslash | |
6823 | is removed before attempting a match. | |
6824 | Any completion that matches the pattern will be removed from the list. | |
6825 | A leading \fB!\fP negates the pattern; in this case any completion | |
6826 | not matching the pattern will be removed. | |
a0c0a00f CR |
6827 | If the |
6828 | .B nocasematch | |
6829 | shell option is enabled, the match is performed without regard to the case | |
6830 | of alphabetic characters. | |
bb70624e JA |
6831 | .PP |
6832 | Finally, any prefix and suffix specified with the \fB\-P\fP and \fB\-S\fP | |
6833 | options are added to each member of the completion list, and the result is | |
6834 | returned to the readline completion code as the list of possible | |
6835 | completions. | |
6836 | .PP | |
28ef6c31 JA |
6837 | If the previously-applied actions do not generate any matches, and the |
6838 | \fB\-o dirnames\fP option was supplied to \fBcomplete\fP when the | |
6839 | compspec was defined, directory name completion is attempted. | |
6840 | .PP | |
b80f6443 JA |
6841 | If the \fB\-o plusdirs\fP option was supplied to \fBcomplete\fP when the |
6842 | compspec was defined, directory name completion is attempted and any | |
6843 | matches are added to the results of the other actions. | |
6844 | .PP | |
28ef6c31 JA |
6845 | By default, if a compspec is found, whatever it generates is returned |
6846 | to the completion code as the full set of possible completions. | |
bb70624e JA |
6847 | The default \fBbash\fP completions are not attempted, and the readline |
6848 | default of filename completion is disabled. | |
b80f6443 JA |
6849 | If the \fB\-o bashdefault\fP option was supplied to \fBcomplete\fP when |
6850 | the compspec was defined, the \fBbash\fP default completions are attempted | |
28ef6c31 | 6851 | if the compspec generates no matches. |
b80f6443 JA |
6852 | If the \fB\-o default\fP option was supplied to \fBcomplete\fP when the |
6853 | compspec was defined, readline's default completion will be performed | |
6854 | if the compspec (and, if attempted, the default \fBbash\fP completions) | |
6855 | generate no matches. | |
7117c2d2 JA |
6856 | .PP |
6857 | When a compspec indicates that directory name completion is desired, | |
6858 | the programmable completion functions force readline to append a slash | |
a0c0a00f | 6859 | to completed names which are symbolic links to directories, subject to |
7117c2d2 JA |
6860 | the value of the \fBmark\-directories\fP readline variable, regardless |
6861 | of the setting of the \fBmark-symlinked\-directories\fP readline variable. | |
0001803f CR |
6862 | .PP |
6863 | There is some support for dynamically modifying completions. This is | |
6864 | most useful when used in combination with a default completion specified | |
9a51695b | 6865 | with \fBcomplete \-D\fP. |
0001803f CR |
6866 | It's possible for shell functions executed as completion |
6867 | handlers to indicate that completion should be retried by returning an | |
6868 | exit status of 124. If a shell function returns 124, and changes | |
6869 | the compspec associated with the command on which completion is being | |
6870 | attempted (supplied as the first argument when the function is executed), | |
6871 | programmable completion restarts from the beginning, with an | |
495aee44 | 6872 | attempt to find a new compspec for that command. This allows a set of |
0001803f CR |
6873 | completions to be built dynamically as completion is attempted, rather than |
6874 | being loaded all at once. | |
6875 | .PP | |
6876 | For instance, assuming that there is a library of compspecs, each kept in a | |
6877 | file corresponding to the name of the command, the following default | |
6878 | completion function would load completions dynamically: | |
6879 | .PP | |
6880 | \f(CW_completion_loader() | |
6881 | .br | |
6882 | { | |
6883 | .br | |
6884 | . "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124 | |
6885 | .br | |
6886 | } | |
6887 | .br | |
ac50fbac | 6888 | complete -D -F _completion_loader -o bashdefault -o default |
0001803f CR |
6889 | .br |
6890 | \fP | |
726f6388 | 6891 | .SH HISTORY |
ccc6cda3 | 6892 | When the |
d166f048 | 6893 | .B \-o history |
ccc6cda3 JA |
6894 | option to the |
6895 | .B set | |
6896 | builtin is enabled, the shell provides access to the | |
6897 | \fIcommand history\fP, | |
bb70624e | 6898 | the list of commands previously typed. |
0001803f CR |
6899 | The value of the |
6900 | .SM | |
6901 | .B HISTSIZE | |
6902 | variable is used as the | |
bb70624e JA |
6903 | number of commands to save in a history list. |
6904 | The text of the last | |
726f6388 JA |
6905 | .SM |
6906 | .B HISTSIZE | |
bb70624e | 6907 | commands (default 500) is saved. The shell |
726f6388 JA |
6908 | stores each command in the history list prior to parameter and |
6909 | variable expansion (see | |
6910 | .SM | |
6911 | .B EXPANSION | |
6912 | above) but after history expansion is performed, subject to the | |
6913 | values of the shell variables | |
ccc6cda3 JA |
6914 | .SM |
6915 | .B HISTIGNORE | |
726f6388 JA |
6916 | and |
6917 | .SM | |
6918 | .BR HISTCONTROL . | |
bb70624e | 6919 | .PP |
726f6388 JA |
6920 | On startup, the history is initialized from the file named by |
6921 | the variable | |
6922 | .SM | |
6923 | .B HISTFILE | |
6924 | (default \fI~/.bash_history\fP). | |
bb70624e | 6925 | The file named by the value of |
726f6388 JA |
6926 | .SM |
6927 | .B HISTFILE | |
6928 | is truncated, if necessary, to contain no more than | |
bb70624e | 6929 | the number of lines specified by the value of |
726f6388 | 6930 | .SM |
bb70624e | 6931 | .BR HISTFILESIZE . |
ac50fbac CR |
6932 | If \fBHISTFILESIZE\fP is unset, or set to null, a non-numeric value, |
6933 | or a numeric value less than zero, the history file is not truncated. | |
3185942a JA |
6934 | When the history file is read, |
6935 | lines beginning with the history comment character followed immediately | |
9a51695b | 6936 | by a digit are interpreted as timestamps for the following history line. |
3185942a JA |
6937 | These timestamps are optionally displayed depending on the value of the |
6938 | .SM | |
6939 | .B HISTTIMEFORMAT | |
6940 | variable. | |
ac50fbac | 6941 | When a shell with history enabled exits, the last |
ccc6cda3 | 6942 | .SM |
bb70624e | 6943 | .B $HISTSIZE |
ccc6cda3 JA |
6944 | lines are copied from the history list to |
6945 | .SM | |
bb70624e | 6946 | .BR $HISTFILE . |
ccc6cda3 JA |
6947 | If the |
6948 | .B histappend | |
6949 | shell option is enabled | |
6950 | (see the description of | |
6951 | .B shopt | |
6952 | under | |
6953 | .SM | |
6954 | .B "SHELL BUILTIN COMMANDS" | |
6955 | below), the lines are appended to the history file, | |
6956 | otherwise the history file is overwritten. | |
6957 | If | |
6958 | .SM | |
6959 | .B HISTFILE | |
6960 | is unset, or if the history file is unwritable, the history is | |
3185942a JA |
6961 | not saved. |
6962 | If the | |
6963 | .SM | |
0001803f | 6964 | .B HISTTIMEFORMAT |
3185942a JA |
6965 | variable is set, time stamps are written to the history file, marked |
6966 | with the history comment character, so | |
6967 | they may be preserved across shell sessions. | |
6968 | This uses the history comment character to distinguish timestamps from | |
6969 | other history lines. | |
6970 | After saving the history, the history file is truncated | |
ccc6cda3 JA |
6971 | to contain no more than |
6972 | .SM | |
6973 | .B HISTFILESIZE | |
6974 | lines. If | |
6975 | .SM | |
6976 | .B HISTFILESIZE | |
ac50fbac CR |
6977 | is unset, or set to null, a non-numeric value, |
6978 | or a numeric value less than zero, the history file is not truncated. | |
ccc6cda3 | 6979 | .PP |
726f6388 JA |
6980 | The builtin command |
6981 | .B fc | |
6982 | (see | |
6983 | .SM | |
6984 | .B SHELL BUILTIN COMMANDS | |
6985 | below) may be used to list or edit and re-execute a portion of | |
6986 | the history list. | |
6987 | The | |
6988 | .B history | |
bb70624e | 6989 | builtin may be used to display or modify the history list and |
ccc6cda3 | 6990 | manipulate the history file. |
bb70624e | 6991 | When using command-line editing, search commands |
726f6388 | 6992 | are available in each editing mode that provide access to the |
ccc6cda3 JA |
6993 | history list. |
6994 | .PP | |
6995 | The shell allows control over which commands are saved on the history | |
6996 | list. The | |
726f6388 | 6997 | .SM |
ccc6cda3 JA |
6998 | .B HISTCONTROL |
6999 | and | |
726f6388 | 7000 | .SM |
ccc6cda3 JA |
7001 | .B HISTIGNORE |
7002 | variables may be set to cause the shell to save only a subset of the | |
7003 | commands entered. | |
7004 | The | |
7005 | .B cmdhist | |
7006 | shell option, if enabled, causes the shell to attempt to save each | |
7007 | line of a multi-line command in the same history entry, adding | |
7008 | semicolons where necessary to preserve syntactic correctness. | |
7009 | The | |
7010 | .B lithist | |
7011 | shell option causes the shell to save the command with embedded newlines | |
7012 | instead of semicolons. See the description of the | |
7013 | .B shopt | |
7014 | builtin below under | |
7015 | .SM | |
7016 | .B "SHELL BUILTIN COMMANDS" | |
7017 | for information on setting and unsetting shell options. | |
726f6388 JA |
7018 | .SH "HISTORY EXPANSION" |
7019 | .PP | |
7020 | The shell supports a history expansion feature that | |
7021 | is similar to the history expansion in | |
9a51695b | 7022 | .BR csh . |
726f6388 JA |
7023 | This section describes what syntax features are available. This |
7024 | feature is enabled by default for interactive shells, and can be | |
7025 | disabled using the | |
ac50fbac | 7026 | .B +H |
726f6388 JA |
7027 | option to the |
7028 | .B set | |
7029 | builtin command (see | |
7030 | .SM | |
7031 | .B SHELL BUILTIN COMMANDS | |
ccc6cda3 JA |
7032 | below). Non-interactive shells do not perform history expansion |
7033 | by default. | |
7034 | .PP | |
7035 | History expansions introduce words from the history list into | |
7036 | the input stream, making it easy to repeat commands, insert the | |
7037 | arguments to a previous command into the current input line, or | |
7038 | fix errors in previous commands quickly. | |
726f6388 JA |
7039 | .PP |
7040 | History expansion is performed immediately after a complete line | |
9a51695b CR |
7041 | is read, before the shell breaks it into words, and is performed |
7042 | on each line individually without taking quoting on previous lines into | |
7043 | account. | |
ccc6cda3 | 7044 | It takes place in two parts. |
cce855bc | 7045 | The first is to determine which line from the history list |
ccc6cda3 JA |
7046 | to use during substitution. |
7047 | The second is to select portions of that line for inclusion into | |
7048 | the current one. | |
cce855bc | 7049 | The line selected from the history is the \fIevent\fP, |
ccc6cda3 JA |
7050 | and the portions of that line that are acted upon are \fIwords\fP. |
7051 | Various \fImodifiers\fP are available to manipulate the selected words. | |
7052 | The line is broken into words in the same fashion as when reading input, | |
7053 | so that several \fImetacharacter\fP-separated words surrounded by | |
cce855bc | 7054 | quotes are considered one word. |
ccc6cda3 JA |
7055 | History expansions are introduced by the appearance of the |
7056 | history expansion character, which is \^\fB!\fP\^ by default. | |
7057 | Only backslash (\^\fB\e\fP\^) and single quotes can quote | |
a0c0a00f CR |
7058 | the history expansion character, but the history expansion character is |
7059 | also treated as quoted if it immediately precedes the closing double quote | |
7060 | in a double-quoted string. | |
ccc6cda3 | 7061 | .PP |
b80f6443 JA |
7062 | Several characters inhibit history expansion if found immediately |
7063 | following the history expansion character, even if it is unquoted: | |
7064 | space, tab, newline, carriage return, and \fB=\fP. | |
7065 | If the \fBextglob\fP shell option is enabled, \fB(\fP will also | |
7066 | inhibit expansion. | |
7067 | .PP | |
ccc6cda3 JA |
7068 | Several shell options settable with the |
7069 | .B shopt | |
7070 | builtin may be used to tailor the behavior of history expansion. | |
7071 | If the | |
7072 | .B histverify | |
7073 | shell option is enabled (see the description of the | |
7074 | .B shopt | |
0001803f | 7075 | builtin below), and |
ccc6cda3 JA |
7076 | .B readline |
7077 | is being used, history substitutions are not immediately passed to | |
7078 | the shell parser. | |
7079 | Instead, the expanded line is reloaded into the | |
7080 | .B readline | |
7081 | editing buffer for further modification. | |
7082 | If | |
7083 | .B readline | |
7084 | is being used, and the | |
7085 | .B histreedit | |
7086 | shell option is enabled, a failed history substitution will be reloaded | |
7087 | into the | |
7088 | .B readline | |
7089 | editing buffer for correction. | |
7090 | The | |
7091 | .B \-p | |
7092 | option to the | |
7093 | .B history | |
7094 | builtin command may be used to see what a history expansion will | |
7095 | do before using it. | |
7096 | The | |
7097 | .B \-s | |
7098 | option to the | |
7099 | .B history | |
7100 | builtin may be used to add commands to the end of the history list | |
7101 | without actually executing them, so that they are available for | |
7102 | subsequent recall. | |
726f6388 JA |
7103 | .PP |
7104 | The shell allows control of the various characters used by the | |
7105 | history expansion mechanism (see the description of | |
7106 | .B histchars | |
7107 | above under | |
7108 | .BR "Shell Variables" ). | |
3185942a JA |
7109 | The shell uses |
7110 | the history comment character to mark history timestamps when | |
7111 | writing the history file. | |
726f6388 JA |
7112 | .SS Event Designators |
7113 | .PP | |
7114 | An event designator is a reference to a command line entry in the | |
7115 | history list. | |
495aee44 CR |
7116 | Unless the reference is absolute, events are relative to the current |
7117 | position in the history list. | |
726f6388 JA |
7118 | .PP |
7119 | .PD 0 | |
7120 | .TP | |
7121 | .B ! | |
7122 | Start a history substitution, except when followed by a | |
7123 | .BR blank , | |
b80f6443 JA |
7124 | newline, carriage return, = |
7125 | or ( (when the \fBextglob\fP shell option is enabled using | |
7126 | the \fBshopt\fP builtin). | |
726f6388 | 7127 | .TP |
726f6388 JA |
7128 | .B !\fIn\fR |
7129 | Refer to command line | |
7130 | .IR n . | |
7131 | .TP | |
7132 | .B !\-\fIn\fR | |
495aee44 | 7133 | Refer to the current command minus |
726f6388 JA |
7134 | .IR n . |
7135 | .TP | |
ccc6cda3 JA |
7136 | .B !! |
7137 | Refer to the previous command. This is a synonym for `!\-1'. | |
7138 | .TP | |
726f6388 | 7139 | .B !\fIstring\fR |
495aee44 CR |
7140 | Refer to the most recent command preceding the current position in the |
7141 | history list starting with | |
726f6388 JA |
7142 | .IR string . |
7143 | .TP | |
7144 | .B !?\fIstring\fR\fB[?]\fR | |
ac50fbac | 7145 | Refer to the most recent command preceding the current position in the |
495aee44 | 7146 | history list containing |
726f6388 | 7147 | .IR string . |
ccc6cda3 JA |
7148 | The trailing \fB?\fP may be omitted if |
7149 | .I string | |
7150 | is followed immediately by a newline. | |
726f6388 JA |
7151 | .TP |
7152 | .B \d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u | |
495aee44 | 7153 | Quick substitution. Repeat the previous command, replacing |
726f6388 JA |
7154 | .I string1 |
7155 | with | |
7156 | .IR string2 . | |
7157 | Equivalent to | |
7158 | ``!!:s/\fIstring1\fP/\fIstring2\fP/'' | |
7159 | (see \fBModifiers\fP below). | |
7160 | .TP | |
7161 | .B !# | |
7162 | The entire command line typed so far. | |
7163 | .PD | |
7164 | .SS Word Designators | |
7165 | .PP | |
ccc6cda3 | 7166 | Word designators are used to select desired words from the event. |
a0c0a00f | 7167 | A |
726f6388 | 7168 | .B : |
ccc6cda3 | 7169 | separates the event specification from the word designator. |
cce855bc | 7170 | It may be omitted if the word designator begins with a |
726f6388 JA |
7171 | .BR ^ , |
7172 | .BR $ , | |
7173 | .BR * , | |
ccc6cda3 | 7174 | .BR \- , |
726f6388 JA |
7175 | or |
7176 | .BR % . | |
7177 | Words are numbered from the beginning of the line, | |
ccc6cda3 JA |
7178 | with the first word being denoted by 0 (zero). |
7179 | Words are inserted into the current line separated by single spaces. | |
726f6388 JA |
7180 | .PP |
7181 | .PD 0 | |
7182 | .TP | |
7183 | .B 0 (zero) | |
7184 | The zeroth word. For the shell, this is the command | |
7185 | word. | |
7186 | .TP | |
7187 | .I n | |
7188 | The \fIn\fRth word. | |
7189 | .TP | |
7190 | .B ^ | |
7191 | The first argument. That is, word 1. | |
7192 | .TP | |
7193 | .B $ | |
ac50fbac CR |
7194 | The last word. This is usually the last argument, but will expand to the |
7195 | zeroth word if there is only one word in the line. | |
726f6388 JA |
7196 | .TP |
7197 | .B % | |
7198 | The word matched by the most recent `?\fIstring\fR?' search. | |
7199 | .TP | |
7200 | .I x\fB\-\fPy | |
7201 | A range of words; `\-\fIy\fR' abbreviates `0\-\fIy\fR'. | |
7202 | .TP | |
7203 | .B * | |
7204 | All of the words but the zeroth. This is a synonym | |
7205 | for `\fI1\-$\fP'. It is not an error to use | |
7206 | .B * | |
7207 | if there is just one | |
7208 | word in the event; the empty string is returned in that case. | |
7209 | .TP | |
7210 | .B x* | |
7211 | Abbreviates \fIx\-$\fP. | |
7212 | .TP | |
7213 | .B x\- | |
7214 | Abbreviates \fIx\-$\fP like \fBx*\fP, but omits the last word. | |
7215 | .PD | |
ccc6cda3 JA |
7216 | .PP |
7217 | If a word designator is supplied without an event specification, the | |
7218 | previous command is used as the event. | |
726f6388 JA |
7219 | .SS Modifiers |
7220 | .PP | |
ccc6cda3 JA |
7221 | After the optional word designator, there may appear a sequence of |
7222 | one or more of the following modifiers, each preceded by a `:'. | |
726f6388 JA |
7223 | .PP |
7224 | .PD 0 | |
7225 | .PP | |
7226 | .TP | |
7227 | .B h | |
ac50fbac | 7228 | Remove a trailing filename component, leaving only the head. |
ccc6cda3 JA |
7229 | .TP |
7230 | .B t | |
ac50fbac | 7231 | Remove all leading filename components, leaving the tail. |
726f6388 JA |
7232 | .TP |
7233 | .B r | |
7234 | Remove a trailing suffix of the form \fI.xxx\fP, leaving the | |
7235 | basename. | |
7236 | .TP | |
7237 | .B e | |
7238 | Remove all but the trailing suffix. | |
7239 | .TP | |
726f6388 JA |
7240 | .B p |
7241 | Print the new command but do not execute it. | |
7242 | .TP | |
7243 | .B q | |
7244 | Quote the substituted words, escaping further substitutions. | |
7245 | .TP | |
cce855bc JA |
7246 | .B x |
7247 | Quote the substituted words as with | |
7248 | .BR q , | |
7249 | but break into words at | |
7250 | .B blanks | |
7251 | and newlines. | |
726f6388 | 7252 | .TP |
cce855bc JA |
7253 | .B s/\fIold\fP/\fInew\fP/ |
7254 | Substitute | |
7255 | .I new | |
7256 | for the first occurrence of | |
7257 | .I old | |
7258 | in the event line. Any delimiter can be used in place of /. The | |
7259 | final delimiter is optional if it is the last character of the | |
7260 | event line. The delimiter may be quoted in | |
7261 | .I old | |
7262 | and | |
7263 | .I new | |
7264 | with a single backslash. If & appears in | |
7265 | .IR new , | |
7266 | it is replaced by | |
7267 | .IR old . | |
7268 | A single backslash will quote the &. If | |
7269 | .I old | |
7270 | is null, it is set to the last | |
7271 | .I old | |
7272 | substituted, or, if no previous history substitutions took place, | |
7273 | the last | |
7274 | .I string | |
7275 | in a | |
7276 | .B !?\fIstring\fR\fB[?]\fR | |
7277 | search. | |
ccc6cda3 | 7278 | .TP |
cce855bc JA |
7279 | .B & |
7280 | Repeat the previous substitution. | |
7281 | .TP | |
7282 | .B g | |
7283 | Cause changes to be applied over the entire event line. This is | |
7284 | used in conjunction with `\fB:s\fP' (e.g., `\fB:gs/\fIold\fP/\fInew\fP/\fR') | |
7285 | or `\fB:&\fP'. If used with | |
7286 | `\fB:s\fP', any delimiter can be used | |
7287 | in place of /, and the final delimiter is optional | |
7288 | if it is the last character of the event line. | |
b80f6443 JA |
7289 | An \fBa\fP may be used as a synonym for \fBg\fP. |
7290 | .TP | |
7291 | .B G | |
7292 | Apply the following `\fBs\fP' modifier once to each word in the event line. | |
726f6388 | 7293 | .PD |
726f6388 JA |
7294 | .SH "SHELL BUILTIN COMMANDS" |
7295 | .\" start of bash_builtins | |
7296 | .zZ | |
ccc6cda3 JA |
7297 | .PP |
7298 | Unless otherwise noted, each builtin command documented in this | |
7299 | section as accepting options preceded by | |
7300 | .B \- | |
7301 | accepts | |
7302 | .B \-\- | |
7303 | to signify the end of the options. | |
9a51695b | 7304 | The \fB:\fP, \fBtrue\fP, \fBfalse\fP, and \fBtest\fP/\fB[\fP builtins |
0001803f | 7305 | do not accept options and do not treat \fB\-\-\fP specially. |
a0c0a00f CR |
7306 | The \fBexit\fP, \fBlogout\fP, \fBreturn\fP, |
7307 | \fBbreak\fP, \fBcontinue\fP, \fBlet\fP, | |
0001803f CR |
7308 | and \fBshift\fP builtins accept and process arguments beginning with |
7309 | \fB\-\fP without requiring \fB\-\-\fP. | |
7310 | Other builtins that accept arguments but are not specified as accepting | |
7311 | options interpret arguments beginning with \fB\-\fP as invalid options and | |
7312 | require \fB\-\-\fP to prevent this interpretation. | |
ccc6cda3 | 7313 | .sp .5 |
726f6388 JA |
7314 | .PD 0 |
7315 | .TP | |
7316 | \fB:\fP [\fIarguments\fP] | |
7317 | .PD | |
7318 | No effect; the command does nothing beyond expanding | |
7319 | .I arguments | |
7320 | and performing any specified | |
a0c0a00f CR |
7321 | redirections. |
7322 | The return status is zero. | |
726f6388 | 7323 | .TP |
726f6388 | 7324 | \fB .\| \fP \fIfilename\fP [\fIarguments\fP] |
7117c2d2 | 7325 | .PD 0 |
726f6388 JA |
7326 | .TP |
7327 | \fBsource\fP \fIfilename\fP [\fIarguments\fP] | |
7328 | .PD | |
7329 | Read and execute commands from | |
7330 | .I filename | |
7331 | in the current | |
7332 | shell environment and return the exit status of the last command | |
7333 | executed from | |
7334 | .IR filename . | |
7335 | If | |
7336 | .I filename | |
ac50fbac | 7337 | does not contain a slash, filenames in |
726f6388 JA |
7338 | .SM |
7339 | .B PATH | |
7340 | are used to find the directory containing | |
7341 | .IR filename . | |
7342 | The file searched for in | |
7343 | .SM | |
7344 | .B PATH | |
28ef6c31 JA |
7345 | need not be executable. |
7346 | When \fBbash\fP is not in \fIposix mode\fP, the current directory is | |
726f6388 JA |
7347 | searched if no file is found in |
7348 | .SM | |
7349 | .BR PATH . | |
ccc6cda3 JA |
7350 | If the |
7351 | .B sourcepath | |
7352 | option to the | |
7353 | .B shopt | |
7354 | builtin command is turned off, the | |
7355 | .SM | |
7356 | .B PATH | |
7357 | is not searched. | |
726f6388 | 7358 | If any \fIarguments\fP are supplied, they become the positional |
ccc6cda3 | 7359 | parameters when \fIfilename\fP is executed. Otherwise the positional |
726f6388 | 7360 | parameters are unchanged. |
a0c0a00f CR |
7361 | If the \fB\-T\fP option is enabled, \fBsource\fP inherits any trap on |
7362 | \fBDEBUG\fP; if it is not, any \fBDEBUG\fP trap string is saved and | |
7363 | restored around the call to \fBsource\fP, and \fBsource\fP unsets the | |
7364 | \fBDEBUG\fP trap while it executes. | |
7365 | If \fB\-T\fP is not set, and the sourced file changes | |
7366 | the \fBDEBUG\fP trap, the new value is retained when \fBsource\fP completes. | |
726f6388 JA |
7367 | The return status is the status of the last command exited within |
7368 | the script (0 if no commands are executed), and false if | |
7369 | .I filename | |
cce855bc | 7370 | is not found or cannot be read. |
726f6388 | 7371 | .TP |
ccc6cda3 JA |
7372 | \fBalias\fP [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...] |
7373 | \fBAlias\fP with no arguments or with the | |
7374 | .B \-p | |
7375 | option prints the list of aliases in the form | |
7376 | \fBalias\fP \fIname\fP=\fIvalue\fP on standard output. | |
7377 | When arguments are supplied, an alias is defined for | |
7378 | each \fIname\fP whose \fIvalue\fP is given. | |
a0c0a00f | 7379 | A trailing space in \fIvalue\fP causes the next word to be |
ccc6cda3 JA |
7380 | checked for alias substitution when the alias is expanded. |
7381 | For each \fIname\fP in the argument list for which no \fIvalue\fP | |
7382 | is supplied, the name and value of the alias is printed. | |
7383 | \fBAlias\fP returns true unless a \fIname\fP is given for which | |
7384 | no alias has been defined. | |
726f6388 | 7385 | .TP |
95732b49 JA |
7386 | \fBbg\fP [\fIjobspec\fP ...] |
7387 | Resume each suspended job \fIjobspec\fP in the background, as if it | |
cce855bc | 7388 | had been started with |
726f6388 | 7389 | .BR & . |
3185942a JA |
7390 | If |
7391 | .I jobspec | |
7392 | is not present, the shell's notion of the \fIcurrent job\fP is used. | |
726f6388 JA |
7393 | .B bg |
7394 | .I jobspec | |
7395 | returns 0 unless run when job control is disabled or, when run with | |
95732b49 JA |
7396 | job control enabled, any specified \fIjobspec\fP was not found |
7397 | or was started without job control. | |
726f6388 | 7398 | .TP |
ac50fbac | 7399 | \fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-lpsvPSVX\fP] |
7117c2d2 | 7400 | .PD 0 |
cce855bc JA |
7401 | .TP |
7402 | \fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-q\fP \fIfunction\fP] [\fB\-u\fP \fIfunction\fP] [\fB\-r\fP \fIkeyseq\fP] | |
726f6388 | 7403 | .TP |
ccc6cda3 | 7404 | \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB\-f\fP \fIfilename\fP |
726f6388 | 7405 | .TP |
bb70624e JA |
7406 | \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB\-x\fP \fIkeyseq\fP:\fIshell\-command\fP |
7407 | .TP | |
ccc6cda3 | 7408 | \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fIkeyseq\fP:\fIfunction\-name\fP |
7117c2d2 | 7409 | .TP |
a0c0a00f | 7410 | \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fIkeyseq\fP:\fIreadline\-command\fP |
726f6388 JA |
7411 | .PD |
7412 | Display current | |
7413 | .B readline | |
7117c2d2 | 7414 | key and function bindings, bind a key sequence to a |
726f6388 | 7415 | .B readline |
7117c2d2 JA |
7416 | function or macro, or set a |
7417 | .B readline | |
7418 | variable. | |
7419 | Each non-option argument is a command as it would appear in | |
726f6388 | 7420 | .IR .inputrc , |
7117c2d2 JA |
7421 | but each binding or command must be passed as a separate argument; |
7422 | e.g., '"\eC\-x\eC\-r": re\-read\-init\-file'. | |
7423 | Options, if supplied, have the following meanings: | |
726f6388 JA |
7424 | .RS |
7425 | .PD 0 | |
7426 | .TP | |
7427 | .B \-m \fIkeymap\fP | |
7428 | Use | |
7429 | .I keymap | |
7430 | as the keymap to be affected by the subsequent bindings. | |
7431 | Acceptable | |
7432 | .I keymap | |
7433 | names are | |
ccc6cda3 | 7434 | \fIemacs, emacs\-standard, emacs\-meta, emacs\-ctlx, vi, |
28ef6c31 | 7435 | vi\-move, vi\-command\fP, and |
ccc6cda3 | 7436 | .IR vi\-insert . |
a0c0a00f CR |
7437 | \fIvi\fP is equivalent to \fIvi\-command\fP (\fIvi\-move\fP is also |
7438 | a synonym); \fIemacs\fP is | |
ccc6cda3 | 7439 | equivalent to \fIemacs\-standard\fP. |
726f6388 JA |
7440 | .TP |
7441 | .B \-l | |
ccc6cda3 JA |
7442 | List the names of all \fBreadline\fP functions. |
7443 | .TP | |
7444 | .B \-p | |
7445 | Display \fBreadline\fP function names and bindings in such a way | |
7446 | that they can be re-read. | |
7447 | .TP | |
7448 | .B \-P | |
7449 | List current \fBreadline\fP function names and bindings. | |
726f6388 | 7450 | .TP |
ccc6cda3 JA |
7451 | .B \-s |
7452 | Display \fBreadline\fP key sequences bound to macros and the strings | |
7453 | they output in such a way that they can be re-read. | |
7454 | .TP | |
7455 | .B \-S | |
7456 | Display \fBreadline\fP key sequences bound to macros and the strings | |
7457 | they output. | |
726f6388 | 7458 | .TP |
3185942a JA |
7459 | .B \-v |
7460 | Display \fBreadline\fP variable names and values in such a way that they | |
7461 | can be re-read. | |
7462 | .TP | |
7463 | .B \-V | |
7464 | List current \fBreadline\fP variable names and values. | |
7465 | .TP | |
726f6388 | 7466 | .B \-f \fIfilename\fP |
ccc6cda3 | 7467 | Read key bindings from \fIfilename\fP. |
726f6388 JA |
7468 | .TP |
7469 | .B \-q \fIfunction\fP | |
ccc6cda3 JA |
7470 | Query about which keys invoke the named \fIfunction\fP. |
7471 | .TP | |
cce855bc JA |
7472 | .B \-u \fIfunction\fP |
7473 | Unbind all keys bound to the named \fIfunction\fP. | |
7474 | .TP | |
ccc6cda3 JA |
7475 | .B \-r \fIkeyseq\fP |
7476 | Remove any current binding for \fIkeyseq\fP. | |
bb70624e JA |
7477 | .TP |
7478 | .B \-x \fIkeyseq\fP:\fIshell\-command\fP | |
7479 | Cause \fIshell\-command\fP to be executed whenever \fIkeyseq\fP is | |
7480 | entered. | |
3185942a | 7481 | When \fIshell\-command\fP is executed, the shell sets the |
0001803f | 7482 | .SM |
3185942a JA |
7483 | .B READLINE_LINE |
7484 | variable to the contents of the \fBreadline\fP line buffer and the | |
0001803f | 7485 | .SM |
3185942a JA |
7486 | .B READLINE_POINT |
7487 | variable to the current location of the insertion point. | |
7488 | If the executed command changes the value of | |
0001803f | 7489 | .SM |
3185942a JA |
7490 | .B READLINE_LINE |
7491 | or | |
0001803f | 7492 | .SM |
3185942a JA |
7493 | .BR READLINE_POINT , |
7494 | those new values will be reflected in the editing state. | |
ac50fbac CR |
7495 | .TP |
7496 | .B \-X | |
7497 | List all key sequences bound to shell commands and the associated commands | |
7498 | in a format that can be reused as input. | |
726f6388 JA |
7499 | .PD |
7500 | .PP | |
7501 | The return value is 0 unless an unrecognized option is given or an | |
7502 | error occurred. | |
7503 | .RE | |
7504 | .TP | |
7505 | \fBbreak\fP [\fIn\fP] | |
7506 | Exit from within a | |
7507 | .BR for , | |
7508 | .BR while , | |
ccc6cda3 | 7509 | .BR until , |
726f6388 | 7510 | or |
ccc6cda3 | 7511 | .B select |
726f6388 JA |
7512 | loop. If \fIn\fP is specified, break \fIn\fP levels. |
7513 | .I n | |
7514 | must be \(>= 1. If | |
7515 | .I n | |
7516 | is greater than the number of enclosing loops, all enclosing loops | |
3185942a JA |
7517 | are exited. |
7518 | The return value is 0 unless \fIn\fP is not greater than or equal to 1. | |
726f6388 JA |
7519 | .TP |
7520 | \fBbuiltin\fP \fIshell\-builtin\fP [\fIarguments\fP] | |
7521 | Execute the specified shell builtin, passing it | |
7522 | .IR arguments , | |
7523 | and return its exit status. | |
cce855bc | 7524 | This is useful when defining a |
726f6388 | 7525 | function whose name is the same as a shell builtin, |
cce855bc JA |
7526 | retaining the functionality of the builtin within the function. |
7527 | The \fBcd\fP builtin is commonly redefined this way. | |
7528 | The return status is false if | |
726f6388 JA |
7529 | .I shell\-builtin |
7530 | is not a shell builtin command. | |
7531 | .TP | |
3185942a JA |
7532 | \fBcaller\fP [\fIexpr\fP] |
7533 | Returns the context of any active subroutine call (a shell function or | |
495aee44 | 7534 | a script executed with the \fB.\fP or \fBsource\fP builtins). |
3185942a JA |
7535 | Without \fIexpr\fP, \fBcaller\fP displays the line number and source |
7536 | filename of the current subroutine call. | |
a0c0a00f | 7537 | If a non-negative integer is supplied as \fIexpr\fP, \fBcaller\fP |
3185942a JA |
7538 | displays the line number, subroutine name, and source file corresponding |
7539 | to that position in the current execution call stack. This extra | |
7540 | information may be used, for example, to print a stack trace. The | |
7541 | current frame is frame 0. | |
7542 | The return value is 0 unless the shell is not executing a subroutine | |
7543 | call or \fIexpr\fP does not correspond to a valid position in the | |
7544 | call stack. | |
7545 | .TP | |
ac50fbac CR |
7546 | \fBcd\fP [\fB\-L\fP|[\fB\-P\fP [\fB\-e\fP]] [\-@]] [\fIdir\fP] |
7547 | Change the current directory to \fIdir\fP. | |
7548 | if \fIdir\fP is not supplied, the value of the | |
726f6388 JA |
7549 | .SM |
7550 | .B HOME | |
ac50fbac CR |
7551 | shell variable is the default. |
7552 | Any additional arguments following \fIdir\fP are ignored. | |
726f6388 JA |
7553 | The variable |
7554 | .SM | |
7555 | .B CDPATH | |
ccc6cda3 | 7556 | defines the search path for the directory containing |
ac50fbac CR |
7557 | .IR dir : |
7558 | each directory name in | |
7559 | .SM | |
7560 | .B CDPATH | |
7561 | is searched for \fIdir\fP. | |
ccc6cda3 JA |
7562 | Alternative directory names in |
7563 | .SM | |
7564 | .B CDPATH | |
7565 | are separated by a colon (:). A null directory name in | |
726f6388 JA |
7566 | .SM |
7567 | .B CDPATH | |
ccc6cda3 | 7568 | is the same as the current directory, i.e., ``\fB.\fP''. If |
726f6388 JA |
7569 | .I dir |
7570 | begins with a slash (/), | |
7571 | then | |
7572 | .SM | |
7573 | .B CDPATH | |
a0c0a00f | 7574 | is not used. The |
ccc6cda3 | 7575 | .B \-P |
ac50fbac CR |
7576 | option causes \fBcd\fP to use the physical directory structure |
7577 | by resolving symbolic links while traversing \fIdir\fP and | |
7578 | before processing instances of \fI..\fP in \fIdir\fP (see also the | |
ccc6cda3 JA |
7579 | .B \-P |
7580 | option to the | |
7581 | .B set | |
7582 | builtin command); the | |
7583 | .B \-L | |
ac50fbac CR |
7584 | option forces symbolic links to be followed by resolving the link |
7585 | after processing instances of \fI..\fP in \fIdir\fP. | |
7586 | If \fI..\fP appears in \fIdir\fP, it is processed by removing the | |
7587 | immediately previous pathname component from \fIdir\fP, back to a slash | |
7588 | or the beginning of \fIdir\fP. | |
495aee44 CR |
7589 | If the |
7590 | .B \-e | |
7591 | option is supplied with | |
7592 | .BR \-P , | |
7593 | and the current working directory cannot be successfully determined | |
7594 | after a successful directory change, \fBcd\fP will return an unsuccessful | |
7595 | status. | |
ac50fbac CR |
7596 | On systems that support it, the \fB\-@\fP option presents the extended |
7597 | attributes associated with a file as a directory. | |
495aee44 | 7598 | An argument of |
726f6388 | 7599 | .B \- |
ac50fbac | 7600 | is converted to |
726f6388 | 7601 | .SM |
ac50fbac CR |
7602 | .B $OLDPWD |
7603 | before the directory change is attempted. | |
0001803f CR |
7604 | If a non-empty directory name from |
7605 | .SM | |
7606 | .B CDPATH | |
7607 | is used, or if | |
b80f6443 JA |
7608 | \fB\-\fP is the first argument, and the directory change is |
7609 | successful, the absolute pathname of the new working directory is | |
7610 | written to the standard output. | |
726f6388 JA |
7611 | The return value is true if the directory was successfully changed; |
7612 | false otherwise. | |
7613 | .TP | |
ccc6cda3 | 7614 | \fBcommand\fP [\fB\-pVv\fP] \fIcommand\fP [\fIarg\fP ...] |
726f6388 JA |
7615 | Run |
7616 | .I command | |
7617 | with | |
7618 | .I args | |
a0c0a00f CR |
7619 | suppressing the normal shell function lookup. |
7620 | Only builtin commands or commands found in the | |
726f6388 JA |
7621 | .SM |
7622 | .B PATH | |
7623 | are executed. If the | |
7624 | .B \-p | |
7625 | option is given, the search for | |
7626 | .I command | |
7627 | is performed using a default value for | |
0001803f | 7628 | .SM |
726f6388 JA |
7629 | .B PATH |
7630 | that is guaranteed to find all of the standard utilities. | |
7631 | If either the | |
7632 | .B \-V | |
7633 | or | |
7634 | .B \-v | |
7635 | option is supplied, a description of | |
7636 | .I command | |
7637 | is printed. The | |
7638 | .B \-v | |
ac50fbac | 7639 | option causes a single word indicating the command or filename |
726f6388 JA |
7640 | used to invoke |
7641 | .I command | |
cce855bc | 7642 | to be displayed; the |
726f6388 JA |
7643 | .B \-V |
7644 | option produces a more verbose description. | |
726f6388 JA |
7645 | If the |
7646 | .B \-V | |
7647 | or | |
7648 | .B \-v | |
7649 | option is supplied, the exit status is 0 if | |
7650 | .I command | |
7651 | was found, and 1 if not. If neither option is supplied and | |
7652 | an error occurred or | |
7653 | .I command | |
7654 | cannot be found, the exit status is 127. Otherwise, the exit status of the | |
7655 | .B command | |
7656 | builtin is the exit status of | |
7657 | .IR command . | |
7658 | .TP | |
bb70624e JA |
7659 | \fBcompgen\fP [\fIoption\fP] [\fIword\fP] |
7660 | Generate possible completion matches for \fIword\fP according to | |
7661 | the \fIoption\fPs, which may be any option accepted by the | |
7662 | .B complete | |
7663 | builtin with the exception of \fB\-p\fP and \fB\-r\fP, and write | |
7664 | the matches to the standard output. | |
7665 | When using the \fB\-F\fP or \fB\-C\fP options, the various shell variables | |
7666 | set by the programmable completion facilities, while available, will not | |
7667 | have useful values. | |
7668 | .sp 1 | |
7669 | The matches will be generated in the same way as if the programmable | |
7670 | completion code had generated them directly from a completion specification | |
7671 | with the same flags. | |
7672 | If \fIword\fP is specified, only those completions matching \fIword\fP | |
7673 | will be displayed. | |
7674 | .sp 1 | |
7675 | The return value is true unless an invalid option is supplied, or no | |
7676 | matches were generated. | |
7677 | .TP | |
2f5dfe5a | 7678 | \fBcomplete\fP [\fB\-abcdefgjksuv\fP] [\fB\-o\fP \fIcomp-option\fP] [\fB\-DEI\fP] [\fB\-A\fP \fIaction\fP] [\fB\-G\fP \fIglobpat\fP] [\fB\-W\fP \fIwordlist\fP] [\fB\-F\fP \fIfunction\fP] [\fB\-C\fP \fIcommand\fP] |
bb70624e | 7679 | .br |
3185942a | 7680 | [\fB\-X\fP \fIfilterpat\fP] [\fB\-P\fP \fIprefix\fP] [\fB\-S\fP \fIsuffix\fP] \fIname\fP [\fIname ...\fP] |
7117c2d2 | 7681 | .PD 0 |
bb70624e | 7682 | .TP |
2f5dfe5a | 7683 | \fBcomplete\fP \fB\-pr\fP [\fB\-DEI\fP] [\fIname\fP ...] |
bb70624e JA |
7684 | .PD |
7685 | Specify how arguments to each \fIname\fP should be completed. | |
7686 | If the \fB\-p\fP option is supplied, or if no options are supplied, | |
7687 | existing completion specifications are printed in a way that allows | |
7688 | them to be reused as input. | |
7689 | The \fB\-r\fP option removes a completion specification for | |
7690 | each \fIname\fP, or, if no \fIname\fPs are supplied, all | |
7691 | completion specifications. | |
2f5dfe5a | 7692 | The \fB\-D\fP option indicates that other supplied options and actions should |
0001803f CR |
7693 | apply to the ``default'' command completion; that is, completion attempted |
7694 | on a command for which no completion has previously been defined. | |
2f5dfe5a | 7695 | The \fB\-E\fP option indicates that other supplied options and actions should |
3185942a JA |
7696 | apply to ``empty'' command completion; that is, completion attempted on a |
7697 | blank line. | |
2f5dfe5a CR |
7698 | The \fB\-I\fP option indicates that other supplied options and actions should |
7699 | apply to completion on the inital non-assignment word on the line, or after | |
7700 | a command delimiter such as \fB;\fP or \fB|\fP, which is usually command | |
7701 | name completion. | |
7702 | If multiple options are supplied, the \fB\-D\fP option takes precedence | |
7703 | over \fB\-E\fP, and both take precedence over \fB\-I\fP. | |
7704 | If any of \fB\-D\fP, \fB\-E\fP, or \fB\-I\fP are supplied, any other | |
7705 | \fIname\fP arguments are ignored; these completions only apply to the case | |
7706 | specified by the option. | |
bb70624e JA |
7707 | .sp 1 |
7708 | The process of applying these completion specifications when word completion | |
7709 | is attempted is described above under \fBProgrammable Completion\fP. | |
7710 | .sp 1 | |
7711 | Other options, if specified, have the following meanings. | |
7712 | The arguments to the \fB\-G\fP, \fB\-W\fP, and \fB\-X\fP options | |
7713 | (and, if necessary, the \fB\-P\fP and \fB\-S\fP options) | |
7714 | should be quoted to protect them from expansion before the | |
7715 | .B complete | |
7716 | builtin is invoked. | |
7717 | .RS | |
7718 | .PD 0 | |
7719 | .TP 8 | |
28ef6c31 JA |
7720 | \fB\-o\fP \fIcomp-option\fP |
7721 | The \fIcomp-option\fP controls several aspects of the compspec's behavior | |
7722 | beyond the simple generation of completions. | |
7723 | \fIcomp-option\fP may be one of: | |
7724 | .RS | |
7725 | .TP 8 | |
b80f6443 JA |
7726 | .B bashdefault |
7727 | Perform the rest of the default \fBbash\fP completions if the compspec | |
7728 | generates no matches. | |
7729 | .TP 8 | |
28ef6c31 | 7730 | .B default |
7117c2d2 JA |
7731 | Use readline's default filename completion if the compspec generates |
7732 | no matches. | |
28ef6c31 JA |
7733 | .TP 8 |
7734 | .B dirnames | |
7735 | Perform directory name completion if the compspec generates no matches. | |
7736 | .TP 8 | |
7737 | .B filenames | |
7738 | Tell readline that the compspec generates filenames, so it can perform any | |
3185942a JA |
7739 | filename\-specific processing (like adding a slash to directory names, |
7740 | quoting special characters, or suppressing trailing spaces). | |
7741 | Intended to be used with shell functions. | |
7117c2d2 | 7742 | .TP 8 |
ac50fbac CR |
7743 | .B noquote |
7744 | Tell readline not to quote the completed words if they are filenames | |
7745 | (quoting filenames is the default). | |
7746 | .TP 8 | |
a0c0a00f CR |
7747 | .B nosort |
7748 | Tell readline not to sort the list of possible completions alphabetically. | |
7749 | .TP 8 | |
7117c2d2 JA |
7750 | .B nospace |
7751 | Tell readline not to append a space (the default) to words completed at | |
7752 | the end of the line. | |
95732b49 JA |
7753 | .TP 8 |
7754 | .B plusdirs | |
a0c0a00f | 7755 | After any matches defined by the compspec are generated, |
95732b49 JA |
7756 | directory name completion is attempted and any |
7757 | matches are added to the results of the other actions. | |
28ef6c31 JA |
7758 | .RE |
7759 | .TP 8 | |
bb70624e JA |
7760 | \fB\-A\fP \fIaction\fP |
7761 | The \fIaction\fP may be one of the following to generate a list of possible | |
7762 | completions: | |
7763 | .RS | |
7764 | .TP 8 | |
7765 | .B alias | |
7766 | Alias names. May also be specified as \fB\-a\fP. | |
7767 | .TP 8 | |
7768 | .B arrayvar | |
7769 | Array variable names. | |
7770 | .TP 8 | |
7771 | .B binding | |
7772 | \fBReadline\fP key binding names. | |
7773 | .TP 8 | |
7774 | .B builtin | |
7775 | Names of shell builtin commands. May also be specified as \fB\-b\fP. | |
7776 | .TP 8 | |
7777 | .B command | |
7778 | Command names. May also be specified as \fB\-c\fP. | |
7779 | .TP 8 | |
7780 | .B directory | |
7781 | Directory names. May also be specified as \fB\-d\fP. | |
7782 | .TP 8 | |
7783 | .B disabled | |
7784 | Names of disabled shell builtins. | |
7785 | .TP 8 | |
7786 | .B enabled | |
7787 | Names of enabled shell builtins. | |
7788 | .TP 8 | |
7789 | .B export | |
7790 | Names of exported shell variables. May also be specified as \fB\-e\fP. | |
7791 | .TP 8 | |
7792 | .B file | |
7793 | File names. May also be specified as \fB\-f\fP. | |
7794 | .TP 8 | |
7795 | .B function | |
7796 | Names of shell functions. | |
7797 | .TP 8 | |
f73dda09 JA |
7798 | .B group |
7799 | Group names. May also be specified as \fB\-g\fP. | |
7800 | .TP 8 | |
bb70624e JA |
7801 | .B helptopic |
7802 | Help topics as accepted by the \fBhelp\fP builtin. | |
7803 | .TP 8 | |
7804 | .B hostname | |
7805 | Hostnames, as taken from the file specified by the | |
7806 | .SM | |
7807 | .B HOSTFILE | |
7808 | shell variable. | |
7809 | .TP 8 | |
7810 | .B job | |
7811 | Job names, if job control is active. May also be specified as \fB\-j\fP. | |
7812 | .TP 8 | |
7813 | .B keyword | |
7814 | Shell reserved words. May also be specified as \fB\-k\fP. | |
7815 | .TP 8 | |
7816 | .B running | |
7817 | Names of running jobs, if job control is active. | |
7818 | .TP 8 | |
7117c2d2 JA |
7819 | .B service |
7820 | Service names. May also be specified as \fB\-s\fP. | |
7821 | .TP 8 | |
bb70624e JA |
7822 | .B setopt |
7823 | Valid arguments for the \fB\-o\fP option to the \fBset\fP builtin. | |
7824 | .TP 8 | |
7825 | .B shopt | |
7826 | Shell option names as accepted by the \fBshopt\fP builtin. | |
7827 | .TP 8 | |
7828 | .B signal | |
7829 | Signal names. | |
7830 | .TP 8 | |
7831 | .B stopped | |
7832 | Names of stopped jobs, if job control is active. | |
7833 | .TP 8 | |
7834 | .B user | |
7835 | User names. May also be specified as \fB\-u\fP. | |
7836 | .TP 8 | |
7837 | .B variable | |
7838 | Names of all shell variables. May also be specified as \fB\-v\fP. | |
7839 | .RE | |
7840 | .TP 8 | |
bb70624e JA |
7841 | \fB\-C\fP \fIcommand\fP |
7842 | \fIcommand\fP is executed in a subshell environment, and its output is | |
7843 | used as the possible completions. | |
7844 | .TP 8 | |
7845 | \fB\-F\fP \fIfunction\fP | |
7846 | The shell function \fIfunction\fP is executed in the current shell | |
7847 | environment. | |
ac50fbac CR |
7848 | When the function is executed, |
7849 | the first argument (\fB$1\fP) is the name of the command whose arguments are | |
7850 | being completed, | |
7851 | the second argument (\fB$2\fP) is the word being completed, | |
7852 | and the third argument (\fB$3\fP) is the word preceding the word being | |
7853 | completed on the current command line. | |
bb70624e JA |
7854 | When it finishes, the possible completions are retrieved from the value |
7855 | of the | |
7856 | .SM | |
7857 | .B COMPREPLY | |
7858 | array variable. | |
7859 | .TP 8 | |
495aee44 CR |
7860 | \fB\-G\fP \fIglobpat\fP |
7861 | The pathname expansion pattern \fIglobpat\fP is expanded to generate | |
7862 | the possible completions. | |
bb70624e JA |
7863 | .TP 8 |
7864 | \fB\-P\fP \fIprefix\fP | |
7865 | \fIprefix\fP is added at the beginning of each possible completion | |
7866 | after all other options have been applied. | |
7867 | .TP 8 | |
7868 | \fB\-S\fP \fIsuffix\fP | |
7869 | \fIsuffix\fP is appended to each possible completion | |
7870 | after all other options have been applied. | |
495aee44 CR |
7871 | .TP 8 |
7872 | \fB\-W\fP \fIwordlist\fP | |
7873 | The \fIwordlist\fP is split using the characters in the | |
7874 | .SM | |
7875 | .B IFS | |
7876 | special variable as delimiters, and each resultant word is expanded. | |
9a51695b CR |
7877 | Shell quoting is honored within \fIwordlist\fP, |
7878 | in order to provide a | |
7879 | mechanism for the words to contain shell metacharacters or characters | |
7880 | in the value of | |
7881 | .SM | |
7882 | .BR IFS . | |
495aee44 CR |
7883 | The possible completions are the members of the resultant list which |
7884 | match the word being completed. | |
7885 | .TP 8 | |
7886 | \fB\-X\fP \fIfilterpat\fP | |
7887 | \fIfilterpat\fP is a pattern as used for pathname expansion. | |
7888 | It is applied to the list of possible completions generated by the | |
7889 | preceding options and arguments, and each completion matching | |
7890 | \fIfilterpat\fP is removed from the list. | |
7891 | A leading \fB!\fP in \fIfilterpat\fP negates the pattern; in this | |
7892 | case, any completion not matching \fIfilterpat\fP is removed. | |
bb70624e JA |
7893 | .PD |
7894 | .PP | |
7895 | The return value is true unless an invalid option is supplied, an option | |
7896 | other than \fB\-p\fP or \fB\-r\fP is supplied without a \fIname\fP | |
7897 | argument, an attempt is made to remove a completion specification for | |
7898 | a \fIname\fP for which no specification exists, or | |
7899 | an error occurs adding a completion specification. | |
7900 | .RE | |
7901 | .TP | |
2f5dfe5a | 7902 | \fBcompopt\fP [\fB\-o\fP \fIoption\fP] [\fB\-DEI\fP] [\fB+o\fP \fIoption\fP] [\fIname\fP] |
3185942a JA |
7903 | Modify completion options for each \fIname\fP according to the |
7904 | \fIoption\fPs, or for the | |
495aee44 | 7905 | currently-executing completion if no \fIname\fPs are supplied. |
3185942a JA |
7906 | If no \fIoption\fPs are given, display the completion options for each |
7907 | \fIname\fP or the current completion. | |
7908 | The possible values of \fIoption\fP are those valid for the \fBcomplete\fP | |
7909 | builtin described above. | |
2f5dfe5a | 7910 | The \fB\-D\fP option indicates that other supplied options should |
0001803f CR |
7911 | apply to the ``default'' command completion; that is, completion attempted |
7912 | on a command for which no completion has previously been defined. | |
2f5dfe5a | 7913 | The \fB\-E\fP option indicates that other supplied options should |
0001803f CR |
7914 | apply to ``empty'' command completion; that is, completion attempted on a |
7915 | blank line. | |
2f5dfe5a CR |
7916 | The \fB\-I\fP option indicates that other supplied options should |
7917 | apply to completion on the inital non-assignment word on the line, | |
7918 | or after a command delimiter such as \fB;\fP or \fB|\fP, which is usually | |
7919 | command name completion. | |
495aee44 | 7920 | .sp 1 |
3185942a JA |
7921 | The return value is true unless an invalid option is supplied, an attempt |
7922 | is made to modify the options for a \fIname\fP for which no completion | |
7923 | specification exists, or an output error occurs. | |
7924 | .TP | |
726f6388 JA |
7925 | \fBcontinue\fP [\fIn\fP] |
7926 | Resume the next iteration of the enclosing | |
7927 | .BR for , | |
7928 | .BR while , | |
ccc6cda3 | 7929 | .BR until , |
726f6388 | 7930 | or |
ccc6cda3 | 7931 | .B select |
726f6388 JA |
7932 | loop. |
7933 | If | |
7934 | .I n | |
7935 | is specified, resume at the \fIn\fPth enclosing loop. | |
7936 | .I n | |
7937 | must be \(>= 1. If | |
7938 | .I n | |
7939 | is greater than the number of enclosing loops, the last enclosing loop | |
3185942a JA |
7940 | (the ``top-level'' loop) is resumed. |
7941 | The return value is 0 unless \fIn\fP is not greater than or equal to 1. | |
726f6388 | 7942 | .TP |
ac50fbac | 7943 | \fBdeclare\fP [\fB\-aAfFgilnrtux\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...] |
726f6388 | 7944 | .PD 0 |
726f6388 | 7945 | .TP |
ac50fbac | 7946 | \fBtypeset\fP [\fB\-aAfFgilnrtux\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...] |
726f6388 | 7947 | .PD |
ccc6cda3 JA |
7948 | Declare variables and/or give them attributes. |
7949 | If no \fIname\fPs are given then display the values of variables. | |
7950 | The | |
7951 | .B \-p | |
7952 | option will display the attributes and values of each | |
7953 | .IR name . | |
7954 | When | |
7955 | .B \-p | |
ac50fbac CR |
7956 | is used with \fIname\fP arguments, additional options, |
7957 | other than \fB\-f\fP and \fB\-F\fP, are ignored. | |
3185942a JA |
7958 | When |
7959 | .B \-p | |
7960 | is supplied without \fIname\fP arguments, it will display the attributes | |
7961 | and values of all variables having the attributes specified by the | |
7962 | additional options. | |
7963 | If no other options are supplied with \fB\-p\fP, \fBdeclare\fP will display | |
7964 | the attributes and values of all shell variables. The \fB\-f\fP option | |
7965 | will restrict the display to shell functions. | |
ccc6cda3 JA |
7966 | The |
7967 | .B \-F | |
7968 | option inhibits the display of function definitions; only the | |
7969 | function name and attributes are printed. | |
b80f6443 | 7970 | If the \fBextdebug\fP shell option is enabled using \fBshopt\fP, |
a0c0a00f CR |
7971 | the source file name and line number where each \fIname\fP |
7972 | is defined are displayed as well. The | |
ccc6cda3 JA |
7973 | .B \-F |
7974 | option implies | |
7975 | .BR \-f . | |
495aee44 CR |
7976 | The |
7977 | .B \-g | |
7978 | option forces variables to be created or modified at the global scope, | |
7979 | even when \fBdeclare\fP is executed in a shell function. | |
7980 | It is ignored in all other cases. | |
ccc6cda3 JA |
7981 | The following options can |
7982 | be used to restrict output to variables with the specified attribute or | |
7983 | to give variables attributes: | |
726f6388 JA |
7984 | .RS |
7985 | .PD 0 | |
7986 | .TP | |
ccc6cda3 | 7987 | .B \-a |
3185942a JA |
7988 | Each \fIname\fP is an indexed array variable (see |
7989 | .B Arrays | |
7990 | above). | |
7991 | .TP | |
7992 | .B \-A | |
7993 | Each \fIname\fP is an associative array variable (see | |
ccc6cda3 JA |
7994 | .B Arrays |
7995 | above). | |
7996 | .TP | |
726f6388 | 7997 | .B \-f |
ccc6cda3 JA |
7998 | Use function names only. |
7999 | .TP | |
8000 | .B \-i | |
8001 | The variable is treated as an integer; arithmetic evaluation (see | |
8002 | .SM | |
0001803f CR |
8003 | .B "ARITHMETIC EVALUATION" |
8004 | above) is performed when the variable is assigned a value. | |
726f6388 | 8005 | .TP |
3185942a JA |
8006 | .B \-l |
8007 | When the variable is assigned a value, all upper-case characters are | |
8008 | converted to lower-case. | |
8009 | The upper-case attribute is disabled. | |
8010 | .TP | |
ac50fbac CR |
8011 | .B \-n |
8012 | Give each \fIname\fP the \fInameref\fP attribute, making | |
8013 | it a name reference to another variable. | |
8014 | That other variable is defined by the value of \fIname\fP. | |
a0c0a00f CR |
8015 | All references, assignments, and attribute modifications |
8016 | to \fIname\fP, except those using or changing the | |
ac50fbac CR |
8017 | \fB\-n\fP attribute itself, are performed on the variable referenced by |
8018 | \fIname\fP's value. | |
a0c0a00f | 8019 | The nameref attribute cannot be applied to array variables. |
ac50fbac | 8020 | .TP |
726f6388 JA |
8021 | .B \-r |
8022 | Make \fIname\fPs readonly. These names cannot then be assigned values | |
cce855bc | 8023 | by subsequent assignment statements or unset. |
726f6388 | 8024 | .TP |
7117c2d2 JA |
8025 | .B \-t |
8026 | Give each \fIname\fP the \fItrace\fP attribute. | |
95732b49 JA |
8027 | Traced functions inherit the \fBDEBUG\fP and \fBRETURN\fP traps from |
8028 | the calling shell. | |
7117c2d2 JA |
8029 | The trace attribute has no special meaning for variables. |
8030 | .TP | |
3185942a JA |
8031 | .B \-u |
8032 | When the variable is assigned a value, all lower-case characters are | |
8033 | converted to upper-case. | |
8034 | The lower-case attribute is disabled. | |
8035 | .TP | |
726f6388 JA |
8036 | .B \-x |
8037 | Mark \fIname\fPs for export to subsequent commands via the environment. | |
726f6388 JA |
8038 | .PD |
8039 | .PP | |
8040 | Using `+' instead of `\-' | |
3185942a | 8041 | turns off the attribute instead, |
f250956c CR |
8042 | with the exceptions that \fB+a\fP and \fB+A\fP |
8043 | may not be used to destroy array variables and \fB+r\fP will not | |
3185942a | 8044 | remove the readonly attribute. |
ac50fbac CR |
8045 | When used in a function, |
8046 | .B declare | |
8047 | and | |
8048 | .B typeset | |
8049 | make each | |
495aee44 | 8050 | \fIname\fP local, as with the |
726f6388 | 8051 | .B local |
495aee44 | 8052 | command, |
ac50fbac | 8053 | unless the \fB\-g\fP option is supplied. |
b80f6443 JA |
8054 | If a variable name is followed by =\fIvalue\fP, the value of |
8055 | the variable is set to \fIvalue\fP. | |
ac50fbac CR |
8056 | When using \fB\-a\fP or \fB\-A\fP and the compound assignment syntax to |
8057 | create array variables, additional attributes do not take effect until | |
8058 | subsequent assignments. | |
b80f6443 | 8059 | The return value is 0 unless an invalid option is encountered, |
bb70624e JA |
8060 | an attempt is made to define a function using |
8061 | .if n ``\-f foo=bar'', | |
8062 | .if t \f(CW\-f foo=bar\fP, | |
ccc6cda3 JA |
8063 | an attempt is made to assign a value to a readonly variable, |
8064 | an attempt is made to assign a value to an array variable without | |
8065 | using the compound assignment syntax (see | |
8066 | .B Arrays | |
cce855bc | 8067 | above), one of the \fInames\fP is not a valid shell variable name, |
726f6388 | 8068 | an attempt is made to turn off readonly status for a readonly variable, |
ccc6cda3 | 8069 | an attempt is made to turn off array status for an array variable, |
bb70624e | 8070 | or an attempt is made to display a non-existent function with \fB\-f\fP. |
726f6388 JA |
8071 | .RE |
8072 | .TP | |
ac50fbac | 8073 | .B dirs [\fB\-clpv\fP] [+\fIn\fP] [\-\fIn\fP] |
ccc6cda3 JA |
8074 | Without options, displays the list of currently remembered directories. |
8075 | The default display is on a single line with directory names separated | |
8076 | by spaces. | |
a0c0a00f | 8077 | Directories are added to the list with the |
726f6388 JA |
8078 | .B pushd |
8079 | command; the | |
8080 | .B popd | |
ccc6cda3 | 8081 | command removes entries from the list. |
a0c0a00f | 8082 | The current directory is always the first directory in the stack. |
726f6388 JA |
8083 | .RS |
8084 | .PD 0 | |
8085 | .TP | |
ccc6cda3 JA |
8086 | .B \-c |
8087 | Clears the directory stack by deleting all of the entries. | |
8088 | .TP | |
726f6388 | 8089 | .B \-l |
ac50fbac CR |
8090 | Produces a listing using full pathnames; |
8091 | the default listing format uses a tilde to denote the home directory. | |
ccc6cda3 JA |
8092 | .TP |
8093 | .B \-p | |
8094 | Print the directory stack with one entry per line. | |
8095 | .TP | |
8096 | .B \-v | |
8097 | Print the directory stack with one entry per line, | |
8098 | prefixing each entry with its index in the stack. | |
ac50fbac CR |
8099 | .TP |
8100 | \fB+\fP\fIn\fP | |
8101 | Displays the \fIn\fPth entry counting from the left of the list | |
8102 | shown by | |
8103 | .B dirs | |
8104 | when invoked without options, starting with zero. | |
8105 | .TP | |
8106 | \fB\-\fP\fIn\fP | |
8107 | Displays the \fIn\fPth entry counting from the right of the list | |
8108 | shown by | |
8109 | .B dirs | |
8110 | when invoked without options, starting with zero. | |
726f6388 JA |
8111 | .PD |
8112 | .PP | |
8113 | The return value is 0 unless an | |
cce855bc | 8114 | invalid option is supplied or \fIn\fP indexes beyond the end |
726f6388 JA |
8115 | of the directory stack. |
8116 | .RE | |
8117 | .TP | |
a0c0a00f | 8118 | \fBdisown\fP [\fB\-ar\fP] [\fB\-h\fP] [\fIjobspec\fP ... | \fIpid\fP ... ] |
ac50fbac | 8119 | Without options, remove each |
ccc6cda3 | 8120 | .I jobspec |
ac50fbac | 8121 | from the table of active jobs. |
3185942a JA |
8122 | If |
8123 | .I jobspec | |
ac50fbac CR |
8124 | is not present, and neither the \fB\-a\fP nor the \fB\-r\fP option |
8125 | is supplied, the \fIcurrent job\fP is used. | |
cce855bc JA |
8126 | If the \fB\-h\fP option is given, each |
8127 | .I jobspec | |
8128 | is not removed from the table, but is marked so that | |
ccc6cda3 JA |
8129 | .SM |
8130 | .B SIGHUP | |
8131 | is not sent to the job if the shell receives a | |
8132 | .SM | |
8133 | .BR SIGHUP . | |
8134 | If no | |
8135 | .I jobspec | |
cce855bc JA |
8136 | is supplied, the |
8137 | .B \-a | |
8138 | option means to remove or mark all jobs; the | |
8139 | .B \-r | |
8140 | option without a | |
8141 | .I jobspec | |
8142 | argument restricts operation to running jobs. | |
8143 | The return value is 0 unless a | |
ccc6cda3 JA |
8144 | .I jobspec |
8145 | does not specify a valid job. | |
8146 | .TP | |
726f6388 | 8147 | \fBecho\fP [\fB\-neE\fP] [\fIarg\fP ...] |
ccc6cda3 | 8148 | Output the \fIarg\fPs, separated by spaces, followed by a newline. |
ac50fbac | 8149 | The return status is 0 unless a write error occurs. |
ccc6cda3 | 8150 | If \fB\-n\fP is specified, the trailing newline is |
726f6388 JA |
8151 | suppressed. If the \fB\-e\fP option is given, interpretation of |
8152 | the following backslash-escaped characters is enabled. The | |
8153 | .B \-E | |
8154 | option disables the interpretation of these escape characters, | |
8155 | even on systems where they are interpreted by default. | |
28ef6c31 | 8156 | The \fBxpg_echo\fP shell option may be used to |
bb70624e JA |
8157 | dynamically determine whether or not \fBecho\fP expands these |
8158 | escape characters by default. | |
ccc6cda3 | 8159 | .B echo |
95732b49 | 8160 | does not interpret \fB\-\-\fP to mean the end of options. |
ccc6cda3 JA |
8161 | .B echo |
8162 | interprets the following escape sequences: | |
726f6388 JA |
8163 | .RS |
8164 | .PD 0 | |
8165 | .TP | |
8166 | .B \ea | |
8167 | alert (bell) | |
8168 | .TP | |
8169 | .B \eb | |
8170 | backspace | |
8171 | .TP | |
8172 | .B \ec | |
3185942a | 8173 | suppress further output |
726f6388 | 8174 | .TP |
ccc6cda3 | 8175 | .B \ee |
495aee44 CR |
8176 | .TP |
8177 | .B \eE | |
ccc6cda3 JA |
8178 | an escape character |
8179 | .TP | |
726f6388 JA |
8180 | .B \ef |
8181 | form feed | |
8182 | .TP | |
8183 | .B \en | |
8184 | new line | |
8185 | .TP | |
8186 | .B \er | |
8187 | carriage return | |
8188 | .TP | |
8189 | .B \et | |
8190 | horizontal tab | |
8191 | .TP | |
8192 | .B \ev | |
8193 | vertical tab | |
8194 | .TP | |
8195 | .B \e\e | |
8196 | backslash | |
8197 | .TP | |
7117c2d2 JA |
8198 | .B \e0\fInnn\fP |
8199 | the eight-bit character whose value is the octal value \fInnn\fP | |
8200 | (zero to three octal digits) | |
8201 | .TP | |
f73dda09 JA |
8202 | .B \ex\fIHH\fP |
8203 | the eight-bit character whose value is the hexadecimal value \fIHH\fP | |
8204 | (one or two hex digits) | |
495aee44 CR |
8205 | .TP |
8206 | .B \eu\fIHHHH\fP | |
8207 | the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value | |
8208 | \fIHHHH\fP (one to four hex digits) | |
8209 | .TP | |
8210 | .B \eU\fIHHHHHHHH\fP | |
8211 | the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value | |
8212 | \fIHHHHHHHH\fP (one to eight hex digits) | |
726f6388 JA |
8213 | .PD |
8214 | .RE | |
8215 | .TP | |
3185942a | 8216 | \fBenable\fP [\fB\-a\fP] [\fB\-dnps\fP] [\fB\-f\fP \fIfilename\fP] [\fIname\fP ...] |
cce855bc JA |
8217 | Enable and disable builtin shell commands. |
8218 | Disabling a builtin allows a disk command which has the same name | |
bb70624e | 8219 | as a shell builtin to be executed without specifying a full pathname, |
cce855bc | 8220 | even though the shell normally searches for builtins before disk commands. |
726f6388 JA |
8221 | If \fB\-n\fP is used, each \fIname\fP |
8222 | is disabled; otherwise, | |
8223 | \fInames\fP are enabled. For example, to use the | |
8224 | .B test | |
8225 | binary found via the | |
8226 | .SM | |
8227 | .B PATH | |
ccc6cda3 | 8228 | instead of the shell builtin version, run |
28ef6c31 JA |
8229 | .if t \f(CWenable -n test\fP. |
8230 | .if n ``enable -n test''. | |
ccc6cda3 JA |
8231 | The |
8232 | .B \-f | |
8233 | option means to load the new builtin command | |
8234 | .I name | |
8235 | from shared object | |
8236 | .IR filename , | |
8237 | on systems that support dynamic loading. The | |
8238 | .B \-d | |
8239 | option will delete a builtin previously loaded with | |
8240 | .BR \-f . | |
8241 | If no \fIname\fP arguments are given, or if the | |
8242 | .B \-p | |
8243 | option is supplied, a list of shell builtins is printed. | |
8244 | With no other option arguments, the list consists of all enabled | |
8245 | shell builtins. | |
8246 | If \fB\-n\fP is supplied, only disabled builtins are printed. | |
8247 | If \fB\-a\fP is supplied, the list printed includes all builtins, with an | |
726f6388 | 8248 | indication of whether or not each is enabled. |
ccc6cda3 JA |
8249 | If \fB\-s\fP is supplied, the output is restricted to the POSIX |
8250 | \fIspecial\fP builtins. | |
726f6388 JA |
8251 | The return value is 0 unless a |
8252 | .I name | |
bb70624e | 8253 | is not a shell builtin or there is an error loading a new builtin |
ccc6cda3 | 8254 | from a shared object. |
726f6388 JA |
8255 | .TP |
8256 | \fBeval\fP [\fIarg\fP ...] | |
8257 | The \fIarg\fPs are read and concatenated together into a single | |
8258 | command. This command is then read and executed by the shell, and | |
ccc6cda3 JA |
8259 | its exit status is returned as the value of |
8260 | .BR eval . | |
8261 | If there are no | |
726f6388 JA |
8262 | .IR args , |
8263 | or only null arguments, | |
8264 | .B eval | |
ccc6cda3 | 8265 | returns 0. |
726f6388 | 8266 | .TP |
cce855bc | 8267 | \fBexec\fP [\fB\-cl\fP] [\fB\-a\fP \fIname\fP] [\fIcommand\fP [\fIarguments\fP]] |
726f6388 JA |
8268 | If |
8269 | .I command | |
8270 | is specified, it replaces the shell. | |
8271 | No new process is created. The | |
8272 | .I arguments | |
8273 | become the arguments to \fIcommand\fP. | |
ccc6cda3 JA |
8274 | If the |
8275 | .B \-l | |
8276 | option is supplied, | |
a0c0a00f | 8277 | the shell places a dash at the beginning of the zeroth argument passed to |
726f6388 | 8278 | .IR command . |
ccc6cda3 JA |
8279 | This is what |
8280 | .IR login (1) | |
8281 | does. The | |
8282 | .B \-c | |
8283 | option causes | |
8284 | .I command | |
8285 | to be executed with an empty environment. If | |
8286 | .B \-a | |
8287 | is supplied, the shell passes | |
8288 | .I name | |
ac50fbac CR |
8289 | as the zeroth argument to the executed command. |
8290 | If | |
ccc6cda3 | 8291 | .I command |
726f6388 | 8292 | cannot be executed for some reason, a non-interactive shell exits, |
ac50fbac | 8293 | unless the |
ccc6cda3 | 8294 | .B execfail |
ac50fbac CR |
8295 | shell option |
8296 | is enabled. In that case, it returns failure. | |
ccc6cda3 | 8297 | An interactive shell returns failure if the file cannot be executed. |
9a51695b | 8298 | A subshell exits unconditionally if \fBexec\fP fails. |
726f6388 JA |
8299 | If |
8300 | .I command | |
8301 | is not specified, any redirections take effect in the current shell, | |
cce855bc JA |
8302 | and the return status is 0. If there is a redirection error, the |
8303 | return status is 1. | |
726f6388 JA |
8304 | .TP |
8305 | \fBexit\fP [\fIn\fP] | |
8306 | Cause the shell to exit | |
8307 | with a status of \fIn\fP. If | |
8308 | .I n | |
8309 | is omitted, the exit status | |
8310 | is that of the last command executed. | |
8311 | A trap on | |
8312 | .SM | |
8313 | .B EXIT | |
8314 | is executed before the shell terminates. | |
8315 | .TP | |
ccc6cda3 | 8316 | \fBexport\fP [\fB\-fn\fP\^] [\fIname\fP[=\fIword\fP]] ... |
7117c2d2 | 8317 | .PD 0 |
726f6388 JA |
8318 | .TP |
8319 | .B export \-p | |
8320 | .PD | |
8321 | The supplied | |
8322 | .I names | |
8323 | are marked for automatic export to the environment of | |
a0c0a00f | 8324 | subsequently executed commands. If the |
726f6388 | 8325 | .B \-f |
a0c0a00f | 8326 | option is given, the |
726f6388 JA |
8327 | .I names |
8328 | refer to functions. | |
8329 | If no | |
8330 | .I names | |
8331 | are given, or if the | |
8332 | .B \-p | |
8333 | option is supplied, a list | |
ac50fbac | 8334 | of names of all exported variables is printed. |
726f6388 JA |
8335 | The |
8336 | .B \-n | |
b80f6443 JA |
8337 | option causes the export property to be removed from each |
8338 | \fIname\fP. | |
8339 | If a variable name is followed by =\fIword\fP, the value of | |
8340 | the variable is set to \fIword\fP. | |
726f6388 | 8341 | .B export |
cce855bc | 8342 | returns an exit status of 0 unless an invalid option is |
726f6388 | 8343 | encountered, |
cce855bc | 8344 | one of the \fInames\fP is not a valid shell variable name, or |
726f6388 JA |
8345 | .B \-f |
8346 | is supplied with a | |
8347 | .I name | |
8348 | that is not a function. | |
8349 | .TP | |
3185942a | 8350 | \fBfc\fP [\fB\-e\fP \fIename\fP] [\fB\-lnr\fP] [\fIfirst\fP] [\fIlast\fP] |
7117c2d2 | 8351 | .PD 0 |
726f6388 JA |
8352 | .TP |
8353 | \fBfc\fP \fB\-s\fP [\fIpat\fP=\fIrep\fP] [\fIcmd\fP] | |
8354 | .PD | |
ac50fbac | 8355 | The first form selects a range of commands from |
726f6388 JA |
8356 | .I first |
8357 | to | |
8358 | .I last | |
ac50fbac | 8359 | from the history list and displays or edits and re-executes them. |
726f6388 JA |
8360 | .I First |
8361 | and | |
8362 | .I last | |
8363 | may be specified as a string (to locate the last command beginning | |
8364 | with that string) or as a number (an index into the history list, | |
8365 | where a negative number is used as an offset from the current | |
a0c0a00f | 8366 | command number). If |
726f6388 | 8367 | .I last |
9a51695b | 8368 | is not specified, it is set to |
726f6388 | 8369 | the current command for listing (so that |
bb70624e JA |
8370 | .if n ``fc \-l \-10'' |
8371 | .if t \f(CWfc \-l \-10\fP | |
726f6388 JA |
8372 | prints the last 10 commands) and to |
8373 | .I first | |
8374 | otherwise. | |
8375 | If | |
8376 | .I first | |
9a51695b | 8377 | is not specified, it is set to the previous |
726f6388 JA |
8378 | command for editing and \-16 for listing. |
8379 | .sp 1 | |
8380 | The | |
8381 | .B \-n | |
cce855bc | 8382 | option suppresses |
726f6388 JA |
8383 | the command numbers when listing. The |
8384 | .B \-r | |
cce855bc | 8385 | option reverses the order of |
726f6388 JA |
8386 | the commands. If the |
8387 | .B \-l | |
cce855bc | 8388 | option is given, |
726f6388 JA |
8389 | the commands are listed on |
8390 | standard output. Otherwise, the editor given by | |
8391 | .I ename | |
8392 | is invoked | |
8393 | on a file containing those commands. If | |
8394 | .I ename | |
8395 | is not given, the | |
8396 | value of the | |
8397 | .SM | |
8398 | .B FCEDIT | |
8399 | variable is used, and | |
8400 | the value of | |
8401 | .SM | |
8402 | .B EDITOR | |
8403 | if | |
8404 | .SM | |
8405 | .B FCEDIT | |
8406 | is not set. If neither variable is set, | |
8407 | .FN vi | |
8408 | is used. When editing is complete, the edited commands are | |
8409 | echoed and executed. | |
8410 | .sp 1 | |
8411 | In the second form, \fIcommand\fP is re-executed after each instance | |
8412 | of \fIpat\fP is replaced by \fIrep\fP. | |
9a51695b | 8413 | \fICommand\fP is interpreted the same as \fIfirst\fP above. |
ccc6cda3 | 8414 | A useful alias to use with this is |
b80f6443 | 8415 | .if n ``r="fc -s"'', |
ccc6cda3 JA |
8416 | .if t \f(CWr='fc \-s'\fP, |
8417 | so that typing | |
8418 | .if n ``r cc'' | |
8419 | .if t \f(CWr cc\fP | |
8420 | runs the last command beginning with | |
8421 | .if n ``cc'' | |
8422 | .if t \f(CWcc\fP | |
8423 | and typing | |
8424 | .if n ``r'' | |
8425 | .if t \f(CWr\fP | |
726f6388 JA |
8426 | re-executes the last command. |
8427 | .sp 1 | |
cce855bc | 8428 | If the first form is used, the return value is 0 unless an invalid |
726f6388 JA |
8429 | option is encountered or |
8430 | .I first | |
8431 | or | |
8432 | .I last | |
8433 | specify history lines out of range. | |
8434 | If the | |
8435 | .B \-e | |
8436 | option is supplied, the return value is the value of the last | |
8437 | command executed or failure if an error occurs with the temporary | |
8438 | file of commands. If the second form is used, the return status | |
8439 | is that of the command re-executed, unless | |
8440 | .I cmd | |
8441 | does not specify a valid history line, in which case | |
8442 | .B fc | |
8443 | returns failure. | |
8444 | .TP | |
8445 | \fBfg\fP [\fIjobspec\fP] | |
cce855bc | 8446 | Resume |
726f6388 | 8447 | .I jobspec |
cce855bc JA |
8448 | in the foreground, and make it the current job. |
8449 | If | |
726f6388 JA |
8450 | .I jobspec |
8451 | is not present, the shell's notion of the \fIcurrent job\fP is used. | |
8452 | The return value is that of the command placed into the foreground, | |
8453 | or failure if run when job control is disabled or, when run with | |
8454 | job control enabled, if | |
8455 | .I jobspec | |
8456 | does not specify a valid job or | |
8457 | .I jobspec | |
8458 | specifies a job that was started without job control. | |
8459 | .TP | |
8460 | \fBgetopts\fP \fIoptstring\fP \fIname\fP [\fIargs\fP] | |
8461 | .B getopts | |
8462 | is used by shell procedures to parse positional parameters. | |
8463 | .I optstring | |
bb70624e | 8464 | contains the option characters to be recognized; if a character |
726f6388 JA |
8465 | is followed by a colon, the option is expected to have an |
8466 | argument, which should be separated from it by white space. | |
bb70624e JA |
8467 | The colon and question mark characters may not be used as |
8468 | option characters. | |
726f6388 JA |
8469 | Each time it is invoked, |
8470 | .B getopts | |
8471 | places the next option in the shell variable | |
8472 | .IR name , | |
8473 | initializing | |
8474 | .I name | |
8475 | if it does not exist, | |
8476 | and the index of the next argument to be processed into the | |
8477 | variable | |
8478 | .SM | |
8479 | .BR OPTIND . | |
8480 | .SM | |
8481 | .B OPTIND | |
8482 | is initialized to 1 each time the shell or a shell script | |
8483 | is invoked. When an option requires an argument, | |
8484 | .B getopts | |
8485 | places that argument into the variable | |
8486 | .SM | |
8487 | .BR OPTARG . | |
8488 | The shell does not reset | |
8489 | .SM | |
8490 | .B OPTIND | |
8491 | automatically; it must be manually reset between multiple | |
8492 | calls to | |
8493 | .B getopts | |
8494 | within the same shell invocation if a new set of parameters | |
8495 | is to be used. | |
8496 | .sp 1 | |
cce855bc JA |
8497 | When the end of options is encountered, \fBgetopts\fP exits with a |
8498 | return value greater than zero. | |
0001803f CR |
8499 | .SM |
8500 | .B OPTIND | |
8501 | is set to the index of the first non-option argument, | |
495aee44 | 8502 | and \fIname\fP is set to ?. |
cce855bc JA |
8503 | .sp 1 |
8504 | .B getopts | |
8505 | normally parses the positional parameters, but if more arguments are | |
8506 | given in | |
8507 | .IR args , | |
8508 | .B getopts | |
8509 | parses those instead. | |
8510 | .sp 1 | |
726f6388 JA |
8511 | .B getopts |
8512 | can report errors in two ways. If the first character of | |
8513 | .I optstring | |
8514 | is a colon, | |
8515 | .I silent | |
ac50fbac | 8516 | error reporting is used. In normal operation, diagnostic messages |
cce855bc | 8517 | are printed when invalid options or missing option arguments are |
726f6388 JA |
8518 | encountered. |
8519 | If the variable | |
8520 | .SM | |
8521 | .B OPTERR | |
cce855bc | 8522 | is set to 0, no error messages will be displayed, even if the first |
a0c0a00f | 8523 | character of |
726f6388 JA |
8524 | .I optstring |
8525 | is not a colon. | |
8526 | .sp 1 | |
cce855bc | 8527 | If an invalid option is seen, |
726f6388 JA |
8528 | .B getopts |
8529 | places ? into | |
8530 | .I name | |
8531 | and, if not silent, | |
8532 | prints an error message and unsets | |
8533 | .SM | |
8534 | .BR OPTARG . | |
8535 | If | |
8536 | .B getopts | |
8537 | is silent, | |
8538 | the option character found is placed in | |
8539 | .SM | |
8540 | .B OPTARG | |
8541 | and no diagnostic message is printed. | |
8542 | .sp 1 | |
8543 | If a required argument is not found, and | |
8544 | .B getopts | |
8545 | is not silent, | |
8546 | a question mark (\^\fB?\fP\^) is placed in | |
8547 | .IR name , | |
f73dda09 | 8548 | .SM |
726f6388 JA |
8549 | .B OPTARG |
8550 | is unset, and a diagnostic message is printed. | |
8551 | If | |
8552 | .B getopts | |
8553 | is silent, then a colon (\^\fB:\fP\^) is placed in | |
8554 | .I name | |
8555 | and | |
8556 | .SM | |
8557 | .B OPTARG | |
8558 | is set to the option character found. | |
8559 | .sp 1 | |
8560 | .B getopts | |
726f6388 JA |
8561 | returns true if an option, specified or unspecified, is found. |
8562 | It returns false if the end of options is encountered or an | |
8563 | error occurs. | |
8564 | .TP | |
7117c2d2 | 8565 | \fBhash\fP [\fB\-lr\fP] [\fB\-p\fP \fIfilename\fP] [\fB\-dt\fP] [\fIname\fP] |
495aee44 | 8566 | Each time \fBhash\fP is invoked, |
a0c0a00f | 8567 | the full pathname of the command |
495aee44 CR |
8568 | .I name |
8569 | is determined by searching | |
ccc6cda3 JA |
8570 | the directories in |
8571 | .B $PATH | |
495aee44 | 8572 | and remembered. Any previously-remembered pathname is discarded. |
ccc6cda3 JA |
8573 | If the |
8574 | .B \-p | |
8575 | option is supplied, no path search is performed, and | |
8576 | .I filename | |
ac50fbac | 8577 | is used as the full filename of the command. |
ccc6cda3 | 8578 | The |
726f6388 JA |
8579 | .B \-r |
8580 | option causes the shell to forget all | |
f73dda09 | 8581 | remembered locations. |
7117c2d2 JA |
8582 | The |
8583 | .B \-d | |
8584 | option causes the shell to forget the remembered location of each \fIname\fP. | |
f73dda09 JA |
8585 | If the |
8586 | .B \-t | |
8587 | option is supplied, the full pathname to which each \fIname\fP corresponds | |
8588 | is printed. If multiple \fIname\fP arguments are supplied with \fB\-t\fP, | |
8589 | the \fIname\fP is printed before the hashed full pathname. | |
7117c2d2 JA |
8590 | The |
8591 | .B \-l | |
8592 | option causes output to be displayed in a format that may be reused as input. | |
8593 | If no arguments are given, or if only \fB\-l\fP is supplied, | |
8594 | information about remembered commands is printed. | |
ccc6cda3 | 8595 | The return status is true unless a |
726f6388 | 8596 | .I name |
cce855bc | 8597 | is not found or an invalid option is supplied. |
726f6388 | 8598 | .TP |
3185942a | 8599 | \fBhelp\fP [\fB\-dms\fP] [\fIpattern\fP] |
726f6388 JA |
8600 | Display helpful information about builtin commands. If |
8601 | .I pattern | |
8602 | is specified, | |
8603 | .B help | |
8604 | gives detailed help on all commands matching | |
8605 | .IR pattern ; | |
ccc6cda3 | 8606 | otherwise help for all the builtins and shell control structures |
bb70624e | 8607 | is printed. |
3185942a JA |
8608 | .RS |
8609 | .PD 0 | |
8610 | .TP | |
8611 | .B \-d | |
8612 | Display a short description of each \fIpattern\fP | |
8613 | .TP | |
0001803f | 8614 | .B \-m |
3185942a JA |
8615 | Display the description of each \fIpattern\fP in a manpage-like format |
8616 | .TP | |
8617 | .B \-s | |
8618 | Display only a short usage synopsis for each \fIpattern\fP | |
8619 | .PD | |
495aee44 | 8620 | .PP |
bb70624e | 8621 | The return status is 0 unless no command matches |
726f6388 | 8622 | .IR pattern . |
495aee44 | 8623 | .RE |
726f6388 | 8624 | .TP |
bb70624e | 8625 | \fBhistory [\fIn\fP] |
7117c2d2 | 8626 | .PD 0 |
bb70624e JA |
8627 | .TP |
8628 | \fBhistory\fP \fB\-c\fP | |
8629 | .TP | |
8630 | \fBhistory \-d\fP \fIoffset\fP | |
ccc6cda3 | 8631 | .TP |
9a51695b CR |
8632 | \fBhistory \-d\fP \fIstart\fP\-\fIend\fP |
8633 | .TP | |
ccc6cda3 | 8634 | \fBhistory\fP \fB\-anrw\fP [\fIfilename\fP] |
726f6388 | 8635 | .TP |
ccc6cda3 JA |
8636 | \fBhistory\fP \fB\-p\fP \fIarg\fP [\fIarg ...\fP] |
8637 | .TP | |
8638 | \fBhistory\fP \fB\-s\fP \fIarg\fP [\fIarg ...\fP] | |
726f6388 JA |
8639 | .PD |
8640 | With no options, display the command | |
8641 | history list with line numbers. Lines listed | |
a0c0a00f | 8642 | with a |
726f6388 JA |
8643 | .B * |
8644 | have been modified. An argument of | |
8645 | .I n | |
8646 | lists only the last | |
8647 | .I n | |
b80f6443 | 8648 | lines. |
0001803f CR |
8649 | If the shell variable |
8650 | .SM | |
8651 | .B HISTTIMEFORMAT | |
8652 | is set and not null, | |
b80f6443 JA |
8653 | it is used as a format string for \fIstrftime\fP(3) to display |
8654 | the time stamp associated with each displayed history entry. | |
8655 | No intervening blank is printed between the formatted time stamp | |
8656 | and the history line. | |
8657 | If \fIfilename\fP is supplied, it is used as the | |
726f6388 JA |
8658 | name of the history file; if not, the value of |
8659 | .SM | |
8660 | .B HISTFILE | |
8661 | is used. Options, if supplied, have the following meanings: | |
8662 | .RS | |
8663 | .PD 0 | |
8664 | .TP | |
bb70624e JA |
8665 | .B \-c |
8666 | Clear the history list by deleting all the entries. | |
8667 | .TP | |
8668 | \fB\-d\fP \fIoffset\fP | |
8669 | Delete the history entry at position \fIoffset\fP. | |
9a51695b CR |
8670 | If \fIoffset\fP is negative, it is interpreted as relative to one greater |
8671 | than the last history position, so negative indices count back from the | |
8672 | end of the history, and an index of \-1 refers to the current | |
8673 | \fBhistory -d\fP command. | |
8674 | .TP | |
8675 | \fB\-d\fP \fIstart\fP\-\fIend\fP | |
8676 | Delete the history entries between positions \fIstart\fP and \fIend\fP, | |
8677 | inclusive. Positive and negative values for \fIstart\fP and \fIend\fP | |
8678 | are interpreted as described above. | |
bb70624e | 8679 | .TP |
726f6388 | 8680 | .B \-a |
a0c0a00f CR |
8681 | Append the ``new'' history lines to the history file. |
8682 | These are history lines entered since the beginning of the current | |
8683 | \fBbash\fP session, but not already appended to the history file. | |
726f6388 JA |
8684 | .TP |
8685 | .B \-n | |
8686 | Read the history lines not already read from the history | |
8687 | file into the current history list. These are lines | |
8688 | appended to the history file since the beginning of the | |
8689 | current \fBbash\fP session. | |
8690 | .TP | |
8691 | .B \-r | |
8692 | Read the contents of the history file | |
ac50fbac | 8693 | and append them to the current history list. |
726f6388 JA |
8694 | .TP |
8695 | .B \-w | |
ac50fbac | 8696 | Write the current history list to the history file, overwriting the |
726f6388 | 8697 | history file's contents. |
ccc6cda3 | 8698 | .TP |
ccc6cda3 JA |
8699 | .B \-p |
8700 | Perform history substitution on the following \fIargs\fP and display | |
8701 | the result on the standard output. | |
8702 | Does not store the results in the history list. | |
8703 | Each \fIarg\fP must be quoted to disable normal history expansion. | |
8704 | .TP | |
8705 | .B \-s | |
8706 | Store the | |
8707 | .I args | |
8708 | in the history list as a single entry. The last command in the | |
8709 | history list is removed before the | |
8710 | .I args | |
8711 | are added. | |
726f6388 JA |
8712 | .PD |
8713 | .PP | |
0001803f CR |
8714 | If the |
8715 | .SM | |
8716 | .B HISTTIMEFORMAT | |
8717 | variable is set, the time stamp information | |
3185942a JA |
8718 | associated with each history entry is written to the history file, |
8719 | marked with the history comment character. | |
8720 | When the history file is read, lines beginning with the history | |
8721 | comment character followed immediately by a digit are interpreted | |
a0c0a00f | 8722 | as timestamps for the following history entry. |
bb70624e JA |
8723 | The return value is 0 unless an invalid option is encountered, an |
8724 | error occurs while reading or writing the history file, an invalid | |
8725 | \fIoffset\fP is supplied as an argument to \fB\-d\fP, or the | |
8726 | history expansion supplied as an argument to \fB\-p\fP fails. | |
726f6388 JA |
8727 | .RE |
8728 | .TP | |
ccc6cda3 | 8729 | \fBjobs\fP [\fB\-lnprs\fP] [ \fIjobspec\fP ... ] |
7117c2d2 | 8730 | .PD 0 |
726f6388 JA |
8731 | .TP |
8732 | \fBjobs\fP \fB\-x\fP \fIcommand\fP [ \fIargs\fP ... ] | |
8733 | .PD | |
ccc6cda3 JA |
8734 | The first form lists the active jobs. The options have the following |
8735 | meanings: | |
8736 | .RS | |
8737 | .PD 0 | |
8738 | .TP | |
726f6388 | 8739 | .B \-l |
ccc6cda3 JA |
8740 | List process IDs |
8741 | in addition to the normal information. | |
8742 | .TP | |
726f6388 | 8743 | .B \-n |
ccc6cda3 JA |
8744 | Display information only about jobs that have changed status since |
8745 | the user was last notified of their status. | |
8746 | .TP | |
495aee44 CR |
8747 | .B \-p |
8748 | List only the process ID of the job's process group | |
8749 | leader. | |
8750 | .TP | |
ccc6cda3 | 8751 | .B \-r |
ac50fbac | 8752 | Display only running jobs. |
ccc6cda3 JA |
8753 | .TP |
8754 | .B \-s | |
ac50fbac | 8755 | Display only stopped jobs. |
ccc6cda3 JA |
8756 | .PD |
8757 | .PP | |
8758 | If | |
726f6388 JA |
8759 | .I jobspec |
8760 | is given, output is restricted to information about that job. | |
cce855bc JA |
8761 | The return status is 0 unless an invalid option is encountered |
8762 | or an invalid | |
726f6388 JA |
8763 | .I jobspec |
8764 | is supplied. | |
ccc6cda3 | 8765 | .PP |
726f6388 JA |
8766 | If the |
8767 | .B \-x | |
8768 | option is supplied, | |
8769 | .B jobs | |
8770 | replaces any | |
8771 | .I jobspec | |
8772 | found in | |
8773 | .I command | |
8774 | or | |
8775 | .I args | |
8776 | with the corresponding process group ID, and executes | |
8777 | .I command | |
8778 | passing it | |
8779 | .IR args , | |
8780 | returning its exit status. | |
ccc6cda3 | 8781 | .RE |
726f6388 | 8782 | .TP |
ccc6cda3 | 8783 | \fBkill\fP [\fB\-s\fP \fIsigspec\fP | \fB\-n\fP \fIsignum\fP | \fB\-\fP\fIsigspec\fP] [\fIpid\fP | \fIjobspec\fP] ... |
7117c2d2 | 8784 | .PD 0 |
726f6388 | 8785 | .TP |
a0c0a00f | 8786 | \fBkill\fP \fB\-l\fP|\fB\-L\fP [\fIsigspec\fP | \fIexit_status\fP] |
726f6388 JA |
8787 | .PD |
8788 | Send the signal named by | |
8789 | .I sigspec | |
ccc6cda3 JA |
8790 | or |
8791 | .I signum | |
726f6388 JA |
8792 | to the processes named by |
8793 | .I pid | |
8794 | or | |
8795 | .IR jobspec . | |
8796 | .I sigspec | |
b80f6443 | 8797 | is either a case-insensitive signal name such as |
726f6388 JA |
8798 | .SM |
8799 | .B SIGKILL | |
b80f6443 | 8800 | (with or without the |
726f6388 JA |
8801 | .SM |
8802 | .B SIG | |
b80f6443 JA |
8803 | prefix) or a signal number; |
8804 | .I signum | |
8805 | is a signal number. | |
726f6388 JA |
8806 | If |
8807 | .I sigspec | |
8808 | is not present, then | |
8809 | .SM | |
8810 | .B SIGTERM | |
cce855bc JA |
8811 | is assumed. |
8812 | An argument of | |
726f6388 | 8813 | .B \-l |
cce855bc JA |
8814 | lists the signal names. |
8815 | If any arguments are supplied when | |
726f6388 | 8816 | .B \-l |
cce855bc JA |
8817 | is given, the names of the signals corresponding to the arguments are |
8818 | listed, and the return status is 0. | |
8819 | The \fIexit_status\fP argument to | |
ccc6cda3 | 8820 | .B \-l |
cce855bc JA |
8821 | is a number specifying either a signal number or the exit status of |
8822 | a process terminated by a signal. | |
a0c0a00f CR |
8823 | The |
8824 | .B \-L | |
8825 | option is equivalent to \fB\-l\fP. | |
726f6388 JA |
8826 | .B kill |
8827 | returns true if at least one signal was successfully sent, or false | |
cce855bc | 8828 | if an error occurs or an invalid option is encountered. |
726f6388 JA |
8829 | .TP |
8830 | \fBlet\fP \fIarg\fP [\fIarg\fP ...] | |
8831 | Each | |
8832 | .I arg | |
8833 | is an arithmetic expression to be evaluated (see | |
8834 | .SM | |
0001803f CR |
8835 | .B "ARITHMETIC EVALUATION" |
8836 | above). | |
726f6388 JA |
8837 | If the last |
8838 | .I arg | |
8839 | evaluates to 0, | |
8840 | .B let | |
8841 | returns 1; 0 is returned otherwise. | |
8842 | .TP | |
a0c0a00f | 8843 | \fBlocal\fP [\fIoption\fP] [\fIname\fP[=\fIvalue\fP] ... | \- ] |
cce855bc | 8844 | For each argument, a local variable named |
a0c0a00f | 8845 | .I name |
cce855bc | 8846 | is created, and assigned |
726f6388 | 8847 | .IR value . |
bb70624e | 8848 | The \fIoption\fP can be any of the options accepted by \fBdeclare\fP. |
726f6388 JA |
8849 | When |
8850 | .B local | |
8851 | is used within a function, it causes the variable | |
8852 | .I name | |
8853 | to have a visible scope restricted to that function and its children. | |
a0c0a00f CR |
8854 | If \fIname\fP is \-, the set of shell options is made local to the function |
8855 | in which \fBlocal\fP is invoked: shell options changed using the | |
8856 | \fBset\fP builtin inside the function are restored to their original values | |
8857 | when the function returns. | |
726f6388 JA |
8858 | With no operands, |
8859 | .B local | |
8860 | writes a list of local variables to the standard output. It is | |
8861 | an error to use | |
8862 | .B local | |
8863 | when not within a function. The return status is 0 unless | |
8864 | .B local | |
bb70624e | 8865 | is used outside a function, an invalid |
726f6388 | 8866 | .I name |
bb70624e JA |
8867 | is supplied, or |
8868 | \fIname\fP is a readonly variable. | |
726f6388 JA |
8869 | .TP |
8870 | .B logout | |
8871 | Exit a login shell. | |
8872 | .TP | |
a0c0a00f | 8873 | \fBmapfile\fP [\fB\-d\fP \fIdelim\fP] [\fB\-n\fP \fIcount\fP] [\fB\-O\fP \fIorigin\fP] [\fB\-s\fP \fIcount\fP] [\fB\-t\fP] [\fB\-u\fP \fIfd\fP] [\fB\-C\fP \fIcallback\fP] [\fB\-c\fP \fIquantum\fP] [\fIarray\fP] |
17345e5a JA |
8874 | .PD 0 |
8875 | .TP | |
a0c0a00f | 8876 | \fBreadarray\fP [\fB\-d\fP \fIdelim\fP] [\fB\-n\fP \fIcount\fP] [\fB\-O\fP \fIorigin\fP] [\fB\-s\fP \fIcount\fP] [\fB\-t\fP] [\fB\-u\fP \fIfd\fP] [\fB\-C\fP \fIcallback\fP] [\fB\-c\fP \fIquantum\fP] [\fIarray\fP] |
17345e5a | 8877 | .PD |
0001803f | 8878 | Read lines from the standard input into the indexed array variable |
3185942a | 8879 | .IR array , |
a0c0a00f | 8880 | or from file descriptor |
9a51695b | 8881 | .I fd |
a0c0a00f | 8882 | if the |
3185942a JA |
8883 | .B \-u |
8884 | option is supplied. | |
0001803f CR |
8885 | The variable |
8886 | .SM | |
8887 | .B MAPFILE | |
8888 | is the default \fIarray\fP. | |
3185942a JA |
8889 | Options, if supplied, have the following meanings: |
8890 | .RS | |
8891 | .PD 0 | |
8892 | .TP | |
a0c0a00f CR |
8893 | .B \-d |
8894 | The first character of \fIdelim\fP is used to terminate each input line, | |
8895 | rather than newline. | |
9a51695b CR |
8896 | If \fIdelim\fP is the empty string, \fBmapfile\fP will terminate a line |
8897 | when it reads a NUL character. | |
a0c0a00f | 8898 | .TP |
3185942a JA |
8899 | .B \-n |
8900 | Copy at most | |
8901 | .I count | |
8902 | lines. If \fIcount\fP is 0, all lines are copied. | |
8903 | .TP | |
8904 | .B \-O | |
8905 | Begin assigning to | |
8906 | .I array | |
8907 | at index | |
8908 | .IR origin . | |
8909 | The default index is 0. | |
8910 | .TP | |
8911 | .B \-s | |
8912 | Discard the first \fIcount\fP lines read. | |
8913 | .TP | |
8914 | .B \-t | |
a0c0a00f | 8915 | Remove a trailing \fIdelim\fP (default newline) from each line read. |
3185942a JA |
8916 | .TP |
8917 | .B \-u | |
8918 | Read lines from file descriptor \fIfd\fP instead of the standard input. | |
8919 | .TP | |
8920 | .B \-C | |
8921 | Evaluate | |
8922 | .I callback | |
8923 | each time \fIquantum\fP lines are read. The \fB\-c\fP option specifies | |
8924 | .IR quantum . | |
8925 | .TP | |
8926 | .B \-c | |
8927 | Specify the number of lines read between each call to | |
8928 | .IR callback . | |
8929 | .PD | |
8930 | .PP | |
8931 | If | |
8932 | .B \-C | |
a0c0a00f | 8933 | is specified without |
3185942a JA |
8934 | .BR \-c , |
8935 | the default quantum is 5000. | |
17345e5a | 8936 | When \fIcallback\fP is evaluated, it is supplied the index of the next |
495aee44 CR |
8937 | array element to be assigned and the line to be assigned to that element |
8938 | as additional arguments. | |
a0c0a00f | 8939 | \fIcallback\fP is evaluated after the line is read but before the |
17345e5a | 8940 | array element is assigned. |
3185942a JA |
8941 | .PP |
8942 | If not supplied with an explicit origin, \fBmapfile\fP will clear \fIarray\fP | |
8943 | before assigning to it. | |
8944 | .PP | |
8945 | \fBmapfile\fP returns successfully unless an invalid option or option | |
0001803f CR |
8946 | argument is supplied, \fIarray\fP is invalid or unassignable, or if |
8947 | \fIarray\fP is not an indexed array. | |
3185942a JA |
8948 | .RE |
8949 | .TP | |
ccc6cda3 | 8950 | \fBpopd\fP [\-\fBn\fP] [+\fIn\fP] [\-\fIn\fP] |
726f6388 JA |
8951 | Removes entries from the directory stack. With no arguments, |
8952 | removes the top directory from the stack, and performs a | |
8953 | .B cd | |
8954 | to the new top directory. | |
ccc6cda3 | 8955 | Arguments, if supplied, have the following meanings: |
726f6388 JA |
8956 | .RS |
8957 | .PD 0 | |
8958 | .TP | |
3185942a JA |
8959 | .B \-n |
8960 | Suppresses the normal change of directory when removing directories | |
8961 | from the stack, so that only the stack is manipulated. | |
8962 | .TP | |
ccc6cda3 JA |
8963 | \fB+\fP\fIn\fP |
8964 | Removes the \fIn\fPth entry counting from the left of the list | |
726f6388 JA |
8965 | shown by |
8966 | .BR dirs , | |
bb70624e JA |
8967 | starting with zero. For example: |
8968 | .if n ``popd +0'' | |
8969 | .if t \f(CWpopd +0\fP | |
8970 | removes the first directory, | |
8971 | .if n ``popd +1'' | |
8972 | .if t \f(CWpopd +1\fP | |
8973 | the second. | |
726f6388 | 8974 | .TP |
ccc6cda3 JA |
8975 | \fB\-\fP\fIn\fP |
8976 | Removes the \fIn\fPth entry counting from the right of the list | |
726f6388 JA |
8977 | shown by |
8978 | .BR dirs , | |
bb70624e JA |
8979 | starting with zero. For example: |
8980 | .if n ``popd -0'' | |
8981 | .if t \f(CWpopd -0\fP | |
8982 | removes the last directory, | |
8983 | .if n ``popd -1'' | |
8984 | .if t \f(CWpopd -1\fP | |
8985 | the next to last. | |
726f6388 JA |
8986 | .PD |
8987 | .PP | |
8988 | If the | |
8989 | .B popd | |
a0c0a00f | 8990 | command is successful, a |
726f6388 JA |
8991 | .B dirs |
8992 | is performed as well, and the return status is 0. | |
8993 | .B popd | |
cce855bc | 8994 | returns false if an invalid option is encountered, the directory stack |
726f6388 JA |
8995 | is empty, a non-existent directory stack entry is specified, or the |
8996 | directory change fails. | |
8997 | .RE | |
8998 | .TP | |
95732b49 | 8999 | \fBprintf\fP [\fB\-v\fP \fIvar\fP] \fIformat\fP [\fIarguments\fP] |
cce855bc JA |
9000 | Write the formatted \fIarguments\fP to the standard output under the |
9001 | control of the \fIformat\fP. | |
495aee44 CR |
9002 | The \fB\-v\fP option causes the output to be assigned to the variable |
9003 | \fIvar\fP rather than being printed to the standard output. | |
9004 | .sp 1 | |
cce855bc JA |
9005 | The \fIformat\fP is a character string which contains three types of objects: |
9006 | plain characters, which are simply copied to standard output, character | |
9007 | escape sequences, which are converted and copied to the standard output, and | |
9008 | format specifications, each of which causes printing of the next successive | |
9009 | \fIargument\fP. | |
495aee44 CR |
9010 | In addition to the standard \fIprintf\fP(1) format specifications, |
9011 | \fBprintf\fP interprets the following extensions: | |
9012 | .RS | |
9013 | .PD 0 | |
9014 | .TP | |
9015 | .B %b | |
9016 | causes | |
cce855bc | 9017 | \fBprintf\fP to expand backslash escape sequences in the corresponding |
a0c0a00f CR |
9018 | \fIargument\fP |
9019 | in the same way as \fBecho \-e\fP. | |
495aee44 CR |
9020 | .TP |
9021 | .B %q | |
9022 | causes \fBprintf\fP to output the corresponding | |
cce855bc | 9023 | \fIargument\fP in a format that can be reused as shell input. |
495aee44 CR |
9024 | .TP |
9025 | .B %(\fIdatefmt\fP)T | |
9026 | causes \fBprintf\fP to output the date-time string resulting from using | |
ac50fbac CR |
9027 | \fIdatefmt\fP as a format string for \fIstrftime\fP(3). |
9028 | The corresponding \fIargument\fP is an integer representing the number of | |
9029 | seconds since the epoch. | |
9a51695b CR |
9030 | Two special argument values may be used: \-1 represents the current |
9031 | time, and \-2 represents the time the shell was invoked. | |
9032 | If no argument is specified, conversion behaves as if \-1 had been given. | |
ac50fbac | 9033 | This is an exception to the usual \fBprintf\fP behavior. |
495aee44 CR |
9034 | .PD |
9035 | .PP | |
9036 | Arguments to non-string format specifiers are treated as C constants, | |
9037 | except that a leading plus or minus sign is allowed, and if the leading | |
9038 | character is a single or double quote, the value is the ASCII value of | |
9039 | the following character. | |
9040 | .PP | |
cce855bc JA |
9041 | The \fIformat\fP is reused as necessary to consume all of the \fIarguments\fP. |
9042 | If the \fIformat\fP requires more \fIarguments\fP than are supplied, the | |
9043 | extra format specifications behave as if a zero value or null string, as | |
495aee44 CR |
9044 | appropriate, had been supplied. |
9045 | The return value is zero on success, non-zero on failure. | |
9046 | .RE | |
cce855bc | 9047 | .TP |
3185942a | 9048 | \fBpushd\fP [\fB\-n\fP] [+\fIn\fP] [\-\fIn\fP] |
7117c2d2 | 9049 | .PD 0 |
726f6388 | 9050 | .TP |
3185942a | 9051 | \fBpushd\fP [\fB\-n\fP] [\fIdir\fP] |
726f6388 JA |
9052 | .PD |
9053 | Adds a directory to the top of the directory stack, or rotates | |
9054 | the stack, making the new top of the stack the current working | |
a0c0a00f | 9055 | directory. With no arguments, \fBpushd\fP exchanges the top two directories |
726f6388 | 9056 | and returns 0, unless the directory stack is empty. |
ccc6cda3 | 9057 | Arguments, if supplied, have the following meanings: |
726f6388 JA |
9058 | .RS |
9059 | .PD 0 | |
9060 | .TP | |
3185942a | 9061 | .B \-n |
a0c0a00f CR |
9062 | Suppresses the normal change of directory when rotating or |
9063 | adding directories to the stack, so that only the stack is manipulated. | |
3185942a | 9064 | .TP |
ccc6cda3 | 9065 | \fB+\fP\fIn\fP |
726f6388 JA |
9066 | Rotates the stack so that the \fIn\fPth directory |
9067 | (counting from the left of the list shown by | |
d166f048 JA |
9068 | .BR dirs , |
9069 | starting with zero) | |
726f6388 JA |
9070 | is at the top. |
9071 | .TP | |
ccc6cda3 | 9072 | \fB\-\fP\fIn\fP |
726f6388 | 9073 | Rotates the stack so that the \fIn\fPth directory |
d166f048 JA |
9074 | (counting from the right of the list shown by |
9075 | .BR dirs , | |
9076 | starting with zero) is at the top. | |
726f6388 | 9077 | .TP |
bb70624e | 9078 | .I dir |
ccc6cda3 | 9079 | Adds |
726f6388 JA |
9080 | .I dir |
9081 | to the directory stack at the top, making it the | |
ac50fbac CR |
9082 | new current working directory as if it had been supplied as the argument |
9083 | to the \fBcd\fP builtin. | |
726f6388 JA |
9084 | .PD |
9085 | .PP | |
9086 | If the | |
9087 | .B pushd | |
a0c0a00f | 9088 | command is successful, a |
726f6388 JA |
9089 | .B dirs |
9090 | is performed as well. | |
9091 | If the first form is used, | |
9092 | .B pushd | |
9093 | returns 0 unless the cd to | |
9094 | .I dir | |
9095 | fails. With the second form, | |
9096 | .B pushd | |
9097 | returns 0 unless the directory stack is empty, | |
ccc6cda3 | 9098 | a non-existent directory stack element is specified, |
726f6388 JA |
9099 | or the directory change to the specified new current directory |
9100 | fails. | |
9101 | .RE | |
9102 | .TP | |
ccc6cda3 | 9103 | \fBpwd\fP [\fB\-LP\fP] |
bb70624e JA |
9104 | Print the absolute pathname of the current working directory. |
9105 | The pathname printed contains no symbolic links if the | |
726f6388 | 9106 | .B \-P |
a0c0a00f | 9107 | option is supplied or the |
ccc6cda3 | 9108 | .B \-o physical |
726f6388 JA |
9109 | option to the |
9110 | .B set | |
ccc6cda3 JA |
9111 | builtin command is enabled. |
9112 | If the | |
9113 | .B \-L | |
bb70624e | 9114 | option is used, the pathname printed may contain symbolic links. |
ccc6cda3 | 9115 | The return status is 0 unless an error occurs while |
cce855bc JA |
9116 | reading the name of the current directory or an |
9117 | invalid option is supplied. | |
726f6388 | 9118 | .TP |
0001803f | 9119 | \fBread\fP [\fB\-ers\fP] [\fB\-a\fP \fIaname\fP] [\fB\-d\fP \fIdelim\fP] [\fB\-i\fP \fItext\fP] [\fB\-n\fP \fInchars\fP] [\fB\-N\fP \fInchars\fP] [\fB\-p\fP \fIprompt\fP] [\fB\-t\fP \fItimeout\fP] [\fB\-u\fP \fIfd\fP] [\fIname\fP ...] |
7117c2d2 | 9120 | One line is read from the standard input, or from the file descriptor |
a0c0a00f CR |
9121 | \fIfd\fP supplied as an argument to the \fB\-u\fP option, |
9122 | split into words as described above under \fBWord Splitting\fP, | |
9123 | and the first word | |
726f6388 JA |
9124 | is assigned to the first |
9125 | .IR name , | |
9126 | the second word to the second | |
9127 | .IR name , | |
a0c0a00f CR |
9128 | and so on. |
9129 | If there are more words than names, the remaining words and their | |
9130 | intervening delimiters are assigned to the last | |
726f6388 | 9131 | .IR name . |
7117c2d2 | 9132 | If there are fewer words read from the input stream than names, |
cce855bc | 9133 | the remaining names are assigned empty values. |
a0c0a00f | 9134 | The characters in |
726f6388 JA |
9135 | .SM |
9136 | .B IFS | |
ac50fbac CR |
9137 | are used to split the line into words using the same rules the shell |
9138 | uses for expansion (described above under \fBWord Splitting\fP). | |
b72432fd JA |
9139 | The backslash character (\fB\e\fP) may be used to remove any special |
9140 | meaning for the next character read and for line continuation. | |
cce855bc | 9141 | Options, if supplied, have the following meanings: |
ccc6cda3 JA |
9142 | .RS |
9143 | .PD 0 | |
9144 | .TP | |
bb70624e | 9145 | .B \-a \fIaname\fP |
ccc6cda3 JA |
9146 | The words are assigned to sequential indices |
9147 | of the array variable | |
9148 | .IR aname , | |
9149 | starting at 0. | |
9150 | .I aname | |
9151 | is unset before any new values are assigned. | |
cce855bc | 9152 | Other \fIname\fP arguments are ignored. |
ccc6cda3 | 9153 | .TP |
bb70624e JA |
9154 | .B \-d \fIdelim\fP |
9155 | The first character of \fIdelim\fP is used to terminate the input line, | |
9156 | rather than newline. | |
9a51695b CR |
9157 | If \fIdelim\fP is the empty string, \fBread\fP will terminate a line |
9158 | when it reads a NUL character. | |
bb70624e | 9159 | .TP |
ccc6cda3 JA |
9160 | .B \-e |
9161 | If the standard input | |
9162 | is coming from a terminal, | |
9163 | .B readline | |
9164 | (see | |
9165 | .SM | |
9166 | .B READLINE | |
9167 | above) is used to obtain the line. | |
3185942a | 9168 | Readline uses the current (or default, if line editing was not previously |
9a51695b | 9169 | active) editing settings, but uses Readline's default filename completion. |
3185942a JA |
9170 | .TP |
9171 | .B \-i \fItext\fP | |
9172 | If | |
9173 | .B readline | |
9174 | is being used to read the line, \fItext\fP is placed into the editing | |
9175 | buffer before editing begins. | |
bb70624e JA |
9176 | .TP |
9177 | .B \-n \fInchars\fP | |
9178 | \fBread\fP returns after reading \fInchars\fP characters rather than | |
a0c0a00f | 9179 | waiting for a complete line of input, but honors a delimiter if fewer |
0001803f CR |
9180 | than \fInchars\fP characters are read before the delimiter. |
9181 | .TP | |
9182 | .B \-N \fInchars\fP | |
9183 | \fBread\fP returns after reading exactly \fInchars\fP characters rather | |
9184 | than waiting for a complete line of input, unless EOF is encountered or | |
9185 | \fBread\fP times out. | |
9186 | Delimiter characters encountered in the input are | |
9187 | not treated specially and do not cause \fBread\fP to return until | |
9188 | \fInchars\fP characters are read. | |
a0c0a00f CR |
9189 | The result is not split on the characters in \fBIFS\fP; the intent is |
9190 | that the variable is assigned exactly the characters read | |
9191 | (with the exception of backslash; see the \fB\-r\fP option below). | |
bb70624e JA |
9192 | .TP |
9193 | .B \-p \fIprompt\fP | |
f73dda09 | 9194 | Display \fIprompt\fP on standard error, without a |
bb70624e JA |
9195 | trailing newline, before attempting to read any input. The prompt |
9196 | is displayed only if input is coming from a terminal. | |
9197 | .TP | |
9198 | .B \-r | |
9199 | Backslash does not act as an escape character. | |
9200 | The backslash is considered to be part of the line. | |
2ae59c11 | 9201 | In particular, a backslash-newline pair may not then be used as a line |
bb70624e JA |
9202 | continuation. |
9203 | .TP | |
9204 | .B \-s | |
9205 | Silent mode. If input is coming from a terminal, characters are | |
9206 | not echoed. | |
9207 | .TP | |
9208 | .B \-t \fItimeout\fP | |
9209 | Cause \fBread\fP to time out and return failure if a complete line of | |
ac50fbac CR |
9210 | input (or a specified number of characters) |
9211 | is not read within \fItimeout\fP seconds. | |
3185942a JA |
9212 | \fItimeout\fP may be a decimal number with a fractional portion following |
9213 | the decimal point. | |
9214 | This option is only effective if \fBread\fP is reading input from a | |
9215 | terminal, pipe, or other special file; it has no effect when reading | |
9216 | from regular files. | |
ac50fbac CR |
9217 | If \fBread\fP times out, \fBread\fP saves any partial input read into |
9218 | the specified variable \fIname\fP. | |
9219 | If \fItimeout\fP is 0, \fBread\fP returns immediately, without trying to | |
9220 | read any data. The exit status is 0 if input is available on | |
9221 | the specified file descriptor, non-zero otherwise. | |
3185942a | 9222 | The exit status is greater than 128 if the timeout is exceeded. |
7117c2d2 | 9223 | .TP |
95732b49 | 9224 | .B \-u \fIfd\fP |
7117c2d2 | 9225 | Read input from file descriptor \fIfd\fP. |
ccc6cda3 JA |
9226 | .PD |
9227 | .PP | |
9228 | If no | |
726f6388 JA |
9229 | .I names |
9230 | are supplied, the line read is assigned to the variable | |
9231 | .SM | |
9232 | .BR REPLY . | |
a0c0a00f CR |
9233 | The exit status is zero, unless end-of-file is encountered, \fBread\fP |
9234 | times out (in which case the status is greater than 128), | |
ac50fbac CR |
9235 | a variable assignment error (such as assigning to a readonly variable) occurs, |
9236 | or an invalid file descriptor is supplied as the argument to \fB\-u\fP. | |
ccc6cda3 | 9237 | .RE |
726f6388 | 9238 | .TP |
495aee44 | 9239 | \fBreadonly\fP [\fB\-aAf\fP] [\fB\-p\fP] [\fIname\fP[=\fIword\fP] ...] |
726f6388 JA |
9240 | .PD |
9241 | The given | |
ccc6cda3 JA |
9242 | \fInames\fP are marked readonly; the values of these |
9243 | .I names | |
726f6388 JA |
9244 | may not be changed by subsequent assignment. |
9245 | If the | |
9246 | .B \-f | |
9247 | option is supplied, the functions corresponding to the | |
9248 | \fInames\fP are so | |
ccc6cda3 JA |
9249 | marked. |
9250 | The | |
9251 | .B \-a | |
3185942a JA |
9252 | option restricts the variables to indexed arrays; the |
9253 | .B \-A | |
9254 | option restricts the variables to associative arrays. | |
495aee44 CR |
9255 | If both options are supplied, |
9256 | .B \-A | |
9257 | takes precedence. | |
ccc6cda3 JA |
9258 | If no |
9259 | .I name | |
9260 | arguments are given, or if the | |
726f6388 | 9261 | .B \-p |
ccc6cda3 | 9262 | option is supplied, a list of all readonly names is printed. |
495aee44 CR |
9263 | The other options may be used to restrict the output to a subset of |
9264 | the set of readonly names. | |
cce855bc JA |
9265 | The |
9266 | .B \-p | |
bb70624e JA |
9267 | option causes output to be displayed in a format that |
9268 | may be reused as input. | |
b80f6443 JA |
9269 | If a variable name is followed by =\fIword\fP, the value of |
9270 | the variable is set to \fIword\fP. | |
cce855bc | 9271 | The return status is 0 unless an invalid option is encountered, |
ccc6cda3 JA |
9272 | one of the |
9273 | .I names | |
cce855bc | 9274 | is not a valid shell variable name, or |
726f6388 JA |
9275 | .B \-f |
9276 | is supplied with a | |
9277 | .I name | |
9278 | that is not a function. | |
9279 | .TP | |
9280 | \fBreturn\fP [\fIn\fP] | |
ac50fbac CR |
9281 | Causes a function to stop executing and return the value specified by |
9282 | .I n | |
9283 | to its caller. | |
a0c0a00f | 9284 | If |
726f6388 JA |
9285 | .I n |
9286 | is omitted, the return status is that of the last command | |
a0c0a00f CR |
9287 | executed in the function body. |
9288 | If \fBreturn\fP is executed by a trap handler, the last command used to | |
9289 | determine the status is the last command executed before the trap handler. | |
9a51695b | 9290 | If \fBreturn\fP is executed during a \fBDEBUG\fP trap, the last command |
a0c0a00f CR |
9291 | used to determine the status is the last command executed by the trap |
9292 | handler before \fBreturn\fP was invoked. | |
9293 | If | |
ac50fbac CR |
9294 | .B return |
9295 | is used outside a function, | |
a0c0a00f | 9296 | but during execution of a script by the |
726f6388 JA |
9297 | .B . |
9298 | (\fBsource\fP) command, it causes the shell to stop executing | |
9299 | that script and return either | |
9300 | .I n | |
9301 | or the exit status of the last command executed within the | |
ac50fbac CR |
9302 | script as the exit status of the script. |
9303 | If \fIn\fP is supplied, the return value is its least significant | |
9304 | 8 bits. | |
9305 | The return status is non-zero if | |
9306 | .B return | |
9307 | is supplied a non-numeric argument, or | |
9308 | is used outside a | |
9309 | function and not during execution of a script by \fB.\fP\^ or \fBsource\fP. | |
b80f6443 JA |
9310 | Any command associated with the \fBRETURN\fP trap is executed |
9311 | before execution resumes after the function or script. | |
726f6388 | 9312 | .TP |
495aee44 | 9313 | \fBset\fP [\fB\-\-abefhkmnptuvxBCEHPT\fP] [\fB\-o\fP \fIoption\-name\fP] [\fIarg\fP ...] |
3185942a JA |
9314 | .PD 0 |
9315 | .TP | |
495aee44 | 9316 | \fBset\fP [\fB+abefhkmnptuvxBCEHPT\fP] [\fB+o\fP \fIoption\-name\fP] [\fIarg\fP ...] |
3185942a | 9317 | .PD |
ccc6cda3 | 9318 | Without options, the name and value of each shell variable are displayed |
95732b49 JA |
9319 | in a format that can be reused as input |
9320 | for setting or resetting the currently-set variables. | |
9321 | Read-only variables cannot be reset. | |
2f5dfe5a | 9322 | In \fIposix mode\fP, only shell variables are listed. |
cce855bc | 9323 | The output is sorted according to the current locale. |
ccc6cda3 | 9324 | When options are specified, they set or unset shell attributes. |
3185942a | 9325 | Any arguments remaining after option processing are treated |
a0c0a00f | 9326 | as values for the positional parameters and are assigned, in order, to |
ccc6cda3 JA |
9327 | .BR $1 , |
9328 | .BR $2 , | |
9329 | .B ... | |
9330 | .BR $\fIn\fP . | |
9331 | Options, if specified, have the following meanings: | |
726f6388 JA |
9332 | .RS |
9333 | .PD 0 | |
9334 | .TP 8 | |
9335 | .B \-a | |
a0c0a00f CR |
9336 | Each variable or function that is created or modified is given the |
9337 | export attribute and marked for export to the environment of | |
9338 | subsequent commands. | |
726f6388 JA |
9339 | .TP 8 |
9340 | .B \-b | |
ccc6cda3 JA |
9341 | Report the status of terminated background jobs |
9342 | immediately, rather than before the next primary prompt. This is | |
9343 | effective only when job control is enabled. | |
726f6388 JA |
9344 | .TP 8 |
9345 | .B \-e | |
ac50fbac CR |
9346 | Exit immediately if a |
9347 | \fIpipeline\fP (which may consist of a single \fIsimple command\fP), | |
9348 | a \fIlist\fP, | |
9349 | or a \fIcompound command\fP | |
9350 | (see | |
726f6388 JA |
9351 | .SM |
9352 | .B SHELL GRAMMAR | |
a0c0a00f | 9353 | above), exits with a non-zero status. |
b80f6443 JA |
9354 | The shell does not exit if the |
9355 | command that fails is part of the command list immediately following a | |
9356 | .B while | |
726f6388 | 9357 | or |
b80f6443 | 9358 | .B until |
a0c0a00f | 9359 | keyword, |
17345e5a | 9360 | part of the test following the |
3185942a | 9361 | .B if |
17345e5a JA |
9362 | or |
9363 | .B elif | |
9364 | reserved words, part of any command executed in a | |
726f6388 JA |
9365 | .B && |
9366 | or | |
495aee44 CR |
9367 | .B || |
9368 | list except the command following the final \fB&&\fP or \fB||\fP, | |
3185942a JA |
9369 | any command in a pipeline but the last, |
9370 | or if the command's return value is | |
17345e5a | 9371 | being inverted with |
726f6388 | 9372 | .BR ! . |
ac50fbac CR |
9373 | If a compound command other than a subshell |
9374 | returns a non-zero status because a command failed | |
9375 | while \fB\-e\fP was being ignored, the shell does not exit. | |
f73dda09 | 9376 | A trap on \fBERR\fP, if set, is executed before the shell exits. |
17345e5a JA |
9377 | This option applies to the shell environment and each subshell environment |
9378 | separately (see | |
0001803f | 9379 | .SM |
17345e5a JA |
9380 | .B "COMMAND EXECUTION ENVIRONMENT" |
9381 | above), and may cause | |
9382 | subshells to exit before executing all the commands in the subshell. | |
ac50fbac CR |
9383 | .if t .sp 0.5 |
9384 | .if n .sp 1 | |
9385 | If a compound command or shell function executes in a context | |
9386 | where \fB\-e\fP is being ignored, | |
9387 | none of the commands executed within the compound command or function body | |
9388 | will be affected by the \fB\-e\fP setting, even if \fB\-e\fP is set | |
9389 | and a command returns a failure status. | |
9390 | If a compound command or shell function sets \fB\-e\fP while executing in | |
9391 | a context where \fB\-e\fP is ignored, that setting will not have any | |
9392 | effect until the compound command or the command containing the function | |
9393 | call completes. | |
726f6388 JA |
9394 | .TP 8 |
9395 | .B \-f | |
9396 | Disable pathname expansion. | |
a0c0a00f | 9397 | .TP 8 |
726f6388 | 9398 | .B \-h |
ccc6cda3 | 9399 | Remember the location of commands as they are looked up for execution. |
cce855bc | 9400 | This is enabled by default. |
726f6388 JA |
9401 | .TP 8 |
9402 | .B \-k | |
ccc6cda3 JA |
9403 | All arguments in the form of assignment statements |
9404 | are placed in the environment for a command, not just | |
9405 | those that precede the command name. | |
726f6388 JA |
9406 | .TP 8 |
9407 | .B \-m | |
cce855bc | 9408 | Monitor mode. Job control is enabled. This option is on |
726f6388 JA |
9409 | by default for interactive shells on systems that support |
9410 | it (see | |
9411 | .SM | |
9412 | .B JOB CONTROL | |
ac50fbac CR |
9413 | above). |
9414 | All processes run in a separate process group. | |
9415 | When a background job completes, the shell prints a line | |
9416 | containing its exit status. | |
726f6388 JA |
9417 | .TP 8 |
9418 | .B \-n | |
a0c0a00f CR |
9419 | Read commands but do not execute them. |
9420 | This may be used to check a shell script for syntax errors. | |
9421 | This is ignored by interactive shells. | |
726f6388 | 9422 | .TP 8 |
ccc6cda3 JA |
9423 | .B \-o \fIoption\-name\fP |
9424 | The \fIoption\-name\fP can be one of the following: | |
726f6388 JA |
9425 | .RS |
9426 | .TP 8 | |
9427 | .B allexport | |
9428 | Same as | |
9429 | .BR \-a . | |
9430 | .TP 8 | |
9431 | .B braceexpand | |
ccc6cda3 JA |
9432 | Same as |
9433 | .BR \-B . | |
726f6388 JA |
9434 | .TP 8 |
9435 | .B emacs | |
9436 | Use an emacs-style command line editing interface. This is enabled | |
9437 | by default when the shell is interactive, unless the shell is started | |
9438 | with the | |
ccc6cda3 | 9439 | .B \-\-noediting |
726f6388 | 9440 | option. |
3185942a | 9441 | This also affects the editing interface used for \fBread \-e\fP. |
726f6388 | 9442 | .TP 8 |
0001803f CR |
9443 | .B errexit |
9444 | Same as | |
9445 | .BR \-e . | |
9446 | .TP 8 | |
b80f6443 JA |
9447 | .B errtrace |
9448 | Same as | |
9449 | .BR \-E . | |
9450 | .TP 8 | |
9451 | .B functrace | |
9452 | Same as | |
9453 | .BR \-T . | |
9454 | .TP 8 | |
ccc6cda3 JA |
9455 | .B hashall |
9456 | Same as | |
9457 | .BR \-h . | |
9458 | .TP 8 | |
726f6388 JA |
9459 | .B histexpand |
9460 | Same as | |
9461 | .BR \-H . | |
9462 | .TP 8 | |
ccc6cda3 JA |
9463 | .B history |
9464 | Enable command history, as described above under | |
9465 | .SM | |
9466 | .BR HISTORY . | |
9467 | This option is on by default in interactive shells. | |
9468 | .TP 8 | |
726f6388 | 9469 | .B ignoreeof |
28ef6c31 JA |
9470 | The effect is as if the shell command |
9471 | .if t \f(CWIGNOREEOF=10\fP | |
9472 | .if n ``IGNOREEOF=10'' | |
9473 | had been executed | |
726f6388 JA |
9474 | (see |
9475 | .B Shell Variables | |
9476 | above). | |
9477 | .TP 8 | |
ccc6cda3 JA |
9478 | .B keyword |
9479 | Same as | |
9480 | .BR \-k . | |
726f6388 JA |
9481 | .TP 8 |
9482 | .B monitor | |
9483 | Same as | |
9484 | .BR \-m . | |
9485 | .TP 8 | |
9486 | .B noclobber | |
9487 | Same as | |
9488 | .BR \-C . | |
9489 | .TP 8 | |
9490 | .B noexec | |
9491 | Same as | |
9492 | .BR \-n . | |
9493 | .TP 8 | |
9494 | .B noglob | |
9495 | Same as | |
9496 | .BR \-f . | |
3185942a | 9497 | .TP 8 |
f73dda09 JA |
9498 | .B nolog |
9499 | Currently ignored. | |
726f6388 | 9500 | .TP 8 |
726f6388 JA |
9501 | .B notify |
9502 | Same as | |
9503 | .BR \-b . | |
9504 | .TP 8 | |
9505 | .B nounset | |
9506 | Same as | |
9507 | .BR \-u . | |
9508 | .TP 8 | |
ccc6cda3 JA |
9509 | .B onecmd |
9510 | Same as | |
9511 | .BR \-t . | |
9512 | .TP 8 | |
726f6388 JA |
9513 | .B physical |
9514 | Same as | |
9515 | .BR \-P . | |
9516 | .TP 8 | |
b80f6443 JA |
9517 | .B pipefail |
9518 | If set, the return value of a pipeline is the value of the last | |
9519 | (rightmost) command to exit with a non-zero status, or zero if all | |
9520 | commands in the pipeline exit successfully. | |
9521 | This option is disabled by default. | |
9522 | .TP 8 | |
726f6388 | 9523 | .B posix |
ccc6cda3 JA |
9524 | Change the behavior of |
9525 | .B bash | |
9526 | where the default operation differs | |
0628567a | 9527 | from the POSIX standard to match the standard (\fIposix mode\fP). |
ac50fbac CR |
9528 | See |
9529 | .SM | |
9530 | .B "SEE ALSO" | |
9531 | below for a reference to a document that details how posix mode affects | |
9532 | bash's behavior. | |
726f6388 JA |
9533 | .TP 8 |
9534 | .B privileged | |
9535 | Same as | |
9536 | .BR \-p . | |
9537 | .TP 8 | |
9538 | .B verbose | |
9539 | Same as | |
9540 | .BR \-v . | |
9541 | .TP 8 | |
9542 | .B vi | |
9543 | Use a vi-style command line editing interface. | |
3185942a | 9544 | This also affects the editing interface used for \fBread \-e\fP. |
726f6388 JA |
9545 | .TP 8 |
9546 | .B xtrace | |
9547 | Same as | |
9548 | .BR \-x . | |
ccc6cda3 | 9549 | .sp .5 |
726f6388 | 9550 | .PP |
ccc6cda3 JA |
9551 | If |
9552 | .B \-o | |
9553 | is supplied with no \fIoption\-name\fP, the values of the current options are | |
726f6388 | 9554 | printed. |
ccc6cda3 JA |
9555 | If |
9556 | .B +o | |
9557 | is supplied with no \fIoption\-name\fP, a series of | |
9558 | .B set | |
9559 | commands to recreate the current option settings is displayed on | |
9560 | the standard output. | |
726f6388 JA |
9561 | .RE |
9562 | .TP 8 | |
9563 | .B \-p | |
9564 | Turn on | |
9565 | .I privileged | |
9566 | mode. In this mode, the | |
bb70624e | 9567 | .SM |
726f6388 | 9568 | .B $ENV |
b72432fd | 9569 | and |
bb70624e | 9570 | .SM |
b72432fd JA |
9571 | .B $BASH_ENV |
9572 | files are not processed, shell functions are not inherited from the | |
bb70624e JA |
9573 | environment, and the |
9574 | .SM | |
3185942a | 9575 | .BR SHELLOPTS , |
0001803f CR |
9576 | .SM |
9577 | .BR BASHOPTS , | |
9578 | .SM | |
3185942a JA |
9579 | .BR CDPATH , |
9580 | and | |
0001803f | 9581 | .SM |
3185942a JA |
9582 | .B GLOBIGNORE |
9583 | variables, if they appear in the environment, are ignored. | |
b72432fd JA |
9584 | If the shell is started with the effective user (group) id not equal to the |
9585 | real user (group) id, and the \fB\-p\fP option is not supplied, these actions | |
9586 | are taken and the effective user id is set to the real user id. | |
9587 | If the \fB\-p\fP option is supplied at startup, the effective user id is | |
9588 | not reset. | |
cce855bc | 9589 | Turning this option off causes the effective user |
726f6388 JA |
9590 | and group ids to be set to the real user and group ids. |
9591 | .TP 8 | |
9592 | .B \-t | |
9593 | Exit after reading and executing one command. | |
9594 | .TP 8 | |
9595 | .B \-u | |
89a92869 CR |
9596 | Treat unset variables and parameters other than the special |
9597 | parameters "@" and "*" as an error when performing | |
726f6388 | 9598 | parameter expansion. If expansion is attempted on an |
89a92869 | 9599 | unset variable or parameter, the shell prints an error message, and, |
ccc6cda3 | 9600 | if not interactive, exits with a non-zero status. |
726f6388 JA |
9601 | .TP 8 |
9602 | .B \-v | |
9603 | Print shell input lines as they are read. | |
9604 | .TP 8 | |
9605 | .B \-x | |
ccc6cda3 | 9606 | After expanding each \fIsimple command\fP, |
b80f6443 JA |
9607 | \fBfor\fP command, \fBcase\fP command, \fBselect\fP command, or |
9608 | arithmetic \fBfor\fP command, display the expanded value of | |
726f6388 JA |
9609 | .SM |
9610 | .BR PS4 , | |
b80f6443 JA |
9611 | followed by the command and its expanded arguments |
9612 | or associated word list. | |
726f6388 | 9613 | .TP 8 |
ccc6cda3 JA |
9614 | .B \-B |
9615 | The shell performs brace expansion (see | |
9616 | .B Brace Expansion | |
9617 | above). This is on by default. | |
726f6388 JA |
9618 | .TP 8 |
9619 | .B \-C | |
ccc6cda3 JA |
9620 | If set, |
9621 | .B bash | |
9622 | does not overwrite an existing file with the | |
9623 | .BR > , | |
9624 | .BR >& , | |
9625 | and | |
9626 | .B <> | |
a0c0a00f | 9627 | redirection operators. This may be overridden when |
ccc6cda3 JA |
9628 | creating output files by using the redirection operator |
9629 | .B >| | |
9630 | instead of | |
9631 | .BR > . | |
726f6388 | 9632 | .TP 8 |
b80f6443 JA |
9633 | .B \-E |
9634 | If set, any trap on \fBERR\fP is inherited by shell functions, command | |
9635 | substitutions, and commands executed in a subshell environment. | |
9636 | The \fBERR\fP trap is normally not inherited in such cases. | |
9637 | .TP 8 | |
726f6388 JA |
9638 | .B \-H |
9639 | Enable | |
9640 | .B ! | |
cce855bc | 9641 | style history substitution. This option is on by |
726f6388 JA |
9642 | default when the shell is interactive. |
9643 | .TP 8 | |
9644 | .B \-P | |
ac50fbac | 9645 | If set, the shell does not resolve symbolic links when executing |
ccc6cda3 | 9646 | commands such as |
726f6388 | 9647 | .B cd |
ccc6cda3 JA |
9648 | that change the current working directory. It uses the |
9649 | physical directory structure instead. By default, | |
9650 | .B bash | |
9651 | follows the logical chain of directories when performing commands | |
9652 | which change the current directory. | |
726f6388 | 9653 | .TP 8 |
b80f6443 | 9654 | .B \-T |
95732b49 JA |
9655 | If set, any traps on \fBDEBUG\fP and \fBRETURN\fP are inherited by shell |
9656 | functions, command substitutions, and commands executed in a | |
9657 | subshell environment. | |
9658 | The \fBDEBUG\fP and \fBRETURN\fP traps are normally not inherited | |
9659 | in such cases. | |
b80f6443 | 9660 | .TP 8 |
726f6388 | 9661 | .B \-\- |
cce855bc | 9662 | If no arguments follow this option, then the positional parameters are |
726f6388 JA |
9663 | unset. Otherwise, the positional parameters are set to the |
9664 | \fIarg\fPs, even if some of them begin with a | |
9665 | .BR \- . | |
9666 | .TP 8 | |
9667 | .B \- | |
9668 | Signal the end of options, cause all remaining \fIarg\fPs to be | |
9669 | assigned to the positional parameters. The | |
9670 | .B \-x | |
9671 | and | |
9672 | .B \-v | |
9673 | options are turned off. | |
9674 | If there are no \fIarg\fPs, | |
9675 | the positional parameters remain unchanged. | |
9676 | .PD | |
9677 | .PP | |
cce855bc JA |
9678 | The options are off by default unless otherwise noted. |
9679 | Using + rather than \- causes these options to be turned off. | |
9680 | The options can also be specified as arguments to an invocation of | |
9681 | the shell. | |
9682 | The current set of options may be found in | |
726f6388 | 9683 | .BR $\- . |
cce855bc | 9684 | The return status is always true unless an invalid option is encountered. |
726f6388 JA |
9685 | .RE |
9686 | .TP | |
9687 | \fBshift\fP [\fIn\fP] | |
9688 | The positional parameters from \fIn\fP+1 ... are renamed to | |
9689 | .B $1 | |
9690 | .B .... | |
9691 | Parameters represented by the numbers \fB$#\fP | |
9692 | down to \fB$#\fP\-\fIn\fP+1 are unset. | |
ccc6cda3 JA |
9693 | .I n |
9694 | must be a non-negative number less than or equal to \fB$#\fP. | |
726f6388 JA |
9695 | If |
9696 | .I n | |
9697 | is 0, no parameters are changed. | |
9698 | If | |
a0c0a00f | 9699 | .I n |
726f6388 | 9700 | is not given, it is assumed to be 1. |
726f6388 JA |
9701 | If |
9702 | .I n | |
9703 | is greater than \fB$#\fP, the positional parameters are not changed. | |
ccc6cda3 | 9704 | The return status is greater than zero if |
726f6388 JA |
9705 | .I n |
9706 | is greater than | |
9707 | .B $# | |
ccc6cda3 JA |
9708 | or less than zero; otherwise 0. |
9709 | .TP | |
9710 | \fBshopt\fP [\fB\-pqsu\fP] [\fB\-o\fP] [\fIoptname\fP ...] | |
ac50fbac CR |
9711 | Toggle the values of settings controlling optional shell behavior. |
9712 | The settings can be either those listed below, or, if the | |
9713 | .B \-o | |
9714 | option is used, those available with the | |
9715 | .B \-o | |
9716 | option to the \fBset\fP builtin command. | |
ccc6cda3 JA |
9717 | With no options, or with the |
9718 | .B \-p | |
9719 | option, a list of all settable options is displayed, with | |
9a51695b CR |
9720 | an indication of whether or not each is set; |
9721 | if \fIoptnames\fP are supplied, the output is restricted to those options. | |
cce855bc JA |
9722 | The \fB\-p\fP option causes output to be displayed in a form that |
9723 | may be reused as input. | |
9724 | Other options have the following meanings: | |
ccc6cda3 JA |
9725 | .RS |
9726 | .PD 0 | |
9727 | .TP | |
9728 | .B \-s | |
9729 | Enable (set) each \fIoptname\fP. | |
9730 | .TP | |
9731 | .B \-u | |
9732 | Disable (unset) each \fIoptname\fP. | |
9733 | .TP | |
9734 | .B \-q | |
9735 | Suppresses normal output (quiet mode); the return status indicates | |
9736 | whether the \fIoptname\fP is set or unset. | |
9737 | If multiple \fIoptname\fP arguments are given with | |
9738 | .BR \-q , | |
9739 | the return status is zero if all \fIoptnames\fP are enabled; non-zero | |
9740 | otherwise. | |
9741 | .TP | |
9742 | .B \-o | |
9743 | Restricts the values of \fIoptname\fP to be those defined for the | |
9744 | .B \-o | |
9745 | option to the | |
9746 | .B set | |
9747 | builtin. | |
9748 | .PD | |
9749 | .PP | |
9750 | If either | |
9751 | .B \-s | |
9752 | or | |
9753 | .B \-u | |
ac50fbac CR |
9754 | is used with no \fIoptname\fP arguments, |
9755 | .B shopt | |
9756 | shows only those options which are set or unset, respectively. | |
ccc6cda3 JA |
9757 | Unless otherwise noted, the \fBshopt\fP options are disabled (unset) |
9758 | by default. | |
9759 | .PP | |
9760 | The return status when listing options is zero if all \fIoptnames\fP | |
9761 | are enabled, non-zero otherwise. When setting or unsetting options, | |
cce855bc | 9762 | the return status is zero unless an \fIoptname\fP is not a valid shell |
ccc6cda3 JA |
9763 | option. |
9764 | .PP | |
9765 | The list of \fBshopt\fP options is: | |
9766 | .if t .sp .5v | |
9767 | .if n .sp 1v | |
9768 | .PD 0 | |
9769 | .TP 8 | |
9a51695b CR |
9770 | .B assoc_expand_once |
9771 | If set, the shell suppresses multiple evaluation of associative array | |
9772 | subscripts during arithmetic expression evaluation and while executing | |
9773 | builtins that can perform variable assignments. | |
9774 | .TP 8 | |
3185942a JA |
9775 | .B autocd |
9776 | If set, a command name that is the name of a directory is executed as if | |
9777 | it were the argument to the \fBcd\fP command. | |
9778 | This option is only used by interactive shells. | |
9779 | .TP 8 | |
ccc6cda3 JA |
9780 | .B cdable_vars |
9781 | If set, an argument to the | |
9782 | .B cd | |
9783 | builtin command that | |
9784 | is not a directory is assumed to be the name of a variable whose | |
9785 | value is the directory to change to. | |
9786 | .TP 8 | |
9787 | .B cdspell | |
9788 | If set, minor errors in the spelling of a directory component in a | |
9789 | .B cd | |
9790 | command will be corrected. | |
9791 | The errors checked for are transposed characters, | |
9792 | a missing character, and one character too many. | |
ac50fbac | 9793 | If a correction is found, the corrected filename is printed, |
ccc6cda3 | 9794 | and the command proceeds. |
d166f048 | 9795 | This option is only used by interactive shells. |
ccc6cda3 JA |
9796 | .TP 8 |
9797 | .B checkhash | |
9798 | If set, \fBbash\fP checks that a command found in the hash | |
9799 | table exists before trying to execute it. If a hashed command no | |
9800 | longer exists, a normal path search is performed. | |
9801 | .TP 8 | |
3185942a JA |
9802 | .B checkjobs |
9803 | If set, \fBbash\fP lists the status of any stopped and running jobs before | |
9804 | exiting an interactive shell. If any jobs are running, this causes | |
9805 | the exit to be deferred until a second exit is attempted without an | |
0001803f CR |
9806 | intervening command (see |
9807 | .SM | |
9808 | .B "JOB CONTROL" | |
9809 | above). The shell always | |
3185942a JA |
9810 | postpones exiting if any jobs are stopped. |
9811 | .TP 8 | |
ccc6cda3 | 9812 | .B checkwinsize |
9a51695b CR |
9813 | If set, \fBbash\fP checks the window size after each external (non-builtin) |
9814 | command and, if necessary, updates the values of | |
ccc6cda3 JA |
9815 | .SM |
9816 | .B LINES | |
9817 | and | |
9818 | .SM | |
9819 | .BR COLUMNS . | |
2ae59c11 | 9820 | This option is enabled by default. |
ccc6cda3 JA |
9821 | .TP 8 |
9822 | .B cmdhist | |
9823 | If set, | |
9824 | .B bash | |
9825 | attempts to save all lines of a multiple-line | |
9826 | command in the same history entry. This allows | |
9827 | easy re-editing of multi-line commands. | |
9a51695b CR |
9828 | This option is enabled by default, but only has an effect if command |
9829 | history is enabled, as described above under | |
9830 | .SM | |
9831 | .BR HISTORY . | |
ccc6cda3 | 9832 | .TP 8 |
f1be666c JA |
9833 | .B compat31 |
9834 | If set, | |
9835 | .B bash | |
9836 | changes its behavior to that of version 3.1 with respect to quoted | |
ac50fbac CR |
9837 | arguments to the \fB[[\fP conditional command's \fB=~\fP operator |
9838 | and locale-specific string comparison when using the \fB[[\fP | |
495aee44 CR |
9839 | conditional command's \fB<\fP and \fB>\fP operators. |
9840 | Bash versions prior to bash-4.1 use ASCII collation and | |
9841 | .IR strcmp (3); | |
ac50fbac | 9842 | bash-4.1 and later use the current locale's collation sequence and |
495aee44 | 9843 | .IR strcoll (3). |
0001803f | 9844 | .TP 8 |
ac50fbac CR |
9845 | .B compat32 |
9846 | If set, | |
9847 | .B bash | |
9848 | changes its behavior to that of version 3.2 with respect to | |
9849 | locale-specific string comparison when using the \fB[[\fP | |
a0c0a00f CR |
9850 | conditional command's \fB<\fP and \fB>\fP operators (see previous item) |
9851 | and the effect of interrupting a command list. | |
9852 | Bash versions 3.2 and earlier continue with the next command in the list | |
9853 | after one terminates due to an interrupt. | |
ac50fbac | 9854 | .TP 8 |
0001803f CR |
9855 | .B compat40 |
9856 | If set, | |
9857 | .B bash | |
9858 | changes its behavior to that of version 4.0 with respect to locale-specific | |
495aee44 | 9859 | string comparison when using the \fB[[\fP |
ac50fbac CR |
9860 | conditional command's \fB<\fP and \fB>\fP operators (see description of |
9861 | \fBcompat31\fP) | |
0001803f | 9862 | and the effect of interrupting a command list. |
ac50fbac CR |
9863 | Bash versions 4.0 and later interrupt the list as if the shell received the |
9864 | interrupt; previous versions continue with the next command in the list. | |
0001803f | 9865 | .TP 8 |
495aee44 CR |
9866 | .B compat41 |
9867 | If set, | |
9868 | .BR bash , | |
2f5dfe5a | 9869 | when in \fIposix mode\fP, treats a single quote in a double-quoted |
495aee44 CR |
9870 | parameter expansion as a special character. The single quotes must match |
9871 | (an even number) and the characters between the single quotes are considered | |
9872 | quoted. This is the behavior of posix mode through version 4.1. | |
9873 | The default bash behavior remains as in previous versions. | |
9874 | .TP 8 | |
ac50fbac CR |
9875 | .B compat42 |
9876 | If set, | |
9877 | .B bash | |
9878 | does not process the replacement string in the pattern substitution word | |
9879 | expansion using quote removal. | |
9880 | .TP 8 | |
a0c0a00f CR |
9881 | .B compat43 |
9882 | If set, | |
9883 | .B bash | |
9884 | does not print a warning message if an attempt is made to use a quoted compound | |
9885 | array assignment as an argument to \fBdeclare\fP, | |
9886 | makes word expansion errors | |
9887 | non-fatal errors that cause the current command to fail (the default behavior is | |
9888 | to make them fatal errors that cause the shell to exit), | |
9889 | and does not reset the | |
9890 | loop state when a shell function is executed (this allows \fBbreak\fP or | |
9891 | \fBcontinue\fP in a shell function to affect loops in the caller's context). | |
9892 | .TP 8 | |
9a51695b CR |
9893 | .B compat44 |
9894 | If set, | |
9895 | .B bash | |
9896 | saves the positional parameters to BASH_ARGV and BASH_ARGC before they are | |
9897 | used, regardless of whether or not extended debugging mode is enabled. | |
9898 | .TP 8 | |
ac50fbac CR |
9899 | .B complete_fullquote |
9900 | If set, | |
9901 | .B bash | |
9902 | quotes all shell metacharacters in filenames and directory names when | |
9903 | performing completion. | |
9904 | If not set, | |
9905 | .B bash | |
9906 | removes metacharacters such as the dollar sign from the set of | |
9907 | characters that will be quoted in completed filenames | |
9908 | when these metacharacters appear in shell variable references in words to be | |
9909 | completed. | |
9910 | This means that dollar signs in variable names that expand to directories | |
9911 | will not be quoted; | |
9912 | however, any dollar signs appearing in filenames will not be quoted, either. | |
9913 | This is active only when bash is using backslashes to quote completed | |
9914 | filenames. | |
9915 | This variable is set by default, which is the default bash behavior in | |
9916 | versions through 4.2. | |
9917 | .TP 8 | |
16b2d7f4 CR |
9918 | .B direxpand |
9919 | If set, | |
9920 | .B bash | |
9921 | replaces directory names with the results of word expansion when performing | |
9922 | filename completion. This changes the contents of the readline editing | |
9923 | buffer. | |
9924 | If not set, | |
9925 | .B bash | |
9926 | attempts to preserve what the user typed. | |
9927 | .TP 8 | |
3185942a JA |
9928 | .B dirspell |
9929 | If set, | |
9930 | .B bash | |
9931 | attempts spelling correction on directory names during word completion | |
9932 | if the directory name initially supplied does not exist. | |
9933 | .TP 8 | |
ccc6cda3 | 9934 | .B dotglob |
a0c0a00f | 9935 | If set, |
ccc6cda3 JA |
9936 | .B bash |
9937 | includes filenames beginning with a `.' in the results of pathname | |
9938 | expansion. | |
9a51695b CR |
9939 | The filenames |
9940 | .B ``.'' | |
9941 | and | |
9942 | .B ``..'' | |
9943 | must always be matched explicitly, even if | |
9944 | .B dotglob | |
9945 | is set. | |
ccc6cda3 JA |
9946 | .TP 8 |
9947 | .B execfail | |
9948 | If set, a non-interactive shell will not exit if | |
9949 | it cannot execute the file specified as an argument to the | |
9950 | .B exec | |
9951 | builtin command. An interactive shell does not exit if | |
9952 | .B exec | |
9953 | fails. | |
9954 | .TP 8 | |
9955 | .B expand_aliases | |
9956 | If set, aliases are expanded as described above under | |
9957 | .SM | |
9958 | .BR ALIASES . | |
9959 | This option is enabled by default for interactive shells. | |
9960 | .TP 8 | |
b80f6443 | 9961 | .B extdebug |
a0c0a00f CR |
9962 | If set at shell invocation, arrange to execute the debugger profile |
9963 | before the shell starts, identical to the \fB\-\-debugger\fP option. | |
9964 | If set after invocation, behavior intended for use by debuggers is enabled: | |
b80f6443 JA |
9965 | .RS |
9966 | .TP | |
9967 | .B 1. | |
9968 | The \fB\-F\fP option to the \fBdeclare\fP builtin displays the source | |
9969 | file name and line number corresponding to each function name supplied | |
9970 | as an argument. | |
9971 | .TP | |
9972 | .B 2. | |
9973 | If the command run by the \fBDEBUG\fP trap returns a non-zero value, the | |
9974 | next command is skipped and not executed. | |
9975 | .TP | |
9976 | .B 3. | |
9977 | If the command run by the \fBDEBUG\fP trap returns a value of 2, and the | |
9978 | shell is executing in a subroutine (a shell function or a shell script | |
a0c0a00f CR |
9979 | executed by the \fB.\fP or \fBsource\fP builtins), the shell simulates |
9980 | a call to \fBreturn\fP. | |
95732b49 JA |
9981 | .TP |
9982 | .B 4. | |
0001803f CR |
9983 | .SM |
9984 | .B BASH_ARGC | |
9985 | and | |
9986 | .SM | |
9987 | .B BASH_ARGV | |
9988 | are updated as described in their descriptions above. | |
95732b49 JA |
9989 | .TP |
9990 | .B 5. | |
a0c0a00f | 9991 | Function tracing is enabled: command substitution, shell functions, and |
95732b49 JA |
9992 | subshells invoked with \fB(\fP \fIcommand\fP \fB)\fP inherit the |
9993 | \fBDEBUG\fP and \fBRETURN\fP traps. | |
9994 | .TP | |
9995 | .B 6. | |
a0c0a00f | 9996 | Error tracing is enabled: command substitution, shell functions, and |
95732b49 | 9997 | subshells invoked with \fB(\fP \fIcommand\fP \fB)\fP inherit the |
495aee44 | 9998 | \fBERR\fP trap. |
b80f6443 JA |
9999 | .RE |
10000 | .TP 8 | |
cce855bc JA |
10001 | .B extglob |
10002 | If set, the extended pattern matching features described above under | |
10003 | \fBPathname Expansion\fP are enabled. | |
10004 | .TP 8 | |
b80f6443 | 10005 | .B extquote |
0628567a | 10006 | If set, \fB$\fP\(aq\fIstring\fP\(aq and \fB$\fP"\fIstring\fP" quoting is |
b80f6443 JA |
10007 | performed within \fB${\fP\fIparameter\fP\fB}\fP expansions |
10008 | enclosed in double quotes. This option is enabled by default. | |
10009 | .TP 8 | |
10010 | .B failglob | |
10011 | If set, patterns which fail to match filenames during pathname expansion | |
10012 | result in an expansion error. | |
10013 | .TP 8 | |
10014 | .B force_fignore | |
0001803f CR |
10015 | If set, the suffixes specified by the |
10016 | .SM | |
10017 | .B FIGNORE | |
10018 | shell variable | |
b80f6443 JA |
10019 | cause words to be ignored when performing word completion even if |
10020 | the ignored words are the only possible completions. | |
10021 | See | |
10022 | .SM | |
10023 | \fBSHELL VARIABLES\fP | |
0001803f CR |
10024 | above for a description of |
10025 | .SM | |
10026 | .BR FIGNORE . | |
b80f6443 JA |
10027 | This option is enabled by default. |
10028 | .TP 8 | |
ac50fbac CR |
10029 | .B globasciiranges |
10030 | If set, range expressions used in pattern matching bracket expressions (see | |
10031 | .SM | |
10032 | .B Pattern Matching | |
10033 | above) behave as if in the traditional C locale when performing | |
10034 | comparisons. That is, the current locale's collating sequence | |
10035 | is not taken into account, so | |
10036 | .B b | |
10037 | will not collate between | |
10038 | .B A | |
10039 | and | |
10040 | .BR B , | |
10041 | and upper-case and lower-case ASCII characters will collate together. | |
10042 | .TP 8 | |
3185942a | 10043 | .B globstar |
0001803f | 10044 | If set, the pattern \fB**\fP used in a pathname expansion context will |
495aee44 | 10045 | match all files and zero or more directories and subdirectories. |
3185942a JA |
10046 | If the pattern is followed by a \fB/\fP, only directories and |
10047 | subdirectories match. | |
10048 | .TP 8 | |
b80f6443 JA |
10049 | .B gnu_errfmt |
10050 | If set, shell error messages are written in the standard GNU error | |
10051 | message format. | |
10052 | .TP 8 | |
ccc6cda3 JA |
10053 | .B histappend |
10054 | If set, the history list is appended to the file named by the value | |
10055 | of the | |
0001803f | 10056 | .SM |
ccc6cda3 JA |
10057 | .B HISTFILE |
10058 | variable when the shell exits, rather than overwriting the file. | |
10059 | .TP 8 | |
10060 | .B histreedit | |
10061 | If set, and | |
10062 | .B readline | |
10063 | is being used, a user is given the opportunity to re-edit a | |
10064 | failed history substitution. | |
10065 | .TP 8 | |
10066 | .B histverify | |
a0c0a00f | 10067 | If set, and |
ccc6cda3 JA |
10068 | .B readline |
10069 | is being used, the results of history substitution are not immediately | |
10070 | passed to the shell parser. Instead, the resulting line is loaded into | |
10071 | the \fBreadline\fP editing buffer, allowing further modification. | |
10072 | .TP 8 | |
10073 | .B hostcomplete | |
10074 | If set, and | |
10075 | .B readline | |
cce855bc JA |
10076 | is being used, \fBbash\fP will attempt to perform hostname completion when a |
10077 | word containing a \fB@\fP is being completed (see | |
ccc6cda3 JA |
10078 | .B Completing |
10079 | under | |
10080 | .SM | |
10081 | .B READLINE | |
10082 | above). | |
10083 | This is enabled by default. | |
10084 | .TP 8 | |
cce855bc JA |
10085 | .B huponexit |
10086 | If set, \fBbash\fP will send | |
10087 | .SM | |
10088 | .B SIGHUP | |
10089 | to all jobs when an interactive login shell exits. | |
10090 | .TP 8 | |
a0c0a00f CR |
10091 | .B inherit_errexit |
10092 | If set, command substitution inherits the value of the \fBerrexit\fP option, | |
10093 | instead of unsetting it in the subshell environment. | |
10094 | This option is enabled when \fIposix mode\fP is enabled. | |
10095 | .TP 8 | |
ccc6cda3 JA |
10096 | .B interactive_comments |
10097 | If set, allow a word beginning with | |
10098 | .B # | |
10099 | to cause that word and all remaining characters on that | |
10100 | line to be ignored in an interactive shell (see | |
10101 | .SM | |
10102 | .B COMMENTS | |
10103 | above). This option is enabled by default. | |
10104 | .TP 8 | |
495aee44 CR |
10105 | .B lastpipe |
10106 | If set, and job control is not active, the shell runs the last command of | |
10107 | a pipeline not executed in the background in the current shell environment. | |
10108 | .TP 8 | |
ccc6cda3 JA |
10109 | .B lithist |
10110 | If set, and the | |
10111 | .B cmdhist | |
10112 | option is enabled, multi-line commands are saved to the history with | |
10113 | embedded newlines rather than using semicolon separators where possible. | |
10114 | .TP 8 | |
9a51695b CR |
10115 | .B localvar_inherit |
10116 | If set, local variables inherit the value and attributes of a variable of | |
10117 | the same name that exists at a previous scope before any new value is | |
10118 | assigned. The nameref attribute is not inherited. | |
10119 | .TP 8 | |
2ae59c11 CR |
10120 | .B localvar_unset |
10121 | If set, calling \fBunset\fP on local variables in previous function scopes | |
10122 | marks them so subsequent lookups find them unset until that function | |
10123 | returns. This is identical to the behavior of unsetting local variables | |
10124 | at the current function scope. | |
10125 | .TP 8 | |
f73dda09 JA |
10126 | .B login_shell |
10127 | The shell sets this option if it is started as a login shell (see | |
10128 | .SM | |
10129 | .B "INVOCATION" | |
10130 | above). | |
10131 | The value may not be changed. | |
10132 | .TP 8 | |
ccc6cda3 | 10133 | .B mailwarn |
a0c0a00f | 10134 | If set, and a file that \fBbash\fP is checking for mail has been |
ccc6cda3 JA |
10135 | accessed since the last time it was checked, the message ``The mail in |
10136 | \fImailfile\fP has been read'' is displayed. | |
10137 | .TP 8 | |
bb70624e JA |
10138 | .B no_empty_cmd_completion |
10139 | If set, and | |
10140 | .B readline | |
10141 | is being used, | |
10142 | .B bash | |
0001803f CR |
10143 | will not attempt to search the |
10144 | .SM | |
10145 | .B PATH | |
10146 | for possible completions when | |
bb70624e JA |
10147 | completion is attempted on an empty line. |
10148 | .TP 8 | |
cce855bc JA |
10149 | .B nocaseglob |
10150 | If set, | |
10151 | .B bash | |
10152 | matches filenames in a case\-insensitive fashion when performing pathname | |
10153 | expansion (see | |
10154 | .B Pathname Expansion | |
10155 | above). | |
10156 | .TP 8 | |
95732b49 JA |
10157 | .B nocasematch |
10158 | If set, | |
10159 | .B bash | |
10160 | matches patterns in a case\-insensitive fashion when performing matching | |
a0c0a00f CR |
10161 | while executing \fBcase\fP or \fB[[\fP conditional commands, |
10162 | when performing pattern substitution word expansions, | |
10163 | or when filtering possible completions as part of programmable completion. | |
95732b49 | 10164 | .TP 8 |
ccc6cda3 JA |
10165 | .B nullglob |
10166 | If set, | |
10167 | .B bash | |
10168 | allows patterns which match no | |
10169 | files (see | |
10170 | .B Pathname Expansion | |
10171 | above) | |
10172 | to expand to a null string, rather than themselves. | |
10173 | .TP 8 | |
bb70624e JA |
10174 | .B progcomp |
10175 | If set, the programmable completion facilities (see | |
10176 | \fBProgrammable Completion\fP above) are enabled. | |
10177 | This option is enabled by default. | |
10178 | .TP 8 | |
2ae59c11 CR |
10179 | .B progcomp_alias |
10180 | If set, and programmable completion is enabled, \fBbash\fP treats a command | |
10181 | name that doesn't have any completions as a possible alias and attempts | |
10182 | alias expansion. If it has an alias, \fBbash\fP attempts programmable | |
10183 | completion using the command word resulting from the expanded alias. | |
10184 | .TP 8 | |
ccc6cda3 | 10185 | .B promptvars |
b80f6443 JA |
10186 | If set, prompt strings undergo |
10187 | parameter expansion, command substitution, arithmetic | |
10188 | expansion, and quote removal after being expanded as described in | |
ccc6cda3 JA |
10189 | .SM |
10190 | .B PROMPTING | |
10191 | above. This option is enabled by default. | |
10192 | .TP 8 | |
b72432fd JA |
10193 | .B restricted_shell |
10194 | The shell sets this option if it is started in restricted mode (see | |
10195 | .SM | |
10196 | .B "RESTRICTED SHELL" | |
10197 | below). | |
10198 | The value may not be changed. | |
10199 | This is not reset when the startup files are executed, allowing | |
10200 | the startup files to discover whether or not a shell is restricted. | |
10201 | .TP 8 | |
ccc6cda3 JA |
10202 | .B shift_verbose |
10203 | If set, the | |
10204 | .B shift | |
10205 | builtin prints an error message when the shift count exceeds the | |
10206 | number of positional parameters. | |
10207 | .TP 8 | |
10208 | .B sourcepath | |
10209 | If set, the | |
10210 | \fBsource\fP (\fB.\fP) builtin uses the value of | |
10211 | .SM | |
10212 | .B PATH | |
10213 | to find the directory containing the file supplied as an argument. | |
cce855bc | 10214 | This option is enabled by default. |
bb70624e JA |
10215 | .TP 8 |
10216 | .B xpg_echo | |
10217 | If set, the \fBecho\fP builtin expands backslash-escape sequences | |
10218 | by default. | |
ccc6cda3 | 10219 | .RE |
495aee44 | 10220 | .PD |
726f6388 JA |
10221 | .TP |
10222 | \fBsuspend\fP [\fB\-f\fP] | |
10223 | Suspend the execution of this shell until it receives a | |
10224 | .SM | |
10225 | .B SIGCONT | |
3185942a | 10226 | signal. A login shell cannot be suspended; the |
726f6388 | 10227 | .B \-f |
3185942a JA |
10228 | option can be used to override this and force the suspension. |
10229 | The return status is 0 unless the shell is a login shell and | |
726f6388 JA |
10230 | .B \-f |
10231 | is not supplied, or if job control is not enabled. | |
10232 | .TP | |
726f6388 | 10233 | \fBtest\fP \fIexpr\fP |
7117c2d2 | 10234 | .PD 0 |
726f6388 JA |
10235 | .TP |
10236 | \fB[\fP \fIexpr\fP \fB]\fP | |
ac50fbac | 10237 | Return a status of 0 (true) or 1 (false) depending on |
726f6388 JA |
10238 | the evaluation of the conditional expression |
10239 | .IR expr . | |
cce855bc JA |
10240 | Each operator and operand must be a separate argument. |
10241 | Expressions are composed of the primaries described above under | |
10242 | .SM | |
10243 | .BR "CONDITIONAL EXPRESSIONS" . | |
95732b49 JA |
10244 | \fBtest\fP does not accept any options, nor does it accept and ignore |
10245 | an argument of \fB\-\-\fP as signifying the end of options. | |
cce855bc JA |
10246 | .if t .sp 0.5 |
10247 | .if n .sp 1 | |
10248 | Expressions may be combined using the following operators, listed | |
10249 | in decreasing order of precedence. | |
3185942a | 10250 | The evaluation depends on the number of arguments; see below. |
495aee44 | 10251 | Operator precedence is used when there are five or more arguments. |
726f6388 JA |
10252 | .RS |
10253 | .PD 0 | |
10254 | .TP | |
726f6388 JA |
10255 | .B ! \fIexpr\fP |
10256 | True if | |
10257 | .I expr | |
10258 | is false. | |
10259 | .TP | |
cce855bc JA |
10260 | .B ( \fIexpr\fP ) |
10261 | Returns the value of \fIexpr\fP. | |
10262 | This may be used to override the normal precedence of operators. | |
10263 | .TP | |
726f6388 JA |
10264 | \fIexpr1\fP \-\fBa\fP \fIexpr2\fP |
10265 | True if both | |
10266 | .I expr1 | |
cce855bc | 10267 | and |
726f6388 JA |
10268 | .I expr2 |
10269 | are true. | |
10270 | .TP | |
10271 | \fIexpr1\fP \-\fBo\fP \fIexpr2\fP | |
10272 | True if either | |
10273 | .I expr1 | |
cce855bc | 10274 | or |
726f6388 JA |
10275 | .I expr2 |
10276 | is true. | |
cce855bc JA |
10277 | .PD |
10278 | .PP | |
10279 | \fBtest\fP and \fB[\fP evaluate conditional | |
10280 | expressions using a set of rules based on the number of arguments. | |
10281 | .if t .sp 0.5 | |
10282 | .if n .sp 1 | |
10283 | .PD 0 | |
726f6388 | 10284 | .TP |
cce855bc JA |
10285 | 0 arguments |
10286 | The expression is false. | |
10287 | .TP | |
10288 | 1 argument | |
10289 | The expression is true if and only if the argument is not null. | |
10290 | .TP | |
10291 | 2 arguments | |
10292 | If the first argument is \fB!\fP, the expression is true if and | |
10293 | only if the second argument is null. | |
10294 | If the first argument is one of the unary conditional operators listed above | |
10295 | under | |
726f6388 | 10296 | .SM |
cce855bc JA |
10297 | .BR "CONDITIONAL EXPRESSIONS" , |
10298 | the expression is true if the unary test is true. | |
10299 | If the first argument is not a valid unary conditional operator, the expression | |
10300 | is false. | |
10301 | .TP | |
10302 | 3 arguments | |
495aee44 | 10303 | The following conditions are applied in the order listed. |
cce855bc JA |
10304 | If the second argument is one of the binary conditional operators listed above |
10305 | under | |
10306 | .SM | |
10307 | .BR "CONDITIONAL EXPRESSIONS" , | |
10308 | the result of the expression is the result of the binary test using | |
10309 | the first and third arguments as operands. | |
3185942a | 10310 | The \fB\-a\fP and \fB\-o\fP operators are considered binary operators |
a0c0a00f | 10311 | when there are three arguments. |
cce855bc JA |
10312 | If the first argument is \fB!\fP, the value is the negation of |
10313 | the two-argument test using the second and third arguments. | |
10314 | If the first argument is exactly \fB(\fP and the third argument is | |
10315 | exactly \fB)\fP, the result is the one-argument test of the second | |
10316 | argument. | |
10317 | Otherwise, the expression is false. | |
cce855bc JA |
10318 | .TP |
10319 | 4 arguments | |
10320 | If the first argument is \fB!\fP, the result is the negation of | |
10321 | the three-argument expression composed of the remaining arguments. | |
a0c0a00f | 10322 | Otherwise, the expression is parsed and evaluated according to |
cce855bc JA |
10323 | precedence using the rules listed above. |
10324 | .TP | |
10325 | 5 or more arguments | |
10326 | The expression is parsed and evaluated according to precedence | |
10327 | using the rules listed above. | |
495aee44 CR |
10328 | .if t .sp 0.5 |
10329 | .if n .sp 1 | |
10330 | .LP | |
10331 | When used with \fBtest\fP or \fB[\fP, the \fB<\fP and \fB>\fP operators | |
10332 | sort lexicographically using ASCII ordering. | |
726f6388 | 10333 | .RE |
cce855bc | 10334 | .PD |
726f6388 JA |
10335 | .TP |
10336 | .B times | |
10337 | Print the accumulated user and system times for the shell and | |
10338 | for processes run from the shell. The return status is 0. | |
10339 | .TP | |
b80f6443 | 10340 | \fBtrap\fP [\fB\-lp\fP] [[\fIarg\fP] \fIsigspec\fP ...] |
726f6388 JA |
10341 | The command |
10342 | .I arg | |
10343 | is to be read and executed when the shell receives | |
10344 | signal(s) | |
10345 | .IR sigspec . | |
10346 | If | |
10347 | .I arg | |
b80f6443 | 10348 | is absent (and there is a single \fIsigspec\fP) or |
726f6388 | 10349 | .BR \- , |
b80f6443 JA |
10350 | each specified signal is |
10351 | reset to its original disposition (the value it had | |
d166f048 | 10352 | upon entrance to the shell). |
a0c0a00f | 10353 | If |
726f6388 | 10354 | .I arg |
d166f048 JA |
10355 | is the null string the signal specified by each |
10356 | .I sigspec | |
10357 | is ignored by the shell and by the commands it invokes. | |
ccc6cda3 JA |
10358 | If |
10359 | .I arg | |
bb70624e | 10360 | is not present and |
ccc6cda3 | 10361 | .B \-p |
bb70624e | 10362 | has been supplied, then the trap commands associated with each |
ccc6cda3 | 10363 | .I sigspec |
bb70624e JA |
10364 | are displayed. |
10365 | If no arguments are supplied or if only | |
ccc6cda3 JA |
10366 | .B \-p |
10367 | is given, | |
10368 | .B trap | |
b80f6443 JA |
10369 | prints the list of commands associated with each signal. |
10370 | The | |
10371 | .B \-l | |
10372 | option causes the shell to print a list of signal names and | |
10373 | their corresponding numbers. | |
d166f048 | 10374 | Each |
726f6388 JA |
10375 | .I sigspec |
10376 | is either | |
d166f048 | 10377 | a signal name defined in <\fIsignal.h\fP>, or a signal number. |
495aee44 CR |
10378 | Signal names are case insensitive and the |
10379 | .SM | |
10380 | .B SIG | |
10381 | prefix is optional. | |
0001803f CR |
10382 | .if t .sp 0.5 |
10383 | .if n .sp 1 | |
d166f048 | 10384 | If a |
726f6388 JA |
10385 | .I sigspec |
10386 | is | |
10387 | .SM | |
10388 | .B EXIT | |
10389 | (0) the command | |
10390 | .I arg | |
f73dda09 JA |
10391 | is executed on exit from the shell. |
10392 | If a | |
ccc6cda3 JA |
10393 | .I sigspec |
10394 | is | |
10395 | .SM | |
10396 | .BR DEBUG , | |
10397 | the command | |
10398 | .I arg | |
b80f6443 JA |
10399 | is executed before every \fIsimple command\fP, \fIfor\fP command, |
10400 | \fIcase\fP command, \fIselect\fP command, every arithmetic \fIfor\fP | |
10401 | command, and before the first command executes in a shell function (see | |
ccc6cda3 JA |
10402 | .SM |
10403 | .B SHELL GRAMMAR | |
10404 | above). | |
95732b49 | 10405 | Refer to the description of the \fBextdebug\fP option to the |
b80f6443 | 10406 | \fBshopt\fP builtin for details of its effect on the \fBDEBUG\fP trap. |
f73dda09 JA |
10407 | If a |
10408 | .I sigspec | |
10409 | is | |
10410 | .SM | |
0001803f CR |
10411 | .BR RETURN , |
10412 | the command | |
10413 | .I arg | |
495aee44 CR |
10414 | is executed each time a shell function or a script executed with |
10415 | the \fB.\fP or \fBsource\fP builtins finishes executing. | |
0001803f CR |
10416 | .if t .sp 0.5 |
10417 | .if n .sp 1 | |
10418 | If a | |
10419 | .I sigspec | |
10420 | is | |
10421 | .SM | |
f73dda09 JA |
10422 | .BR ERR , |
10423 | the command | |
10424 | .I arg | |
a0c0a00f | 10425 | is executed whenever |
ac50fbac | 10426 | a pipeline (which may consist of a single simple |
a0c0a00f | 10427 | command), a list, or a compound command returns a |
ac50fbac | 10428 | non\-zero exit status, |
b80f6443 | 10429 | subject to the following conditions. |
f73dda09 JA |
10430 | The |
10431 | .SM | |
b80f6443 JA |
10432 | .B ERR |
10433 | trap is not executed if the failed | |
10434 | command is part of the command list immediately following a | |
10435 | .B while | |
f73dda09 | 10436 | or |
b80f6443 | 10437 | .B until |
a0c0a00f | 10438 | keyword, |
b80f6443 | 10439 | part of the test in an |
f73dda09 | 10440 | .I if |
3185942a | 10441 | statement, part of a command executed in a |
f73dda09 JA |
10442 | .B && |
10443 | or | |
495aee44 | 10444 | .B || |
ac50fbac CR |
10445 | list except the command following the final \fB&&\fP or \fB||\fP, |
10446 | any command in a pipeline but the last, | |
10447 | or if the command's return value is | |
10448 | being inverted using | |
f73dda09 | 10449 | .BR ! . |
ac50fbac | 10450 | These are the same conditions obeyed by the \fBerrexit\fP (\fB\-e\fP) option. |
0001803f CR |
10451 | .if t .sp 0.5 |
10452 | .if n .sp 1 | |
726f6388 | 10453 | Signals ignored upon entry to the shell cannot be trapped or reset. |
0628567a | 10454 | Trapped signals that are not being ignored are reset to their original |
0001803f | 10455 | values in a subshell or subshell environment when one is created. |
d166f048 | 10456 | The return status is false if any |
ccc6cda3 JA |
10457 | .I sigspec |
10458 | is invalid; otherwise | |
726f6388 JA |
10459 | .B trap |
10460 | returns true. | |
10461 | .TP | |
7117c2d2 | 10462 | \fBtype\fP [\fB\-aftpP\fP] \fIname\fP [\fIname\fP ...] |
a0c0a00f | 10463 | With no options, |
726f6388 JA |
10464 | indicate how each |
10465 | .I name | |
10466 | would be interpreted if used as a command name. | |
10467 | If the | |
cce855bc JA |
10468 | .B \-t |
10469 | option is used, | |
726f6388 | 10470 | .B type |
ccc6cda3 | 10471 | prints a string which is one of |
726f6388 JA |
10472 | .IR alias , |
10473 | .IR keyword , | |
10474 | .IR function , | |
10475 | .IR builtin , | |
10476 | or | |
a0c0a00f | 10477 | .I file |
726f6388 JA |
10478 | if |
10479 | .I name | |
10480 | is an alias, shell reserved word, function, builtin, or disk file, | |
ccc6cda3 JA |
10481 | respectively. |
10482 | If the | |
10483 | .I name | |
10484 | is not found, then nothing is printed, and an exit status of false | |
10485 | is returned. | |
726f6388 | 10486 | If the |
cce855bc JA |
10487 | .B \-p |
10488 | option is used, | |
726f6388 JA |
10489 | .B type |
10490 | either returns the name of the disk file | |
10491 | that would be executed if | |
10492 | .I name | |
10493 | were specified as a command name, | |
28ef6c31 JA |
10494 | or nothing if |
10495 | .if t \f(CWtype -t name\fP | |
10496 | .if n ``type -t name'' | |
726f6388 JA |
10497 | would not return |
10498 | .IR file . | |
7117c2d2 JA |
10499 | The |
10500 | .B \-P | |
10501 | option forces a | |
10502 | .SM | |
10503 | .B PATH | |
10504 | search for each \fIname\fP, even if | |
10505 | .if t \f(CWtype -t name\fP | |
10506 | .if n ``type -t name'' | |
10507 | would not return | |
10508 | .IR file . | |
726f6388 | 10509 | If a command is hashed, |
cce855bc | 10510 | .B \-p |
7117c2d2 JA |
10511 | and |
10512 | .B \-P | |
ac50fbac | 10513 | print the hashed value, which is not necessarily the file that appears |
a0c0a00f | 10514 | first in |
726f6388 JA |
10515 | .SM |
10516 | .BR PATH . | |
10517 | If the | |
cce855bc | 10518 | .B \-a |
a0c0a00f | 10519 | option is used, |
726f6388 JA |
10520 | .B type |
10521 | prints all of the places that contain | |
a0c0a00f | 10522 | an executable named |
726f6388 JA |
10523 | .IR name . |
10524 | This includes aliases and functions, | |
a0c0a00f | 10525 | if and only if the |
cce855bc JA |
10526 | .B \-p |
10527 | option is not also used. | |
726f6388 JA |
10528 | The table of hashed commands is not consulted |
10529 | when using | |
cce855bc | 10530 | .BR \-a . |
7117c2d2 JA |
10531 | The |
10532 | .B \-f | |
10533 | option suppresses shell function lookup, as with the \fBcommand\fP builtin. | |
726f6388 | 10534 | .B type |
3185942a JA |
10535 | returns true if all of the arguments are found, false if |
10536 | any are not found. | |
726f6388 | 10537 | .TP |
a0c0a00f | 10538 | \fBulimit\fP [\fB\-HSabcdefiklmnpqrstuvxPT\fP [\fIlimit\fP]] |
ccc6cda3 | 10539 | Provides control over the resources available to the shell and to |
f73dda09 | 10540 | processes started by it, on systems that allow such control. |
ccc6cda3 | 10541 | The \fB\-H\fP and \fB\-S\fP options specify that the hard or soft limit is |
3185942a JA |
10542 | set for the given resource. |
10543 | A hard limit cannot be increased by a non-root user once it is set; | |
10544 | a soft limit may be increased up to the value of the hard limit. | |
ccc6cda3 JA |
10545 | If neither \fB\-H\fP nor \fB\-S\fP is specified, both the soft and hard |
10546 | limits are set. | |
f73dda09 JA |
10547 | The value of |
10548 | .I limit | |
10549 | can be a number in the unit specified for the resource | |
10550 | or one of the special values | |
10551 | .BR hard , | |
10552 | .BR soft , | |
10553 | or | |
10554 | .BR unlimited , | |
10555 | which stand for the current hard limit, the current soft limit, and | |
10556 | no limit, respectively. | |
ccc6cda3 | 10557 | If |
726f6388 JA |
10558 | .I limit |
10559 | is omitted, the current value of the soft limit of the resource is | |
ccc6cda3 JA |
10560 | printed, unless the \fB\-H\fP option is given. When more than one |
10561 | resource is specified, the limit name and unit are printed before the value. | |
726f6388 JA |
10562 | Other options are interpreted as follows: |
10563 | .RS | |
10564 | .PD 0 | |
10565 | .TP | |
10566 | .B \-a | |
ccc6cda3 | 10567 | All current limits are reported |
726f6388 | 10568 | .TP |
3185942a JA |
10569 | .B \-b |
10570 | The maximum socket buffer size | |
10571 | .TP | |
726f6388 | 10572 | .B \-c |
ccc6cda3 | 10573 | The maximum size of core files created |
726f6388 JA |
10574 | .TP |
10575 | .B \-d | |
ccc6cda3 | 10576 | The maximum size of a process's data segment |
726f6388 | 10577 | .TP |
0628567a JA |
10578 | .B \-e |
10579 | The maximum scheduling priority ("nice") | |
10580 | .TP | |
726f6388 | 10581 | .B \-f |
0628567a JA |
10582 | The maximum size of files written by the shell and its children |
10583 | .TP | |
10584 | .B \-i | |
10585 | The maximum number of pending signals | |
726f6388 | 10586 | .TP |
a0c0a00f CR |
10587 | .B \-k |
10588 | The maximum number of kqueues that may be allocated | |
10589 | .TP | |
ccc6cda3 JA |
10590 | .B \-l |
10591 | The maximum size that may be locked into memory | |
726f6388 | 10592 | .TP |
ccc6cda3 | 10593 | .B \-m |
17345e5a | 10594 | The maximum resident set size (many systems do not honor this limit) |
726f6388 | 10595 | .TP |
ccc6cda3 JA |
10596 | .B \-n |
10597 | The maximum number of open file descriptors (most systems do not | |
10598 | allow this value to be set) | |
726f6388 JA |
10599 | .TP |
10600 | .B \-p | |
ccc6cda3 | 10601 | The pipe size in 512-byte blocks (this may not be set) |
726f6388 | 10602 | .TP |
0628567a JA |
10603 | .B \-q |
10604 | The maximum number of bytes in POSIX message queues | |
10605 | .TP | |
10606 | .B \-r | |
10607 | The maximum real-time scheduling priority | |
10608 | .TP | |
ccc6cda3 JA |
10609 | .B \-s |
10610 | The maximum stack size | |
10611 | .TP | |
10612 | .B \-t | |
10613 | The maximum amount of cpu time in seconds | |
726f6388 JA |
10614 | .TP |
10615 | .B \-u | |
ccc6cda3 | 10616 | The maximum number of processes available to a single user |
726f6388 JA |
10617 | .TP |
10618 | .B \-v | |
495aee44 CR |
10619 | The maximum amount of virtual memory available to the shell and, on |
10620 | some systems, to its children | |
0628567a JA |
10621 | .TP |
10622 | .B \-x | |
10623 | The maximum number of file locks | |
3185942a | 10624 | .TP |
a0c0a00f CR |
10625 | .B \-P |
10626 | The maximum number of pseudoterminals | |
10627 | .TP | |
3185942a JA |
10628 | .B \-T |
10629 | The maximum number of threads | |
726f6388 JA |
10630 | .PD |
10631 | .PP | |
ccc6cda3 | 10632 | If |
726f6388 | 10633 | .I limit |
ac50fbac | 10634 | is given, and the |
726f6388 | 10635 | .B \-a |
ac50fbac CR |
10636 | option is not used, |
10637 | \fIlimit\fP is the new value of the specified resource. | |
726f6388 JA |
10638 | If no option is given, then |
10639 | .B \-f | |
10640 | is assumed. Values are in 1024-byte increments, except for | |
10641 | .BR \-t , | |
ac50fbac | 10642 | which is in seconds; |
726f6388 | 10643 | .BR \-p , |
ac50fbac | 10644 | which is in units of 512-byte blocks; |
a0c0a00f | 10645 | .BR \-P , |
3185942a JA |
10646 | .BR \-T , |
10647 | .BR \-b , | |
a0c0a00f | 10648 | .BR \-k , |
3185942a | 10649 | .BR \-n , |
726f6388 JA |
10650 | and |
10651 | .BR \-u , | |
a0c0a00f | 10652 | which are unscaled values; |
2f5dfe5a | 10653 | and, when in posix mode, |
a0c0a00f CR |
10654 | .B \-c |
10655 | and | |
10656 | .BR \-f , | |
10657 | which are in 512-byte increments. | |
f73dda09 JA |
10658 | The return status is 0 unless an invalid option or argument is supplied, |
10659 | or an error occurs while setting a new limit. | |
726f6388 JA |
10660 | .RE |
10661 | .TP | |
cce855bc | 10662 | \fBumask\fP [\fB\-p\fP] [\fB\-S\fP] [\fImode\fP] |
a0c0a00f | 10663 | The user file-creation mask is set to |
726f6388 JA |
10664 | .IR mode . |
10665 | If | |
10666 | .I mode | |
10667 | begins with a digit, it | |
10668 | is interpreted as an octal number; otherwise | |
10669 | it is interpreted as a symbolic mode mask similar | |
10670 | to that accepted by | |
10671 | .IR chmod (1). | |
10672 | If | |
10673 | .I mode | |
bb70624e | 10674 | is omitted, the current value of the mask is printed. |
ccc6cda3 | 10675 | The |
726f6388 JA |
10676 | .B \-S |
10677 | option causes the mask to be printed in symbolic form; the | |
10678 | default output is an octal number. | |
cce855bc JA |
10679 | If the |
10680 | .B \-p | |
10681 | option is supplied, and | |
10682 | .I mode | |
10683 | is omitted, the output is in a form that may be reused as input. | |
ccc6cda3 | 10684 | The return status is 0 if the mode was successfully changed or if |
726f6388 JA |
10685 | no \fImode\fP argument was supplied, and false otherwise. |
10686 | .TP | |
10687 | \fBunalias\fP [\-\fBa\fP] [\fIname\fP ...] | |
bb70624e | 10688 | Remove each \fIname\fP from the list of defined aliases. If |
726f6388 JA |
10689 | .B \-a |
10690 | is supplied, all alias definitions are removed. The return | |
10691 | value is true unless a supplied | |
10692 | .I name | |
10693 | is not a defined alias. | |
10694 | .TP | |
ac50fbac | 10695 | \fBunset\fP [\-\fBfv\fP] [\-\fBn\fP] [\fIname\fP ...] |
726f6388 JA |
10696 | For each |
10697 | .IR name , | |
ccc6cda3 | 10698 | remove the corresponding variable or function. |
ac50fbac | 10699 | If the |
ccc6cda3 JA |
10700 | .B \-v |
10701 | option is given, each | |
10702 | .I name | |
ac50fbac | 10703 | refers to a shell variable, and that variable is removed. |
ccc6cda3 JA |
10704 | Read-only variables may not be unset. |
10705 | If | |
726f6388 | 10706 | .B \-f |
95732b49 | 10707 | is specified, each |
ccc6cda3 JA |
10708 | .I name |
10709 | refers to a shell function, and the function definition | |
10710 | is removed. | |
ac50fbac CR |
10711 | If the |
10712 | .B \-n | |
10713 | option is supplied, and \fIname\fP is a variable with the \fInameref\fP | |
10714 | attribute, \fIname\fP will be unset rather than the variable it | |
10715 | references. | |
10716 | \fB\-n\fP has no effect if the \fB\-f\fP option is supplied. | |
10717 | If no options are supplied, each \fIname\fP refers to a variable; if | |
10718 | there is no variable by that name, any function with that name is | |
10719 | unset. | |
ccc6cda3 JA |
10720 | Each unset variable or function is removed from the environment |
10721 | passed to subsequent commands. | |
10722 | If any of | |
726f6388 | 10723 | .SM |
0001803f CR |
10724 | .BR COMP_WORDBREAKS , |
10725 | .SM | |
726f6388 JA |
10726 | .BR RANDOM , |
10727 | .SM | |
10728 | .BR SECONDS , | |
10729 | .SM | |
10730 | .BR LINENO , | |
ccc6cda3 JA |
10731 | .SM |
10732 | .BR HISTCMD , | |
bb70624e JA |
10733 | .SM |
10734 | .BR FUNCNAME , | |
10735 | .SM | |
10736 | .BR GROUPS , | |
726f6388 JA |
10737 | or |
10738 | .SM | |
ccc6cda3 | 10739 | .B DIRSTACK |
726f6388 JA |
10740 | are unset, they lose their special properties, even if they are |
10741 | subsequently reset. The exit status is true unless a | |
10742 | .I name | |
b80f6443 | 10743 | is readonly. |
726f6388 | 10744 | .TP |
9a51695b | 10745 | \fBwait\fP [\fB\-fn\fP] [\fIid ...\fP] |
ac50fbac | 10746 | Wait for each specified child process and return its termination status. |
95732b49 | 10747 | Each |
9a51695b | 10748 | .I id |
726f6388 JA |
10749 | may be a process |
10750 | ID or a job specification; if a job spec is given, all processes | |
10751 | in that job's pipeline are waited for. If | |
9a51695b | 10752 | .I id |
726f6388 | 10753 | is not given, all currently active child processes |
ac50fbac CR |
10754 | are waited for, and the return status is zero. |
10755 | If the \fB\-n\fP option is supplied, \fBwait\fP waits for any job to | |
10756 | terminate and returns its exit status. | |
9a51695b CR |
10757 | If the \fB\-f\fP option is supplied, and job control is enabled, |
10758 | \fBwait\fP forces \fIid\fP to terminate before returning its status, | |
10759 | instead of returning when it changes status. | |
ac50fbac | 10760 | If |
9a51695b | 10761 | .I id |
ccc6cda3 | 10762 | specifies a non-existent process or job, the return status is |
726f6388 JA |
10763 | 127. Otherwise, the return status is the exit status of the last |
10764 | process or job waited for. | |
10765 | .\" bash_builtins | |
10766 | .if \n(zZ=1 .ig zZ | |
ccc6cda3 | 10767 | .SH "RESTRICTED SHELL" |
bb70624e JA |
10768 | .\" rbash.1 |
10769 | .zY | |
726f6388 | 10770 | .PP |
ccc6cda3 | 10771 | If |
726f6388 | 10772 | .B bash |
ccc6cda3 JA |
10773 | is started with the name |
10774 | .BR rbash , | |
10775 | or the | |
10776 | .B \-r | |
10777 | option is supplied at invocation, | |
10778 | the shell becomes restricted. | |
10779 | A restricted shell is used to | |
10780 | set up an environment more controlled than the standard shell. | |
10781 | It behaves identically to | |
10782 | .B bash | |
cce855bc | 10783 | with the exception that the following are disallowed or not performed: |
ccc6cda3 JA |
10784 | .IP \(bu |
10785 | changing directories with \fBcd\fP | |
10786 | .IP \(bu | |
10787 | setting or unsetting the values of | |
0001803f | 10788 | .SM |
b72432fd | 10789 | .BR SHELL , |
0001803f | 10790 | .SM |
b72432fd | 10791 | .BR PATH , |
0001803f | 10792 | .SM |
b72432fd | 10793 | .BR ENV , |
ccc6cda3 | 10794 | or |
0001803f | 10795 | .SM |
b72432fd | 10796 | .B BASH_ENV |
ccc6cda3 JA |
10797 | .IP \(bu |
10798 | specifying command names containing | |
10799 | .B / | |
10800 | .IP \(bu | |
ac50fbac | 10801 | specifying a filename containing a |
ccc6cda3 JA |
10802 | .B / |
10803 | as an argument to the | |
10804 | .B . | |
10805 | builtin command | |
10806 | .IP \(bu | |
495aee44 | 10807 | specifying a filename containing a slash as an argument to the |
bb70624e JA |
10808 | .B \-p |
10809 | option to the | |
10810 | .B hash | |
10811 | builtin command | |
10812 | .IP \(bu | |
ccc6cda3 JA |
10813 | importing function definitions from the shell environment at startup |
10814 | .IP \(bu | |
0001803f CR |
10815 | parsing the value of |
10816 | .SM | |
10817 | .B SHELLOPTS | |
10818 | from the shell environment at startup | |
cce855bc | 10819 | .IP \(bu |
ccc6cda3 JA |
10820 | redirecting output using the >, >|, <>, >&, &>, and >> redirection operators |
10821 | .IP \(bu | |
10822 | using the | |
10823 | .B exec | |
10824 | builtin command to replace the shell with another command | |
10825 | .IP \(bu | |
10826 | adding or deleting builtin commands with the | |
10827 | .B \-f | |
726f6388 | 10828 | and |
ccc6cda3 JA |
10829 | .B \-d |
10830 | options to the | |
10831 | .B enable | |
10832 | builtin command | |
10833 | .IP \(bu | |
495aee44 | 10834 | using the \fBenable\fP builtin command to enable disabled shell builtins |
7117c2d2 | 10835 | .IP \(bu |
ccc6cda3 JA |
10836 | specifying the |
10837 | .B \-p | |
10838 | option to the | |
10839 | .B command | |
10840 | builtin command | |
10841 | .IP \(bu | |
10842 | turning off restricted mode with | |
cce855bc | 10843 | \fBset +r\fP or \fBset +o restricted\fP. |
726f6388 | 10844 | .PP |
ccc6cda3 JA |
10845 | These restrictions are enforced after any startup files are read. |
10846 | .PP | |
b80f6443 JA |
10847 | .ie \n(zY=1 When a command that is found to be a shell script is executed, |
10848 | .el \{ When a command that is found to be a shell script is executed | |
10849 | (see | |
ccc6cda3 JA |
10850 | .SM |
10851 | .B "COMMAND EXECUTION" | |
10852 | above), | |
b80f6443 | 10853 | \} |
ccc6cda3 JA |
10854 | .B rbash |
10855 | turns off any restrictions in the shell spawned to execute the | |
10856 | script. | |
bb70624e JA |
10857 | .\" end of rbash.1 |
10858 | .if \n(zY=1 .ig zY | |
726f6388 JA |
10859 | .SH "SEE ALSO" |
10860 | .PD 0 | |
10861 | .TP | |
bb70624e | 10862 | \fIBash Reference Manual\fP, Brian Fox and Chet Ramey |
726f6388 JA |
10863 | .TP |
10864 | \fIThe Gnu Readline Library\fP, Brian Fox and Chet Ramey | |
10865 | .TP | |
10866 | \fIThe Gnu History Library\fP, Brian Fox and Chet Ramey | |
10867 | .TP | |
ac50fbac CR |
10868 | \fIPortable Operating System Interface (POSIX) Part 2: Shell and Utilities\fP, IEEE -- |
10869 | http://pubs.opengroup.org/onlinepubs/9699919799/ | |
10870 | .TP | |
10871 | http://tiswww.case.edu/~chet/bash/POSIX -- a description of posix mode | |
726f6388 JA |
10872 | .TP |
10873 | \fIsh\fP(1), \fIksh\fP(1), \fIcsh\fP(1) | |
10874 | .TP | |
10875 | \fIemacs\fP(1), \fIvi\fP(1) | |
10876 | .TP | |
10877 | \fIreadline\fP(3) | |
10878 | .PD | |
10879 | .SH FILES | |
10880 | .PD 0 | |
10881 | .TP | |
10882 | .FN /bin/bash | |
10883 | The \fBbash\fP executable | |
10884 | .TP | |
10885 | .FN /etc/profile | |
10886 | The systemwide initialization file, executed for login shells | |
10887 | .TP | |
10888 | .FN ~/.bash_profile | |
10889 | The personal initialization file, executed for login shells | |
10890 | .TP | |
10891 | .FN ~/.bashrc | |
10892 | The individual per-interactive-shell startup file | |
10893 | .TP | |
b72432fd JA |
10894 | .FN ~/.bash_logout |
10895 | The individual login shell cleanup file, executed when a login shell exits | |
10896 | .TP | |
726f6388 JA |
10897 | .FN ~/.inputrc |
10898 | Individual \fIreadline\fP initialization file | |
10899 | .PD | |
10900 | .SH AUTHORS | |
ccc6cda3 | 10901 | Brian Fox, Free Software Foundation |
726f6388 | 10902 | .br |
bb70624e | 10903 | bfox@gnu.org |
726f6388 JA |
10904 | .PP |
10905 | Chet Ramey, Case Western Reserve University | |
10906 | .br | |
17345e5a | 10907 | chet.ramey@case.edu |
726f6388 JA |
10908 | .SH BUG REPORTS |
10909 | If you find a bug in | |
10910 | .B bash, | |
10911 | you should report it. But first, you should | |
10912 | make sure that it really is a bug, and that it appears in the latest | |
10913 | version of | |
b80f6443 JA |
10914 | .BR bash . |
10915 | The latest version is always available from | |
495aee44 | 10916 | \fIftp://ftp.gnu.org/pub/gnu/bash/\fP. |
726f6388 JA |
10917 | .PP |
10918 | Once you have determined that a bug actually exists, use the | |
10919 | .I bashbug | |
10920 | command to submit a bug report. | |
d166f048 | 10921 | If you have a fix, you are encouraged to mail that as well! |
726f6388 | 10922 | Suggestions and `philosophical' bug reports may be mailed |
cce855bc | 10923 | to \fIbug-bash@gnu.org\fP or posted to the Usenet |
726f6388 JA |
10924 | newsgroup |
10925 | .BR gnu.bash.bug . | |
10926 | .PP | |
10927 | ALL bug reports should include: | |
10928 | .PP | |
10929 | .PD 0 | |
10930 | .TP 20 | |
10931 | The version number of \fBbash\fR | |
10932 | .TP | |
10933 | The hardware and operating system | |
10934 | .TP | |
10935 | The compiler used to compile | |
10936 | .TP | |
10937 | A description of the bug behaviour | |
10938 | .TP | |
10939 | A short script or `recipe' which exercises the bug | |
10940 | .PD | |
10941 | .PP | |
10942 | .I bashbug | |
10943 | inserts the first three items automatically into the template | |
10944 | it provides for filing a bug report. | |
10945 | .PP | |
10946 | Comments and bug reports concerning | |
10947 | this manual page should be directed to | |
495aee44 | 10948 | .IR chet.ramey@case.edu . |
726f6388 JA |
10949 | .SH BUGS |
10950 | .PP | |
10951 | It's too big and too slow. | |
10952 | .PP | |
a0c0a00f | 10953 | There are some subtle differences between |
726f6388 JA |
10954 | .B bash |
10955 | and traditional versions of | |
10956 | .BR sh , | |
10957 | mostly because of the | |
10958 | .SM | |
10959 | .B POSIX | |
10960 | specification. | |
10961 | .PP | |
10962 | Aliases are confusing in some uses. | |
ccc6cda3 JA |
10963 | .PP |
10964 | Shell builtin commands and functions are not stoppable/restartable. | |
10965 | .PP | |
10966 | Compound commands and command sequences of the form `a ; b ; c' | |
10967 | are not handled gracefully when process suspension is attempted. | |
10968 | When a process is stopped, the shell immediately executes the next | |
10969 | command in the sequence. | |
10970 | It suffices to place the sequence of commands between | |
10971 | parentheses to force it into a subshell, which may be stopped as | |
10972 | a unit. | |
10973 | .PP | |
ccc6cda3 | 10974 | Array variables may not (yet) be exported. |
3185942a JA |
10975 | .PP |
10976 | There may be only one active coprocess at a time. | |
726f6388 | 10977 | .zZ |
bb70624e | 10978 | .zY |