]>
Commit | Line | Data |
---|---|---|
726f6388 JA |
1 | .\" |
2 | .\" MAN PAGE COMMENTS to | |
3 | .\" | |
4 | .\" Chet Ramey | |
5 | .\" Information Network Services | |
6 | .\" Case Western Reserve University | |
7 | .\" chet@ins.CWRU.Edu | |
8 | .\" | |
f73dda09 | 9 | .\" Last Change: Tue Nov 13 12:55:51 EST 2001 |
726f6388 JA |
10 | .\" |
11 | .\" bash_builtins, strip all but Built-Ins section | |
12 | .if \n(zZ=1 .ig zZ | |
bb70624e | 13 | .if \n(zY=1 .ig zY |
f73dda09 | 14 | .TH BASH 1 "2001 November 13" "GNU Bash-2.05a" |
726f6388 JA |
15 | .\" |
16 | .\" There's some problem with having a `@' | |
17 | .\" in a tagged paragraph with the BSD man macros. | |
18 | .\" It has to do with `@' appearing in the }1 macro. | |
19 | .\" This is a problem on 4.3 BSD and Ultrix, but Sun | |
20 | .\" appears to have fixed it. | |
21 | .\" If you're seeing the characters | |
22 | .\" `@u-3p' appearing before the lines reading | |
23 | .\" `possible-hostname-completions | |
24 | .\" and `complete-hostname' down in READLINE, | |
25 | .\" then uncomment this redefinition. | |
26 | .\" | |
27 | .de }1 | |
28 | .ds ]X \&\\*(]B\\ | |
29 | .nr )E 0 | |
30 | .if !"\\$1"" .nr )I \\$1n | |
31 | .}f | |
32 | .ll \\n(LLu | |
33 | .in \\n()Ru+\\n(INu+\\n()Iu | |
34 | .ti \\n(INu | |
35 | .ie !\\n()Iu+\\n()Ru-\w\a\\*(]X\au-3p \{\\*(]X | |
36 | .br\} | |
37 | .el \\*(]X\h\a|\\n()Iu+\\n()Ru\a\c | |
38 | .}f | |
39 | .. | |
40 | .\" | |
41 | .\" File Name macro. This used to be `.PN', for Path Name, | |
42 | .\" but Sun doesn't seem to like that very much. | |
43 | .\" | |
44 | .de FN | |
45 | \fI\|\\$1\|\fP | |
46 | .. | |
47 | .SH NAME | |
ccc6cda3 | 48 | bash \- GNU Bourne-Again SHell |
726f6388 JA |
49 | .SH SYNOPSIS |
50 | .B bash | |
51 | [options] | |
52 | [file] | |
53 | .SH COPYRIGHT | |
28ef6c31 JA |
54 | .if n Bash is Copyright (C) 1989-2001 by the Free Software Foundation, Inc. |
55 | .if t Bash is Copyright \(co 1989-2001 by the Free Software Foundation, Inc. | |
726f6388 JA |
56 | .SH DESCRIPTION |
57 | .B Bash | |
ccc6cda3 | 58 | is an \fBsh\fR-compatible command language interpreter that |
726f6388 JA |
59 | executes commands read from the standard input or from a file. |
60 | .B Bash | |
61 | also incorporates useful features from the \fIKorn\fP and \fIC\fP | |
62 | shells (\fBksh\fP and \fBcsh\fP). | |
63 | .PP | |
64 | .B Bash | |
cce855bc | 65 | is intended to be a conformant implementation of the IEEE |
ccc6cda3 | 66 | POSIX Shell and Tools specification (IEEE Working Group 1003\.2). |
726f6388 | 67 | .SH OPTIONS |
ccc6cda3 | 68 | In addition to the single-character shell options documented in the |
726f6388 | 69 | description of the \fBset\fR builtin command, \fBbash\fR |
cce855bc | 70 | interprets the following options when it is invoked: |
726f6388 JA |
71 | .PP |
72 | .PD 0 | |
73 | .TP 10 | |
74 | .BI \-c "\| string\^" | |
ccc6cda3 | 75 | If the |
726f6388 | 76 | .B \-c |
cce855bc | 77 | option is present, then commands are read from |
726f6388 JA |
78 | .IR string . |
79 | If there are arguments after the | |
80 | .IR string , | |
81 | they are assigned to the positional parameters, starting with | |
82 | .BR $0 . | |
83 | .TP | |
ccc6cda3 JA |
84 | .B \-r |
85 | If the | |
86 | .B \-r | |
cce855bc | 87 | option is present, the shell becomes |
ccc6cda3 JA |
88 | .I restricted |
89 | (see | |
90 | .SM | |
91 | .B "RESTRICTED SHELL" | |
92 | below). | |
93 | .TP | |
726f6388 JA |
94 | .B \-i |
95 | If the | |
96 | .B \-i | |
cce855bc | 97 | option is present, the shell is |
726f6388 JA |
98 | .IR interactive . |
99 | .TP | |
100 | .B \-s | |
101 | If the | |
102 | .B \-s | |
cce855bc | 103 | option is present, or if no arguments remain after option |
726f6388 JA |
104 | processing, then commands are read from the standard input. |
105 | This option allows the positional parameters to be set | |
106 | when invoking an interactive shell. | |
107 | .TP | |
ccc6cda3 JA |
108 | .B \-D |
109 | A list of all double-quoted strings preceded by \fB$\fP | |
110 | is printed on the standard ouput. | |
111 | These are the strings that | |
112 | are subject to language translation when the current locale | |
28ef6c31 | 113 | is not \fBC\fP or \fBPOSIX\fP. |
ccc6cda3 JA |
114 | This implies the \fB\-n\fP option; no commands will be executed. |
115 | .TP | |
f73dda09 JA |
116 | .B [\-+]O [\fIshopt_option\fP] |
117 | \fIshopt_option\fP is one of the shell options accepted by the | |
118 | \fBshopt\fP builtin (see | |
119 | .SM | |
120 | .B SHELL BUILTIN COMMANDS | |
121 | below). | |
122 | If \fIshopt_option\fP is present, \fB\-O\fP sets the value of that option; | |
123 | \fB+O\fP unsets it. | |
124 | If \fIshopt_option\fP is not supplied, the names and values of the shell | |
125 | options accepted by \fBshopt\fP are printed on the standard output. | |
126 | If the invocation option is \fB+O\fP, the output is displayed in a format | |
127 | that may be reused as input. | |
128 | .TP | |
ccc6cda3 JA |
129 | .B \-\- |
130 | A | |
131 | .B \-\- | |
726f6388 JA |
132 | signals the end of options and disables further option processing. |
133 | Any arguments after the | |
726f6388 | 134 | .B \-\- |
ccc6cda3 JA |
135 | are treated as filenames and arguments. An argument of |
136 | .B \- | |
137 | is equivalent to \fB\-\-\fP. | |
726f6388 JA |
138 | .PD |
139 | .PP | |
140 | .B Bash | |
ccc6cda3 JA |
141 | also interprets a number of multi-character options. |
142 | These options must appear on the command line before the | |
143 | single-character options in order for them to be recognized. | |
726f6388 JA |
144 | .PP |
145 | .PD 0 | |
726f6388 | 146 | .TP |
cce855bc JA |
147 | .B \-\-dump\-po\-strings |
148 | Equivalent to \fB\-D\fP, but the output is in the GNU \fIgettext\fP | |
149 | \fBpo\fP (portable object) file format. | |
150 | .TP | |
ccc6cda3 JA |
151 | .B \-\-dump\-strings |
152 | Equivalent to \fB\-D\fP. | |
153 | .TP | |
154 | .B \-\-help | |
155 | Display a usage message on standard output and exit successfully. | |
156 | .TP | |
28ef6c31 JA |
157 | .PD 0 |
158 | \fB\-\-init\-file\fP \fIfile\fP | |
159 | .TP | |
160 | \fB\-\-rcfile\fP \fIfile\fP | |
161 | .PD | |
162 | Execute commands from | |
163 | .I file | |
164 | instead of the standard personal initialization file | |
165 | .I ~/.bashrc | |
166 | if the shell is interactive (see | |
167 | .SM | |
168 | .B INVOCATION | |
169 | below). | |
170 | .TP | |
ccc6cda3 JA |
171 | .B \-\-login |
172 | Make | |
173 | .B bash | |
174 | act as if it had been invoked as a login shell (see | |
175 | .SM | |
176 | .B INVOCATION | |
177 | below). | |
178 | .TP | |
179 | .B \-\-noediting | |
180 | Do not use the GNU | |
181 | .B readline | |
bb70624e | 182 | library to read command lines when the shell is interactive. |
ccc6cda3 JA |
183 | .TP |
184 | .B \-\-noprofile | |
185 | Do not read either the system-wide startup file | |
726f6388 JA |
186 | .FN /etc/profile |
187 | or any of the personal initialization files | |
188 | .IR ~/.bash_profile , | |
189 | .IR ~/.bash_login , | |
190 | or | |
191 | .IR ~/.profile . | |
192 | By default, | |
193 | .B bash | |
ccc6cda3 | 194 | reads these files when it is invoked as a login shell (see |
726f6388 JA |
195 | .SM |
196 | .B INVOCATION | |
197 | below). | |
198 | .TP | |
ccc6cda3 JA |
199 | .B \-\-norc |
200 | Do not read and execute the personal initialization file | |
201 | .I ~/.bashrc | |
202 | if the shell is interactive. | |
203 | This option is on by default if the shell is invoked as | |
204 | .BR sh . | |
205 | .TP | |
206 | .B \-\-posix | |
207 | Change the behavior of \fBbash\fP where the default operation differs | |
28ef6c31 | 208 | from the POSIX 1003.2 standard to match the standard (\fIposix mode\fP). |
726f6388 | 209 | .TP |
ccc6cda3 JA |
210 | .B \-\-restricted |
211 | The shell becomes restricted (see | |
212 | .SM | |
213 | .B "RESTRICTED SHELL" | |
726f6388 JA |
214 | below). |
215 | .TP | |
ccc6cda3 JA |
216 | .B \-\-verbose |
217 | Equivalent to \fB\-v\fP. | |
726f6388 | 218 | .TP |
ccc6cda3 JA |
219 | .B \-\-version |
220 | Show version information for this instance of | |
221 | .B bash | |
222 | on the standard output and exit successfully. | |
726f6388 JA |
223 | .PD |
224 | .SH ARGUMENTS | |
225 | If arguments remain after option processing, and neither the | |
226 | .B \-c | |
227 | nor the | |
228 | .B \-s | |
229 | option has been supplied, the first argument is assumed to | |
ccc6cda3 JA |
230 | be the name of a file containing shell commands. |
231 | If | |
726f6388 JA |
232 | .B bash |
233 | is invoked in this fashion, | |
234 | .B $0 | |
235 | is set to the name of the file, and the positional parameters | |
236 | are set to the remaining arguments. | |
237 | .B Bash | |
238 | reads and executes commands from this file, then exits. | |
ccc6cda3 JA |
239 | \fBBash\fP's exit status is the exit status of the last command |
240 | executed in the script. | |
241 | If no commands are executed, the exit status is 0. | |
f73dda09 JA |
242 | An attempt is first made to open the file in the current directory, and, |
243 | if no file is found, then the shell searches the directories in | |
244 | .SM | |
245 | .B PATH | |
246 | for the script. | |
ccc6cda3 JA |
247 | .SH INVOCATION |
248 | A \fIlogin shell\fP is one whose first character of argument zero is a | |
249 | .BR \- , | |
250 | or one started with the | |
251 | .B \-\-login | |
252 | option. | |
253 | .PP | |
bb70624e JA |
254 | An \fIinteractive\fP shell is one started without non-option arguments |
255 | and without the | |
256 | .B \-c | |
257 | option | |
258 | whose standard input and output are | |
ccc6cda3 JA |
259 | both connected to terminals (as determined by |
260 | .IR isatty (3)), | |
261 | or one started with the | |
262 | .B \-i | |
263 | option. | |
264 | .SM | |
265 | .B PS1 | |
266 | is set and | |
267 | .B $\- | |
268 | includes | |
269 | .B i | |
270 | if | |
271 | .B bash | |
272 | is interactive, | |
273 | allowing a shell script or a startup file to test this state. | |
274 | .PP | |
275 | The following paragraphs describe how | |
276 | .B bash | |
277 | executes its startup files. | |
278 | If any of the files exist but cannot be read, | |
279 | .B bash | |
280 | reports an error. | |
281 | Tildes are expanded in file names as described below under | |
282 | .B "Tilde Expansion" | |
283 | in the | |
284 | .SM | |
285 | .B EXPANSION | |
286 | section. | |
287 | .PP | |
288 | When | |
289 | .B bash | |
b72432fd JA |
290 | is invoked as an interactive login shell, or as a non-interactive shell |
291 | with the \fB\-\-login\fP option, it first reads and | |
d166f048 JA |
292 | executes commands from the file \fI/etc/profile\fP, if that |
293 | file exists. | |
ccc6cda3 JA |
294 | After reading that file, it looks for \fI~/.bash_profile\fP, |
295 | \fI~/.bash_login\fP, and \fI~/.profile\fP, in that order, and reads | |
296 | and executes commands from the first one that exists and is readable. | |
297 | The | |
298 | .B \-\-noprofile | |
299 | option may be used when the shell is started to inhibit this behavior. | |
300 | .PP | |
301 | When a login shell exits, | |
302 | .B bash | |
303 | reads and executes commands from the file \fI~/.bash_logout\fP, if it | |
304 | exists. | |
305 | .PP | |
306 | When an interactive shell that is not a login shell is started, | |
307 | .B bash | |
308 | reads and executes commands from \fI~/.bashrc\fP, if that file exists. | |
309 | This may be inhibited by using the | |
310 | .B \-\-norc | |
311 | option. | |
312 | The \fB\-\-rcfile\fP \fIfile\fP option will force | |
313 | .B bash | |
314 | to read and execute commands from \fIfile\fP instead of \fI~/.bashrc\fP. | |
315 | .PP | |
316 | When | |
317 | .B bash | |
318 | is started non-interactively, to run a shell script, for example, it | |
319 | looks for the variable | |
320 | .SM | |
321 | .B BASH_ENV | |
322 | in the environment, expands its value if it appears there, and uses the | |
323 | expanded value as the name of a file to read and execute. | |
324 | .B Bash | |
325 | behaves as if the following command were executed: | |
326 | .sp .5 | |
327 | .RS | |
28ef6c31 JA |
328 | .if t \f(CWif [ \-n "$BASH_ENV" ]; then . "$BASH_ENV"; fi\fP |
329 | .if n if [ \-n "$BASH_ENV" ]; then . "$BASH_ENV"; fi | |
ccc6cda3 JA |
330 | .RE |
331 | .sp .5 | |
332 | but the value of the | |
333 | .SM | |
334 | .B PATH | |
335 | variable is not used to search for the file name. | |
336 | .PP | |
337 | If | |
338 | .B bash | |
339 | is invoked with the name | |
340 | .BR sh , | |
341 | it tries to mimic the startup behavior of historical versions of | |
342 | .B sh | |
343 | as closely as possible, | |
344 | while conforming to the POSIX standard as well. | |
b72432fd JA |
345 | When invoked as an interactive login shell, or a non-interactive |
346 | shell with the \fB\-\-login\fP option, it first attempts to | |
cce855bc | 347 | read and execute commands from |
ccc6cda3 JA |
348 | .I /etc/profile |
349 | and | |
350 | .IR ~/.profile , | |
351 | in that order. | |
352 | The | |
353 | .B \-\-noprofile | |
354 | option may be used to inhibit this behavior. | |
355 | When invoked as an interactive shell with the name | |
356 | .BR sh , | |
357 | .B bash | |
358 | looks for the variable | |
359 | .SM | |
360 | .BR ENV , | |
361 | expands its value if it is defined, and uses the | |
362 | expanded value as the name of a file to read and execute. | |
363 | Since a shell invoked as | |
364 | .B sh | |
365 | does not attempt to read and execute commands from any other startup | |
366 | files, the | |
367 | .B \-\-rcfile | |
368 | option has no effect. | |
369 | A non-interactive shell invoked with the name | |
370 | .B sh | |
b72432fd | 371 | does not attempt to read any other startup files. |
ccc6cda3 JA |
372 | When invoked as |
373 | .BR sh , | |
374 | .B bash | |
375 | enters | |
376 | .I posix | |
377 | mode after the startup files are read. | |
378 | .PP | |
379 | When | |
380 | .B bash | |
381 | is started in | |
382 | .I posix | |
383 | mode, as with the | |
384 | .B \-\-posix | |
385 | command line option, it follows the POSIX standard for startup files. | |
cce855bc | 386 | In this mode, interactive shells expand the |
ccc6cda3 JA |
387 | .SM |
388 | .B ENV | |
cce855bc | 389 | variable and commands are read and executed from the file |
ccc6cda3 JA |
390 | whose name is the expanded value. |
391 | No other startup files are read. | |
ccc6cda3 JA |
392 | .PP |
393 | .B Bash | |
394 | attempts to determine when it is being run by the remote shell | |
395 | daemon, usually \fIrshd\fP. | |
396 | If | |
397 | .B bash | |
398 | determines it is being run by \fIrshd\fP, it reads and executes | |
399 | commands from \fI~/.bashrc\fP, if that file exists and is readable. | |
400 | It will not do this if invoked as \fBsh\fP. | |
401 | The | |
402 | .B \-\-norc | |
403 | option may be used to inhibit this behavior, and the | |
404 | .B \-\-rcfile | |
405 | option may be used to force another file to be read, but | |
406 | \fIrshd\fP does not generally invoke the shell with those options | |
407 | or allow them to be specified. | |
b72432fd JA |
408 | .PP |
409 | If the shell is started with the effective user (group) id not equal to the | |
410 | real user (group) id, and the \fB\-p\fP option is not supplied, no startup | |
f73dda09 JA |
411 | files are read, shell functions are not inherited from the environment, the |
412 | .SM | |
413 | .B SHELLOPTS | |
414 | variable, if it appears in the environment, is ignored, | |
b72432fd JA |
415 | and the effective user id is set to the real user id. |
416 | If the \fB\-p\fP option is supplied at invocation, the startup behavior is | |
417 | the same, but the effective user id is not reset. | |
726f6388 | 418 | .SH DEFINITIONS |
ccc6cda3 JA |
419 | .PP |
420 | The following definitions are used throughout the rest of this | |
421 | document. | |
726f6388 JA |
422 | .PD 0 |
423 | .TP | |
424 | .B blank | |
425 | A space or tab. | |
426 | .TP | |
427 | .B word | |
428 | A sequence of characters considered as a single unit by the shell. | |
429 | Also known as a | |
430 | .BR token . | |
431 | .TP | |
432 | .B name | |
433 | A | |
434 | .I word | |
435 | consisting only of alphanumeric characters and underscores, and | |
436 | beginning with an alphabetic character or an underscore. Also | |
437 | referred to as an | |
438 | .BR identifier . | |
439 | .TP | |
440 | .B metacharacter | |
441 | A character that, when unquoted, separates words. One of the following: | |
442 | .br | |
443 | .RS | |
444 | .PP | |
445 | .if t \fB| & ; ( ) < > space tab\fP | |
446 | .if n \fB| & ; ( ) < > space tab\fP | |
447 | .RE | |
448 | .PP | |
449 | .TP | |
450 | .B control operator | |
451 | A \fItoken\fP that performs a control function. It is one of the following | |
452 | symbols: | |
453 | .RS | |
454 | .PP | |
ccc6cda3 | 455 | .if t \fB\(bv\(bv & && ; ;; ( ) | <newline>\fP |
726f6388 JA |
456 | .if n \fB|| & && ; ;; ( ) | <newline>\fP |
457 | .RE | |
458 | .PD | |
459 | .SH "RESERVED WORDS" | |
460 | \fIReserved words\fP are words that have a special meaning to the shell. | |
461 | The following words are recognized as reserved when unquoted and either | |
462 | the first word of a simple command (see | |
463 | .SM | |
464 | .B SHELL GRAMMAR | |
465 | below) or the third word of a | |
466 | .B case | |
467 | or | |
468 | .B for | |
469 | command: | |
470 | .if t .RS | |
471 | .PP | |
472 | .B | |
cce855bc JA |
473 | .if n ! case do done elif else esac fi for function if in select then until while { } time [[ ]] |
474 | .if t ! case do done elif else esac fi for function if in select then until while { } time [[ ]] | |
726f6388 JA |
475 | .if t .RE |
476 | .RE | |
477 | .SH "SHELL GRAMMAR" | |
478 | .SS Simple Commands | |
479 | .PP | |
480 | A \fIsimple command\fP is a sequence of optional variable assignments | |
ccc6cda3 | 481 | followed by \fBblank\fP-separated words and redirections, and |
726f6388 | 482 | terminated by a \fIcontrol operator\fP. The first word |
f73dda09 JA |
483 | specifies the command to be executed, and is passed as argument zero. |
484 | The remaining words are passed as arguments to the invoked command. | |
726f6388 JA |
485 | .PP |
486 | The return value of a \fIsimple command\fP is its exit status, or | |
487 | 128+\fIn\^\fP if the command is terminated by signal | |
488 | .IR n . | |
489 | .SS Pipelines | |
490 | .PP | |
491 | A \fIpipeline\fP is a sequence of one or more commands separated by | |
492 | the character | |
493 | .BR | . | |
494 | The format for a pipeline is: | |
495 | .RS | |
496 | .PP | |
ccc6cda3 | 497 | [\fBtime\fP [\fB\-p\fP]] [ ! ] \fIcommand\fP [ \fB|\fP \fIcommand2\fP ... ] |
726f6388 JA |
498 | .RE |
499 | .PP | |
500 | The standard output of | |
501 | .I command | |
f73dda09 | 502 | is connected via a pipe to the standard input of |
726f6388 JA |
503 | .IR command2 . |
504 | This connection is performed before any redirections specified by the | |
505 | command (see | |
506 | .SM | |
507 | .B REDIRECTION | |
508 | below). | |
509 | .PP | |
510 | If the reserved word | |
511 | .B ! | |
512 | precedes a pipeline, the exit status of that | |
513 | pipeline is the logical NOT of the exit status of the last command. | |
514 | Otherwise, the status of the pipeline is the exit status of the last | |
ccc6cda3 JA |
515 | command. |
516 | The shell waits for all commands in the pipeline to | |
726f6388 JA |
517 | terminate before returning a value. |
518 | .PP | |
ccc6cda3 JA |
519 | If the |
520 | .B time | |
521 | reserved word precedes a pipeline, the elapsed as well as user and | |
522 | system time consumed by its execution are reported when the pipeline | |
523 | terminates. | |
524 | The \fB\-p\fP option changes the output format to that specified by POSIX. | |
525 | The | |
526 | .SM | |
527 | .B TIMEFORMAT | |
528 | variable may be set to a format string that specifies how the timing | |
529 | information should be displayed; see the description of | |
530 | .SM | |
531 | .B TIMEFORMAT | |
532 | under | |
533 | .B "Shell Variables" | |
534 | below. | |
535 | .PP | |
726f6388 JA |
536 | Each command in a pipeline is executed as a separate process (i.e., in a |
537 | subshell). | |
538 | .SS Lists | |
539 | .PP | |
540 | A \fIlist\fP is a sequence of one or more pipelines separated by one | |
541 | of the operators | |
542 | .BR ; , | |
543 | .BR & , | |
544 | .BR && , | |
545 | or | |
ccc6cda3 JA |
546 | .BR \(bv\(bv , |
547 | and optionally terminated by one of | |
726f6388 JA |
548 | .BR ; , |
549 | .BR & , | |
550 | or | |
551 | .BR <newline> . | |
552 | .PP | |
553 | Of these list operators, | |
554 | .B && | |
555 | and | |
ccc6cda3 | 556 | .B \(bv\(bv |
726f6388 JA |
557 | have equal precedence, followed by |
558 | .B ; | |
559 | and | |
560 | .BR &, | |
561 | which have equal precedence. | |
562 | .PP | |
563 | If a command is terminated by the control operator | |
564 | .BR & , | |
565 | the shell executes the command in the \fIbackground\fP | |
566 | in a subshell. The shell does not wait for the command to | |
567 | finish, and the return status is 0. Commands separated by a | |
568 | .B ; | |
569 | are executed sequentially; the shell waits for each | |
570 | command to terminate in turn. The return status is the | |
571 | exit status of the last command executed. | |
572 | .PP | |
573 | The control operators | |
574 | .B && | |
575 | and | |
ccc6cda3 | 576 | .B \(bv\(bv |
726f6388 JA |
577 | denote AND lists and OR lists, respectively. |
578 | An AND list has the form | |
579 | .RS | |
580 | .PP | |
bb70624e | 581 | \fIcommand1\fP \fB&&\fP \fIcommand2\fP |
726f6388 JA |
582 | .RE |
583 | .PP | |
584 | .I command2 | |
585 | is executed if, and only if, | |
bb70624e | 586 | .I command1 |
726f6388 JA |
587 | returns an exit status of zero. |
588 | .PP | |
589 | An OR list has the form | |
590 | .RS | |
591 | .PP | |
bb70624e | 592 | \fIcommand1\fP \fB\(bv\(bv\fP \fIcommand2\fP |
726f6388 JA |
593 | .PP |
594 | .RE | |
595 | .PP | |
596 | .I command2 | |
597 | is executed if and only if | |
bb70624e | 598 | .I command1 |
ccc6cda3 | 599 | returns a non-zero exit status. The return status of |
726f6388 JA |
600 | AND and OR lists is the exit status of the last command |
601 | executed in the list. | |
602 | .SS Compound Commands | |
603 | .PP | |
604 | A \fIcompound command\fP is one of the following: | |
605 | .TP | |
606 | (\fIlist\fP) | |
607 | \fIlist\fP is executed in a subshell. Variable assignments and builtin | |
608 | commands that affect the shell's environment do not remain in effect | |
609 | after the command completes. The return status is the exit status of | |
610 | \fIlist\fP. | |
611 | .TP | |
612 | { \fIlist\fP; } | |
ccc6cda3 JA |
613 | \fIlist\fP is simply executed in the current shell environment. |
614 | \fIlist\fP must be terminated with a newline or semicolon. | |
615 | This is known as a \fIgroup command\fP. | |
616 | The return status is the exit status of | |
726f6388 | 617 | \fIlist\fP. |
f73dda09 JA |
618 | Note that unlike the metacharacters \fB(\fP and \fB\)\fP, \fB{\fP and |
619 | \fB}\fP are \fIreserved words\fP and must occur where a reserved | |
620 | word is permitted to be recognized. Since they do not cause a word | |
621 | break, they must be separated from \fIlist\fP by whitespace. | |
726f6388 | 622 | .TP |
ccc6cda3 JA |
623 | ((\fIexpression\fP)) |
624 | The \fIexpression\fP is evaluated according to the rules described | |
625 | below under | |
626 | .SM | |
627 | .BR "ARITHMETIC EVALUATION" . | |
628 | If the value of the expression is non-zero, the return status is 0; | |
629 | otherwise the return status is 1. This is exactly equivalent to | |
630 | \fBlet "\fIexpression\fP"\fR. | |
631 | .TP | |
cce855bc JA |
632 | \fB[[\fP \fIexpression\fP \fB]]\fP |
633 | Return a status of 0 or 1 depending on the evaluation of | |
634 | the conditional expression \fIexpression\fP. | |
635 | Expressions are composed of the primaries described below under | |
636 | .SM | |
637 | .BR "CONDITIONAL EXPRESSIONS" . | |
638 | Word splitting and pathname expansion are not performed on the words | |
639 | between the \fB[[\fP and \fB]]\fP; tilde expansion, parameter and | |
640 | variable expansion, arithmetic expansion, command substitution, process | |
641 | substitution, and quote removal are performed. | |
642 | .if t .sp 0.5 | |
643 | .if n .sp 1 | |
644 | When the \fB==\fP and \fB!=\fP operators are used, the string to the | |
645 | right of the operator is considered a pattern and matched according | |
646 | to the rules described below under \fBPattern Matching\fP. | |
647 | The return value is 0 if the string matches or does not match | |
648 | the pattern, respectively, and 1 otherwise. | |
649 | Any part of the pattern may be quoted to force it to be matched as a | |
650 | string. | |
651 | .if t .sp 0.5 | |
652 | .if n .sp 1 | |
653 | Expressions may be combined using the following operators, listed | |
654 | in decreasing order of precedence: | |
655 | .if t .sp 0.5 | |
656 | .if n .sp 1 | |
657 | .RS | |
658 | .PD 0 | |
659 | .TP | |
660 | .B ( \fIexpression\fP ) | |
661 | Returns the value of \fIexpression\fP. | |
662 | This may be used to override the normal precedence of operators. | |
663 | .TP | |
664 | .B ! \fIexpression\fP | |
665 | True if | |
666 | .I expression | |
667 | is false. | |
668 | .TP | |
669 | \fIexpression1\fP \fB&&\fP \fIexpression2\fP | |
670 | True if both | |
671 | .I expression1 | |
672 | and | |
673 | .I expression2 | |
674 | are true. | |
675 | .TP | |
676 | .if t \fIexpression1\fP \fB\(bv\(bv\fP \fIexpression2\fP | |
677 | .if n \fIexpression1\fP \fB||\fP \fIexpression2\fP | |
678 | True if either | |
679 | .I expression1 | |
680 | or | |
681 | .I expression2 | |
682 | is true. | |
683 | .PD | |
cce855bc JA |
684 | .LP |
685 | The \fB&&\fP and | |
686 | .if t \fB\(bv\(bv\fP | |
687 | .if n \fB||\fP | |
688 | operators do not execute \fIexpression2\fP if the value of | |
689 | \fIexpression1\fP is sufficient to determine the return value of | |
690 | the entire conditional expression. | |
f73dda09 | 691 | .RE |
cce855bc | 692 | .TP |
b72432fd | 693 | \fBfor\fP \fIname\fP [ \fBin\fP \fIword\fP ] ; \fBdo\fP \fIlist\fP ; \fBdone\fP |
726f6388 | 694 | The list of words following \fBin\fP is expanded, generating a list |
bb70624e JA |
695 | of items. |
696 | The variable \fIname\fP is set to each element of this list | |
697 | in turn, and \fIlist\fP is executed each time. | |
698 | If the \fBin\fP \fIword\fP is omitted, the \fBfor\fP command executes | |
699 | \fIlist\fP once for each positional parameter that is set (see | |
726f6388 JA |
700 | .SM |
701 | .B PARAMETERS | |
702 | below). | |
cce855bc JA |
703 | The return status is the exit status of the last command that executes. |
704 | If the expansion of the items following \fBin\fP results in an empty | |
705 | list, no commands are executed, and the return status is 0. | |
726f6388 | 706 | .TP |
bb70624e JA |
707 | \fBfor\fP (( \fIexpr1\fP ; \fIexpr2\fP ; \fIexpr3\fP )) ; \fBdo\fP \fIlist\fP ; \fBdone\fP |
708 | First, the arithmetic expression \fIexpr1\fP is evaluated according | |
709 | to the rules described below under | |
710 | .SM | |
711 | .BR "ARITHMETIC EVALUATION" . | |
712 | The arithmetic expression \fIexpr2\fP is then evaluated repeatedly | |
713 | until it evaluates to zero. | |
714 | Each time \fIexpr2\fP evaluates to a non-zero value, \fIlist\fP is | |
715 | executed and the arithmetic expression \fIexpr3\fP is evaluated. | |
716 | If any expression is omitted, it behaves as if it evaluates to 1. | |
717 | The return value is the exit status of the last command in \fIlist\fP | |
718 | that is executed, or false if any of the expressions is invalid. | |
719 | .TP | |
b72432fd | 720 | \fBselect\fP \fIname\fP [ \fBin\fP \fIword\fP ] ; \fBdo\fP \fIlist\fP ; \fBdone\fP |
726f6388 JA |
721 | The list of words following \fBin\fP is expanded, generating a list |
722 | of items. The set of expanded words is printed on the standard | |
723 | error, each preceded by a number. If the \fBin\fP | |
724 | \fIword\fP is omitted, the positional parameters are printed (see | |
725 | .SM | |
726 | .B PARAMETERS | |
727 | below). The | |
728 | .B PS3 | |
729 | prompt is then displayed and a line read from the standard input. | |
ccc6cda3 | 730 | If the line consists of a number corresponding to one of |
726f6388 JA |
731 | the displayed words, then the value of |
732 | .I name | |
733 | is set to that word. If the line is empty, the words and prompt | |
734 | are displayed again. If EOF is read, the command completes. Any | |
735 | other value read causes | |
736 | .I name | |
737 | to be set to null. The line read is saved in the variable | |
738 | .BR REPLY . | |
739 | The | |
740 | .I list | |
741 | is executed after each selection until a | |
742 | .B break | |
726f6388 JA |
743 | command is executed. |
744 | The exit status of | |
745 | .B select | |
746 | is the exit status of the last command executed in | |
747 | .IR list , | |
748 | or zero if no commands were executed. | |
749 | .TP | |
bb70624e | 750 | \fBcase\fP \fIword\fP \fBin\fP [ [(] \fIpattern\fP [ \fB|\fP \fIpattern\fP ] \ |
726f6388 JA |
751 | ... ) \fIlist\fP ;; ] ... \fBesac\fP |
752 | A \fBcase\fP command first expands \fIword\fP, and tries to match | |
753 | it against each \fIpattern\fP in turn, using the same matching rules | |
754 | as for pathname expansion (see | |
755 | .B Pathname Expansion | |
756 | below). When a match is found, the | |
757 | corresponding \fIlist\fP is executed. After the first match, no | |
758 | subsequent matches are attempted. The exit status is zero if no | |
ccc6cda3 | 759 | pattern matches. Otherwise, it is the exit status of the |
726f6388 JA |
760 | last command executed in \fIlist\fP. |
761 | .TP | |
ccc6cda3 JA |
762 | \fBif\fP \fIlist\fP; \fBthen\fP \fIlist;\fP \ |
763 | [ \fBelif\fP \fIlist\fP; \fBthen\fP \fIlist\fP; ] ... \ | |
764 | [ \fBelse\fP \fIlist\fP; ] \fBfi\fP | |
726f6388 JA |
765 | The |
766 | .B if | |
767 | .I list | |
768 | is executed. If its exit status is zero, the | |
769 | \fBthen\fP \fIlist\fP is executed. Otherwise, each \fBelif\fP | |
770 | \fIlist\fP is executed in turn, and if its exit status is zero, | |
771 | the corresponding \fBthen\fP \fIlist\fP is executed and the | |
772 | command completes. Otherwise, the \fBelse\fP \fIlist\fP is | |
773 | executed, if present. The exit status is the exit status of the | |
774 | last command executed, or zero if no condition tested true. | |
775 | .TP | |
776 | .PD 0 | |
ccc6cda3 | 777 | \fBwhile\fP \fIlist\fP; \fBdo\fP \fIlist\fP; \fBdone\fP |
726f6388 | 778 | .TP |
ccc6cda3 | 779 | \fBuntil\fP \fIlist\fP; \fBdo\fP \fIlist\fP; \fBdone\fP |
726f6388 JA |
780 | .PD |
781 | The \fBwhile\fP command continuously executes the \fBdo\fP | |
782 | \fIlist\fP as long as the last command in \fIlist\fP returns | |
783 | an exit status of zero. The \fBuntil\fP command is identical | |
784 | to the \fBwhile\fP command, except that the test is negated; | |
785 | the | |
786 | .B do | |
787 | .I list | |
788 | is executed as long as the last command in | |
789 | .I list | |
ccc6cda3 | 790 | returns a non-zero exit status. |
726f6388 JA |
791 | The exit status of the \fBwhile\fP and \fBuntil\fP commands |
792 | is the exit status | |
793 | of the last \fBdo\fP \fIlist\fP command executed, or zero if | |
794 | none was executed. | |
795 | .TP | |
796 | [ \fBfunction\fP ] \fIname\fP () { \fIlist\fP; } | |
797 | This defines a function named \fIname\fP. The \fIbody\fP of the | |
798 | function is the | |
799 | .I list | |
800 | of commands between { and }. This list | |
801 | is executed whenever \fIname\fP is specified as the | |
802 | name of a simple command. The exit status of a function is | |
803 | the exit status of the last command executed in the body. (See | |
804 | .SM | |
805 | .B FUNCTIONS | |
806 | below.) | |
807 | .SH COMMENTS | |
ccc6cda3 JA |
808 | In a non-interactive shell, or an interactive shell in which the |
809 | .B interactive_comments | |
810 | option to the | |
811 | .B shopt | |
812 | builtin is enabled (see | |
813 | .SM | |
814 | .B "SHELL BUILTIN COMMANDS" | |
815 | below), a word beginning with | |
726f6388 JA |
816 | .B # |
817 | causes that word and all remaining characters on that line to | |
818 | be ignored. An interactive shell without the | |
ccc6cda3 | 819 | .B interactive_comments |
ccc6cda3 JA |
820 | option enabled does not allow comments. The |
821 | .B interactive_comments | |
822 | option is on by default in interactive shells. | |
726f6388 JA |
823 | .SH QUOTING |
824 | \fIQuoting\fP is used to remove the special meaning of certain | |
825 | characters or words to the shell. Quoting can be used to | |
826 | disable special treatment for special characters, to prevent | |
827 | reserved words from being recognized as such, and to prevent | |
828 | parameter expansion. | |
829 | .PP | |
830 | Each of the \fImetacharacters\fP listed above under | |
831 | .SM | |
832 | .B DEFINITIONS | |
bb70624e JA |
833 | has special meaning to the shell and must be quoted if it is to |
834 | represent itself. | |
835 | .PP | |
836 | When the command history expansion facilities are being used, the | |
837 | \fIhistory expansion\fP character, usually \fB!\fP, must be quoted | |
838 | to prevent history expansion. | |
839 | .PP | |
840 | There are three quoting mechanisms: the | |
726f6388 JA |
841 | .IR "escape character" , |
842 | single quotes, and double quotes. | |
843 | .PP | |
844 | A non-quoted backslash (\fB\e\fP) is the | |
845 | .IR "escape character" . | |
846 | It preserves the literal value of the next character that follows, | |
847 | with the exception of <newline>. If a \fB\e\fP<newline> pair | |
cce855bc JA |
848 | appears, and the backslash is not itself quoted, the \fB\e\fP<newline> |
849 | is treated as a line continuation (that is, it is removed from the | |
850 | input stream and effectively ignored). | |
726f6388 JA |
851 | .PP |
852 | Enclosing characters in single quotes preserves the literal value | |
853 | of each character within the quotes. A single quote may not occur | |
854 | between single quotes, even when preceded by a backslash. | |
855 | .PP | |
856 | Enclosing characters in double quotes preserves the literal value | |
857 | of all characters within the quotes, with the exception of | |
858 | .BR $ , | |
859 | .BR ` , | |
860 | and | |
861 | .BR \e . | |
862 | The characters | |
863 | .B $ | |
864 | and | |
865 | .B ` | |
866 | retain their special meaning within double quotes. The backslash | |
867 | retains its special meaning only when followed by one of the following | |
868 | characters: | |
869 | .BR $ , | |
870 | .BR ` , | |
871 | \^\fB"\fP\^, | |
872 | .BR \e , | |
873 | or | |
874 | .BR <newline> . | |
875 | A double quote may be quoted within double quotes by preceding it with | |
876 | a backslash. | |
877 | .PP | |
878 | The special parameters | |
879 | .B * | |
880 | and | |
881 | .B @ | |
882 | have special meaning when in double | |
883 | quotes (see | |
884 | .SM | |
885 | .B PARAMETERS | |
886 | below). | |
ccc6cda3 JA |
887 | .PP |
888 | Words of the form \fB$\fP'\fIstring\fP' are treated specially. The | |
889 | word expands to \fIstring\fP, with backslash-escaped characters replaced | |
890 | as specifed by the ANSI C standard. Backslash escape sequences, if | |
891 | present, are decoded as follows: | |
892 | .RS | |
893 | .PD 0 | |
894 | .TP | |
895 | .B \ea | |
896 | alert (bell) | |
897 | .TP | |
898 | .B \eb | |
899 | backspace | |
900 | .TP | |
901 | .B \ee | |
902 | an escape character | |
903 | .TP | |
904 | .B \ef | |
905 | form feed | |
906 | .TP | |
907 | .B \en | |
908 | new line | |
909 | .TP | |
910 | .B \er | |
911 | carriage return | |
912 | .TP | |
913 | .B \et | |
914 | horizontal tab | |
915 | .TP | |
916 | .B \ev | |
917 | vertical tab | |
918 | .TP | |
919 | .B \e\e | |
920 | backslash | |
bb70624e JA |
921 | .TP |
922 | .B \e' | |
923 | single quote | |
ccc6cda3 JA |
924 | .TP |
925 | .B \e\fInnn\fP | |
f73dda09 | 926 | the eight-bit character whose value is the octal value \fInnn\fP |
cce855bc JA |
927 | (one to three digits) |
928 | .TP | |
f73dda09 JA |
929 | .B \ex\fIHH\fP |
930 | the eight-bit character whose value is the hexadecimal value \fIHH\fP | |
931 | (one or two hex digits) | |
ccc6cda3 JA |
932 | .PD |
933 | .RE | |
934 | .LP | |
bb70624e | 935 | The expanded result is single-quoted, as if the dollar sign had |
ccc6cda3 JA |
936 | not been present. |
937 | .PP | |
938 | A double-quoted string preceded by a dollar sign (\fB$\fP) will cause | |
939 | the string to be translated according to the current locale. | |
940 | If the current locale is \fBC\fP or \fBPOSIX\fP, the dollar sign | |
941 | is ignored. | |
942 | If the string is translated and replaced, the replacement is | |
943 | double-quoted. | |
726f6388 JA |
944 | .SH PARAMETERS |
945 | A | |
946 | .I parameter | |
ccc6cda3 JA |
947 | is an entity that stores values. |
948 | It can be a | |
726f6388 JA |
949 | .IR name , |
950 | a number, or one of the special characters listed below under | |
951 | .BR "Special Parameters" . | |
952 | For the shell's purposes, a | |
953 | .I variable | |
954 | is a parameter denoted by a | |
955 | .IR name . | |
f73dda09 JA |
956 | A variable has a \fIvalue\fP and zero or more \fIattributes\fP. |
957 | Attributes are assigned using the | |
958 | .B declare | |
959 | builtin command (see | |
960 | .B declare | |
961 | below in | |
962 | .SM | |
963 | .BR "SHELL BUILTIN COMMANDS" ). | |
726f6388 JA |
964 | .PP |
965 | A parameter is set if it has been assigned a value. The null string is | |
966 | a valid value. Once a variable is set, it may be unset only by using | |
967 | the | |
968 | .B unset | |
969 | builtin command (see | |
970 | .SM | |
971 | .B SHELL BUILTIN COMMANDS | |
972 | below). | |
973 | .PP | |
974 | A | |
975 | .I variable | |
976 | may be assigned to by a statement of the form | |
977 | .RS | |
978 | .PP | |
979 | \fIname\fP=[\fIvalue\fP] | |
980 | .RE | |
981 | .PP | |
982 | If | |
983 | .I value | |
984 | is not given, the variable is assigned the null string. All | |
985 | .I values | |
bb70624e JA |
986 | undergo tilde expansion, parameter and variable expansion, |
987 | command substitution, arithmetic expansion, and quote | |
ccc6cda3 JA |
988 | removal (see |
989 | .SM | |
990 | .B EXPANSION | |
991 | below). If the variable has its | |
cce855bc | 992 | .B integer |
f73dda09 | 993 | attribute set, then |
726f6388 | 994 | .I value |
cce855bc JA |
995 | is subject to arithmetic expansion even if the $((...)) expansion is |
996 | not used (see | |
ccc6cda3 JA |
997 | .B "Arithmetic Expansion" |
998 | below). | |
999 | Word splitting is not performed, with the exception | |
726f6388 JA |
1000 | of \fB"$@"\fP as explained below under |
1001 | .BR "Special Parameters" . | |
1002 | Pathname expansion is not performed. | |
f73dda09 JA |
1003 | Assignment statements may also appear as arguments to the |
1004 | .BR declare , | |
1005 | .BR typeset , | |
1006 | .BR export , | |
1007 | .BR readonly , | |
1008 | and | |
1009 | .B local | |
1010 | builtin commands. | |
726f6388 JA |
1011 | .SS Positional Parameters |
1012 | .PP | |
1013 | A | |
1014 | .I positional parameter | |
1015 | is a parameter denoted by one or more | |
1016 | digits, other than the single digit 0. Positional parameters are | |
1017 | assigned from the shell's arguments when it is invoked, | |
1018 | and may be reassigned using the | |
1019 | .B set | |
1020 | builtin command. Positional parameters may not be assigned to | |
1021 | with assignment statements. The positional parameters are | |
1022 | temporarily replaced when a shell function is executed (see | |
1023 | .SM | |
1024 | .B FUNCTIONS | |
1025 | below). | |
1026 | .PP | |
1027 | When a positional parameter consisting of more than a single | |
1028 | digit is expanded, it must be enclosed in braces (see | |
1029 | .SM | |
1030 | .B EXPANSION | |
1031 | below). | |
1032 | .SS Special Parameters | |
1033 | .PP | |
1034 | The shell treats several parameters specially. These parameters may | |
1035 | only be referenced; assignment to them is not allowed. | |
1036 | .PD 0 | |
1037 | .TP | |
1038 | .B * | |
1039 | Expands to the positional parameters, starting from one. When the | |
1040 | expansion occurs within double quotes, it expands to a single word | |
1041 | with the value of each parameter separated by the first character | |
1042 | of the | |
1043 | .SM | |
1044 | .B IFS | |
cce855bc JA |
1045 | special variable. That is, "\fB$*\fP" is equivalent |
1046 | to "\fB$1\fP\fIc\fP\fB$2\fP\fIc\fP\fB...\fP", where | |
726f6388 JA |
1047 | .I c |
1048 | is the first character of the value of the | |
1049 | .SM | |
1050 | .B IFS | |
1051 | variable. If | |
1052 | .SM | |
1053 | .B IFS | |
d166f048 JA |
1054 | is unset, the parameters are separated by spaces. |
1055 | If | |
1056 | .SM | |
1057 | .B IFS | |
1058 | is null, the parameters are joined without intervening separators. | |
726f6388 JA |
1059 | .TP |
1060 | .B @ | |
1061 | Expands to the positional parameters, starting from one. When the | |
cce855bc JA |
1062 | expansion occurs within double quotes, each parameter expands to a |
1063 | separate word. That is, "\fB$@\fP" is equivalent to | |
1064 | "\fB$1\fP" "\fB$2\fP" ... | |
1065 | When there are no positional parameters, "\fB$@\fP" and | |
726f6388 JA |
1066 | .B $@ |
1067 | expand to nothing (i.e., they are removed). | |
1068 | .TP | |
1069 | .B # | |
1070 | Expands to the number of positional parameters in decimal. | |
1071 | .TP | |
1072 | .B ? | |
1073 | Expands to the status of the most recently executed foreground | |
1074 | pipeline. | |
1075 | .TP | |
1076 | .B \- | |
1077 | Expands to the current option flags as specified upon invocation, | |
1078 | by the | |
1079 | .B set | |
1080 | builtin command, or those set by the shell itself | |
1081 | (such as the | |
1082 | .B \-i | |
cce855bc | 1083 | option). |
726f6388 JA |
1084 | .TP |
1085 | .B $ | |
1086 | Expands to the process ID of the shell. In a () subshell, it | |
1087 | expands to the process ID of the current shell, not the | |
1088 | subshell. | |
1089 | .TP | |
1090 | .B ! | |
1091 | Expands to the process ID of the most recently executed background | |
1092 | (asynchronous) command. | |
1093 | .TP | |
1094 | .B 0 | |
1095 | Expands to the name of the shell or shell script. This is set at | |
1096 | shell initialization. If | |
1097 | .B bash | |
1098 | is invoked with a file of commands, | |
1099 | .B $0 | |
1100 | is set to the name of that file. If | |
1101 | .B bash | |
1102 | is started with the | |
1103 | .B \-c | |
1104 | option, then | |
1105 | .B $0 | |
1106 | is set to the first argument after the string to be | |
1107 | executed, if one is present. Otherwise, it is set | |
ccc6cda3 | 1108 | to the file name used to invoke |
726f6388 JA |
1109 | .BR bash , |
1110 | as given by argument zero. | |
1111 | .TP | |
1112 | .B _ | |
ccc6cda3 JA |
1113 | At shell startup, set to the absolute file name of the shell or shell |
1114 | script being executed as passed in the argument list. | |
1115 | Subsequently, expands to the last argument to the previous command, | |
1116 | after expansion. | |
1117 | Also set to the full file name of each command executed and placed in | |
726f6388 | 1118 | the environment exported to that command. |
ccc6cda3 JA |
1119 | When checking mail, this parameter holds the name of the mail file |
1120 | currently being checked. | |
726f6388 JA |
1121 | .PD |
1122 | .SS Shell Variables | |
1123 | .PP | |
1124 | The following variables are set by the shell: | |
1125 | .PP | |
1126 | .PD 0 | |
1127 | .TP | |
726f6388 | 1128 | .B BASH |
ccc6cda3 | 1129 | Expands to the full file name used to invoke this instance of |
726f6388 JA |
1130 | .BR bash . |
1131 | .TP | |
ccc6cda3 | 1132 | .B BASH_VERSINFO |
cce855bc JA |
1133 | A readonly array variable whose members hold version information for |
1134 | this instance of | |
ccc6cda3 JA |
1135 | .BR bash . |
1136 | The values assigned to the array members are as follows: | |
1137 | .sp .5 | |
1138 | .RS | |
1139 | .PD 0 | |
1140 | .TP 24 | |
1141 | .B BASH_VERSINFO[\fR0\fP] | |
1142 | The major version number (the \fIrelease\fP). | |
1143 | .TP | |
1144 | .B BASH_VERSINFO[\fR1\fP] | |
1145 | The minor version number (the \fIversion\fP). | |
1146 | .TP | |
1147 | .B BASH_VERSINFO[\fR2\fP] | |
1148 | The patch level. | |
1149 | .TP | |
1150 | .B BASH_VERSINFO[\fR3\fP] | |
1151 | The build version. | |
1152 | .TP | |
1153 | .B BASH_VERSINFO[\fR4\fP] | |
1154 | The release status (e.g., \fIbeta1\fP). | |
1155 | .TP | |
1156 | .B BASH_VERSINFO[\fR5\fP] | |
1157 | The value of \fBMACHTYPE\fP. | |
1158 | .PD | |
1159 | .RE | |
1160 | .TP | |
f73dda09 JA |
1161 | .B BASH_VERSION |
1162 | Expands to a string describing the version of this instance of | |
1163 | .BR bash . | |
726f6388 | 1164 | .TP |
f73dda09 JA |
1165 | .B COMP_CWORD |
1166 | An index into \fB${COMP_WORDS}\fP of the word containing the current | |
1167 | cursor position. | |
1168 | This variable is available only in shell functions invoked by the | |
1169 | programmable completion facilities (see \fBProgrammable Completion\fP | |
1170 | below). | |
1171 | .TP | |
1172 | .B COMP_LINE | |
1173 | The current command line. | |
1174 | This variable is available only in shell functions and external | |
1175 | commands invoked by the | |
1176 | programmable completion facilities (see \fBProgrammable Completion\fP | |
1177 | below). | |
1178 | .TP | |
1179 | .B COMP_POINT | |
1180 | The index of the current cursor position relative to the beginning of | |
1181 | the current command. | |
1182 | If the current cursor position is at the end of the current command, | |
1183 | the value of this variable is equal to \fB${#COMP_LINE}\fP. | |
1184 | This variable is available only in shell functions and external | |
1185 | commands invoked by the | |
1186 | programmable completion facilities (see \fBProgrammable Completion\fP | |
1187 | below). | |
1188 | .TP | |
1189 | .B COMP_WORDS | |
1190 | An array variable (see \fBArrays\fP below) consisting of the individual | |
1191 | words in the current command line. | |
1192 | This variable is available only in shell functions invoked by the | |
1193 | programmable completion facilities (see \fBProgrammable Completion\fP | |
1194 | below). | |
1195 | .TP | |
1196 | .B DIRSTACK | |
1197 | An array variable (see | |
1198 | .B Arrays | |
1199 | below) containing the current contents of the directory stack. | |
1200 | Directories appear in the stack in the order they are displayed by the | |
1201 | .B dirs | |
1202 | builtin. | |
1203 | Assigning to members of this array variable may be used to modify | |
1204 | directories already in the stack, but the | |
1205 | .B pushd | |
1206 | and | |
1207 | .B popd | |
1208 | builtins must be used to add and remove directories. | |
1209 | Assignment to this variable will not change the current directory. | |
726f6388 JA |
1210 | If |
1211 | .SM | |
f73dda09 | 1212 | .B DIRSTACK |
726f6388 JA |
1213 | is unset, it loses its special properties, even if it is |
1214 | subsequently reset. | |
1215 | .TP | |
f73dda09 JA |
1216 | .B EUID |
1217 | Expands to the effective user ID of the current user, initialized at | |
1218 | shell startup. This variable is readonly. | |
1219 | .TP | |
1220 | .B FUNCNAME | |
1221 | The name of any currently-executing shell function. | |
1222 | This variable exists only when a shell function is executing. | |
1223 | Assignments to | |
726f6388 | 1224 | .SM |
f73dda09 JA |
1225 | .B FUNCNAME |
1226 | have no effect and return an error status. | |
726f6388 JA |
1227 | If |
1228 | .SM | |
f73dda09 | 1229 | .B FUNCNAME |
726f6388 JA |
1230 | is unset, it loses its special properties, even if it is |
1231 | subsequently reset. | |
1232 | .TP | |
f73dda09 JA |
1233 | .B GROUPS |
1234 | An array variable containing the list of groups of which the current | |
1235 | user is a member. | |
1236 | Assignments to | |
1237 | .SM | |
1238 | .B GROUPS | |
1239 | have no effect and return an error status. | |
726f6388 JA |
1240 | If |
1241 | .SM | |
f73dda09 | 1242 | .B GROUPS |
726f6388 JA |
1243 | is unset, it loses its special properties, even if it is |
1244 | subsequently reset. | |
1245 | .TP | |
1246 | .B HISTCMD | |
1247 | The history number, or index in the history list, of the current | |
ccc6cda3 JA |
1248 | command. |
1249 | If | |
726f6388 JA |
1250 | .SM |
1251 | .B HISTCMD | |
1252 | is unset, it loses its special properties, even if it is | |
1253 | subsequently reset. | |
1254 | .TP | |
f73dda09 JA |
1255 | .B HOSTNAME |
1256 | Automatically set to the name of the current host. | |
bb70624e | 1257 | .TP |
f73dda09 JA |
1258 | .B HOSTTYPE |
1259 | Automatically set to a string that uniquely | |
1260 | describes the type of machine on which | |
1261 | .B bash | |
1262 | is executing. | |
1263 | The default is system-dependent. | |
1264 | .TP | |
1265 | .B LINENO | |
1266 | Each time this parameter is referenced, the shell substitutes | |
1267 | a decimal number representing the current sequential line number | |
1268 | (starting with 1) within a script or function. When not in a | |
1269 | script or function, the value substituted is not guaranteed to | |
1270 | be meaningful. | |
ccc6cda3 JA |
1271 | If |
1272 | .SM | |
f73dda09 | 1273 | .B LINENO |
ccc6cda3 JA |
1274 | is unset, it loses its special properties, even if it is |
1275 | subsequently reset. | |
1276 | .TP | |
f73dda09 JA |
1277 | .B MACHTYPE |
1278 | Automatically set to a string that fully describes the system | |
1279 | type on which | |
1280 | .B bash | |
1281 | is executing, in the standard GNU \fIcpu-company-system\fP format. | |
1282 | The default is system-dependent. | |
1283 | .TP | |
1284 | .B OLDPWD | |
1285 | The previous working directory as set by the | |
1286 | .B cd | |
1287 | command. | |
ccc6cda3 | 1288 | .TP |
726f6388 JA |
1289 | .B OPTARG |
1290 | The value of the last option argument processed by the | |
1291 | .B getopts | |
1292 | builtin command (see | |
1293 | .SM | |
1294 | .B SHELL BUILTIN COMMANDS | |
1295 | below). | |
1296 | .TP | |
1297 | .B OPTIND | |
1298 | The index of the next argument to be processed by the | |
1299 | .B getopts | |
1300 | builtin command (see | |
1301 | .SM | |
1302 | .B SHELL BUILTIN COMMANDS | |
1303 | below). | |
1304 | .TP | |
726f6388 JA |
1305 | .B OSTYPE |
1306 | Automatically set to a string that | |
1307 | describes the operating system on which | |
1308 | .B bash | |
ccc6cda3 JA |
1309 | is executing. |
1310 | The default is system-dependent. | |
1311 | .TP | |
f73dda09 JA |
1312 | .B PIPESTATUS |
1313 | An array variable (see | |
1314 | .B Arrays | |
1315 | below) containing a list of exit status values from the processes | |
1316 | in the most-recently-executed foreground pipeline (which may | |
1317 | contain only a single command). | |
ccc6cda3 | 1318 | .TP |
f73dda09 JA |
1319 | .B PPID |
1320 | The process ID of the shell's parent. This variable is readonly. | |
1321 | .TP | |
1322 | .B PWD | |
1323 | The current working directory as set by the | |
1324 | .B cd | |
1325 | command. | |
1326 | .TP | |
1327 | .B RANDOM | |
1328 | Each time this parameter is referenced, a random integer between | |
1329 | 0 and 32767 is | |
1330 | generated. The sequence of random numbers may be initialized by assigning | |
1331 | a value to | |
1332 | .SM | |
1333 | .BR RANDOM . | |
1334 | If | |
1335 | .SM | |
1336 | .B RANDOM | |
1337 | is unset, it loses its special properties, even if it is | |
1338 | subsequently reset. | |
1339 | .TP | |
1340 | .B REPLY | |
1341 | Set to the line of input read by the | |
1342 | .B read | |
1343 | builtin command when no arguments are supplied. | |
1344 | .TP | |
1345 | .B SECONDS | |
1346 | Each time this parameter is | |
1347 | referenced, the number of seconds since shell invocation is returned. If a | |
1348 | value is assigned to | |
1349 | .SM | |
1350 | .BR SECONDS , | |
1351 | the value returned upon subsequent | |
1352 | references is | |
1353 | the number of seconds since the assignment plus the value assigned. | |
1354 | If | |
1355 | .SM | |
1356 | .B SECONDS | |
1357 | is unset, it loses its special properties, even if it is | |
1358 | subsequently reset. | |
1359 | .TP | |
1360 | .B SHELLOPTS | |
1361 | A colon-separated list of enabled shell options. Each word in | |
1362 | the list is a valid argument for the | |
1363 | .B \-o | |
1364 | option to the | |
1365 | .B set | |
1366 | builtin command (see | |
1367 | .SM | |
1368 | .B "SHELL BUILTIN COMMANDS" | |
1369 | below). The options appearing in | |
ccc6cda3 JA |
1370 | .SM |
1371 | .B SHELLOPTS | |
1372 | are those reported as | |
1373 | .I on | |
1374 | by \fBset \-o\fP. | |
1375 | If this variable is in the environment when | |
1376 | .B bash | |
1377 | starts up, each shell option in the list will be enabled before | |
1378 | reading any startup files. | |
1379 | This variable is read-only. | |
bb70624e | 1380 | .TP |
f73dda09 JA |
1381 | .B SHLVL |
1382 | Incremented by one each time an instance of | |
1383 | .B bash | |
1384 | is started. | |
bb70624e | 1385 | .TP |
f73dda09 JA |
1386 | .B UID |
1387 | Expands to the user ID of the current user, initialized at shell startup. | |
1388 | This variable is readonly. | |
726f6388 JA |
1389 | .PD |
1390 | .PP | |
1391 | The following variables are used by the shell. In some cases, | |
1392 | .B bash | |
1393 | assigns a default value to a variable; these cases are noted | |
1394 | below. | |
1395 | .PP | |
1396 | .PD 0 | |
1397 | .TP | |
d166f048 | 1398 | .B BASH_ENV |
726f6388 JA |
1399 | If this parameter is set when \fBbash\fP is executing a shell script, |
1400 | its value is interpreted as a filename containing commands to | |
1401 | initialize the shell, as in | |
cce855bc | 1402 | .IR ~/.bashrc . |
726f6388 JA |
1403 | The value of |
1404 | .SM | |
d166f048 | 1405 | .B BASH_ENV |
726f6388 | 1406 | is subjected to parameter expansion, command substitution, and arithmetic |
ccc6cda3 | 1407 | expansion before being interpreted as a file name. |
726f6388 JA |
1408 | .SM |
1409 | .B PATH | |
ccc6cda3 | 1410 | is not used to search for the resultant file name. |
726f6388 | 1411 | .TP |
f73dda09 JA |
1412 | .B CDPATH |
1413 | The search path for the | |
1414 | .B cd | |
1415 | command. | |
1416 | This is a colon-separated list of directories in which the shell looks | |
1417 | for destination directories specified by the | |
1418 | .B cd | |
1419 | command. | |
1420 | A sample value is ``.:~:/usr''. | |
726f6388 | 1421 | .TP |
f73dda09 JA |
1422 | .B COLUMNS |
1423 | Used by the \fBselect\fP builtin command to determine the terminal width | |
1424 | when printing selection lists. Automatically set upon receipt of a SIGWINCH. | |
726f6388 | 1425 | .TP |
f73dda09 JA |
1426 | .B COMPREPLY |
1427 | An array variable from which \fBbash\fP reads the possible completions | |
1428 | generated by a shell function invoked by the programmable completion | |
1429 | facility (see \fBProgrammable Completion\fP below). | |
726f6388 | 1430 | .TP |
f73dda09 JA |
1431 | .B FCEDIT |
1432 | The default editor for the | |
1433 | .B fc | |
1434 | builtin command. | |
726f6388 | 1435 | .TP |
f73dda09 JA |
1436 | .B FIGNORE |
1437 | A colon-separated list of suffixes to ignore when performing | |
1438 | filename completion (see | |
726f6388 | 1439 | .SM |
f73dda09 JA |
1440 | .B READLINE |
1441 | below). | |
1442 | A filename whose suffix matches one of the entries in | |
726f6388 | 1443 | .SM |
f73dda09 JA |
1444 | .B FIGNORE |
1445 | is excluded from the list of matched filenames. | |
1446 | A sample value is ``.o:~''. | |
ccc6cda3 | 1447 | .TP |
f73dda09 JA |
1448 | .B GLOBIGNORE |
1449 | A colon-separated list of patterns defining the set of filenames to | |
1450 | be ignored by pathname expansion. | |
1451 | If a filename matched by a pathname expansion pattern also matches one | |
1452 | of the patterns in | |
726f6388 | 1453 | .SM |
f73dda09 JA |
1454 | .BR GLOBIGNORE , |
1455 | it is removed from the list of matches. | |
1456 | .TP | |
1457 | .B HISTCONTROL | |
1458 | If set to a value of | |
1459 | .IR ignorespace , | |
1460 | lines which begin with a | |
1461 | .B space | |
1462 | character are not entered on the history list. | |
1463 | If set to a value of | |
1464 | .IR ignoredups , | |
1465 | lines matching the last history line are not entered. | |
1466 | A value of | |
1467 | .I ignoreboth | |
1468 | combines the two options. | |
1469 | If unset, or if set to any other value than those above, | |
1470 | all lines read | |
1471 | by the parser are saved on the history list, subject to the value | |
1472 | of | |
1473 | .BR HISTIGNORE . | |
1474 | This variable's function is superseded by | |
1475 | .BR HISTIGNORE . | |
1476 | The second and subsequent lines of a multi-line compound command are | |
1477 | not tested, and are added to the history regardless of the value of | |
1478 | .BR HISTCONTROL . | |
726f6388 JA |
1479 | .TP |
1480 | .B HISTFILE | |
ccc6cda3 | 1481 | The name of the file in which command history is saved (see |
726f6388 JA |
1482 | .SM |
1483 | .B HISTORY | |
ccc6cda3 | 1484 | below). The default value is \fI~/.bash_history\fP. If unset, the |
726f6388 JA |
1485 | command history is not saved when an interactive shell exits. |
1486 | .TP | |
1487 | .B HISTFILESIZE | |
1488 | The maximum number of lines contained in the history file. When this | |
1489 | variable is assigned a value, the history file is truncated, if | |
1490 | necessary, to contain no more than that number of lines. The default | |
ccc6cda3 JA |
1491 | value is 500. The history file is also truncated to this size after |
1492 | writing it when an interactive shell exits. | |
726f6388 | 1493 | .TP |
f73dda09 JA |
1494 | .B HISTIGNORE |
1495 | A colon-separated list of patterns used to decide which command lines | |
1496 | should be saved on the history list. Each pattern is anchored at the | |
1497 | beginning of the line and must match the complete line (no implicit | |
1498 | `\fB*\fP' is appended). Each pattern is tested against the line | |
1499 | after the checks specified by | |
1500 | .B HISTCONTROL | |
1501 | are applied. | |
1502 | In addition to the normal shell pattern matching characters, `\fB&\fP' | |
1503 | matches the previous history line. `\fB&\fP' may be escaped using a | |
1504 | backslash; the backslash is removed before attempting a match. | |
1505 | The second and subsequent lines of a multi-line compound command are | |
1506 | not tested, and are added to the history regardless of the value of | |
1507 | .BR HISTIGNORE . | |
1508 | .TP | |
1509 | .B HISTSIZE | |
1510 | The number of commands to remember in the command history (see | |
1511 | .SM | |
1512 | .B HISTORY | |
1513 | below). The default value is 500. | |
1514 | .TP | |
1515 | .B HOME | |
1516 | The home directory of the current user; the default argument for the | |
1517 | \fBcd\fP builtin command. | |
1518 | The value of this variable is also used when performing tilde expansion. | |
1519 | .TP | |
1520 | .B HOSTFILE | |
1521 | Contains the name of a file in the same format as | |
1522 | .FN /etc/hosts | |
1523 | that should be read when the shell needs to complete a | |
1524 | hostname. | |
1525 | The list of possible hostname completions may be changed while the | |
1526 | shell is running; | |
1527 | the next time hostname completion is attempted after the | |
1528 | value is changed, | |
726f6388 | 1529 | .B bash |
f73dda09 JA |
1530 | adds the contents of the new file to the existing list. |
1531 | If | |
726f6388 | 1532 | .SM |
f73dda09 JA |
1533 | .B HOSTFILE |
1534 | is set, but has no value, \fBbash\fP attempts to read | |
1535 | .FN /etc/hosts | |
1536 | to obtain the list of possible hostname completions. | |
1537 | When | |
726f6388 | 1538 | .SM |
f73dda09 JA |
1539 | .B HOSTFILE |
1540 | is unset, the hostname list is cleared. | |
1541 | .TP | |
1542 | .B IFS | |
1543 | The | |
1544 | .I Internal Field Separator | |
1545 | that is used | |
1546 | for word splitting after expansion and to | |
1547 | split lines into words with the | |
1548 | .B read | |
1549 | builtin command. The default value is | |
1550 | ``<space><tab><newline>''. | |
1551 | .TP | |
1552 | .B IGNOREEOF | |
1553 | Controls the | |
1554 | action of an interactive shell on receipt of an | |
1555 | .SM | |
1556 | .B EOF | |
1557 | character as the sole input. If set, the value is the number of | |
1558 | consecutive | |
1559 | .SM | |
1560 | .B EOF | |
1561 | characters which must be | |
1562 | typed as the first characters on an input line before | |
1563 | .B bash | |
1564 | exits. If the variable exists but does not have a numeric value, or | |
1565 | has no value, the default value is 10. If it does not exist, | |
1566 | .SM | |
1567 | .B EOF | |
1568 | signifies the end of input to the shell. | |
1569 | .TP | |
1570 | .B INPUTRC | |
1571 | The filename for the | |
1572 | .B readline | |
1573 | startup file, overriding the default of | |
1574 | .FN ~/.inputrc | |
1575 | (see | |
1576 | .SM | |
1577 | .B READLINE | |
1578 | below). | |
726f6388 | 1579 | .TP |
ccc6cda3 JA |
1580 | .B LANG |
1581 | Used to determine the locale category for any category not specifically | |
1582 | selected with a variable starting with \fBLC_\fP. | |
1583 | .TP | |
1584 | .B LC_ALL | |
1585 | This variable overrides the value of \fBLANG\fP and any other | |
1586 | \fBLC_\fP variable specifying a locale category. | |
1587 | .TP | |
1588 | .B LC_COLLATE | |
1589 | This variable determines the collation order used when sorting the | |
cce855bc JA |
1590 | results of pathname expansion, and determines the behavior of range |
1591 | expressions, equivalence classes, and collating sequences within | |
1592 | pathname expansion and pattern matching. | |
1593 | .TP | |
1594 | .B LC_CTYPE | |
1595 | This variable determines the interpretation of characters and the | |
1596 | behavior of character classes within pathname expansion and pattern | |
1597 | matching. | |
ccc6cda3 JA |
1598 | .TP |
1599 | .B LC_MESSAGES | |
1600 | This variable determines the locale used to translate double-quoted | |
1601 | strings preceded by a \fB$\fP. | |
1602 | .TP | |
bb70624e JA |
1603 | .B LC_NUMERIC |
1604 | This variable determines the locale category used for number formatting. | |
1605 | .TP | |
28ef6c31 JA |
1606 | .B LINES |
1607 | Used by the \fBselect\fP builtin command to determine the column length | |
1608 | for printing selection lists. Automatically set upon receipt of a SIGWINCH. | |
1609 | .TP | |
f73dda09 JA |
1610 | .B MAIL |
1611 | If this parameter is set to a file name and the | |
726f6388 | 1612 | .SM |
f73dda09 JA |
1613 | .B MAILPATH |
1614 | variable is not set, | |
726f6388 | 1615 | .B bash |
f73dda09 | 1616 | informs the user of the arrival of mail in the specified file. |
726f6388 | 1617 | .TP |
f73dda09 JA |
1618 | .B MAILCHECK |
1619 | Specifies how | |
1620 | often (in seconds) | |
1621 | .B bash | |
1622 | checks for mail. The default is 60 seconds. When it is time to check | |
1623 | for mail, the shell does so before displaying the primary prompt. | |
1624 | If this variable is unset, or set to a value that is not a number | |
1625 | greater than or equal to zero, the shell disables mail checking. | |
726f6388 | 1626 | .TP |
f73dda09 JA |
1627 | .B MAILPATH |
1628 | A colon-separated list of file names to be checked for mail. | |
1629 | The message to be printed when mail arrives in a particular file | |
1630 | may be specified by separating the file name from the message with a `?'. | |
1631 | When used in the text of the message, \fB$_\fP expands to the name of | |
1632 | the current mailfile. | |
1633 | Example: | |
1634 | .RS | |
1635 | .PP | |
1636 | \fBMAILPATH\fP='/var/mail/bfox?"You have mail":~/shell\-mail?"$_ has mail!"' | |
1637 | .PP | |
1638 | .B Bash | |
1639 | supplies a default value for this variable, but the location of the user | |
1640 | mail files that it uses is system dependent (e.g., /var/mail/\fB$USER\fP). | |
1641 | .RE | |
726f6388 | 1642 | .TP |
f73dda09 JA |
1643 | .B OPTERR |
1644 | If set to the value 1, | |
1645 | .B bash | |
1646 | displays error messages generated by the | |
1647 | .B getopts | |
1648 | builtin command (see | |
726f6388 | 1649 | .SM |
f73dda09 | 1650 | .B SHELL BUILTIN COMMANDS |
ccc6cda3 | 1651 | below). |
726f6388 | 1652 | .SM |
f73dda09 JA |
1653 | .B OPTERR |
1654 | is initialized to 1 each time the shell is invoked or a shell | |
1655 | script is executed. | |
ccc6cda3 | 1656 | .TP |
f73dda09 JA |
1657 | .B PATH |
1658 | The search path for commands. It | |
1659 | is a colon-separated list of directories in which | |
1660 | the shell looks for commands (see | |
ccc6cda3 | 1661 | .SM |
f73dda09 JA |
1662 | .B COMMAND EXECUTION |
1663 | below). The default path is system-dependent, | |
1664 | and is set by the administrator who installs | |
1665 | .BR bash . | |
1666 | A common value is | |
1667 | .if t \f(CW/usr/gnu/bin:/usr/local/bin:/usr/ucb:/bin:/usr/bin:.\fP. | |
1668 | .if n ``/usr/gnu/bin:/usr/local/bin:/usr/ucb:/bin:/usr/bin:.''. | |
726f6388 | 1669 | .TP |
f73dda09 JA |
1670 | .B POSIXLY_CORRECT |
1671 | If this variable is in the environment when \fBbash\fP starts, the shell | |
1672 | enters \fIposix mode\fP before reading the startup files, as if the | |
1673 | .B \-\-posix | |
1674 | invocation option had been supplied. If it is set while the shell is | |
1675 | running, \fBbash\fP enables \fIposix mode\fP, as if the command | |
1676 | .if t \f(CWset -o posix\fP | |
1677 | .if n \fIset -o posix\fP | |
1678 | had been executed. | |
726f6388 | 1679 | .TP |
f73dda09 JA |
1680 | .B PROMPT_COMMAND |
1681 | If set, the value is executed as a command prior to issuing each primary | |
1682 | prompt. | |
ccc6cda3 | 1683 | .TP |
f73dda09 JA |
1684 | .B PS1 |
1685 | The value of this parameter is expanded (see | |
1686 | .SM | |
1687 | .B PROMPTING | |
1688 | below) and used as the primary prompt string. The default value is | |
1689 | ``\fB\es\-\ev\e$ \fP''. | |
726f6388 | 1690 | .TP |
f73dda09 JA |
1691 | .B PS2 |
1692 | The value of this parameter is expanded as with | |
1693 | .B PS1 | |
1694 | and used as the secondary prompt string. The default is | |
1695 | ``\fB> \fP''. | |
1696 | .TP | |
1697 | .B PS3 | |
1698 | The value of this parameter is used as the prompt for the | |
1699 | .B select | |
1700 | command (see | |
726f6388 | 1701 | .SM |
f73dda09 JA |
1702 | .B SHELL GRAMMAR |
1703 | above). | |
726f6388 | 1704 | .TP |
f73dda09 JA |
1705 | .B PS4 |
1706 | The value of this parameter is expanded as with | |
1707 | .B PS1 | |
1708 | and the value is printed before each command | |
726f6388 | 1709 | .B bash |
f73dda09 | 1710 | displays during an execution trace. The first character of |
bb70624e | 1711 | .SM |
f73dda09 JA |
1712 | .B PS4 |
1713 | is replicated multiple times, as necessary, to indicate multiple | |
1714 | levels of indirection. The default is ``\fB+ \fP''. | |
1715 | .TP | |
1716 | .B TIMEFORMAT | |
1717 | The value of this parameter is used as a format string specifying | |
1718 | how the timing information for pipelines prefixed with the | |
1719 | .B time | |
1720 | reserved word should be displayed. | |
1721 | The \fB%\fP character introduces an escape sequence that is | |
1722 | expanded to a time value or other information. | |
1723 | The escape sequences and their meanings are as follows; the | |
1724 | braces denote optional portions. | |
1725 | .sp .5 | |
1726 | .RS | |
1727 | .PD 0 | |
1728 | .TP 10 | |
1729 | .B %% | |
1730 | A literal \fB%\fP. | |
1731 | .TP | |
1732 | .B %[\fIp\fP][l]R | |
1733 | The elapsed time in seconds. | |
1734 | .TP | |
1735 | .B %[\fIp\fP][l]U | |
1736 | The number of CPU seconds spent in user mode. | |
1737 | .TP | |
1738 | .B %[\fIp\fP][l]S | |
1739 | The number of CPU seconds spent in system mode. | |
1740 | .TP | |
1741 | .B %P | |
1742 | The CPU percentage, computed as (%U + %S) / %R. | |
1743 | .PD | |
1744 | .RE | |
1745 | .IP | |
1746 | The optional \fIp\fP is a digit specifying the \fIprecision\fP, | |
1747 | the number of fractional digits after a decimal point. | |
1748 | A value of 0 causes no decimal point or fraction to be output. | |
1749 | At most three places after the decimal point may be specified; | |
1750 | values of \fIp\fP greater than 3 are changed to 3. | |
1751 | If \fIp\fP is not specified, the value 3 is used. | |
1752 | .IP | |
1753 | The optional \fBl\fP specifies a longer format, including | |
1754 | minutes, of the form \fIMM\fPm\fISS\fP.\fIFF\fPs. | |
1755 | The value of \fIp\fP determines whether or not the fraction is | |
1756 | included. | |
1757 | .IP | |
1758 | If this variable is not set, \fBbash\fP acts as if it had the | |
1759 | value \fB$'\enreal\et%3lR\enuser\et%3lU\ensys\t%3lS'\fP. | |
1760 | If the value is null, no timing information is displayed. | |
1761 | A trailing newline is added when the format string is displayed. | |
1762 | .TP | |
1763 | .B TMOUT | |
1764 | If set to a value greater than zero, the value is interpreted as the | |
1765 | number of seconds to wait for input after issuing the primary prompt. | |
1766 | .B Bash | |
1767 | terminates after waiting for that number of seconds if input does | |
1768 | not arrive. | |
726f6388 | 1769 | .TP |
726f6388 JA |
1770 | .B auto_resume |
1771 | This variable controls how the shell interacts with the user and | |
1772 | job control. If this variable is set, single word simple | |
1773 | commands without redirections are treated as candidates for resumption | |
1774 | of an existing stopped job. There is no ambiguity allowed; if there is | |
1775 | more than one job beginning with the string typed, the job most recently | |
1776 | accessed is selected. The | |
1777 | .I name | |
1778 | of a stopped job, in this context, is the command line used to | |
1779 | start it. | |
1780 | If set to the value | |
1781 | .IR exact , | |
1782 | the string supplied must match the name of a stopped job exactly; | |
1783 | if set to | |
1784 | .IR substring , | |
1785 | the string supplied needs to match a substring of the name of a | |
1786 | stopped job. The | |
1787 | .I substring | |
1788 | value provides functionality analogous to the | |
1789 | .B %? | |
ccc6cda3 | 1790 | job identifier (see |
726f6388 JA |
1791 | .SM |
1792 | .B JOB CONTROL | |
1793 | below). If set to any other value, the supplied string must | |
1794 | be a prefix of a stopped job's name; this provides functionality | |
1795 | analogous to the | |
1796 | .B % | |
ccc6cda3 | 1797 | job identifier. |
bb70624e | 1798 | .TP |
f73dda09 JA |
1799 | .B histchars |
1800 | The two or three characters which control history expansion | |
1801 | and tokenization (see | |
1802 | .SM | |
1803 | .B HISTORY EXPANSION | |
1804 | below). The first character is the \fIhistory expansion\fP character, | |
1805 | the character which signals the start of a history | |
1806 | expansion, normally `\fB!\fP'. | |
1807 | The second character is the \fIquick substitution\fP | |
1808 | character, which is used as shorthand for re-running the previous | |
1809 | command entered, substituting one string for another in the command. | |
1810 | The default is `\fB^\fP'. | |
1811 | The optional third character is the character | |
1812 | which indicates that the remainder of the line is a comment when found | |
1813 | as the first character of a word, normally `\fB#\fP'. The history | |
1814 | comment character causes history substitution to be skipped for the | |
1815 | remaining words on the line. It does not necessarily cause the shell | |
1816 | parser to treat the rest of the line as a comment. | |
726f6388 | 1817 | .PD |
ccc6cda3 JA |
1818 | .SS Arrays |
1819 | .B Bash | |
1820 | provides one-dimensional array variables. Any variable may be used as | |
1821 | an array; the | |
1822 | .B declare | |
1823 | builtin will explicitly declare an array. There is no maximum | |
1824 | limit on the size of an array, nor any requirement that members | |
1825 | be indexed or assigned contiguously. Arrays are indexed using | |
1826 | integers and are zero-based. | |
1827 | .PP | |
1828 | An array is created automatically if any variable is assigned to using | |
1829 | the syntax \fIname\fP[\fIsubscript\fP]=\fIvalue\fP. The | |
1830 | .I subscript | |
1831 | is treated as an arithmetic expression that must evaluate to a number | |
1832 | greater than or equal to zero. To explicitly declare an array, use | |
1833 | .B declare \-a \fIname\fP | |
1834 | (see | |
1835 | .SM | |
1836 | .B SHELL BUILTIN COMMANDS | |
1837 | below). | |
1838 | .B declare \-a \fIname\fP[\fIsubscript\fP] | |
1839 | is also accepted; the \fIsubscript\fP is ignored. Attributes may be | |
1840 | specified for an array variable using the | |
1841 | .B declare | |
1842 | and | |
1843 | .B readonly | |
1844 | builtins. Each attribute applies to all members of an array. | |
1845 | .PP | |
1846 | Arrays are assigned to using compound assignments of the form | |
1847 | \fIname\fP=\fB(\fPvalue\fI1\fP ... value\fIn\fP\fB)\fP, where each | |
1848 | \fIvalue\fP is of the form [\fIsubscript\fP]=\fIstring\fP. Only | |
1849 | \fIstring\fP is required. If | |
1850 | the optional brackets and subscript are supplied, that index is assigned to; | |
1851 | otherwise the index of the element assigned is the last index assigned | |
1852 | to by the statement plus one. Indexing starts at zero. | |
1853 | This syntax is also accepted by the | |
1854 | .B declare | |
1855 | builtin. Individual array elements may be assigned to using the | |
1856 | \fIname\fP[\fIsubscript\fP]=\fIvalue\fP syntax introduced above. | |
1857 | .PP | |
1858 | Any element of an array may be referenced using | |
1859 | ${\fIname\fP[\fIsubscript\fP]}. The braces are required to avoid | |
1860 | conflicts with pathname expansion. If | |
1861 | \fIsubscript\fP is \fB@\fP or \fB*\fP, the word expands to | |
1862 | all members of \fIname\fP. These subscripts differ only when the | |
1863 | word appears within double quotes. If the word is double-quoted, | |
1864 | ${\fIname\fP[*]} expands to a single | |
1865 | word with the value of each array member separated by the first | |
1866 | character of the | |
1867 | .SM | |
1868 | .B IFS | |
1869 | special variable, and ${\fIname\fP[@]} expands each element of | |
1870 | \fIname\fP to a separate word. When there are no array members, | |
1871 | ${\fIname\fP[@]} expands to nothing. This is analogous to the expansion | |
1872 | of the special parameters \fB*\fP and \fB@\fP (see | |
1873 | .B Special Parameters | |
1874 | above). ${#\fIname\fP[\fIsubscript\fP]} expands to the length of | |
1875 | ${\fIname\fP[\fIsubscript\fP]}. If \fIsubscript\fP is \fB*\fP or | |
1876 | \fB@\fP, the expansion is the number of elements in the array. | |
1877 | Referencing an array variable without a subscript is equivalent to | |
1878 | referencing element zero. | |
1879 | .PP | |
1880 | The | |
1881 | .B unset | |
bb70624e | 1882 | builtin is used to destroy arrays. \fBunset\fP \fIname\fP[\fIsubscript\fP] |
ccc6cda3 JA |
1883 | destroys the array element at index \fIsubscript\fP. |
1884 | \fBunset\fP \fIname\fP, where \fIname\fP is an array, or | |
1885 | \fBunset\fP \fIname\fP[\fIsubscript\fP], where | |
1886 | \fIsubscript\fP is \fB*\fP or \fB@\fP, removes the entire array. | |
1887 | .PP | |
1888 | The | |
1889 | .BR declare , | |
1890 | .BR local , | |
1891 | and | |
1892 | .B readonly | |
1893 | builtins each accept a | |
1894 | .B \-a | |
1895 | option to specify an array. The | |
1896 | .B read | |
1897 | builtin accepts a | |
1898 | .B \-a | |
1899 | option to assign a list of words read from the standard input | |
1900 | to an array. The | |
1901 | .B set | |
1902 | and | |
1903 | .B declare | |
1904 | builtins display array values in a way that allows them to be | |
1905 | reused as assignments. | |
726f6388 JA |
1906 | .SH EXPANSION |
1907 | Expansion is performed on the command line after it has been split into | |
1908 | words. There are seven kinds of expansion performed: | |
1909 | .IR "brace expansion" , | |
1910 | .IR "tilde expansion" , | |
1911 | .IR "parameter and variable expansion" , | |
1912 | .IR "command substitution" , | |
1913 | .IR "arithmetic expansion" , | |
1914 | .IR "word splitting" , | |
1915 | and | |
1916 | .IR "pathname expansion" . | |
1917 | .PP | |
1918 | The order of expansions is: brace expansion, tilde expansion, | |
ccc6cda3 JA |
1919 | parameter, variable and arithmetic expansion and |
1920 | command substitution | |
1921 | (done in a left-to-right fashion), word splitting, and pathname | |
726f6388 JA |
1922 | expansion. |
1923 | .PP | |
1924 | On systems that can support it, there is an additional expansion | |
1925 | available: \fIprocess substitution\fP. | |
1926 | .PP | |
1927 | Only brace expansion, word splitting, and pathname expansion | |
1928 | can change the number of words of the expansion; other expansions | |
1929 | expand a single word to a single word. | |
ccc6cda3 | 1930 | The only exceptions to this are the expansions of |
cce855bc | 1931 | "\fB$@\fP" and "\fB${\fP\fIname\fP\fB[@]}\fP" |
ccc6cda3 | 1932 | as explained above (see |
726f6388 JA |
1933 | .SM |
1934 | .BR PARAMETERS ). | |
1935 | .SS Brace Expansion | |
1936 | .PP | |
1937 | .I "Brace expansion" | |
1938 | is a mechanism by which arbitrary strings | |
1939 | may be generated. This mechanism is similar to | |
1940 | \fIpathname expansion\fP, but the filenames generated | |
1941 | need not exist. Patterns to be brace expanded take | |
1942 | the form of an optional | |
1943 | .IR preamble , | |
1944 | followed by a series of comma-separated strings | |
1945 | between a pair of braces, followed by an optional | |
cce855bc | 1946 | .IR postscript . |
ccc6cda3 | 1947 | The preamble is prefixed to each string contained |
cce855bc | 1948 | within the braces, and the postscript is then appended |
726f6388 JA |
1949 | to each resulting string, expanding left to right. |
1950 | .PP | |
1951 | Brace expansions may be nested. The results of each expanded | |
1952 | string are not sorted; left to right order is preserved. | |
1953 | For example, a\fB{\fPd,c,b\fB}\fPe expands into `ade ace abe'. | |
1954 | .PP | |
1955 | Brace expansion is performed before any other expansions, | |
1956 | and any characters special to other expansions are preserved | |
1957 | in the result. It is strictly textual. | |
1958 | .B Bash | |
1959 | does not apply any syntactic interpretation to the context of the | |
1960 | expansion or the text between the braces. | |
1961 | .PP | |
1962 | A correctly-formed brace expansion must contain unquoted opening | |
1963 | and closing braces, and at least one unquoted comma. | |
1964 | Any incorrectly formed brace expansion is left unchanged. | |
ccc6cda3 JA |
1965 | A \fB{\fP or \fB,\fP may be quoted with a backslash to prevent its |
1966 | being considered part of a brace expression. | |
bb70624e JA |
1967 | To avoid conflicts with parameter expansion, the string \fB${\fP |
1968 | is not considered eligible for brace expansion. | |
726f6388 JA |
1969 | .PP |
1970 | This construct is typically used as shorthand when the common | |
1971 | prefix of the strings to be generated is longer than in the | |
1972 | above example: | |
1973 | .RS | |
1974 | .PP | |
1975 | mkdir /usr/local/src/bash/{old,new,dist,bugs} | |
1976 | .RE | |
1977 | or | |
1978 | .RS | |
1979 | chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}} | |
1980 | .RE | |
1981 | .PP | |
1982 | Brace expansion introduces a slight incompatibility with | |
ccc6cda3 JA |
1983 | historical versions of |
1984 | .BR sh . | |
726f6388 JA |
1985 | .B sh |
1986 | does not treat opening or closing braces specially when they | |
1987 | appear as part of a word, and preserves them in the output. | |
1988 | .B Bash | |
1989 | removes braces from words as a consequence of brace | |
1990 | expansion. For example, a word entered to | |
1991 | .B sh | |
1992 | as \fIfile{1,2}\fP | |
1993 | appears identically in the output. The same word is | |
1994 | output as | |
1995 | .I file1 file2 | |
1996 | after expansion by | |
1997 | .BR bash . | |
1998 | If strict compatibility with | |
1999 | .B sh | |
2000 | is desired, start | |
2001 | .B bash | |
2002 | with the | |
ccc6cda3 JA |
2003 | .B +B |
2004 | option or disable brace expansion with the | |
2005 | .B +B | |
726f6388 JA |
2006 | option to the |
2007 | .B set | |
2008 | command (see | |
2009 | .SM | |
2010 | .B SHELL BUILTIN COMMANDS | |
2011 | below). | |
2012 | .SS Tilde Expansion | |
2013 | .PP | |
cce855bc JA |
2014 | If a word begins with an unquoted tilde character (`\fB~\fP'), all of |
2015 | the characters preceding the first unquoted slash (or all characters, | |
2016 | if there is no unquoted slash) are considered a \fItilde-prefix\fP. | |
2017 | If none of the characters in the tilde-prefix are quoted, the | |
2018 | characters in the tilde-prefix following the tilde are treated as a | |
2019 | possible \fIlogin name\fP. | |
2020 | If this login name is the null string, the tilde is replaced with the | |
2021 | value of the shell parameter | |
726f6388 JA |
2022 | .SM |
2023 | .BR HOME . | |
2024 | If | |
2025 | .SM | |
2026 | .B HOME | |
cce855bc JA |
2027 | is unset, the home directory of the user executing the shell is |
2028 | substituted instead. | |
2029 | Otherwise, the tilde-prefix is replaced with the home directory | |
2030 | associated with the specified login name. | |
726f6388 | 2031 | .PP |
cce855bc | 2032 | If the tilde-prefix is a `~+', the value of the shell variable |
726f6388 JA |
2033 | .SM |
2034 | .B PWD | |
cce855bc JA |
2035 | replaces the tilde-prefix. |
2036 | If the tilde-prefix is a `~\-', the value of the shell variable | |
2037 | .SM | |
2038 | .BR OLDPWD , | |
2039 | if it is set, is substituted. | |
2040 | If the characters following the tilde in the tilde-prefix consist | |
2041 | of a number \fIN\fP, optionally prefixed | |
2042 | by a `+' or a `\-', the tilde-prefix is replaced with the corresponding | |
2043 | element from the directory stack, as it would be displayed by the | |
2044 | .B dirs | |
2045 | builtin invoked with the tilde-prefix as an argument. | |
2046 | If the characters following the tilde in the tilde-prefix consist of a | |
2047 | number without a leading `+' or `\-', `+' is assumed. | |
2048 | .PP | |
2049 | If the login name is invalid, or the tilde expansion fails, the word | |
2050 | is unchanged. | |
726f6388 | 2051 | .PP |
cce855bc JA |
2052 | Each variable assignment is checked for unquoted tilde-prefixes immediately |
2053 | following a | |
726f6388 JA |
2054 | .B : |
2055 | or | |
2056 | .BR = . | |
cce855bc JA |
2057 | In these cases, tilde expansion is also performed. |
2058 | Consequently, one may use file names with tildes in assignments to | |
726f6388 JA |
2059 | .SM |
2060 | .BR PATH , | |
2061 | .SM | |
2062 | .BR MAILPATH , | |
2063 | and | |
2064 | .SM | |
2065 | .BR CDPATH , | |
2066 | and the shell assigns the expanded value. | |
2067 | .SS Parameter Expansion | |
2068 | .PP | |
2069 | The `\fB$\fP' character introduces parameter expansion, | |
2070 | command substitution, or arithmetic expansion. The parameter name | |
2071 | or symbol to be expanded may be enclosed in braces, which | |
2072 | are optional but serve to protect the variable to be expanded from | |
2073 | characters immediately following it which could be | |
2074 | interpreted as part of the name. | |
2075 | .PP | |
cce855bc JA |
2076 | When braces are used, the matching ending brace is the first `\fB}\fP' |
2077 | not escaped by a backslash or within a quoted string, and not within an | |
2078 | embedded arithmetic expansion, command substitution, or paramter | |
2079 | expansion. | |
2080 | .PP | |
726f6388 JA |
2081 | .PD 0 |
2082 | .TP | |
2083 | ${\fIparameter\fP} | |
2084 | The value of \fIparameter\fP is substituted. The braces are required | |
2085 | when | |
2086 | .I parameter | |
2087 | is a positional parameter with more than one digit, | |
2088 | or when | |
2089 | .I parameter | |
2090 | is followed by a character which is not to be | |
2091 | interpreted as part of its name. | |
2092 | .PD | |
2093 | .PP | |
ccc6cda3 JA |
2094 | If the first character of \fIparameter\fP is an exclamation point, |
2095 | a level of variable indirection is introduced. | |
2096 | \fBBash\fP uses the value of the variable formed from the rest of | |
2097 | \fIparameter\fP as the name of the variable; this variable is then | |
bb70624e | 2098 | expanded and that value is used in the rest of the substitution, rather |
ccc6cda3 JA |
2099 | than the value of \fIparameter\fP itself. |
2100 | This is known as \fIindirect expansion\fP. | |
bb70624e JA |
2101 | The exception to this is the expansion of ${!\fIprefix\fP*} |
2102 | described below. | |
ccc6cda3 | 2103 | .PP |
726f6388 JA |
2104 | In each of the cases below, \fIword\fP is subject to tilde expansion, |
2105 | parameter expansion, command substitution, and arithmetic expansion. | |
ccc6cda3 JA |
2106 | When not performing substring expansion, \fBbash\fP tests for a parameter |
2107 | that is unset or null; omitting the colon results in a test only for a | |
2108 | parameter that is unset. | |
726f6388 JA |
2109 | .PP |
2110 | .PD 0 | |
2111 | .TP | |
2112 | ${\fIparameter\fP\fB:\-\fP\fIword\fP} | |
2113 | \fBUse Default Values\fP. If | |
2114 | .I parameter | |
2115 | is unset or null, the expansion of | |
2116 | .I word | |
2117 | is substituted. Otherwise, the value of | |
2118 | .I parameter | |
2119 | is substituted. | |
2120 | .TP | |
2121 | ${\fIparameter\fP\fB:=\fP\fIword\fP} | |
2122 | \fBAssign Default Values\fP. | |
2123 | If | |
2124 | .I parameter | |
2125 | is unset or null, the expansion of | |
2126 | .I word | |
2127 | is assigned to | |
2128 | .IR parameter . | |
2129 | The value of | |
2130 | .I parameter | |
2131 | is then substituted. Positional parameters and special parameters may | |
2132 | not be assigned to in this way. | |
2133 | .TP | |
2134 | ${\fIparameter\fP\fB:?\fP\fIword\fP} | |
2135 | \fBDisplay Error if Null or Unset\fP. | |
2136 | If | |
2137 | .I parameter | |
2138 | is null or unset, the expansion of \fIword\fP (or a message to that effect | |
2139 | if | |
2140 | .I word | |
2141 | is not present) is written to the standard error and the shell, if it | |
2142 | is not interactive, exits. Otherwise, the value of \fIparameter\fP is | |
2143 | substituted. | |
2144 | .TP | |
2145 | ${\fIparameter\fP\fB:+\fP\fIword\fP} | |
2146 | \fBUse Alternate Value\fP. | |
2147 | If | |
2148 | .I parameter | |
2149 | is null or unset, nothing is substituted, otherwise the expansion of | |
2150 | .I word | |
2151 | is substituted. | |
2152 | .TP | |
ccc6cda3 JA |
2153 | .PD 0 |
2154 | ${\fIparameter\fP\fB:\fP\fIoffset\fP} | |
2155 | .TP | |
2156 | ${\fIparameter\fP\fB:\fP\fIoffset\fP\fB:\fP\fIlength\fP} | |
2157 | .PD | |
2158 | \fBSubstring Expansion.\fP | |
bb70624e JA |
2159 | Expands to up to \fIlength\fP characters of \fIparameter\fP |
2160 | starting at the character specified by \fIoffset\fP. | |
ccc6cda3 | 2161 | If \fIlength\fP is omitted, expands to the substring of |
bb70624e | 2162 | \fIparameter\fP starting at the character specified by \fIoffset\fP. |
ccc6cda3 JA |
2163 | \fIlength\fP and \fIoffset\fP are arithmetic expressions (see |
2164 | .SM | |
2165 | .B | |
2166 | ARITHMETIC EVALUATION | |
2167 | below). | |
2168 | \fIlength\fP must evaluate to a number greater than or equal to zero. | |
2169 | If \fIoffset\fP evaluates to a number less than zero, the value | |
2170 | is used as an offset from the end of the value of \fIparameter\fP. | |
2171 | If \fIparameter\fP is \fB@\fP, the result is \fIlength\fP positional | |
2172 | parameters beginning at \fIoffset\fP. | |
2173 | If \fIparameter\fP is an array name indexed by @ or *, | |
2174 | the result is the \fIlength\fP | |
2175 | members of the array beginning with ${\fIparameter\fP[\fIoffset\fP]}. | |
cce855bc JA |
2176 | Substring indexing is zero-based unless the positional parameters |
2177 | are used, in which case the indexing starts at 1. | |
ccc6cda3 | 2178 | .TP |
bb70624e JA |
2179 | ${\fB!\fP\fIprefix\fP\fB*\fP} |
2180 | Expands to the names of variables whose names begin with \fIprefix\fP, | |
2181 | separated by the first character of the | |
2182 | .SM | |
2183 | .B IFS | |
2184 | special variable. | |
2185 | .TP | |
726f6388 JA |
2186 | ${\fB#\fP\fIparameter\fP} |
2187 | The length in characters of the value of \fIparameter\fP is substituted. | |
ccc6cda3 JA |
2188 | If |
2189 | .I parameter | |
2190 | is | |
726f6388 JA |
2191 | .B * |
2192 | or | |
2193 | .BR @ , | |
cce855bc | 2194 | the value substituted is the number of positional parameters. |
ccc6cda3 JA |
2195 | If |
2196 | .I parameter | |
2197 | is an array name subscripted by | |
726f6388 | 2198 | .B * |
ccc6cda3 JA |
2199 | or |
2200 | .BR @ , | |
cce855bc | 2201 | the value substituted is the number of elements in the array. |
726f6388 JA |
2202 | .TP |
2203 | .PD 0 | |
2204 | ${\fIparameter\fP\fB#\fP\fIword\fP} | |
2205 | .TP | |
2206 | ${\fIparameter\fP\fB##\fP\fIword\fP} | |
2207 | .PD | |
2208 | The | |
2209 | .I word | |
2210 | is expanded to produce a pattern just as in pathname | |
2211 | expansion. If the pattern matches the beginning of | |
2212 | the value of | |
2213 | .IR parameter , | |
cce855bc | 2214 | then the result of the expansion is the expanded value of |
726f6388 | 2215 | .I parameter |
ccc6cda3 JA |
2216 | with the shortest matching pattern (the ``\fB#\fP'' case) or the |
2217 | longest matching pattern (the ``\fB##\fP'' case) deleted. | |
2218 | If | |
2219 | .I parameter | |
2220 | is | |
2221 | .B @ | |
2222 | or | |
2223 | .BR * , | |
2224 | the pattern removal operation is applied to each positional | |
2225 | parameter in turn, and the expansion is the resultant list. | |
2226 | If | |
2227 | .I parameter | |
2228 | is an array variable subscripted with | |
2229 | .B @ | |
2230 | or | |
2231 | .BR * , | |
2232 | the pattern removal operation is applied to each member of the | |
2233 | array in turn, and the expansion is the resultant list. | |
726f6388 JA |
2234 | .TP |
2235 | .PD 0 | |
2236 | ${\fIparameter\fP\fB%\fP\fIword\fP} | |
2237 | .TP | |
2238 | ${\fIparameter\fP\fB%%\fP\fIword\fP} | |
2239 | .PD | |
2240 | The \fIword\fP is expanded to produce a pattern just as in | |
ccc6cda3 | 2241 | pathname expansion. |
cce855bc | 2242 | If the pattern matches a trailing portion of the expanded value of |
726f6388 | 2243 | .IR parameter , |
cce855bc | 2244 | then the result of the expansion is the expanded value of |
726f6388 | 2245 | .I parameter |
ccc6cda3 JA |
2246 | with the shortest matching pattern (the ``\fB%\fP'' case) or the |
2247 | longest matching pattern (the ``\fB%%\fP'' case) deleted. | |
2248 | If | |
2249 | .I parameter | |
2250 | is | |
2251 | .B @ | |
2252 | or | |
2253 | .BR * , | |
2254 | the pattern removal operation is applied to each positional | |
2255 | parameter in turn, and the expansion is the resultant list. | |
2256 | If | |
2257 | .I parameter | |
2258 | is an array variable subscripted with | |
2259 | .B @ | |
2260 | or | |
2261 | .BR * , | |
2262 | the pattern removal operation is applied to each member of the | |
2263 | array in turn, and the expansion is the resultant list. | |
2264 | .TP | |
2265 | .PD 0 | |
2266 | ${\fIparameter\fP\fB/\fP\fIpattern\fP\fB/\fP\fIstring\fP} | |
2267 | .TP | |
2268 | ${\fIparameter\fP\fB//\fP\fIpattern\fP\fB/\fP\fIstring\fP} | |
2269 | .PD | |
2270 | The \fIpattern\fP is expanded to produce a pattern just as in | |
2271 | pathname expansion. | |
2272 | \fIParameter\fP is expanded and the longest match of \fIpattern\fP | |
2273 | against its value is replaced with \fIstring\fP. | |
2274 | In the first form, only the first match is replaced. | |
2275 | The second form causes all matches of \fIpattern\fP to be | |
2276 | replaced with \fIstring\fP. | |
2277 | If \fIpattern\fP begins with \fB#\fP, it must match at the beginning | |
b72432fd | 2278 | of the expanded value of \fIparameter\fP. |
ccc6cda3 | 2279 | If \fIpattern\fP begins with \fB%\fP, it must match at the end |
b72432fd | 2280 | of the expanded value of \fIparameter\fP. |
ccc6cda3 JA |
2281 | If \fIstring\fP is null, matches of \fIpattern\fP are deleted |
2282 | and the \fB/\fP following \fIpattern\fP may be omitted. | |
2283 | If | |
2284 | .I parameter | |
2285 | is | |
2286 | .B @ | |
2287 | or | |
2288 | .BR * , | |
2289 | the substitution operation is applied to each positional | |
2290 | parameter in turn, and the expansion is the resultant list. | |
2291 | If | |
2292 | .I parameter | |
2293 | is an array variable subscripted with | |
2294 | .B @ | |
2295 | or | |
2296 | .BR * , | |
2297 | the substitution operation is applied to each member of the | |
2298 | array in turn, and the expansion is the resultant list. | |
726f6388 JA |
2299 | .SS Command Substitution |
2300 | .PP | |
cce855bc | 2301 | \fICommand substitution\fP allows the output of a command to replace |
726f6388 JA |
2302 | the command name. There are two forms: |
2303 | .PP | |
2304 | .RS | |
2305 | .PP | |
2306 | \fB$(\fP\fIcommand\fP\|\fB)\fP | |
2307 | .RE | |
2308 | or | |
2309 | .RS | |
2310 | \fB`\fP\fIcommand\fP\fB`\fP | |
2311 | .RE | |
2312 | .PP | |
ccc6cda3 | 2313 | .B Bash |
726f6388 JA |
2314 | performs the expansion by executing \fIcommand\fP and |
2315 | replacing the command substitution with the standard output of the | |
2316 | command, with any trailing newlines deleted. | |
cce855bc JA |
2317 | Embedded newlines are not deleted, but they may be removed during |
2318 | word splitting. | |
2319 | The command substitution \fB$(cat \fIfile\fP)\fR can be replaced by | |
2320 | the equivalent but faster \fB$(< \fIfile\fP)\fR. | |
726f6388 | 2321 | .PP |
ccc6cda3 | 2322 | When the old-style backquote form of substitution is used, |
726f6388 JA |
2323 | backslash retains its literal meaning except when followed by |
2324 | .BR $ , | |
2325 | .BR ` , | |
2326 | or | |
2327 | .BR \e . | |
cce855bc JA |
2328 | The first backquote not preceded by a backslash terminates the |
2329 | command substitution. | |
726f6388 JA |
2330 | When using the $(\^\fIcommand\fP\|) form, all characters between the |
2331 | parentheses make up the command; none are treated specially. | |
2332 | .PP | |
cce855bc | 2333 | Command substitutions may be nested. To nest when using the backquoted form, |
726f6388 JA |
2334 | escape the inner backquotes with backslashes. |
2335 | .PP | |
2336 | If the substitution appears within double quotes, word splitting and | |
2337 | pathname expansion are not performed on the results. | |
2338 | .SS Arithmetic Expansion | |
2339 | .PP | |
2340 | Arithmetic expansion allows the evaluation of an arithmetic expression | |
ccc6cda3 | 2341 | and the substitution of the result. The format for arithmetic expansion is: |
726f6388 JA |
2342 | .RS |
2343 | .PP | |
726f6388 JA |
2344 | \fB$((\fP\fIexpression\fP\fB))\fP |
2345 | .RE | |
2346 | .PP | |
2347 | The | |
2348 | .I expression | |
2349 | is treated as if it were within double quotes, but a double quote | |
ccc6cda3 JA |
2350 | inside the parentheses is not treated specially. |
2351 | All tokens in the expression undergo parameter expansion, string | |
2352 | expansion, command substitution, and quote removal. | |
2353 | Arithmetic substitutions may be nested. | |
726f6388 JA |
2354 | .PP |
2355 | The evaluation is performed according to the rules listed below under | |
2356 | .SM | |
2357 | .BR "ARITHMETIC EVALUATION" . | |
2358 | If | |
2359 | .I expression | |
2360 | is invalid, | |
2361 | .B bash | |
2362 | prints a message indicating failure and no substitution occurs. | |
2363 | .SS Process Substitution | |
2364 | .PP | |
2365 | \fIProcess substitution\fP is supported on systems that support named | |
2366 | pipes (\fIFIFOs\fP) or the \fB/dev/fd\fP method of naming open files. | |
2367 | It takes the form of | |
2368 | \fB<(\fP\fIlist\^\fP\fB)\fP | |
2369 | or | |
2370 | \fB>(\fP\fIlist\^\fP\fB)\fP. | |
2371 | The process \fIlist\fP is run with its input or output connected to a | |
2372 | \fIFIFO\fP or some file in \fB/dev/fd\fP. The name of this file is | |
2373 | passed as an argument to the current command as the result of the | |
2374 | expansion. If the \fB>(\fP\fIlist\^\fP\fB)\fP form is used, writing to | |
2375 | the file will provide input for \fIlist\fP. If the | |
2376 | \fB<(\fP\fIlist\^\fP\fB)\fP form is used, the file passed as an | |
2377 | argument should be read to obtain the output of \fIlist\fP. | |
2378 | .PP | |
bb70624e | 2379 | When available, process substitution is performed |
ccc6cda3 JA |
2380 | simultaneously with parameter and variable expansion, |
2381 | command substitution, | |
2382 | and arithmetic expansion. | |
726f6388 JA |
2383 | .SS Word Splitting |
2384 | .PP | |
2385 | The shell scans the results of | |
2386 | parameter expansion, | |
2387 | command substitution, | |
2388 | and | |
2389 | arithmetic expansion | |
2390 | that did not occur within double quotes for | |
2391 | .IR "word splitting" . | |
2392 | .PP | |
2393 | The shell treats each character of | |
2394 | .SM | |
2395 | .B IFS | |
2396 | as a delimiter, and splits the results of the other | |
ccc6cda3 | 2397 | expansions into words on these characters. If |
726f6388 JA |
2398 | .SM |
2399 | .B IFS | |
ccc6cda3 JA |
2400 | is unset, or its |
2401 | value is exactly | |
726f6388 JA |
2402 | .BR <space><tab><newline> , |
2403 | the default, then | |
2404 | any sequence of | |
2405 | .SM | |
2406 | .B IFS | |
2407 | characters serves to delimit words. If | |
2408 | .SM | |
2409 | .B IFS | |
2410 | has a value other than the default, then sequences of | |
2411 | the whitespace characters | |
2412 | .B space | |
2413 | and | |
2414 | .B tab | |
2415 | are ignored at the beginning and end of the | |
2416 | word, as long as the whitespace character is in the | |
2417 | value of | |
2418 | .SM | |
2419 | .BR IFS | |
2420 | (an | |
2421 | .SM | |
2422 | .B IFS | |
2423 | whitespace character). | |
2424 | Any character in | |
2425 | .SM | |
2426 | .B IFS | |
2427 | that is not | |
2428 | .SM | |
2429 | .B IFS | |
2430 | whitespace, along with any adjacent | |
2431 | .SM | |
2432 | .B IFS | |
2433 | whitespace characters, delimits a field. | |
2434 | A sequence of | |
2435 | .SM | |
2436 | .B IFS | |
2437 | whitespace characters is also treated as a delimiter. | |
2438 | If the value of | |
2439 | .SM | |
2440 | .B IFS | |
2441 | is null, no word splitting occurs. | |
726f6388 | 2442 | .PP |
ccc6cda3 JA |
2443 | Explicit null arguments (\^\f3"\^"\fP or \^\f3'\^'\fP\^) are retained. |
2444 | Unquoted implicit null arguments, resulting from the expansion of | |
bb70624e | 2445 | parameters that have no values, are removed. |
ccc6cda3 JA |
2446 | If a parameter with no value is expanded within double quotes, a |
2447 | null argument results and is retained. | |
726f6388 JA |
2448 | .PP |
2449 | Note that if no expansion occurs, no splitting | |
2450 | is performed. | |
2451 | .SS Pathname Expansion | |
2452 | .PP | |
2453 | After word splitting, | |
2454 | unless the | |
2455 | .B \-f | |
2456 | option has been set, | |
2457 | .B bash | |
ccc6cda3 | 2458 | scans each word for the characters |
726f6388 JA |
2459 | .BR * , |
2460 | .BR ? , | |
2461 | and | |
2462 | .BR [ . | |
2463 | If one of these characters appears, then the word is | |
2464 | regarded as a | |
2465 | .IR pattern , | |
2466 | and replaced with an alphabetically sorted list of | |
ccc6cda3 JA |
2467 | file names matching the pattern. |
2468 | If no matching file names are found, | |
2469 | and the shell option | |
2470 | .B nullglob | |
2471 | is disabled, the word is left unchanged. | |
cce855bc JA |
2472 | If the |
2473 | .B nullglob | |
2474 | option is set, and no matches are found, | |
726f6388 | 2475 | the word is removed. |
cce855bc JA |
2476 | If the shell option |
2477 | .B nocaseglob | |
2478 | is enabled, the match is performed without regard to the case | |
2479 | of alphabetic characters. | |
ccc6cda3 | 2480 | When a pattern is used for pathname expansion, |
726f6388 JA |
2481 | the character |
2482 | .B ``.'' | |
2483 | at the start of a name or immediately following a slash | |
ccc6cda3 JA |
2484 | must be matched explicitly, unless the shell option |
2485 | .B dotglob | |
2486 | is set. | |
cce855bc JA |
2487 | When matching a pathname, the slash character must always be |
2488 | matched explicitly. | |
ccc6cda3 | 2489 | In other cases, the |
726f6388 JA |
2490 | .B ``.'' |
2491 | character is not treated specially. | |
ccc6cda3 JA |
2492 | See the description of |
2493 | .B shopt | |
2494 | below under | |
2495 | .SM | |
2496 | .B SHELL BUILTIN COMMANDS | |
2497 | for a description of the | |
cce855bc JA |
2498 | .BR nocaseglob , |
2499 | .BR nullglob , | |
ccc6cda3 JA |
2500 | and |
2501 | .B dotglob | |
2502 | shell options. | |
2503 | .PP | |
2504 | The | |
2505 | .SM | |
2506 | .B GLOBIGNORE | |
2507 | shell variable may be used to restrict the set of file names matching a | |
2508 | .IR pattern . | |
2509 | If | |
2510 | .SM | |
2511 | .B GLOBIGNORE | |
2512 | is set, each matching file name that also matches one of the patterns in | |
2513 | .SM | |
2514 | .B GLOBIGNORE | |
2515 | is removed from the list of matches. | |
2516 | The file names | |
2517 | .B ``.'' | |
2518 | and | |
2519 | .B ``..'' | |
2520 | are always ignored, even when | |
2521 | .SM | |
2522 | .B GLOBIGNORE | |
2523 | is set. However, setting | |
2524 | .SM | |
2525 | .B GLOBIGNORE | |
2526 | has the effect of enabling the | |
2527 | .B dotglob | |
2528 | shell option, so all other file names beginning with a | |
2529 | .B ``.'' | |
2530 | will match. | |
2531 | To get the old behavior of ignoring file names beginning with a | |
2532 | .BR ``.'' , | |
2533 | make | |
2534 | .B ``.*'' | |
2535 | one of the patterns in | |
2536 | .SM | |
2537 | .BR GLOBIGNORE . | |
2538 | The | |
2539 | .B dotglob | |
2540 | option is disabled when | |
2541 | .SM | |
2542 | .B GLOBIGNORE | |
2543 | is unset. | |
726f6388 | 2544 | .PP |
cce855bc JA |
2545 | \fBPattern Matching\fP |
2546 | .PP | |
2547 | Any character that appears in a pattern, other than the special pattern | |
2548 | characters described below, matches itself. The NUL character may not | |
2549 | occur in a pattern. The special pattern characters must be quoted if | |
2550 | they are to be matched literally. | |
2551 | .PP | |
726f6388 JA |
2552 | The special pattern characters have the following meanings: |
2553 | .PP | |
2554 | .PD 0 | |
2555 | .TP | |
2556 | .B * | |
2557 | Matches any string, including the null string. | |
2558 | .TP | |
2559 | .B ? | |
2560 | Matches any single character. | |
2561 | .TP | |
2562 | .B [...] | |
2563 | Matches any one of the enclosed characters. A pair of characters | |
28ef6c31 JA |
2564 | separated by a hyphen denotes a |
2565 | \fIrange expression\fP; | |
2566 | any character that sorts between those two characters, inclusive, | |
2567 | using the current locale's collating sequence and character set, | |
726f6388 JA |
2568 | is matched. If the first character following the |
2569 | .B [ | |
2570 | is a | |
2571 | .B ! | |
2572 | or a | |
2573 | .B ^ | |
ccc6cda3 | 2574 | then any character not enclosed is matched. |
28ef6c31 JA |
2575 | The sorting order of characters in range expressions is determined by |
2576 | the current locale and the value of the \fBLC_COLLATE\fP shell variable, | |
2577 | if set. | |
ccc6cda3 | 2578 | A |
726f6388 | 2579 | .B \- |
726f6388 JA |
2580 | may be matched by including it as the first or last character |
2581 | in the set. | |
ccc6cda3 JA |
2582 | A |
2583 | .B ] | |
2584 | may be matched by including it as the first character | |
2585 | in the set. | |
cce855bc JA |
2586 | .br |
2587 | .if t .sp 0.5 | |
2588 | .if n .sp 1 | |
2589 | Within | |
2590 | .B [ | |
2591 | and | |
2592 | .BR ] , | |
2593 | \fIcharacter classes\fP can be specified using the syntax | |
2594 | \fB[:\fP\fIclass\fP\fB:]\fP, where \fIclass\fP is one of the | |
2595 | following classes defined in the POSIX.2 standard: | |
2596 | .PP | |
2597 | .RS | |
2598 | .B | |
2599 | .if n alnum alpha ascii blank cntrl digit graph lower print punct space upper xdigit | |
2600 | .if t alnum alpha ascii blank cntrl digit graph lower print punct space upper xdigit | |
2601 | .br | |
2602 | A character class matches any character belonging to that class. | |
2603 | .br | |
2604 | .if t .sp 0.5 | |
2605 | .if n .sp 1 | |
2606 | Within | |
2607 | .B [ | |
2608 | and | |
2609 | .BR ] , | |
2610 | an \fIequivalence class\fP can be specified using the syntax | |
2611 | \fB[=\fP\fIc\fP\fB=]\fP, which matches all characters with the | |
2612 | same collation weight (as defined by the current locale) as | |
2613 | the character \fIc\fP. | |
2614 | .br | |
2615 | .if t .sp 0.5 | |
2616 | .if n .sp 1 | |
2617 | Within | |
2618 | .B [ | |
2619 | and | |
2620 | .BR ] , | |
2621 | the syntax \fB[.\fP\fIsymbol\fP\fB.]\fP matches the collating symbol | |
2622 | \fIsymbol\fP. | |
2623 | .RE | |
2624 | .PD | |
2625 | .PP | |
2626 | If the \fBextglob\fP shell option is enabled using the \fBshopt\fP | |
2627 | builtin, several extended pattern matching operators are recognized. | |
bb70624e | 2628 | In the following description, a \fIpattern-list\fP is a list of one |
cce855bc JA |
2629 | or more patterns separated by a \fB|\fP. |
2630 | Composite patterns may be formed using one or more of the following | |
2631 | sub-patterns: | |
2632 | .sp 1 | |
2633 | .PD 0 | |
2634 | .RS | |
2635 | .TP | |
2636 | \fB?(\fP\^\fIpattern-list\^\fP\fB)\fP | |
2637 | Matches zero or one occurrence of the given patterns | |
2638 | .TP | |
2639 | \fB*(\fP\^\fIpattern-list\^\fP\fB)\fP | |
2640 | Matches zero or more occurrences of the given patterns | |
2641 | .TP | |
2642 | \fB+(\fP\^\fIpattern-list\^\fP\fB)\fP | |
2643 | Matches one or more occurrences of the given patterns | |
2644 | .TP | |
2645 | \fB@(\fP\^\fIpattern-list\^\fP\fB)\fP | |
2646 | Matches exactly one of the given patterns | |
2647 | .TP | |
2648 | \fB!(\fP\^\fIpattern-list\^\fP\fB)\fP | |
2649 | Matches anything except one of the given patterns | |
2650 | .RE | |
726f6388 JA |
2651 | .PD |
2652 | .SS Quote Removal | |
2653 | .PP | |
2654 | After the preceding expansions, all unquoted occurrences of the | |
2655 | characters | |
2656 | .BR \e , | |
cce855bc | 2657 | .BR ' , |
ccc6cda3 JA |
2658 | and \^\f3"\fP\^ that did not result from one of the above |
2659 | expansions are removed. | |
726f6388 JA |
2660 | .SH REDIRECTION |
2661 | Before a command is executed, its input and output | |
2662 | may be | |
2663 | .I redirected | |
2664 | using a special notation interpreted by the shell. | |
2665 | Redirection may also be used to open and close files for the | |
2666 | current shell execution environment. The following redirection | |
2667 | operators may precede or appear anywhere within a | |
2668 | .I simple command | |
2669 | or may follow a | |
2670 | .IR command . | |
2671 | Redirections are processed in the order they appear, from | |
2672 | left to right. | |
2673 | .PP | |
2674 | In the following descriptions, if the file descriptor number is | |
2675 | omitted, and the first character of the redirection operator is | |
2676 | .BR < , | |
2677 | the redirection refers to the standard input (file descriptor | |
2678 | 0). If the first character of the redirection operator is | |
2679 | .BR > , | |
2680 | the redirection refers to the standard output (file descriptor | |
2681 | 1). | |
2682 | .PP | |
cce855bc JA |
2683 | The word following the redirection operator in the following |
2684 | descriptions, unless otherwise noted, is subjected to brace expansion, | |
2685 | tilde expansion, parameter expansion, command substitution, arithmetic | |
bb70624e | 2686 | expansion, quote removal, pathname expansion, and word splitting. |
cce855bc | 2687 | If it expands to more than one word, |
726f6388 JA |
2688 | .B bash |
2689 | reports an error. | |
2690 | .PP | |
2691 | Note that the order of redirections is significant. For example, | |
2692 | the command | |
2693 | .RS | |
2694 | .PP | |
2695 | ls \fB>\fP dirlist 2\fB>&\fP1 | |
2696 | .RE | |
2697 | .PP | |
2698 | directs both standard output and standard error to the file | |
2699 | .IR dirlist , | |
2700 | while the command | |
2701 | .RS | |
2702 | .PP | |
2703 | ls 2\fB>&\fP1 \fB>\fP dirlist | |
2704 | .RE | |
2705 | .PP | |
2706 | directs only the standard output to file | |
2707 | .IR dirlist , | |
2708 | because the standard error was duplicated as standard output | |
2709 | before the standard output was redirected to | |
2710 | .IR dirlist . | |
cce855bc | 2711 | .PP |
bb70624e JA |
2712 | \fBBash\fP handles several filenames specially when they are used in |
2713 | redirections, as described in the following table: | |
2714 | .RS | |
2715 | .PP | |
2716 | .PD 0 | |
2717 | .TP | |
2718 | .B /dev/fd/\fIfd\fP | |
2719 | If \fIfd\fP is a valid integer, file descriptor \fIfd\fP is duplicated. | |
2720 | .TP | |
2721 | .B /dev/stdin | |
2722 | File descriptor 0 is duplicated. | |
2723 | .TP | |
2724 | .B /dev/stdout | |
2725 | File descriptor 1 is duplicated. | |
2726 | .TP | |
2727 | .B /dev/stderr | |
2728 | File descriptor 2 is duplicated. | |
2729 | .TP | |
2730 | .B /dev/tcp/\fIhost\fP/\fIport\fP | |
2731 | If \fIhost\fP is a valid hostname or Internet address, and \fIport\fP | |
f73dda09 JA |
2732 | is an integer port number or service name, \fBbash\fP attempts to open |
2733 | a TCP connection to the corresponding socket. | |
bb70624e JA |
2734 | .TP |
2735 | .B /dev/udp/\fIhost\fP/\fIport\fP | |
2736 | If \fIhost\fP is a valid hostname or Internet address, and \fIport\fP | |
f73dda09 JA |
2737 | is an integer port number or service name, \fBbash\fP attempts to open |
2738 | a UDP connection to the corresponding socket. | |
bb70624e JA |
2739 | .PD |
2740 | .RE | |
2741 | .PP | |
cce855bc | 2742 | A failure to open or create a file causes the redirection to fail. |
726f6388 JA |
2743 | .SS Redirecting Input |
2744 | .PP | |
2745 | Redirection of input causes the file whose name results from | |
2746 | the expansion of | |
2747 | .I word | |
2748 | to be opened for reading on file descriptor | |
2749 | .IR n , | |
2750 | or the standard input (file descriptor 0) if | |
2751 | .I n | |
2752 | is not specified. | |
2753 | .PP | |
2754 | The general format for redirecting input is: | |
2755 | .RS | |
2756 | .PP | |
2757 | [\fIn\fP]\fB<\fP\fIword\fP | |
2758 | .RE | |
2759 | .SS Redirecting Output | |
2760 | .PP | |
2761 | Redirection of output causes the file whose name results from | |
2762 | the expansion of | |
2763 | .I word | |
2764 | to be opened for writing on file descriptor | |
2765 | .IR n , | |
2766 | or the standard output (file descriptor 1) if | |
2767 | .I n | |
2768 | is not specified. If the file does not exist it is created; | |
2769 | if it does exist it is truncated to zero size. | |
2770 | .PP | |
2771 | The general format for redirecting output is: | |
2772 | .RS | |
2773 | .PP | |
2774 | [\fIn\fP]\fB>\fP\fIword\fP | |
2775 | .RE | |
2776 | .PP | |
2777 | If the redirection operator is | |
ccc6cda3 JA |
2778 | .BR > , |
2779 | and the | |
cce855bc | 2780 | .B noclobber |
ccc6cda3 JA |
2781 | option to the |
2782 | .B set | |
bb70624e | 2783 | builtin has been enabled, the redirection will fail if the file |
cce855bc JA |
2784 | whose name results from the expansion of \fIword\fP exists and is |
2785 | a regular file. | |
ccc6cda3 | 2786 | If the redirection operator is |
726f6388 | 2787 | .BR >| , |
cce855bc JA |
2788 | or the redirection operator is |
2789 | .B > | |
2790 | and the | |
2791 | .B noclobber | |
726f6388 JA |
2792 | option to the |
2793 | .B set | |
cce855bc | 2794 | builtin command is not enabled, the redirection is attempted even |
ccc6cda3 | 2795 | if the file named by \fIword\fP exists. |
726f6388 JA |
2796 | .SS Appending Redirected Output |
2797 | .PP | |
2798 | Redirection of output in this fashion | |
2799 | causes the file whose name results from | |
2800 | the expansion of | |
2801 | .I word | |
2802 | to be opened for appending on file descriptor | |
2803 | .IR n , | |
2804 | or the standard output (file descriptor 1) if | |
2805 | .I n | |
2806 | is not specified. If the file does not exist it is created. | |
2807 | .PP | |
2808 | The general format for appending output is: | |
2809 | .RS | |
2810 | .PP | |
2811 | [\fIn\fP]\fB>>\fP\fIword\fP | |
2812 | .RE | |
2813 | .PP | |
2814 | .SS Redirecting Standard Output and Standard Error | |
2815 | .PP | |
2816 | .B Bash | |
2817 | allows both the | |
2818 | standard output (file descriptor 1) and | |
2819 | the standard error output (file descriptor 2) | |
2820 | to be redirected to the file whose name is the | |
2821 | expansion of | |
2822 | .I word | |
2823 | with this construct. | |
2824 | .PP | |
2825 | There are two formats for redirecting standard output and | |
2826 | standard error: | |
2827 | .RS | |
2828 | .PP | |
2829 | \fB&>\fP\fIword\fP | |
2830 | .RE | |
2831 | and | |
2832 | .RS | |
2833 | \fB>&\fP\fIword\fP | |
2834 | .RE | |
2835 | .PP | |
2836 | Of the two forms, the first is preferred. | |
2837 | This is semantically equivalent to | |
2838 | .RS | |
2839 | .PP | |
2840 | \fB>\fP\fIword\fP 2\fB>&\fP1 | |
2841 | .RE | |
2842 | .SS Here Documents | |
2843 | .PP | |
2844 | This type of redirection instructs the shell to read input from the | |
2845 | current source until a line containing only | |
2846 | .I word | |
2847 | (with no trailing blanks) | |
2848 | is seen. All of | |
2849 | the lines read up to that point are then used as the standard | |
2850 | input for a command. | |
2851 | .PP | |
2852 | The format of here-documents is as follows: | |
2853 | .RS | |
2854 | .PP | |
2855 | .nf | |
2856 | \fB<<\fP[\fB\-\fP]\fIword\fP | |
f73dda09 | 2857 | \fIhere-document\fP |
726f6388 JA |
2858 | \fIdelimiter\fP |
2859 | .fi | |
2860 | .RE | |
2861 | .PP | |
bb70624e JA |
2862 | No parameter expansion, command substitution, arithmetic expansion, |
2863 | or pathname expansion is performed on | |
726f6388 JA |
2864 | .IR word . |
2865 | If any characters in | |
2866 | .I word | |
2867 | are quoted, the | |
2868 | .I delimiter | |
2869 | is the result of quote removal on | |
2870 | .IR word , | |
cce855bc JA |
2871 | and the lines in the here-document are not expanded. |
2872 | If \fIword\fP is unquoted, | |
726f6388 JA |
2873 | all lines of the here-document are subjected to parameter expansion, |
2874 | command substitution, and arithmetic expansion. In the latter | |
bb70624e | 2875 | case, the character sequence |
726f6388 JA |
2876 | .B \e<newline> |
2877 | is ignored, and | |
2878 | .B \e | |
2879 | must be used to quote the characters | |
2880 | .BR \e , | |
2881 | .BR $ , | |
2882 | and | |
2883 | .BR ` . | |
2884 | .PP | |
2885 | If the redirection operator is | |
2886 | .BR <<\- , | |
2887 | then all leading tab characters are stripped from input lines and the | |
2888 | line containing | |
2889 | .IR delimiter . | |
2890 | This allows | |
2891 | here-documents within shell scripts to be indented in a | |
2892 | natural fashion. | |
2893 | .SS "Duplicating File Descriptors" | |
2894 | .PP | |
2895 | The redirection operator | |
2896 | .RS | |
2897 | .PP | |
2898 | [\fIn\fP]\fB<&\fP\fIword\fP | |
2899 | .RE | |
2900 | .PP | |
2901 | is used to duplicate input file descriptors. | |
2902 | If | |
2903 | .I word | |
2904 | expands to one or more digits, the file descriptor denoted by | |
2905 | .I n | |
cce855bc JA |
2906 | is made to be a copy of that file descriptor. |
2907 | If the digits in | |
2908 | .I word | |
2909 | do not specify a file descriptor open for input, a redirection error occurs. | |
2910 | If | |
726f6388 JA |
2911 | .I word |
2912 | evaluates to | |
2913 | .BR \- , | |
2914 | file descriptor | |
2915 | .I n | |
2916 | is closed. If | |
2917 | .I n | |
2918 | is not specified, the standard input (file descriptor 0) is used. | |
2919 | .PP | |
2920 | The operator | |
2921 | .RS | |
2922 | .PP | |
2923 | [\fIn\fP]\fB>&\fP\fIword\fP | |
2924 | .RE | |
2925 | .PP | |
2926 | is used similarly to duplicate output file descriptors. If | |
2927 | .I n | |
2928 | is not specified, the standard output (file descriptor 1) is used. | |
cce855bc JA |
2929 | If the digits in |
2930 | .I word | |
2931 | do not specify a file descriptor open for output, a redirection error occurs. | |
726f6388 JA |
2932 | As a special case, if \fIn\fP is omitted, and \fIword\fP does not |
2933 | expand to one or more digits, the standard output and standard | |
2934 | error are redirected as described previously. | |
2935 | .SS "Opening File Descriptors for Reading and Writing" | |
2936 | .PP | |
2937 | The redirection operator | |
2938 | .RS | |
2939 | .PP | |
2940 | [\fIn\fP]\fB<>\fP\fIword\fP | |
2941 | .RE | |
2942 | .PP | |
2943 | causes the file whose name is the expansion of | |
2944 | .I word | |
2945 | to be opened for both reading and writing on file descriptor | |
2946 | .IR n , | |
ccc6cda3 | 2947 | or on file descriptor 0 if |
726f6388 JA |
2948 | .I n |
2949 | is not specified. If the file does not exist, it is created. | |
726f6388 | 2950 | .SH ALIASES |
bb70624e | 2951 | \fIAliases\fP allow a string to be substituted for a word when it is used |
cce855bc | 2952 | as the first word of a simple command. |
bb70624e | 2953 | The shell maintains a list of aliases that may be set and unset with the |
726f6388 JA |
2954 | .B alias |
2955 | and | |
2956 | .B unalias | |
2957 | builtin commands (see | |
2958 | .SM | |
2959 | .B SHELL BUILTIN COMMANDS | |
2960 | below). | |
2961 | The first word of each command, if unquoted, | |
2962 | is checked to see if it has an | |
2963 | alias. If so, that word is replaced by the text of the alias. | |
2964 | The alias name and the replacement text may contain any valid | |
2965 | shell input, including the | |
2966 | .I metacharacters | |
2967 | listed above, with the exception that the alias name may not | |
2968 | contain \fI=\fP. The first word of the replacement text is tested | |
2969 | for aliases, but a word that is identical to an alias being expanded | |
2970 | is not expanded a second time. This means that one may alias | |
2971 | .B ls | |
2972 | to | |
2973 | .BR "ls \-F" , | |
2974 | for instance, and | |
2975 | .B bash | |
2976 | does not try to recursively expand the replacement text. | |
2977 | If the last character of the alias value is a | |
2978 | .IR blank , | |
2979 | then the next command | |
2980 | word following the alias is also checked for alias expansion. | |
2981 | .PP | |
2982 | Aliases are created and listed with the | |
2983 | .B alias | |
2984 | command, and removed with the | |
2985 | .B unalias | |
2986 | command. | |
2987 | .PP | |
ccc6cda3 | 2988 | There is no mechanism for using arguments in the replacement text. |
bb70624e JA |
2989 | If arguments are needed, a shell function should be used (see |
2990 | .SM | |
2991 | .B FUNCTIONS | |
2992 | below). | |
726f6388 | 2993 | .PP |
ccc6cda3 JA |
2994 | Aliases are not expanded when the shell is not interactive, unless |
2995 | the | |
2996 | .B expand_aliases | |
2997 | shell option is set using | |
2998 | .B shopt | |
2999 | (see the description of | |
3000 | .B shopt | |
3001 | under | |
3002 | .SM | |
3003 | \fBSHELL BUILTIN COMMANDS\fP | |
3004 | below). | |
726f6388 JA |
3005 | .PP |
3006 | The rules concerning the definition and use of aliases are | |
3007 | somewhat confusing. | |
3008 | .B Bash | |
3009 | always reads at least one complete line | |
3010 | of input before executing any | |
3011 | of the commands on that line. Aliases are expanded when a | |
3012 | command is read, not when it is executed. Therefore, an | |
3013 | alias definition appearing on the same line as another | |
3014 | command does not take effect until the next line of input is read. | |
ccc6cda3 | 3015 | The commands following the alias definition |
726f6388 JA |
3016 | on that line are not affected by the new alias. |
3017 | This behavior is also an issue when functions are executed. | |
cce855bc | 3018 | Aliases are expanded when a function definition is read, |
726f6388 JA |
3019 | not when the function is executed, because a function definition |
3020 | is itself a compound command. As a consequence, aliases | |
3021 | defined in a function are not available until after that | |
3022 | function is executed. To be safe, always put | |
3023 | alias definitions on a separate line, and do not use | |
3024 | .B alias | |
3025 | in compound commands. | |
3026 | .PP | |
cce855bc | 3027 | For almost every purpose, aliases are superseded by |
726f6388 | 3028 | shell functions. |
ccc6cda3 JA |
3029 | .SH FUNCTIONS |
3030 | A shell function, defined as described above under | |
3031 | .SM | |
3032 | .BR "SHELL GRAMMAR" , | |
3033 | stores a series of commands for later execution. | |
bb70624e JA |
3034 | When the name of a shell function is used as a simple command name, |
3035 | the list of commands associated with that function name is executed. | |
ccc6cda3 JA |
3036 | Functions are executed in the context of the |
3037 | current shell; no new process is created to interpret | |
3038 | them (contrast this with the execution of a shell script). | |
3039 | When a function is executed, the arguments to the | |
3040 | function become the positional parameters | |
bb70624e JA |
3041 | during its execution. |
3042 | The special parameter | |
ccc6cda3 JA |
3043 | .B # |
3044 | is updated to reflect the change. Positional parameter 0 | |
bb70624e JA |
3045 | is unchanged. |
3046 | The | |
3047 | .SM | |
3048 | .B FUNCNAME | |
3049 | variable is set to the name of the function while the function | |
3050 | is executing. | |
3051 | All other aspects of the shell execution | |
ccc6cda3 JA |
3052 | environment are identical between a function and its caller |
3053 | with the exception that the | |
3054 | .SM | |
3055 | .B DEBUG | |
3056 | trap (see the description of the | |
3057 | .B trap | |
3058 | builtin under | |
3059 | .SM | |
3060 | .B SHELL BUILTIN COMMANDS | |
3061 | below) is not inherited. | |
726f6388 | 3062 | .PP |
ccc6cda3 JA |
3063 | Variables local to the function may be declared with the |
3064 | .B local | |
3065 | builtin command. Ordinarily, variables and their values | |
3066 | are shared between the function and its caller. | |
726f6388 | 3067 | .PP |
ccc6cda3 JA |
3068 | If the builtin command |
3069 | .B return | |
3070 | is executed in a function, the function completes and | |
3071 | execution resumes with the next command after the function | |
3072 | call. When a function completes, the values of the | |
3073 | positional parameters and the special parameter | |
3074 | .B # | |
cce855bc | 3075 | are restored to the values they had prior to the function's |
ccc6cda3 | 3076 | execution. |
726f6388 | 3077 | .PP |
ccc6cda3 JA |
3078 | Function names and definitions may be listed with the |
3079 | .B \-f | |
726f6388 | 3080 | option to the |
ccc6cda3 JA |
3081 | .B declare |
3082 | or | |
3083 | .B typeset | |
3084 | builtin commands. The | |
3085 | .B \-F | |
3086 | option to | |
3087 | .B declare | |
3088 | or | |
3089 | .B typeset | |
3090 | will list the function names only. | |
3091 | Functions may be exported so that subshells | |
3092 | automatically have them defined with the | |
3093 | .B \-f | |
3094 | option to the | |
3095 | .B export | |
3096 | builtin. | |
726f6388 | 3097 | .PP |
ccc6cda3 JA |
3098 | Functions may be recursive. No limit is imposed on the number |
3099 | of recursive calls. | |
cce855bc JA |
3100 | .SH "ARITHMETIC EVALUATION" |
3101 | The shell allows arithmetic expressions to be evaluated, under | |
3102 | certain circumstances (see the \fBlet\fP builtin command and | |
3103 | \fBArithmetic Expansion\fP). | |
3104 | Evaluation is done in long integers with no check for overflow, | |
3105 | though division by 0 is trapped and flagged as an error. | |
bb70624e JA |
3106 | The operators and their precedence and associativity are the same |
3107 | as in the C language. | |
cce855bc JA |
3108 | The following list of operators is grouped into levels of |
3109 | equal-precedence operators. | |
3110 | The levels are listed in order of decreasing precedence. | |
726f6388 | 3111 | .PP |
cce855bc JA |
3112 | .PD 0 |
3113 | .TP | |
bb70624e JA |
3114 | .B \fIid\fP++ \fIid\fP\-\- |
3115 | variable post-increment and post-decrement | |
3116 | .TP | |
3117 | .B ++\fIid\fP \-\-\fIid\fP | |
3118 | variable pre-increment and pre-decrement | |
3119 | .TP | |
cce855bc JA |
3120 | .B \- + |
3121 | unary minus and plus | |
3122 | .TP | |
3123 | .B ! ~ | |
3124 | logical and bitwise negation | |
3125 | .TP | |
3126 | .B ** | |
3127 | exponentiation | |
3128 | .TP | |
3129 | .B * / % | |
3130 | multiplication, division, remainder | |
3131 | .TP | |
3132 | .B + \- | |
3133 | addition, subtraction | |
3134 | .TP | |
3135 | .B << >> | |
3136 | left and right bitwise shifts | |
3137 | .TP | |
3138 | .B <= >= < > | |
3139 | comparison | |
3140 | .TP | |
3141 | .B == != | |
3142 | equality and inequality | |
3143 | .TP | |
3144 | .B & | |
3145 | bitwise AND | |
3146 | .TP | |
3147 | .B ^ | |
3148 | bitwise exclusive OR | |
3149 | .TP | |
3150 | .B | | |
3151 | bitwise OR | |
3152 | .TP | |
3153 | .B && | |
3154 | logical AND | |
3155 | .TP | |
3156 | .B || | |
3157 | logical OR | |
3158 | .TP | |
3159 | .B \fIexpr\fP?\fIexpr\fP:\fIexpr\fP | |
3160 | conditional evaluation | |
3161 | .TP | |
3162 | .B = *= /= %= += \-= <<= >>= &= ^= |= | |
3163 | assignment | |
bb70624e JA |
3164 | .TP |
3165 | .B \fIexpr1\fP , \fIexpr2\fP | |
3166 | comma | |
cce855bc | 3167 | .PD |
ccc6cda3 | 3168 | .PP |
cce855bc | 3169 | Shell variables are allowed as operands; parameter expansion is |
bb70624e JA |
3170 | performed before the expression is evaluated. |
3171 | Within an expression, shell variables may also be referenced by name | |
3172 | without using the parameter expansion syntax. | |
3173 | The value of a variable is evaluated as an arithmetic expression | |
3174 | when it is referenced. | |
3175 | A shell variable need not have its integer attribute | |
cce855bc | 3176 | turned on to be used in an expression. |
ccc6cda3 | 3177 | .PP |
cce855bc JA |
3178 | Constants with a leading 0 are interpreted as octal numbers. |
3179 | A leading 0x or 0X denotes hexadecimal. | |
3180 | Otherwise, numbers take the form [\fIbase#\fP]n, where \fIbase\fP | |
3181 | is a decimal number between 2 and 64 representing the arithmetic | |
3182 | base, and \fIn\fP is a number in that base. | |
bb70624e | 3183 | If \fIbase#\fP is omitted, then base 10 is used. |
cce855bc | 3184 | The digits greater than 9 are represented by the lowercase letters, |
f73dda09 | 3185 | the uppercase letters, @, and _, in that order. |
cce855bc JA |
3186 | If \fIbase\fP is less than or equal to 36, lowercase and uppercase |
3187 | letters may be used interchangably to represent numbers between 10 | |
3188 | and 35. | |
ccc6cda3 | 3189 | .PP |
cce855bc JA |
3190 | Operators are evaluated in order of precedence. Sub-expressions in |
3191 | parentheses are evaluated first and may override the precedence | |
3192 | rules above. | |
3193 | .SH "CONDITIONAL EXPRESSIONS" | |
3194 | Conditional expressions are used by the \fB[[\fP compound command and | |
3195 | the \fBtest\fP and \fB[\fP builtin commands to test file attributes | |
3196 | and perform string and arithmetic comparisons. | |
3197 | Expressions are formed from the following unary or binary primaries. | |
3198 | If any \fIfile\fP argument to one of the primaries is of the form | |
bb70624e JA |
3199 | \fI/dev/fd/n\fP, then file descriptor \fIn\fP is checked. |
3200 | If the \fIfile\fP argument to one of the primaries is one of | |
3201 | \fI/dev/stdin\fP, \fI/dev/stdout\fP, or \fI/dev/stderr\fP, file | |
3202 | descriptor 0, 1, or 2, respectively, is checked. | |
cce855bc JA |
3203 | .sp 1 |
3204 | .PD 0 | |
3205 | .TP | |
3206 | .B \-a \fIfile\fP | |
3207 | True if \fIfile\fP exists. | |
3208 | .TP | |
3209 | .B \-b \fIfile\fP | |
3210 | True if \fIfile\fP exists and is a block special file. | |
3211 | .TP | |
3212 | .B \-c \fIfile\fP | |
3213 | True if \fIfile\fP exists and is a character special file. | |
3214 | .TP | |
3215 | .B \-d \fIfile\fP | |
3216 | True if \fIfile\fP exists and is a directory. | |
3217 | .TP | |
3218 | .B \-e \fIfile\fP | |
3219 | True if \fIfile\fP exists. | |
3220 | .TP | |
3221 | .B \-f \fIfile\fP | |
3222 | True if \fIfile\fP exists and is a regular file. | |
3223 | .TP | |
3224 | .B \-g \fIfile\fP | |
3225 | True if \fIfile\fP exists and is set-group-id. | |
3226 | .TP | |
b72432fd JA |
3227 | .B \-h \fIfile\fP |
3228 | True if \fIfile\fP exists and is a symbolic link. | |
3229 | .TP | |
cce855bc JA |
3230 | .B \-k \fIfile\fP |
3231 | True if \fIfile\fP exists and its ``sticky'' bit is set. | |
3232 | .TP | |
3233 | .B \-p \fIfile\fP | |
3234 | True if \fIfile\fP exists and is a named pipe (FIFO). | |
3235 | .TP | |
3236 | .B \-r \fIfile\fP | |
3237 | True if \fIfile\fP exists and is readable. | |
3238 | .TP | |
3239 | .B \-s \fIfile\fP | |
3240 | True if \fIfile\fP exists and has a size greater than zero. | |
3241 | .TP | |
3242 | .B \-t \fIfd\fP | |
3243 | True if file descriptor | |
3244 | .I fd | |
3245 | is open and refers to a terminal. | |
3246 | .TP | |
3247 | .B \-u \fIfile\fP | |
3248 | True if \fIfile\fP exists and its set-user-id bit is set. | |
3249 | .TP | |
3250 | .B \-w \fIfile\fP | |
3251 | True if \fIfile\fP exists and is writable. | |
3252 | .TP | |
3253 | .B \-x \fIfile\fP | |
3254 | True if \fIfile\fP exists and is executable. | |
3255 | .TP | |
3256 | .B \-O \fIfile\fP | |
3257 | True if \fIfile\fP exists and is owned by the effective user id. | |
3258 | .TP | |
3259 | .B \-G \fIfile\fP | |
3260 | True if \fIfile\fP exists and is owned by the effective group id. | |
3261 | .TP | |
3262 | .B \-L \fIfile\fP | |
3263 | True if \fIfile\fP exists and is a symbolic link. | |
3264 | .TP | |
3265 | .B \-S \fIfile\fP | |
3266 | True if \fIfile\fP exists and is a socket. | |
3267 | .TP | |
3268 | .B \-N \fIfile\fP | |
3269 | True if \fIfile\fP exists and has been modified since it was last read. | |
3270 | .TP | |
3271 | \fIfile1\fP \-\fBnt\fP \fIfile2\fP | |
3272 | True if \fIfile1\fP is newer (according to | |
3273 | modification date) than \fIfile2\fP. | |
3274 | .TP | |
3275 | \fIfile1\fP \-\fBot\fP \fIfile2\fP | |
3276 | True if \fIfile1\fP is older than \fIfile2\fP. | |
3277 | .TP | |
3278 | \fIfile1\fP \fB\-ef\fP \fIfile2\fP | |
3279 | True if \fIfile1\fP and \fIfile2\fP have the same device and | |
3280 | inode numbers. | |
3281 | .TP | |
3282 | .B \-o \fIoptname\fP | |
3283 | True if shell option | |
3284 | .I optname | |
3285 | is enabled. | |
3286 | See the list of options under the description of the | |
3287 | .B \-o | |
3288 | option to the | |
3289 | .B set | |
3290 | builtin below. | |
3291 | .TP | |
3292 | .B \-z \fIstring\fP | |
3293 | True if the length of \fIstring\fP is zero. | |
3294 | .TP | |
3295 | .B \-n \fIstring\fP | |
3296 | .TP | |
3297 | \fIstring\fP | |
3298 | True if the length of | |
3299 | .I string | |
3300 | is non-zero. | |
3301 | .TP | |
3302 | \fIstring1\fP \fB==\fP \fIstring2\fP | |
3303 | True if the strings are equal. \fB=\fP may be used in place of | |
3304 | \fB==\fP. | |
3305 | .TP | |
3306 | \fIstring1\fP \fB!=\fP \fIstring2\fP | |
3307 | True if the strings are not equal. | |
3308 | .TP | |
3309 | \fIstring1\fP \fB<\fP \fIstring2\fP | |
3310 | True if \fIstring1\fP sorts before \fIstring2\fP lexicographically | |
3311 | in the current locale. | |
3312 | .TP | |
3313 | \fIstring1\fP \fB>\fP \fIstring2\fP | |
3314 | True if \fIstring1\fP sorts after \fIstring2\fP lexicographically | |
3315 | in the current locale. | |
3316 | .TP | |
3317 | .I \fIarg1\fP \fBOP\fP \fIarg2\fP | |
3318 | .SM | |
3319 | .B OP | |
3320 | is one of | |
3321 | .BR \-eq , | |
3322 | .BR \-ne , | |
3323 | .BR \-lt , | |
3324 | .BR \-le , | |
3325 | .BR \-gt , | |
3326 | or | |
3327 | .BR \-ge . | |
3328 | These arithmetic binary operators return true if \fIarg1\fP | |
3329 | is equal to, not equal to, less than, less than or equal to, | |
3330 | greater than, or greater than or equal to \fIarg2\fP, respectively. | |
3331 | .I Arg1 | |
3332 | and | |
3333 | .I arg2 | |
3334 | may be positive or negative integers. | |
3335 | .PD | |
3336 | .SH "SIMPLE COMMAND EXPANSION" | |
3337 | When a simple command is executed, the shell performs the following | |
3338 | expansions, assignments, and redirections, from left to right. | |
3339 | .IP 1. | |
3340 | The words that the parser has marked as variable assignments (those | |
3341 | preceding the command name) and redirections are saved for later | |
3342 | processing. | |
3343 | .IP 2. | |
3344 | The words that are not variable assignments or redirections are | |
3345 | expanded. If any words remain after expansion, the first word | |
3346 | is taken to be the name of the command and the remaining words are | |
3347 | the arguments. | |
3348 | .IP 3. | |
3349 | Redirections are performed as described above under | |
3350 | .SM | |
3351 | .BR REDIRECTION . | |
3352 | .IP 4. | |
3353 | The text after the \fB=\fP in each variable assignment undergoes tilde | |
3354 | expansion, parameter expansion, command substitution, arithmetic expansion, | |
3355 | and quote removal before being assigned to the variable. | |
3356 | .PP | |
3357 | If no command name results, the variable assignments affect the current | |
3358 | shell environment. Otherwise, the variables are added to the environment | |
3359 | of the executed command and do not affect the current shell environment. | |
3360 | If any of the assignments attempts to assign a value to a readonly variable, | |
3361 | an error occurs, and the command exits with a non-zero status. | |
3362 | .PP | |
3363 | If no command name results, redirections are performed, but do not | |
3364 | affect the current shell environment. A redirection error causes the | |
3365 | command to exit with a non-zero status. | |
3366 | .PP | |
3367 | If there is a command name left after expansion, execution proceeds as | |
3368 | described below. Otherwise, the command exits. If one of the expansions | |
3369 | contained a command substitution, the exit status of the command is | |
3370 | the exit status of the last command substitution performed. If there | |
3371 | were no command substitutions, the command exits with a status of zero. | |
3372 | .SH "COMMAND EXECUTION" | |
3373 | After a command has been split into words, if it results in a | |
3374 | simple command and an optional list of arguments, the following | |
3375 | actions are taken. | |
3376 | .PP | |
3377 | If the command name contains no slashes, the shell attempts to | |
3378 | locate it. If there exists a shell function by that name, that | |
3379 | function is invoked as described above in | |
3380 | .SM | |
3381 | .BR FUNCTIONS . | |
3382 | If the name does not match a function, the shell searches for | |
3383 | it in the list of shell builtins. If a match is found, that | |
3384 | builtin is invoked. | |
3385 | .PP | |
3386 | If the name is neither a shell function nor a builtin, | |
3387 | and contains no slashes, | |
3388 | .B bash | |
3389 | searches each element of the | |
3390 | .SM | |
3391 | .B PATH | |
3392 | for a directory containing an executable file by that name. | |
3393 | .B Bash | |
bb70624e | 3394 | uses a hash table to remember the full pathnames of executable |
cce855bc JA |
3395 | files (see |
3396 | .B hash | |
3397 | under | |
3398 | .SM | |
3399 | .B "SHELL BUILTIN COMMANDS" | |
3400 | below). | |
3401 | A full search of the directories in | |
3402 | .SM | |
3403 | .B PATH | |
3404 | is performed only if the command is not found in the hash table. | |
3405 | If the search is unsuccessful, the shell prints an error | |
3406 | message and returns an exit status of 127. | |
3407 | .PP | |
3408 | If the search is successful, or if the command name contains | |
3409 | one or more slashes, the shell executes the named program in a | |
3410 | separate execution environment. | |
3411 | Argument 0 is set to the name given, and the remaining arguments | |
3412 | to the command are set to the arguments given, if any. | |
3413 | .PP | |
3414 | If this execution fails because the file is not in executable | |
3415 | format, and the file is not a directory, it is assumed to be | |
3416 | a \fIshell script\fP, a file | |
3417 | containing shell commands. A subshell is spawned to execute | |
3418 | it. This subshell reinitializes itself, so | |
3419 | that the effect is as if a new shell had been invoked | |
3420 | to handle the script, with the exception that the locations of | |
3421 | commands remembered by the parent (see | |
3422 | .B hash | |
3423 | below under | |
3424 | .SM | |
3425 | \fBSHELL BUILTIN COMMANDS\fP) | |
3426 | are retained by the child. | |
3427 | .PP | |
3428 | If the program is a file beginning with | |
3429 | .BR #! , | |
3430 | the remainder of the first line specifies an interpreter | |
3431 | for the program. The shell executes the | |
3432 | specified interpreter on operating systems that do not | |
3433 | handle this executable format themselves. The arguments to the | |
3434 | interpreter consist of a single optional argument following the | |
3435 | interpreter name on the first line of the program, followed | |
3436 | by the name of the program, followed by the command | |
3437 | arguments, if any. | |
3438 | .SH COMMAND EXECUTION ENVIRONMENT | |
3439 | The shell has an \fIexecution environment\fP, which consists of the | |
3440 | following: | |
3441 | .sp 1 | |
3442 | .IP \(bu | |
3443 | open files inherited by the shell at invocation, as modified by | |
3444 | redirections supplied to the \fBexec\fP builtin | |
3445 | .IP \(bu | |
3446 | the current working directory as set by \fBcd\fP, \fBpushd\fP, or | |
3447 | \fBpopd\fP, or inherited by the shell at invocation | |
3448 | .IP \(bu | |
3449 | the file creation mode mask as set by \fBumask\fP or inherited from | |
3450 | the shell's parent | |
3451 | .IP \(bu | |
3452 | current traps set by \fBtrap\fP | |
3453 | .IP \(bu | |
3454 | shell parameters that are set by variable assignment or with \fBset\fP | |
3455 | or inherited from the shell's parent in the environment | |
3456 | .IP \(bu | |
3457 | shell functions defined during execution or inherited from the shell's | |
3458 | parent in the environment | |
3459 | .IP \(bu | |
3460 | options enabled at invocation (either by default or with command-line | |
3461 | arguments) or by \fBset\fP | |
3462 | .IP \(bu | |
3463 | options enabled by \fBshopt\fP | |
3464 | .IP \(bu | |
3465 | shell aliases defined with \fBalias\fP | |
3466 | .IP \(bu | |
3467 | various process IDs, including those of background jobs, the value | |
3468 | of \fB$$\fP, and the value of \fB$PPID\fP | |
3469 | .PP | |
3470 | When a simple command other than a builtin or shell function | |
3471 | is to be executed, it | |
3472 | is invoked in a separate execution environment that consists of | |
3473 | the following. Unless otherwise noted, the values are inherited | |
3474 | from the shell. | |
3475 | .sp 1 | |
3476 | .IP \(bu | |
3477 | the shell's open files, plus any modifications and additions specified | |
3478 | by redirections to the command | |
3479 | .IP \(bu | |
3480 | the current working directory | |
3481 | .IP \(bu | |
3482 | the file creation mode mask | |
3483 | .IP \(bu | |
3484 | shell variables marked for export, along with variables exported for | |
3485 | the command, passed in the environment | |
3486 | .IP \(bu | |
3487 | traps caught by the shell are reset to the values the inherited | |
3488 | from the shell's parent, and traps ignored by the shell are ignored | |
3489 | .PP | |
3490 | A command invoked in this separate environment cannot affect the | |
3491 | shell's execution environment. | |
3492 | .PP | |
3493 | Command substitution and asynchronous commands are invoked in a | |
3494 | subshell environment that is a duplicate of the shell environment, | |
3495 | except that traps caught by the shell are reset to the values | |
3496 | that the shell inherited from its parent at invocation. Builtin | |
3497 | commands that are invoked as part of a pipeline are also executed in a | |
3498 | subshell environment. Changes made to the subshell environment | |
3499 | cannot affect the shell's execution environment. | |
f73dda09 JA |
3500 | .PP |
3501 | If a command is followed by a \fB&\fP and job control is not active, the | |
3502 | default standard input for the command is the empty file \fI/dev/null\fP. | |
3503 | Otherwise, the invoked command inherits the file descriptors of the calling | |
3504 | shell as modified by redirections. | |
cce855bc JA |
3505 | .SH ENVIRONMENT |
3506 | When a program is invoked it is given an array of strings | |
3507 | called the | |
3508 | .IR environment . | |
3509 | This is a list of | |
3510 | \fIname\fP\-\fIvalue\fP pairs, of the form | |
3511 | .IR "name\fR=\fPvalue" . | |
3512 | .PP | |
bb70624e JA |
3513 | The shell provides several ways to manipulate the environment. |
3514 | On invocation, the shell scans its own environment and | |
cce855bc JA |
3515 | creates a parameter for each name found, automatically marking |
3516 | it for | |
3517 | .I export | |
3518 | to child processes. Executed commands inherit the environment. | |
3519 | The | |
3520 | .B export | |
3521 | and | |
3522 | .B declare \-x | |
3523 | commands allow parameters and functions to be added to and | |
3524 | deleted from the environment. If the value of a parameter | |
3525 | in the environment is modified, the new value becomes part | |
3526 | of the environment, replacing the old. The environment | |
3527 | inherited by any executed command consists of the shell's | |
3528 | initial environment, whose values may be modified in the shell, | |
3529 | less any pairs removed by the | |
3530 | .B unset | |
3531 | command, plus any additions via the | |
3532 | .B export | |
3533 | and | |
3534 | .B declare \-x | |
3535 | commands. | |
3536 | .PP | |
3537 | The environment for any | |
3538 | .I simple command | |
3539 | or function may be augmented temporarily by prefixing it with | |
3540 | parameter assignments, as described above in | |
3541 | .SM | |
3542 | .BR PARAMETERS . | |
3543 | These assignment statements affect only the environment seen | |
3544 | by that command. | |
3545 | .PP | |
3546 | If the | |
3547 | .B \-k | |
3548 | option is set (see the | |
3549 | .B set | |
3550 | builtin command below), then | |
3551 | .I all | |
3552 | parameter assignments are placed in the environment for a command, | |
3553 | not just those that precede the command name. | |
3554 | .PP | |
3555 | When | |
3556 | .B bash | |
3557 | invokes an external command, the variable | |
3558 | .B _ | |
3559 | is set to the full file name of the command and passed to that | |
ccc6cda3 JA |
3560 | command in its environment. |
3561 | .SH "EXIT STATUS" | |
cce855bc | 3562 | For the shell's purposes, a command which exits with a |
ccc6cda3 JA |
3563 | zero exit status has succeeded. An exit status of zero |
3564 | indicates success. A non-zero exit status indicates failure. | |
bb70624e JA |
3565 | When a command terminates on a fatal signal \fIN\fP, \fBbash\fP uses |
3566 | the value of 128+\fIN\fP as the exit status. | |
ccc6cda3 JA |
3567 | .PP |
3568 | If a command is not found, the child process created to | |
3569 | execute it returns a status of 127. If a command is found | |
3570 | but is not executable, the return status is 126. | |
3571 | .PP | |
cce855bc JA |
3572 | If a command fails because of an error during expansion or redirection, |
3573 | the exit status is greater than zero. | |
3574 | .PP | |
ccc6cda3 JA |
3575 | Shell builtin commands return a status of 0 (\fItrue\fP) if |
3576 | successful, and non-zero (\fIfalse\fP) if an error occurs | |
3577 | while they execute. | |
3578 | All builtins return an exit status of 2 to indicate incorrect usage. | |
3579 | .PP | |
3580 | \fBBash\fP itself returns the exit status of the last command | |
3581 | executed, unless a syntax error occurs, in which case it exits | |
3582 | with a non-zero value. See also the \fBexit\fP builtin | |
3583 | command below. | |
3584 | .SH SIGNALS | |
cce855bc | 3585 | When \fBbash\fP is interactive, in the absence of any traps, it ignores |
ccc6cda3 JA |
3586 | .SM |
3587 | .B SIGTERM | |
3588 | (so that \fBkill 0\fP does not kill an interactive shell), | |
3589 | and | |
3590 | .SM | |
3591 | .B SIGINT | |
3592 | is caught and handled (so that the \fBwait\fP builtin is interruptible). | |
3593 | In all cases, \fBbash\fP ignores | |
3594 | .SM | |
3595 | .BR SIGQUIT . | |
3596 | If job control is in effect, | |
3597 | .B bash | |
3598 | ignores | |
3599 | .SM | |
3600 | .BR SIGTTIN , | |
3601 | .SM | |
3602 | .BR SIGTTOU , | |
3603 | and | |
3604 | .SM | |
3605 | .BR SIGTSTP . | |
3606 | .PP | |
cce855bc JA |
3607 | Synchronous jobs started by \fBbash\fP have signal handlers |
3608 | set to the values inherited by the shell from its parent. | |
3609 | When job control is not in effect, asynchronous commands | |
ccc6cda3 JA |
3610 | ignore |
3611 | .SM | |
3612 | .B SIGINT | |
3613 | and | |
3614 | .SM | |
cce855bc JA |
3615 | .B SIGQUIT |
3616 | as well. | |
ccc6cda3 JA |
3617 | Commands run as a result of command substitution ignore the |
3618 | keyboard-generated job control signals | |
3619 | .SM | |
3620 | .BR SIGTTIN , | |
3621 | .SM | |
3622 | .BR SIGTTOU , | |
3623 | and | |
3624 | .SM | |
3625 | .BR SIGTSTP . | |
3626 | .PP | |
3627 | The shell exits by default upon receipt of a | |
3628 | .SM | |
3629 | .BR SIGHUP . | |
f73dda09 | 3630 | Before exiting, an interactive shell resends the |
ccc6cda3 JA |
3631 | .SM |
3632 | .B SIGHUP | |
cce855bc JA |
3633 | to all jobs, running or stopped. |
3634 | Stopped jobs are sent | |
3635 | .SM | |
3636 | .B SIGCONT | |
3637 | to ensure that they receive the | |
3638 | .SM | |
3639 | .BR SIGHUP . | |
3640 | To prevent the shell from | |
3641 | sending the signal to a particular job, it should be removed from the | |
ccc6cda3 JA |
3642 | jobs table with the |
3643 | .B disown | |
3644 | builtin (see | |
3645 | .SM | |
3646 | .B "SHELL BUILTIN COMMANDS" | |
cce855bc JA |
3647 | below) or marked |
3648 | to not receive | |
ccc6cda3 | 3649 | .SM |
cce855bc JA |
3650 | .B SIGHUP |
3651 | using | |
3652 | .BR "disown \-h" . | |
3653 | .PP | |
3654 | If the | |
3655 | .B huponexit | |
3656 | shell option has been set with | |
3657 | .BR shopt , | |
3658 | .B bash | |
3659 | sends a | |
3660 | .SM | |
3661 | .B SIGHUP | |
3662 | to all jobs when an interactive login shell exits. | |
3663 | .PP | |
3664 | When \fBbash\fP receives a signal for which a trap has been set while | |
3665 | waiting for a command to complete, the trap will not be executed until | |
3666 | the command completes. | |
3667 | When \fBbash\fP is waiting for an asynchronous command via the \fBwait\fP | |
3668 | builtin, the reception of a signal for which a trap has been set will | |
3669 | cause the \fBwait\fP builtin to return immediately with an exit status | |
3670 | greater than 128, immediately after which the trap is executed. | |
ccc6cda3 JA |
3671 | .SH "JOB CONTROL" |
3672 | .I Job control | |
3673 | refers to the ability to selectively stop (\fIsuspend\fP) | |
3674 | the execution of processes and continue (\fIresume\fP) | |
3675 | their execution at a later point. A user typically employs | |
3676 | this facility via an interactive interface supplied jointly | |
3677 | by the system's terminal driver and | |
3678 | .BR bash . | |
3679 | .PP | |
3680 | The shell associates a | |
3681 | .I job | |
3682 | with each pipeline. It keeps a table of currently executing | |
3683 | jobs, which may be listed with the | |
3684 | .B jobs | |
3685 | command. When | |
3686 | .B bash | |
3687 | starts a job asynchronously (in the | |
3688 | .IR background ), | |
3689 | it prints a line that looks like: | |
3690 | .RS | |
3691 | .PP | |
3692 | [1] 25647 | |
3693 | .RE | |
3694 | .PP | |
3695 | indicating that this job is job number 1 and that the process ID | |
3696 | of the last process in the pipeline associated with this job is 25647. | |
3697 | All of the processes in a single pipeline are members of the same job. | |
3698 | .B Bash | |
3699 | uses the | |
3700 | .I job | |
3701 | abstraction as the basis for job control. | |
3702 | .PP | |
3703 | To facilitate the implementation of the user interface to job | |
bb70624e | 3704 | control, the operating system maintains the notion of a \fIcurrent terminal |
ccc6cda3 JA |
3705 | process group ID\fP. Members of this process group (processes whose |
3706 | process group ID is equal to the current terminal process group ID) | |
3707 | receive keyboard-generated signals such as | |
3708 | .SM | |
3709 | .BR SIGINT . | |
3710 | These processes are said to be in the | |
3711 | .IR foreground . | |
3712 | .I Background | |
3713 | processes are those whose process group ID differs from the terminal's; | |
3714 | such processes are immune to keyboard-generated signals. | |
3715 | Only foreground processes are allowed to read from or write to the | |
3716 | terminal. Background processes which attempt to read from (write to) the | |
3717 | terminal are sent a | |
3718 | .SM | |
3719 | .B SIGTTIN (SIGTTOU) | |
3720 | signal by the terminal driver, | |
3721 | which, unless caught, suspends the process. | |
3722 | .PP | |
3723 | If the operating system on which | |
3724 | .B bash | |
3725 | is running supports | |
3726 | job control, | |
3727 | .B bash | |
bb70624e | 3728 | contains facilities to use it. |
ccc6cda3 JA |
3729 | Typing the |
3730 | .I suspend | |
3731 | character (typically | |
3732 | .BR ^Z , | |
3733 | Control-Z) while a process is running | |
bb70624e | 3734 | causes that process to be stopped and returns control to |
ccc6cda3 JA |
3735 | .BR bash . |
3736 | Typing the | |
3737 | .I "delayed suspend" | |
3738 | character (typically | |
3739 | .BR ^Y , | |
3740 | Control-Y) causes the process to be stopped when it | |
3741 | attempts to read input from the terminal, and control to | |
3742 | be returned to | |
3743 | .BR bash . | |
cce855bc | 3744 | The user may then manipulate the state of this job, using the |
ccc6cda3 JA |
3745 | .B bg |
3746 | command to continue it in the background, the | |
3747 | .B fg | |
3748 | command to continue it in the foreground, or | |
3749 | the | |
3750 | .B kill | |
3751 | command to kill it. A \fB^Z\fP takes effect immediately, | |
3752 | and has the additional side effect of causing pending output | |
3753 | and typeahead to be discarded. | |
3754 | .PP | |
3755 | There are a number of ways to refer to a job in the shell. | |
3756 | The character | |
3757 | .B % | |
3758 | introduces a job name. Job number | |
3759 | .I n | |
3760 | may be referred to as | |
3761 | .BR %n . | |
3762 | A job may also be referred to using a prefix of the name used to | |
3763 | start it, or using a substring that appears in its command line. | |
3764 | For example, | |
3765 | .B %ce | |
3766 | refers to a stopped | |
3767 | .B ce | |
3768 | job. If a prefix matches more than one job, | |
3769 | .B bash | |
3770 | reports an error. Using | |
3771 | .BR %?ce , | |
3772 | on the other hand, refers to any job containing the string | |
3773 | .B ce | |
3774 | in its command line. If the substring matches more than one job, | |
3775 | .B bash | |
3776 | reports an error. The symbols | |
3777 | .B %% | |
3778 | and | |
3779 | .B %+ | |
3780 | refer to the shell's notion of the | |
3781 | .IR "current job" , | |
3782 | which is the last job stopped while it was in | |
cce855bc | 3783 | the foreground or started in the background. |
ccc6cda3 JA |
3784 | The |
3785 | .I "previous job" | |
3786 | may be referenced using | |
3787 | .BR %\- . | |
3788 | In output pertaining to jobs (e.g., the output of the | |
3789 | .B jobs | |
3790 | command), the current job is always flagged with a | |
3791 | .BR + , | |
3792 | and the previous job with a | |
3793 | .BR \- . | |
726f6388 | 3794 | .PP |
ccc6cda3 JA |
3795 | Simply naming a job can be used to bring it into the |
3796 | foreground: | |
3797 | .B %1 | |
3798 | is a synonym for | |
3799 | \fB``fg %1''\fP, | |
3800 | bringing job 1 from the background into the foreground. | |
3801 | Similarly, | |
3802 | .B ``%1 &'' | |
3803 | resumes job 1 in the background, equivalent to | |
3804 | \fB``bg %1''\fP. | |
726f6388 | 3805 | .PP |
ccc6cda3 JA |
3806 | The shell learns immediately whenever a job changes state. |
3807 | Normally, | |
3808 | .B bash | |
3809 | waits until it is about to print a prompt before reporting | |
3810 | changes in a job's status so as to not interrupt | |
3811 | any other output. If the | |
3812 | .B \-b | |
3813 | option to the | |
726f6388 | 3814 | .B set |
ccc6cda3 | 3815 | builtin command |
cce855bc | 3816 | is enabled, |
726f6388 | 3817 | .B bash |
ccc6cda3 | 3818 | reports such changes immediately. |
f73dda09 JA |
3819 | Any trap on |
3820 | .SM | |
3821 | .B SIGCHLD | |
3822 | is executed for each child that exits. | |
726f6388 | 3823 | .PP |
ccc6cda3 JA |
3824 | If an attempt to exit |
3825 | .B bash | |
3826 | is made while jobs are stopped, the shell prints a warning message. The | |
3827 | .B jobs | |
3828 | command may then be used to inspect their status. | |
3829 | If a second attempt to exit is made without an intervening command, | |
3830 | the shell does not print another warning, and the stopped | |
3831 | jobs are terminated. | |
726f6388 JA |
3832 | .SH PROMPTING |
3833 | When executing interactively, | |
3834 | .B bash | |
3835 | displays the primary prompt | |
3836 | .SM | |
3837 | .B PS1 | |
3838 | when it is ready to read a command, and the secondary prompt | |
3839 | .SM | |
3840 | .B PS2 | |
3841 | when it needs more input to complete a command. | |
3842 | .B Bash | |
3843 | allows these prompt strings to be customized by inserting a number of | |
3844 | backslash-escaped special characters that are decoded as follows: | |
3845 | .RS | |
3846 | .PD 0 | |
3847 | .TP | |
ccc6cda3 JA |
3848 | .B \ea |
3849 | an ASCII bell character (07) | |
726f6388 JA |
3850 | .TP |
3851 | .B \ed | |
3852 | the date in "Weekday Month Date" format (e.g., "Tue May 26") | |
3853 | .TP | |
ccc6cda3 JA |
3854 | .B \ee |
3855 | an ASCII escape character (033) | |
3856 | .TP | |
3857 | .B \eh | |
3858 | the hostname up to the first `.' | |
3859 | .TP | |
3860 | .B \eH | |
3861 | the hostname | |
3862 | .TP | |
bb70624e JA |
3863 | .B \ej |
3864 | the number of jobs currently managed by the shell | |
3865 | .TP | |
3866 | .B \el | |
3867 | the basename of the shell's terminal device name | |
3868 | .TP | |
726f6388 JA |
3869 | .B \en |
3870 | newline | |
3871 | .TP | |
cce855bc JA |
3872 | .B \er |
3873 | carriage return | |
3874 | .TP | |
726f6388 JA |
3875 | .B \es |
3876 | the name of the shell, the basename of | |
3877 | .B $0 | |
3878 | (the portion following the final slash) | |
3879 | .TP | |
ccc6cda3 JA |
3880 | .B \et |
3881 | the current time in 24-hour HH:MM:SS format | |
726f6388 | 3882 | .TP |
ccc6cda3 JA |
3883 | .B \eT |
3884 | the current time in 12-hour HH:MM:SS format | |
3885 | .TP | |
3886 | .B \e@ | |
3887 | the current time in 12-hour am/pm format | |
726f6388 | 3888 | .TP |
f73dda09 JA |
3889 | .B \eA |
3890 | the current time in 24-hour HH:MM format | |
3891 | .TP | |
726f6388 JA |
3892 | .B \eu |
3893 | the username of the current user | |
3894 | .TP | |
ccc6cda3 JA |
3895 | .B \ev |
3896 | the version of \fBbash\fP (e.g., 2.00) | |
726f6388 | 3897 | .TP |
ccc6cda3 | 3898 | .B \eV |
f73dda09 | 3899 | the release of \fBbash\fP, version + patchelvel (e.g., 2.00.0) |
ccc6cda3 JA |
3900 | .TP |
3901 | .B \ew | |
3902 | the current working directory | |
3903 | .TP | |
3904 | .B \eW | |
3905 | the basename of the current working directory | |
726f6388 JA |
3906 | .TP |
3907 | .B \e! | |
3908 | the history number of this command | |
3909 | .TP | |
ccc6cda3 JA |
3910 | .B \e# |
3911 | the command number of this command | |
3912 | .TP | |
726f6388 JA |
3913 | .B \e$ |
3914 | if the effective UID is 0, a | |
3915 | .BR # , | |
3916 | otherwise a | |
3917 | .B $ | |
3918 | .TP | |
ccc6cda3 JA |
3919 | .B \e\fInnn\fP |
3920 | the character corresponding to the octal number \fInnn\fP | |
726f6388 JA |
3921 | .TP |
3922 | .B \e\e | |
3923 | a backslash | |
3924 | .TP | |
3925 | .B \e[ | |
3926 | begin a sequence of non-printing characters, which could be used to | |
3927 | embed a terminal control sequence into the prompt | |
3928 | .TP | |
3929 | .B \e] | |
3930 | end a sequence of non-printing characters | |
3931 | .PD | |
3932 | .RE | |
3933 | .PP | |
3934 | The command number and the history number are usually different: | |
3935 | the history number of a command is its position in the history | |
3936 | list, which may include commands restored from the history file | |
3937 | (see | |
3938 | .SM | |
3939 | .B HISTORY | |
3940 | below), while the command number is the position in the sequence | |
3941 | of commands executed during the current shell session. | |
3942 | After the string is decoded, it is expanded via | |
bb70624e JA |
3943 | parameter expansion, command substitution, arithmetic |
3944 | expansion, and quote removal, subject to the value of the | |
ccc6cda3 JA |
3945 | .B promptvars |
3946 | shell option (see the description of the | |
3947 | .B shopt | |
3948 | command under | |
3949 | .SM | |
3950 | .B "SHELL BUILTIN COMMANDS" | |
3951 | below). | |
726f6388 JA |
3952 | .SH READLINE |
3953 | This is the library that handles reading input when using an interactive | |
3954 | shell, unless the | |
d166f048 | 3955 | .B \-\-noediting |
ccc6cda3 JA |
3956 | option is given at shell invocation. |
3957 | By default, the line editing commands are similar to those of emacs. | |
726f6388 | 3958 | A vi-style line editing interface is also available. |
ccc6cda3 JA |
3959 | To turn off line editing after the shell is running, use the |
3960 | .B +o emacs | |
3961 | or | |
3962 | .B +o vi | |
3963 | options to the | |
3964 | .B set | |
3965 | builtin (see | |
3966 | .SM | |
3967 | .B SHELL BUILTIN COMMANDS | |
3968 | below). | |
3969 | .SS "Readline Notation" | |
726f6388 JA |
3970 | .PP |
3971 | In this section, the emacs-style notation is used to denote | |
3972 | keystrokes. Control keys are denoted by C\-\fIkey\fR, e.g., C\-n | |
3973 | means Control\-N. Similarly, | |
3974 | .I meta | |
3975 | keys are denoted by M\-\fIkey\fR, so M\-x means Meta\-X. (On keyboards | |
3976 | without a | |
3977 | .I meta | |
3978 | key, M\-\fIx\fP means ESC \fIx\fP, i.e., press the Escape key | |
3979 | then the | |
3980 | .I x | |
3981 | key. This makes ESC the \fImeta prefix\fP. | |
3982 | The combination M\-C\-\fIx\fP means ESC\-Control\-\fIx\fP, | |
3983 | or press the Escape key | |
3984 | then hold the Control key while pressing the | |
3985 | .I x | |
3986 | key.) | |
3987 | .PP | |
ccc6cda3 JA |
3988 | Readline commands may be given numeric |
3989 | .IR arguments , | |
3990 | which normally act as a repeat count. | |
3991 | Sometimes, however, it is the sign of the argument that is significant. | |
3992 | Passing a negative argument to a command that acts in the forward | |
3993 | direction (e.g., \fBkill\-line\fP) causes that command to act in a | |
3994 | backward direction. | |
3995 | Commands whose behavior with arguments deviates from this are noted | |
3996 | below. | |
3997 | .PP | |
3998 | When a command is described as \fIkilling\fP text, the text | |
3999 | deleted is saved for possible future retrieval | |
4000 | (\fIyanking\fP). The killed text is saved in a | |
4001 | \fIkill ring\fP. Consecutive kills cause the text to be | |
4002 | accumulated into one unit, which can be yanked all at once. | |
4003 | Commands which do not kill text separate the chunks of text | |
4004 | on the kill ring. | |
4005 | .SS "Readline Initialization" | |
4006 | .PP | |
4007 | Readline is customized by putting commands in an initialization | |
4008 | file (the \fIinputrc\fP file). | |
4009 | The name of this file is taken from the value of the | |
726f6388 | 4010 | .SM |
ccc6cda3 JA |
4011 | .B INPUTRC |
4012 | variable. If that variable is unset, the default is | |
726f6388 | 4013 | .IR ~/.inputrc . |
ccc6cda3 JA |
4014 | When a program which uses the readline library starts up, the |
4015 | initialization file is read, and the key bindings and variables | |
4016 | are set. | |
4017 | There are only a few basic constructs allowed in the | |
4018 | readline initialization file. | |
4019 | Blank lines are ignored. | |
4020 | Lines beginning with a \fB#\fP are comments. | |
4021 | Lines beginning with a \fB$\fP indicate conditional constructs. | |
4022 | Other lines denote key bindings and variable settings. | |
4023 | .PP | |
4024 | The default key-bindings may be changed with an | |
4025 | .I inputrc | |
4026 | file. | |
726f6388 JA |
4027 | Other programs that use this library may add their own commands |
4028 | and bindings. | |
4029 | .PP | |
4030 | For example, placing | |
4031 | .RS | |
4032 | .PP | |
4033 | M\-Control\-u: universal\-argument | |
4034 | .RE | |
4035 | or | |
4036 | .RS | |
4037 | C\-Meta\-u: universal\-argument | |
4038 | .RE | |
4039 | into the | |
ccc6cda3 | 4040 | .I inputrc |
726f6388 JA |
4041 | would make M\-C\-u execute the readline command |
4042 | .IR universal\-argument . | |
4043 | .PP | |
4044 | The following symbolic character names are recognized: | |
4045 | .IR RUBOUT , | |
4046 | .IR DEL , | |
4047 | .IR ESC , | |
4048 | .IR LFD , | |
4049 | .IR NEWLINE , | |
4050 | .IR RET , | |
4051 | .IR RETURN , | |
4052 | .IR SPC , | |
4053 | .IR SPACE , | |
4054 | and | |
4055 | .IR TAB . | |
bb70624e | 4056 | .PP |
726f6388 JA |
4057 | In addition to command names, readline allows keys to be bound |
4058 | to a string that is inserted when the key is pressed (a \fImacro\fP). | |
ccc6cda3 | 4059 | .SS "Readline Key Bindings" |
726f6388 JA |
4060 | .PP |
4061 | The syntax for controlling key bindings in the | |
cce855bc | 4062 | .I inputrc |
726f6388 JA |
4063 | file is simple. All that is required is the name of the |
4064 | command or the text of a macro and a key sequence to which | |
4065 | it should be bound. The name may be specified in one of two ways: | |
ccc6cda3 | 4066 | as a symbolic key name, possibly with \fIMeta\-\fP or \fIControl\-\fP |
726f6388 | 4067 | prefixes, or as a key sequence. |
28ef6c31 | 4068 | .PP |
cce855bc | 4069 | When using the form \fBkeyname\fP:\^\fIfunction\-name\fP or \fImacro\fP, |
726f6388 JA |
4070 | .I keyname |
4071 | is the name of a key spelled out in English. For example: | |
4072 | .sp | |
4073 | .RS | |
4074 | Control-u: universal\-argument | |
4075 | .br | |
4076 | Meta-Rubout: backward-kill-word | |
4077 | .br | |
ccc6cda3 | 4078 | Control-o: "> output" |
726f6388 JA |
4079 | .RE |
4080 | .LP | |
4081 | In the above example, | |
ccc6cda3 | 4082 | .I C\-u |
726f6388 JA |
4083 | is bound to the function |
4084 | .BR universal\-argument , | |
ccc6cda3 | 4085 | .I M\-DEL |
726f6388 JA |
4086 | is bound to the function |
4087 | .BR backward\-kill\-word , | |
4088 | and | |
ccc6cda3 | 4089 | .I C\-o |
726f6388 JA |
4090 | is bound to run the macro |
4091 | expressed on the right hand side (that is, to insert the text | |
28ef6c31 JA |
4092 | .if t \f(CW> output\fP |
4093 | .if n ``> output'' | |
726f6388 JA |
4094 | into the line). |
4095 | .PP | |
cce855bc | 4096 | In the second form, \fB"keyseq"\fP:\^\fIfunction\-name\fP or \fImacro\fP, |
726f6388 JA |
4097 | .B keyseq |
4098 | differs from | |
4099 | .B keyname | |
4100 | above in that strings denoting | |
4101 | an entire key sequence may be specified by placing the sequence | |
4102 | within double quotes. Some GNU Emacs style key escapes can be | |
28ef6c31 JA |
4103 | used, as in the following example, but the symbolic character names |
4104 | are not recognized. | |
726f6388 JA |
4105 | .sp |
4106 | .RS | |
ccc6cda3 | 4107 | "\eC\-u": universal\-argument |
726f6388 | 4108 | .br |
ccc6cda3 | 4109 | "\eC\-x\eC\-r": re\-read\-init\-file |
726f6388 JA |
4110 | .br |
4111 | "\ee[11~": "Function Key 1" | |
4112 | .RE | |
4113 | .PP | |
4114 | In this example, | |
ccc6cda3 | 4115 | .I C\-u |
726f6388 JA |
4116 | is again bound to the function |
4117 | .BR universal\-argument . | |
ccc6cda3 | 4118 | .I "C\-x C\-r" |
726f6388 JA |
4119 | is bound to the function |
4120 | .BR re\-read\-init\-file , | |
4121 | and | |
4122 | .I "ESC [ 1 1 ~" | |
4123 | is bound to insert the text | |
28ef6c31 JA |
4124 | .if t \f(CWFunction Key 1\fP. |
4125 | .if n ``Function Key 1''. | |
4126 | .PP | |
cce855bc | 4127 | The full set of GNU Emacs style escape sequences is |
726f6388 | 4128 | .RS |
cce855bc | 4129 | .PD 0 |
726f6388 JA |
4130 | .TP |
4131 | .B \eC\- | |
4132 | control prefix | |
4133 | .TP | |
ccc6cda3 | 4134 | .B \eM\- |
726f6388 JA |
4135 | meta prefix |
4136 | .TP | |
4137 | .B \ee | |
4138 | an escape character | |
4139 | .TP | |
4140 | .B \e\e | |
4141 | backslash | |
4142 | .TP | |
4143 | .B \e" | |
4144 | literal " | |
4145 | .TP | |
4146 | .B \e' | |
4147 | literal ' | |
4148 | .RE | |
cce855bc JA |
4149 | .PD |
4150 | .PP | |
4151 | In addition to the GNU Emacs style escape sequences, a second | |
4152 | set of backslash escapes is available: | |
4153 | .RS | |
4154 | .PD 0 | |
4155 | .TP | |
4156 | .B \ea | |
4157 | alert (bell) | |
4158 | .TP | |
4159 | .B \eb | |
4160 | backspace | |
4161 | .TP | |
4162 | .B \ed | |
4163 | delete | |
4164 | .TP | |
4165 | .B \ef | |
4166 | form feed | |
4167 | .TP | |
4168 | .B \en | |
4169 | newline | |
4170 | .TP | |
4171 | .B \er | |
4172 | carriage return | |
4173 | .TP | |
4174 | .B \et | |
4175 | horizontal tab | |
4176 | .TP | |
4177 | .B \ev | |
4178 | vertical tab | |
4179 | .TP | |
4180 | .B \e\fInnn\fP | |
f73dda09 | 4181 | the eight-bit character whose value is the octal value \fInnn\fP |
cce855bc JA |
4182 | (one to three digits) |
4183 | .TP | |
f73dda09 JA |
4184 | .B \ex\fIHH\fP |
4185 | the eight-bit character whose value is the hexadecimal value \fIHH\fP | |
4186 | (one or two hex digits) | |
cce855bc JA |
4187 | .RE |
4188 | .PD | |
726f6388 | 4189 | .PP |
cce855bc JA |
4190 | When entering the text of a macro, single or double quotes must |
4191 | be used to indicate a macro definition. | |
4192 | Unquoted text is assumed to be a function name. | |
4193 | In the macro body, the backslash escapes described above are expanded. | |
4194 | Backslash will quote any other character in the macro text, | |
4195 | including " and '. | |
726f6388 JA |
4196 | .PP |
4197 | .B Bash | |
4198 | allows the current readline key bindings to be displayed or modified | |
4199 | with the | |
4200 | .B bind | |
4201 | builtin command. The editing mode may be switched during interactive | |
4202 | use by using the | |
4203 | .B \-o | |
4204 | option to the | |
4205 | .B set | |
4206 | builtin command (see | |
4207 | .SM | |
4208 | .B SHELL BUILTIN COMMANDS | |
4209 | below). | |
ccc6cda3 | 4210 | .SS "Readline Variables" |
726f6388 JA |
4211 | .PP |
4212 | Readline has variables that can be used to further customize its | |
4213 | behavior. A variable may be set in the | |
4214 | .I inputrc | |
4215 | file with a statement of the form | |
4216 | .RS | |
4217 | .PP | |
4218 | \fBset\fP \fIvariable\-name\fP \fIvalue\fP | |
4219 | .RE | |
4220 | .PP | |
4221 | Except where noted, readline variables can take the values | |
4222 | .B On | |
4223 | or | |
4224 | .BR Off . | |
4225 | The variables and their default values are: | |
4226 | .PP | |
4227 | .PD 0 | |
4228 | .TP | |
726f6388 JA |
4229 | .B bell\-style (audible) |
4230 | Controls what happens when readline wants to ring the terminal bell. | |
4231 | If set to \fBnone\fP, readline never rings the bell. If set to | |
4232 | \fBvisible\fP, readline uses a visible bell if one is available. | |
4233 | If set to \fBaudible\fP, readline attempts to ring the terminal's bell. | |
4234 | .TP | |
4235 | .B comment\-begin (``#'') | |
bb70624e | 4236 | The string that is inserted when the readline |
ccc6cda3 | 4237 | .B insert\-comment |
726f6388 | 4238 | command is executed. |
ccc6cda3 JA |
4239 | This command is bound to |
4240 | .B M\-# | |
4241 | in emacs mode and to | |
4242 | .B # | |
4243 | in vi command mode. | |
726f6388 | 4244 | .TP |
cce855bc JA |
4245 | .B completion\-ignore\-case (Off) |
4246 | If set to \fBOn\fP, readline performs filename matching and completion | |
4247 | in a case\-insensitive fashion. | |
4248 | .TP | |
726f6388 JA |
4249 | .B completion\-query\-items (100) |
4250 | This determines when the user is queried about viewing | |
4251 | the number of possible completions | |
4252 | generated by the \fBpossible\-completions\fP command. | |
4253 | It may be set to any integer value greater than or equal to | |
4254 | zero. If the number of possible completions is greater than | |
4255 | or equal to the value of this variable, the user is asked whether | |
4256 | or not he wishes to view them; otherwise they are simply listed | |
4257 | on the terminal. | |
4258 | .TP | |
ccc6cda3 JA |
4259 | .B convert\-meta (On) |
4260 | If set to \fBOn\fP, readline will convert characters with the | |
4261 | eighth bit set to an ASCII key sequence | |
bb70624e | 4262 | by stripping the eighth bit and prefixing an |
ccc6cda3 JA |
4263 | escape character (in effect, using escape as the \fImeta prefix\fP). |
4264 | .TP | |
4265 | .B disable\-completion (Off) | |
4266 | If set to \fBOn\fP, readline will inhibit word completion. Completion | |
4267 | characters will be inserted into the line as if they had been | |
4268 | mapped to \fBself-insert\fP. | |
4269 | .TP | |
4270 | .B editing\-mode (emacs) | |
4271 | Controls whether readline begins with a set of key bindings similar | |
4272 | to \fIemacs\fP or \fIvi\fP. | |
4273 | .B editing\-mode | |
4274 | can be set to either | |
4275 | .B emacs | |
4276 | or | |
4277 | .BR vi . | |
4278 | .TP | |
4279 | .B enable\-keypad (Off) | |
4280 | When set to \fBOn\fP, readline will try to enable the application | |
4281 | keypad when it is called. Some systems need this to enable the | |
4282 | arrow keys. | |
4283 | .TP | |
4284 | .B expand\-tilde (Off) | |
4285 | If set to \fBon\fP, tilde expansion is performed when readline | |
4286 | attempts word completion. | |
4287 | .TP | |
f73dda09 JA |
4288 | .B history-preserve-point |
4289 | If set to \fBon\fP, the history code attempts to place point at the | |
4290 | same location on each history line retrived with \fBprevious-history\fP | |
4291 | or \fBnext-history\fP. | |
4292 | .TP | |
ccc6cda3 JA |
4293 | .B horizontal\-scroll\-mode (Off) |
4294 | When set to \fBOn\fP, makes readline use a single line for display, | |
4295 | scrolling the input horizontally on a single screen line when it | |
4296 | becomes longer than the screen width rather than wrapping to a new line. | |
4297 | .TP | |
4298 | .B input\-meta (Off) | |
4299 | If set to \fBOn\fP, readline will enable eight-bit input (that is, | |
4300 | it will not strip the high bit from the characters it reads), | |
4301 | regardless of what the terminal claims it can support. The name | |
4302 | .B meta\-flag | |
4303 | is a synonym for this variable. | |
4304 | .TP | |
b72432fd JA |
4305 | .B isearch\-terminators (``C\-[C\-J'') |
4306 | The string of characters that should terminate an incremental | |
4307 | search without subsequently executing the character as a command. | |
4308 | If this variable has not been given a value, the characters | |
4309 | \fIESC\fP and \fIC\-J\fP will terminate an incremental search. | |
4310 | .TP | |
726f6388 | 4311 | .B keymap (emacs) |
cce855bc | 4312 | Set the current readline keymap. The set of valid keymap names is |
ccc6cda3 JA |
4313 | \fIemacs, emacs\-standard, emacs\-meta, emacs\-ctlx, vi, |
4314 | vi\-command\fP, and | |
4315 | .IR vi\-insert . | |
4316 | \fIvi\fP is equivalent to \fIvi\-command\fP; \fIemacs\fP is | |
4317 | equivalent to \fIemacs\-standard\fP. The default value is | |
726f6388 JA |
4318 | .IR emacs ; |
4319 | the value of | |
4320 | .B editing\-mode | |
4321 | also affects the default keymap. | |
4322 | .TP | |
ccc6cda3 JA |
4323 | .B mark\-directories (On) |
4324 | If set to \fBOn\fP, completed directory names have a slash | |
4325 | appended. | |
4326 | .TP | |
4327 | .B mark\-modified\-lines (Off) | |
4328 | If set to \fBOn\fP, history lines that have been modified are displayed | |
4329 | with a preceding asterisk (\fB*\fP). | |
4330 | .TP | |
f73dda09 JA |
4331 | .B match\-hidden\-files (On) |
4332 | This variable, when set to \fBOn\fP, causes readline to match files whose | |
4333 | names begin with a `.' (hidden files) when performing filename | |
4334 | completion, unless the leading `.' is | |
4335 | supplied by the user in the filename to be completed. | |
4336 | .TP | |
ccc6cda3 JA |
4337 | .B output\-meta (Off) |
4338 | If set to \fBOn\fP, readline will display characters with the | |
4339 | eighth bit set directly rather than as a meta-prefixed escape | |
4340 | sequence. | |
4341 | .TP | |
cce855bc JA |
4342 | .B print\-completions\-horizontally (Off) |
4343 | If set to \fBOn\fP, readline will display completions with matches | |
4344 | sorted horizontally in alphabetical order, rather than down the screen. | |
4345 | .TP | |
726f6388 JA |
4346 | .B show\-all\-if\-ambiguous (Off) |
4347 | This alters the default behavior of the completion functions. If | |
4348 | set to | |
4349 | .BR on , | |
4350 | words which have more than one possible completion cause the | |
4351 | matches to be listed immediately instead of ringing the bell. | |
4352 | .TP | |
ccc6cda3 JA |
4353 | .B visible\-stats (Off) |
4354 | If set to \fBOn\fP, a character denoting a file's type as reported | |
4355 | by \fIstat\fP(2) is appended to the filename when listing possible | |
4356 | completions. | |
726f6388 | 4357 | .PD |
ccc6cda3 | 4358 | .SS "Readline Conditional Constructs" |
726f6388 JA |
4359 | .PP |
4360 | Readline implements a facility similar in spirit to the conditional | |
4361 | compilation features of the C preprocessor which allows key | |
4362 | bindings and variable settings to be performed as the result | |
cce855bc | 4363 | of tests. There are four parser directives used. |
726f6388 JA |
4364 | .IP \fB$if\fP |
4365 | The | |
4366 | .B $if | |
4367 | construct allows bindings to be made based on the | |
4368 | editing mode, the terminal being used, or the application using | |
4369 | readline. The text of the test extends to the end of the line; | |
4370 | no characters are required to isolate it. | |
4371 | .RS | |
4372 | .IP \fBmode\fP | |
4373 | The \fBmode=\fP form of the \fB$if\fP directive is used to test | |
4374 | whether readline is in emacs or vi mode. | |
4375 | This may be used in conjunction | |
4376 | with the \fBset keymap\fP command, for instance, to set bindings in | |
ccc6cda3 | 4377 | the \fIemacs\-standard\fP and \fIemacs\-ctlx\fP keymaps only if |
726f6388 JA |
4378 | readline is starting out in emacs mode. |
4379 | .IP \fBterm\fP | |
4380 | The \fBterm=\fP form may be used to include terminal-specific | |
4381 | key bindings, perhaps to bind the key sequences output by the | |
4382 | terminal's function keys. The word on the right side of the | |
4383 | .B = | |
cce855bc | 4384 | is tested against the both full name of the terminal and the portion |
726f6388 JA |
4385 | of the terminal name before the first \fB\-\fP. This allows |
4386 | .I sun | |
4387 | to match both | |
4388 | .I sun | |
4389 | and | |
4390 | .IR sun\-cmd , | |
4391 | for instance. | |
4392 | .IP \fBapplication\fP | |
4393 | The \fBapplication\fP construct is used to include | |
ccc6cda3 | 4394 | application-specific settings. Each program using the readline |
726f6388 JA |
4395 | library sets the \fIapplication name\fP, and an initialization |
4396 | file can test for a particular value. | |
4397 | This could be used to bind key sequences to functions useful for | |
4398 | a specific program. For instance, the following command adds a | |
4399 | key sequence that quotes the current or previous word in Bash: | |
cce855bc | 4400 | .sp 1 |
726f6388 JA |
4401 | .RS |
4402 | .nf | |
4403 | \fB$if\fP Bash | |
4404 | # Quote the current or previous word | |
ccc6cda3 | 4405 | "\eC\-xq": "\eeb\e"\eef\e"" |
726f6388 JA |
4406 | \fB$endif\fP |
4407 | .fi | |
4408 | .RE | |
4409 | .RE | |
4410 | .IP \fB$endif\fP | |
cce855bc | 4411 | This command, as seen in the previous example, terminates an |
726f6388 JA |
4412 | \fB$if\fP command. |
4413 | .IP \fB$else\fP | |
4414 | Commands in this branch of the \fB$if\fP directive are executed if | |
4415 | the test fails. | |
cce855bc JA |
4416 | .IP \fB$include\fP |
4417 | This directive takes a single filename as an argument and reads commands | |
4418 | and bindings from that file. For example, the following directive | |
4419 | would read \fI/etc/inputrc\fP: | |
4420 | .sp 1 | |
4421 | .RS | |
4422 | .nf | |
4423 | \fB$include\fP \^ \fI/etc/inputrc\fP | |
4424 | .fi | |
4425 | .RE | |
ccc6cda3 | 4426 | .SS Searching |
726f6388 | 4427 | .PP |
ccc6cda3 JA |
4428 | Readline provides commands for searching through the command history |
4429 | (see | |
4430 | .SM | |
4431 | .B HISTORY | |
4432 | below) for lines containing a specified string. | |
4433 | There are two search modes: | |
4434 | .I incremental | |
4435 | and | |
4436 | .IR non-incremental . | |
4437 | .PP | |
4438 | Incremental searches begin before the user has finished typing the | |
4439 | search string. | |
4440 | As each character of the search string is typed, readline displays | |
4441 | the next entry from the history matching the string typed so far. | |
4442 | An incremental search requires only as many characters as needed to | |
4443 | find the desired history entry. | |
bb70624e | 4444 | The characters present in the value of the \fBisearch-terminators\fP |
b72432fd JA |
4445 | variable are used to terminate an incremental search. |
4446 | If that variable has not been assigned a value the Escape and | |
4447 | Control-J characters will terminate an incremental search. | |
ccc6cda3 JA |
4448 | Control-G will abort an incremental search and restore the original |
4449 | line. | |
4450 | When the search is terminated, the history entry containing the | |
4451 | search string becomes the current line. | |
bb70624e | 4452 | .PP |
ccc6cda3 JA |
4453 | To find other matching entries in the history list, type Control-S or |
4454 | Control-R as appropriate. | |
4455 | This will search backward or forward in the history for the next | |
4456 | entry matching the search string typed so far. | |
4457 | Any other key sequence bound to a readline command will terminate | |
4458 | the search and execute that command. | |
4459 | For instance, a \fInewline\fP will terminate the search and accept | |
4460 | the line, thereby executing the command from the history list. | |
4461 | .PP | |
f73dda09 JA |
4462 | Readline remembers the last incremental search string. If two |
4463 | Control-Rs are typed without any intervening characters defining a | |
4464 | new search string, any remembered search string is used. | |
4465 | .PP | |
ccc6cda3 JA |
4466 | Non-incremental searches read the entire search string before starting |
4467 | to search for matching history lines. The search string may be | |
cce855bc | 4468 | typed by the user or be part of the contents of the current line. |
ccc6cda3 | 4469 | .SS "Readline Command Names" |
726f6388 JA |
4470 | .PP |
4471 | The following is a list of the names of the commands and the default | |
4472 | key sequences to which they are bound. | |
ccc6cda3 | 4473 | Command names without an accompanying key sequence are unbound by default. |
bb70624e JA |
4474 | In the following descriptions, \fIpoint\fP refers to the current cursor |
4475 | position, and \fImark\fP refers to a cursor position saved by the | |
4476 | \fBset\-mark\fP command. | |
4477 | The text between the point and mark is referred to as the \fIregion\fP. | |
726f6388 JA |
4478 | .SS Commands for Moving |
4479 | .PP | |
4480 | .PD 0 | |
4481 | .TP | |
4482 | .B beginning\-of\-line (C\-a) | |
4483 | Move to the start of the current line. | |
4484 | .TP | |
4485 | .B end\-of\-line (C\-e) | |
4486 | Move to the end of the line. | |
4487 | .TP | |
4488 | .B forward\-char (C\-f) | |
4489 | Move forward a character. | |
4490 | .TP | |
4491 | .B backward\-char (C\-b) | |
4492 | Move back a character. | |
4493 | .TP | |
4494 | .B forward\-word (M\-f) | |
4495 | Move forward to the end of the next word. Words are composed of | |
4496 | alphanumeric characters (letters and digits). | |
4497 | .TP | |
4498 | .B backward\-word (M\-b) | |
bb70624e | 4499 | Move back to the start of the current or previous word. Words are |
726f6388 JA |
4500 | composed of alphanumeric characters (letters and digits). |
4501 | .TP | |
4502 | .B clear\-screen (C\-l) | |
4503 | Clear the screen leaving the current line at the top of the screen. | |
4504 | With an argument, refresh the current line without clearing the | |
4505 | screen. | |
4506 | .TP | |
4507 | .B redraw\-current\-line | |
ccc6cda3 | 4508 | Refresh the current line. |
726f6388 JA |
4509 | .PD |
4510 | .SS Commands for Manipulating the History | |
4511 | .PP | |
4512 | .PD 0 | |
4513 | .TP | |
4514 | .B accept\-line (Newline, Return) | |
4515 | Accept the line regardless of where the cursor is. If this line is | |
ccc6cda3 | 4516 | non-empty, add it to the history list according to the state of the |
726f6388 JA |
4517 | .SM |
4518 | .B HISTCONTROL | |
4519 | variable. If the line is a modified history | |
4520 | line, then restore the history line to its original state. | |
4521 | .TP | |
4522 | .B previous\-history (C\-p) | |
4523 | Fetch the previous command from the history list, moving back in | |
4524 | the list. | |
4525 | .TP | |
4526 | .B next\-history (C\-n) | |
4527 | Fetch the next command from the history list, moving forward in the | |
4528 | list. | |
4529 | .TP | |
4530 | .B beginning\-of\-history (M\-<) | |
4531 | Move to the first line in the history. | |
4532 | .TP | |
4533 | .B end\-of\-history (M\->) | |
4534 | Move to the end of the input history, i.e., the line currently being | |
4535 | entered. | |
4536 | .TP | |
4537 | .B reverse\-search\-history (C\-r) | |
4538 | Search backward starting at the current line and moving `up' through | |
4539 | the history as necessary. This is an incremental search. | |
4540 | .TP | |
4541 | .B forward\-search\-history (C\-s) | |
4542 | Search forward starting at the current line and moving `down' through | |
4543 | the history as necessary. This is an incremental search. | |
4544 | .TP | |
4545 | .B non\-incremental\-reverse\-search\-history (M\-p) | |
4546 | Search backward through the history starting at the current line | |
ccc6cda3 | 4547 | using a non-incremental search for a string supplied by the user. |
726f6388 JA |
4548 | .TP |
4549 | .B non\-incremental\-forward\-search\-history (M\-n) | |
ccc6cda3 | 4550 | Search forward through the history using a non-incremental search for |
726f6388 JA |
4551 | a string supplied by the user. |
4552 | .TP | |
4553 | .B history\-search\-forward | |
4554 | Search forward through the history for the string of characters | |
bb70624e | 4555 | between the start of the current line and the point. |
ccc6cda3 | 4556 | This is a non-incremental search. |
726f6388 JA |
4557 | .TP |
4558 | .B history\-search\-backward | |
4559 | Search backward through the history for the string of characters | |
ccc6cda3 JA |
4560 | between the start of the current line and the point. |
4561 | This is a non-incremental search. | |
726f6388 JA |
4562 | .TP |
4563 | .B yank\-nth\-arg (M\-C\-y) | |
4564 | Insert the first argument to the previous command (usually | |
28ef6c31 JA |
4565 | the second word on the previous line) at point. |
4566 | With an argument | |
726f6388 JA |
4567 | .IR n , |
4568 | insert the \fIn\fPth word from the previous command (the words | |
4569 | in the previous command begin with word 0). A negative argument | |
4570 | inserts the \fIn\fPth word from the end of the previous command. | |
4571 | .TP | |
4572 | .B | |
4573 | yank\-last\-arg (M\-.\^, M\-_\^) | |
ccc6cda3 JA |
4574 | Insert the last argument to the previous command (the last word of |
4575 | the previous history entry). With an argument, | |
4576 | behave exactly like \fByank\-nth\-arg\fP. | |
cce855bc JA |
4577 | Successive calls to \fByank\-last\-arg\fP move back through the history |
4578 | list, inserting the last argument of each line in turn. | |
726f6388 JA |
4579 | .TP |
4580 | .B shell\-expand\-line (M\-C\-e) | |
cce855bc | 4581 | Expand the line as the shell does. This |
726f6388 JA |
4582 | performs alias and history expansion as well as all of the shell |
4583 | word expansions. See | |
4584 | .SM | |
4585 | .B HISTORY EXPANSION | |
4586 | below for a description of history expansion. | |
4587 | .TP | |
4588 | .B history\-expand\-line (M\-^) | |
d166f048 JA |
4589 | Perform history expansion on the current line. |
4590 | See | |
726f6388 JA |
4591 | .SM |
4592 | .B HISTORY EXPANSION | |
4593 | below for a description of history expansion. | |
4594 | .TP | |
cce855bc JA |
4595 | .B magic\-space |
4596 | Perform history expansion on the current line and insert a space. | |
4597 | See | |
4598 | .SM | |
4599 | .B HISTORY EXPANSION | |
4600 | below for a description of history expansion. | |
4601 | .TP | |
d166f048 JA |
4602 | .B alias\-expand\-line |
4603 | Perform alias expansion on the current line. | |
4604 | See | |
4605 | .SM | |
4606 | .B ALIASES | |
4607 | above for a description of alias expansion. | |
4608 | .TP | |
4609 | .B history\-and\-alias\-expand\-line | |
4610 | Perform history and alias expansion on the current line. | |
4611 | .TP | |
726f6388 JA |
4612 | .B insert\-last\-argument (M\-.\^, M\-_\^) |
4613 | A synonym for \fByank\-last\-arg\fP. | |
4614 | .TP | |
ccc6cda3 | 4615 | .B operate\-and\-get\-next (C\-o) |
726f6388 JA |
4616 | Accept the current line for execution and fetch the next line |
4617 | relative to the current line from the history for editing. Any | |
4618 | argument is ignored. | |
4619 | .PD | |
4620 | .SS Commands for Changing Text | |
4621 | .PP | |
4622 | .PD 0 | |
4623 | .TP | |
4624 | .B delete\-char (C\-d) | |
28ef6c31 | 4625 | Delete the character at point. If point is at the |
726f6388 | 4626 | beginning of the line, there are no characters in the line, and |
cce855bc | 4627 | the last character typed was not bound to \fBdelete\-char\fP, |
726f6388 JA |
4628 | then return |
4629 | .SM | |
4630 | .BR EOF . | |
4631 | .TP | |
4632 | .B backward\-delete\-char (Rubout) | |
4633 | Delete the character behind the cursor. When given a numeric argument, | |
ccc6cda3 | 4634 | save the deleted text on the kill ring. |
726f6388 | 4635 | .TP |
b72432fd JA |
4636 | .B forward\-backward\-delete\-char |
4637 | Delete the character under the cursor, unless the cursor is at the | |
4638 | end of the line, in which case the character behind the cursor is | |
f73dda09 | 4639 | deleted. |
b72432fd | 4640 | .TP |
726f6388 | 4641 | .B quoted\-insert (C\-q, C\-v) |
cce855bc | 4642 | Add the next character typed to the line verbatim. This is |
726f6388 JA |
4643 | how to insert characters like \fBC\-q\fP, for example. |
4644 | .TP | |
ccc6cda3 | 4645 | .B tab\-insert (C\-v TAB) |
726f6388 JA |
4646 | Insert a tab character. |
4647 | .TP | |
4648 | .B self\-insert (a,\ b,\ A,\ 1,\ !,\ ...) | |
4649 | Insert the character typed. | |
4650 | .TP | |
4651 | .B transpose\-chars (C\-t) | |
28ef6c31 JA |
4652 | Drag the character before point forward over the character at point, |
4653 | moving point forward as well. | |
4654 | If point is at the end of the line, then this transposes | |
4655 | the two characters before point. | |
bb70624e | 4656 | Negative arguments have no effect. |
726f6388 JA |
4657 | .TP |
4658 | .B transpose\-words (M\-t) | |
bb70624e | 4659 | Drag the word before point past the word after point, |
28ef6c31 | 4660 | moving point over that word as well. |
f73dda09 JA |
4661 | If point is at the end of the line, this transposes |
4662 | the last two words on the line. | |
726f6388 JA |
4663 | .TP |
4664 | .B upcase\-word (M\-u) | |
4665 | Uppercase the current (or following) word. With a negative argument, | |
cce855bc | 4666 | uppercase the previous word, but do not move point. |
726f6388 JA |
4667 | .TP |
4668 | .B downcase\-word (M\-l) | |
4669 | Lowercase the current (or following) word. With a negative argument, | |
cce855bc | 4670 | lowercase the previous word, but do not move point. |
726f6388 JA |
4671 | .TP |
4672 | .B capitalize\-word (M\-c) | |
4673 | Capitalize the current (or following) word. With a negative argument, | |
cce855bc | 4674 | capitalize the previous word, but do not move point. |
726f6388 JA |
4675 | .PD |
4676 | .SS Killing and Yanking | |
4677 | .PP | |
4678 | .PD 0 | |
4679 | .TP | |
4680 | .B kill\-line (C\-k) | |
bb70624e | 4681 | Kill the text from point to the end of the line. |
726f6388 | 4682 | .TP |
ccc6cda3 | 4683 | .B backward\-kill\-line (C\-x Rubout) |
726f6388 JA |
4684 | Kill backward to the beginning of the line. |
4685 | .TP | |
4686 | .B unix\-line\-discard (C\-u) | |
4687 | Kill backward from point to the beginning of the line. | |
cce855bc | 4688 | The killed text is saved on the kill-ring. |
bb70624e | 4689 | .\" There is no real difference between this and backward-kill-line |
726f6388 JA |
4690 | .TP |
4691 | .B kill\-whole\-line | |
bb70624e | 4692 | Kill all characters on the current line, no matter where point is. |
726f6388 JA |
4693 | .TP |
4694 | .B kill\-word (M\-d) | |
bb70624e JA |
4695 | Kill from point to the end of the current word, or if between |
4696 | words, to the end of the next word. | |
4697 | Word boundaries are the same as those used by \fBforward\-word\fP. | |
726f6388 JA |
4698 | .TP |
4699 | .B backward\-kill\-word (M\-Rubout) | |
bb70624e JA |
4700 | Kill the word behind point. |
4701 | Word boundaries are the same as those used by \fBbackward\-word\fP. | |
726f6388 JA |
4702 | .TP |
4703 | .B unix\-word\-rubout (C\-w) | |
bb70624e | 4704 | Kill the word behind point, using white space as a word boundary. |
bb70624e | 4705 | The killed text is saved on the kill-ring. |
ccc6cda3 JA |
4706 | .TP |
4707 | .B delete\-horizontal\-space (M\-\e) | |
4708 | Delete all spaces and tabs around point. | |
4709 | .TP | |
4710 | .B kill\-region | |
bb70624e | 4711 | Kill the text in the current region. |
ccc6cda3 JA |
4712 | .TP |
4713 | .B copy\-region\-as\-kill | |
4714 | Copy the text in the region to the kill buffer. | |
726f6388 | 4715 | .TP |
ccc6cda3 JA |
4716 | .B copy\-backward\-word |
4717 | Copy the word before point to the kill buffer. | |
cce855bc | 4718 | The word boundaries are the same as \fBbackward\-word\fP. |
ccc6cda3 JA |
4719 | .TP |
4720 | .B copy\-forward\-word | |
4721 | Copy the word following point to the kill buffer. | |
cce855bc | 4722 | The word boundaries are the same as \fBforward\-word\fP. |
726f6388 JA |
4723 | .TP |
4724 | .B yank (C\-y) | |
28ef6c31 | 4725 | Yank the top of the kill ring into the buffer at point. |
726f6388 JA |
4726 | .TP |
4727 | .B yank\-pop (M\-y) | |
ccc6cda3 | 4728 | Rotate the kill ring, and yank the new top. Only works following |
726f6388 JA |
4729 | .B yank |
4730 | or | |
4731 | .BR yank\-pop . | |
4732 | .PD | |
4733 | .SS Numeric Arguments | |
4734 | .PP | |
4735 | .PD 0 | |
4736 | .TP | |
4737 | .B digit\-argument (M\-0, M\-1, ..., M\-\-) | |
4738 | Add this digit to the argument already accumulating, or start a new | |
4739 | argument. M\-\- starts a negative argument. | |
4740 | .TP | |
4741 | .B universal\-argument | |
d166f048 JA |
4742 | This is another way to specify an argument. |
4743 | If this command is followed by one or more digits, optionally with a | |
4744 | leading minus sign, those digits define the argument. | |
4745 | If the command is followed by digits, executing | |
4746 | .B universal\-argument | |
4747 | again ends the numeric argument, but is otherwise ignored. | |
4748 | As a special case, if this command is immediately followed by a | |
4749 | character that is neither a digit or minus sign, the argument count | |
4750 | for the next command is multiplied by four. | |
726f6388 | 4751 | The argument count is initially one, so executing this function the |
d166f048 JA |
4752 | first time makes the argument count four, a second time makes the |
4753 | argument count sixteen, and so on. | |
726f6388 JA |
4754 | .PD |
4755 | .SS Completing | |
4756 | .PP | |
4757 | .PD 0 | |
4758 | .TP | |
4759 | .B complete (TAB) | |
4760 | Attempt to perform completion on the text before point. | |
4761 | .B Bash | |
4762 | attempts completion treating the text as a variable (if the | |
4763 | text begins with \fB$\fP), username (if the text begins with | |
4764 | \fB~\fP), hostname (if the text begins with \fB@\fP), or | |
4765 | command (including aliases and functions) in turn. If none | |
4766 | of these produces a match, filename completion is attempted. | |
4767 | .TP | |
ccc6cda3 | 4768 | .B possible\-completions (M\-?) |
726f6388 JA |
4769 | List the possible completions of the text before point. |
4770 | .TP | |
ccc6cda3 | 4771 | .B insert\-completions (M\-*) |
726f6388 JA |
4772 | Insert all completions of the text before point |
4773 | that would have been generated by | |
ccc6cda3 | 4774 | \fBpossible\-completions\fP. |
726f6388 | 4775 | .TP |
cce855bc JA |
4776 | .B menu\-complete |
4777 | Similar to \fBcomplete\fP, but replaces the word to be completed | |
4778 | with a single match from the list of possible completions. | |
4779 | Repeated execution of \fBmenu\-complete\fP steps through the list | |
4780 | of possible completions, inserting each match in turn. | |
28ef6c31 | 4781 | At the end of the list of completions, the bell is rung |
f73dda09 | 4782 | (subject to the setting of \fBbell\-style\fP) |
28ef6c31 | 4783 | and the original text is restored. |
cce855bc JA |
4784 | An argument of \fIn\fP moves \fIn\fP positions forward in the list |
4785 | of matches; a negative argument may be used to move backward | |
4786 | through the list. | |
4787 | This command is intended to be bound to \fBTAB\fP, but is unbound | |
4788 | by default. | |
4789 | .TP | |
b72432fd JA |
4790 | .B delete\-char\-or\-list |
4791 | Deletes the character under the cursor if not at the beginning or | |
bb70624e | 4792 | end of the line (like \fBdelete\-char\fP). |
b72432fd | 4793 | If at the end of the line, behaves identically to |
bb70624e | 4794 | \fBpossible\-completions\fP. |
b72432fd JA |
4795 | This command is unbound by default. |
4796 | .TP | |
726f6388 JA |
4797 | .B complete\-filename (M\-/) |
4798 | Attempt filename completion on the text before point. | |
4799 | .TP | |
4800 | .B possible\-filename\-completions (C\-x /) | |
4801 | List the possible completions of the text before point, | |
4802 | treating it as a filename. | |
4803 | .TP | |
4804 | .B complete\-username (M\-~) | |
4805 | Attempt completion on the text before point, treating | |
4806 | it as a username. | |
4807 | .TP | |
4808 | .B possible\-username\-completions (C\-x ~) | |
4809 | List the possible completions of the text before point, | |
4810 | treating it as a username. | |
4811 | .TP | |
4812 | .B complete\-variable (M\-$) | |
4813 | Attempt completion on the text before point, treating | |
4814 | it as a shell variable. | |
4815 | .TP | |
4816 | .B possible\-variable\-completions (C\-x $) | |
4817 | List the possible completions of the text before point, | |
4818 | treating it as a shell variable. | |
4819 | .TP | |
4820 | .B complete\-hostname (M\-@) | |
4821 | Attempt completion on the text before point, treating | |
4822 | it as a hostname. | |
4823 | .TP | |
4824 | .B possible\-hostname\-completions (C\-x @) | |
4825 | List the possible completions of the text before point, | |
4826 | treating it as a hostname. | |
4827 | .TP | |
4828 | .B complete\-command (M\-!) | |
4829 | Attempt completion on the text before point, treating | |
4830 | it as a command name. Command completion attempts to | |
4831 | match the text against aliases, reserved words, shell | |
cce855bc | 4832 | functions, shell builtins, and finally executable filenames, |
726f6388 JA |
4833 | in that order. |
4834 | .TP | |
4835 | .B possible\-command\-completions (C\-x !) | |
4836 | List the possible completions of the text before point, | |
4837 | treating it as a command name. | |
4838 | .TP | |
ccc6cda3 | 4839 | .B dynamic\-complete\-history (M\-TAB) |
726f6388 JA |
4840 | Attempt completion on the text before point, comparing |
4841 | the text against lines from the history list for possible | |
4842 | completion matches. | |
4843 | .TP | |
4844 | .B complete\-into\-braces (M\-{) | |
bb70624e | 4845 | Perform filename completion and insert the list of possible completions |
726f6388 JA |
4846 | enclosed within braces so the list is available to the shell (see |
4847 | .B Brace Expansion | |
4848 | above). | |
4849 | .PD | |
4850 | .SS Keyboard Macros | |
4851 | .PP | |
4852 | .PD 0 | |
4853 | .TP | |
ccc6cda3 | 4854 | .B start\-kbd\-macro (C\-x (\^) |
726f6388 JA |
4855 | Begin saving the characters typed into the current keyboard macro. |
4856 | .TP | |
ccc6cda3 | 4857 | .B end\-kbd\-macro (C\-x )\^) |
726f6388 | 4858 | Stop saving the characters typed into the current keyboard macro |
ccc6cda3 | 4859 | and store the definition. |
726f6388 | 4860 | .TP |
ccc6cda3 | 4861 | .B call\-last\-kbd\-macro (C\-x e) |
726f6388 JA |
4862 | Re-execute the last keyboard macro defined, by making the characters |
4863 | in the macro appear as if typed at the keyboard. | |
4864 | .PD | |
4865 | .SS Miscellaneous | |
4866 | .PP | |
4867 | .PD 0 | |
4868 | .TP | |
4869 | .B re\-read\-init\-file (C\-x C\-r) | |
ccc6cda3 | 4870 | Read in the contents of the \fIinputrc\fP file, and incorporate |
726f6388 JA |
4871 | any bindings or variable assignments found there. |
4872 | .TP | |
4873 | .B abort (C\-g) | |
4874 | Abort the current editing command and | |
4875 | ring the terminal's bell (subject to the setting of | |
4876 | .BR bell\-style ). | |
4877 | .TP | |
ccc6cda3 JA |
4878 | .B do\-uppercase\-version (M\-a, M\-b, M\-\fIx\fP, ...) |
4879 | If the metafied character \fIx\fP is lowercase, run the command | |
4880 | that is bound to the corresponding uppercase character. | |
726f6388 JA |
4881 | .TP |
4882 | .B prefix\-meta (ESC) | |
4883 | Metafy the next character typed. | |
4884 | .SM | |
4885 | .B ESC | |
4886 | .B f | |
4887 | is equivalent to | |
4888 | .BR Meta\-f . | |
4889 | .TP | |
4890 | .B undo (C\-_, C\-x C\-u) | |
4891 | Incremental undo, separately remembered for each line. | |
4892 | .TP | |
4893 | .B revert\-line (M\-r) | |
cce855bc | 4894 | Undo all changes made to this line. This is like executing the |
726f6388 JA |
4895 | .B undo |
4896 | command enough times to return the line to its initial state. | |
4897 | .TP | |
b72432fd | 4898 | .B tilde\-expand (M\-&) |
726f6388 JA |
4899 | Perform tilde expansion on the current word. |
4900 | .TP | |
ccc6cda3 | 4901 | .B set\-mark (C\-@, M\-<space>) |
28ef6c31 | 4902 | Set the mark to the point. If a |
ccc6cda3 JA |
4903 | numeric argument is supplied, the mark is set to that position. |
4904 | .TP | |
4905 | .B exchange\-point\-and\-mark (C\-x C\-x) | |
4906 | Swap the point with the mark. The current cursor position is set to | |
4907 | the saved position, and the old cursor position is saved as the mark. | |
4908 | .TP | |
4909 | .B character\-search (C\-]) | |
4910 | A character is read and point is moved to the next occurrence of that | |
4911 | character. A negative count searches for previous occurrences. | |
4912 | .TP | |
4913 | .B character\-search\-backward (M\-C\-]) | |
4914 | A character is read and point is moved to the previous occurrence of that | |
4915 | character. A negative count searches for subsequent occurrences. | |
4916 | .TP | |
4917 | .B insert\-comment (M\-#) | |
bb70624e | 4918 | The value of the readline |
ccc6cda3 JA |
4919 | .B comment\-begin |
4920 | variable is inserted at the beginning of the current line, and the line | |
bb70624e JA |
4921 | is accepted as if a newline had been typed. The default value of |
4922 | \fBcomment\-begin\fP causes this command to make the current line | |
ccc6cda3 JA |
4923 | a shell comment. |
4924 | .TP | |
4925 | .B glob\-expand\-word (C\-x *) | |
4926 | The word before point is treated as a pattern for pathname expansion, | |
4927 | and the list of matching file names is inserted, replacing the word. | |
4928 | .TP | |
4929 | .B glob\-list\-expansions (C\-x g) | |
4930 | The list of expansions that would have been generated by | |
4931 | .B glob\-expand\-word | |
4932 | is displayed, and the line is redrawn. | |
4933 | .TP | |
726f6388 JA |
4934 | .B dump\-functions |
4935 | Print all of the functions and their key bindings to the | |
4936 | readline output stream. If a numeric argument is supplied, | |
4937 | the output is formatted in such a way that it can be made part | |
4938 | of an \fIinputrc\fP file. | |
4939 | .TP | |
ccc6cda3 JA |
4940 | .B dump\-variables |
4941 | Print all of the settable readline variables and their values to the | |
4942 | readline output stream. If a numeric argument is supplied, | |
4943 | the output is formatted in such a way that it can be made part | |
4944 | of an \fIinputrc\fP file. | |
4945 | .TP | |
4946 | .B dump\-macros | |
4947 | Print all of the readline key sequences bound to macros and the | |
4948 | strings they ouput. If a numeric argument is supplied, | |
4949 | the output is formatted in such a way that it can be made part | |
4950 | of an \fIinputrc\fP file. | |
4951 | .TP | |
726f6388 JA |
4952 | .B display\-shell\-version (C\-x C\-v) |
4953 | Display version information about the current instance of | |
4954 | .BR bash . | |
4955 | .PD | |
bb70624e JA |
4956 | .SS Programmable Completion |
4957 | .PP | |
4958 | When word completion is attempted for an argument to a command for | |
4959 | which a completion specification (a \fIcompspec\fP) has been defined | |
4960 | using the \fBcomplete\fP builtin (see | |
4961 | .SM | |
4962 | .B "SHELL BUILTIN COMMANDS" | |
4963 | below), the programmable completion facilities are invoked. | |
4964 | .PP | |
4965 | First, the command name is identified. | |
4966 | If a compspec has been defined for that command, the | |
4967 | compspec is used to generate the list of possible completions for the word. | |
4968 | If the command word is a full pathname, a compspec for the full | |
4969 | pathname is searched for first. | |
4970 | If no compspec is found for the full pathname, an attempt is made to | |
4971 | find a compspec for the portion following the final slash. | |
4972 | .PP | |
4973 | Once a compspec has been found, it is used to generate the list of | |
4974 | matching words. | |
4975 | If a compspec is not found, the default \fBbash\fP completion as | |
4976 | described above under \fBCompleting\fP is performed. | |
4977 | .PP | |
4978 | First, the actions specified by the compspec are used. | |
4979 | Only matches which are prefixed by the word being completed are | |
4980 | returned. | |
4981 | When the | |
4982 | .B \-f | |
4983 | or | |
4984 | .B \-d | |
4985 | option is used for filename or directory name completion, the shell | |
4986 | variable | |
4987 | .SM | |
4988 | .B FIGNORE | |
4989 | is used to filter the matches. | |
4990 | .PP | |
4991 | Any completions specified by a filename expansion pattern to the | |
4992 | \fB\-G\fP option are generated next. | |
4993 | The words generated by the pattern need not match the word | |
4994 | being completed. | |
4995 | The | |
4996 | .SM | |
4997 | .B GLOBIGNORE | |
4998 | shell variable is not used to filter the matches, but the | |
4999 | .SM | |
5000 | .B FIGNORE | |
5001 | variable is used. | |
5002 | .PP | |
5003 | Next, the string specified as the argument to the \fB\-W\fP option | |
5004 | is considered. | |
5005 | The string is first split using the characters in the | |
5006 | .SM | |
5007 | .B IFS | |
5008 | special variable as delimiters. | |
5009 | Shell quoting is honored. | |
5010 | Each word is then expanded using | |
5011 | brace expansion, tilde expansion, parameter and variable expansion, | |
5012 | command substitution, arithmetic expansion, and pathname expansion, | |
5013 | as described above under | |
5014 | .SM | |
5015 | .BR EXPANSION . | |
5016 | The results are split using the rules described above under | |
5017 | \fBWord Splitting\fP. | |
5018 | The results of the expansion are prefix-matched against the word being | |
5019 | completed, and the matching words become the possible completions. | |
5020 | .PP | |
5021 | After these matches have been generated, any shell function or command | |
5022 | specified with the \fB\-F\fP and \fB\-C\fP options is invoked. | |
5023 | When the command or function is invoked, the | |
5024 | .SM | |
5025 | .B COMP_LINE | |
5026 | and | |
5027 | .SM | |
5028 | .B COMP_POINT | |
5029 | variables are assigned values as described above under | |
5030 | \fBShell Variables\fP. | |
5031 | If a shell function is being invoked, the | |
5032 | .SM | |
5033 | .B COMP_WORDS | |
5034 | and | |
5035 | .SM | |
5036 | .B COMP_CWORD | |
5037 | variables are also set. | |
5038 | When the function or command is invoked, the first argument is the | |
5039 | name of the command whose arguments are being completed, the | |
5040 | second argument is the word being completed, and the third argument | |
5041 | is the word preceding the word being completed on the current command line. | |
5042 | No filtering of the generated completions against the word being completed | |
5043 | is performed; the function or command has complete freedom in generating | |
5044 | the matches. | |
5045 | .PP | |
5046 | Any function specified with \fB\-F\fP is invoked first. | |
5047 | The function may use any of the shell facilities, including the | |
5048 | \fBcompgen\fP builtin described below, to generate the matches. | |
5049 | It must put the possible completions in the | |
5050 | .SM | |
5051 | .B COMPREPLY | |
5052 | array variable. | |
5053 | .PP | |
5054 | Next, any command specified with the \fB\-C\fP option is invoked | |
5055 | in an environment equivalent to command substitution. | |
5056 | It should print a list of completions, one per line, to the | |
5057 | standard output. | |
5058 | Backslash may be used to escape a newline, if necessary. | |
5059 | .PP | |
5060 | After all of the possible completions are generated, any filter | |
5061 | specified with the \fB\-X\fP option is applied to the list. | |
5062 | The filter is a pattern as used for pathname expansion; a \fB&\fP | |
5063 | in the pattern is replaced with the text of the word being completed. | |
5064 | A literal \fB&\fP may be escaped with a backslash; the backslash | |
5065 | is removed before attempting a match. | |
5066 | Any completion that matches the pattern will be removed from the list. | |
5067 | A leading \fB!\fP negates the pattern; in this case any completion | |
5068 | not matching the pattern will be removed. | |
5069 | .PP | |
5070 | Finally, any prefix and suffix specified with the \fB\-P\fP and \fB\-S\fP | |
5071 | options are added to each member of the completion list, and the result is | |
5072 | returned to the readline completion code as the list of possible | |
5073 | completions. | |
5074 | .PP | |
28ef6c31 JA |
5075 | If the previously-applied actions do not generate any matches, and the |
5076 | \fB\-o dirnames\fP option was supplied to \fBcomplete\fP when the | |
5077 | compspec was defined, directory name completion is attempted. | |
5078 | .PP | |
5079 | By default, if a compspec is found, whatever it generates is returned | |
5080 | to the completion code as the full set of possible completions. | |
bb70624e JA |
5081 | The default \fBbash\fP completions are not attempted, and the readline |
5082 | default of filename completion is disabled. | |
28ef6c31 JA |
5083 | If the \fB-o default\fP option was supplied to \fBcomplete\fP when the |
5084 | compspec was defined, readline's default completion will be performed | |
5085 | if the compspec generates no matches. | |
726f6388 | 5086 | .SH HISTORY |
ccc6cda3 | 5087 | When the |
d166f048 | 5088 | .B \-o history |
ccc6cda3 JA |
5089 | option to the |
5090 | .B set | |
5091 | builtin is enabled, the shell provides access to the | |
5092 | \fIcommand history\fP, | |
bb70624e JA |
5093 | the list of commands previously typed. |
5094 | The value of the \fBHISTSIZE\fP variable is used as the | |
5095 | number of commands to save in a history list. | |
5096 | The text of the last | |
726f6388 JA |
5097 | .SM |
5098 | .B HISTSIZE | |
bb70624e | 5099 | commands (default 500) is saved. The shell |
726f6388 JA |
5100 | stores each command in the history list prior to parameter and |
5101 | variable expansion (see | |
5102 | .SM | |
5103 | .B EXPANSION | |
5104 | above) but after history expansion is performed, subject to the | |
5105 | values of the shell variables | |
ccc6cda3 JA |
5106 | .SM |
5107 | .B HISTIGNORE | |
726f6388 JA |
5108 | and |
5109 | .SM | |
5110 | .BR HISTCONTROL . | |
bb70624e | 5111 | .PP |
726f6388 JA |
5112 | On startup, the history is initialized from the file named by |
5113 | the variable | |
5114 | .SM | |
5115 | .B HISTFILE | |
5116 | (default \fI~/.bash_history\fP). | |
bb70624e | 5117 | The file named by the value of |
726f6388 JA |
5118 | .SM |
5119 | .B HISTFILE | |
5120 | is truncated, if necessary, to contain no more than | |
bb70624e | 5121 | the number of lines specified by the value of |
726f6388 | 5122 | .SM |
bb70624e | 5123 | .BR HISTFILESIZE . |
ccc6cda3 JA |
5124 | When an interactive shell exits, the last |
5125 | .SM | |
bb70624e | 5126 | .B $HISTSIZE |
ccc6cda3 JA |
5127 | lines are copied from the history list to |
5128 | .SM | |
bb70624e | 5129 | .BR $HISTFILE . |
ccc6cda3 JA |
5130 | If the |
5131 | .B histappend | |
5132 | shell option is enabled | |
5133 | (see the description of | |
5134 | .B shopt | |
5135 | under | |
5136 | .SM | |
5137 | .B "SHELL BUILTIN COMMANDS" | |
5138 | below), the lines are appended to the history file, | |
5139 | otherwise the history file is overwritten. | |
5140 | If | |
5141 | .SM | |
5142 | .B HISTFILE | |
5143 | is unset, or if the history file is unwritable, the history is | |
5144 | not saved. After saving the history, the history file is truncated | |
5145 | to contain no more than | |
5146 | .SM | |
5147 | .B HISTFILESIZE | |
5148 | lines. If | |
5149 | .SM | |
5150 | .B HISTFILESIZE | |
5151 | is not set, no truncation is performed. | |
5152 | .PP | |
726f6388 JA |
5153 | The builtin command |
5154 | .B fc | |
5155 | (see | |
5156 | .SM | |
5157 | .B SHELL BUILTIN COMMANDS | |
5158 | below) may be used to list or edit and re-execute a portion of | |
5159 | the history list. | |
5160 | The | |
5161 | .B history | |
bb70624e | 5162 | builtin may be used to display or modify the history list and |
ccc6cda3 | 5163 | manipulate the history file. |
bb70624e | 5164 | When using command-line editing, search commands |
726f6388 | 5165 | are available in each editing mode that provide access to the |
ccc6cda3 JA |
5166 | history list. |
5167 | .PP | |
5168 | The shell allows control over which commands are saved on the history | |
5169 | list. The | |
726f6388 | 5170 | .SM |
ccc6cda3 JA |
5171 | .B HISTCONTROL |
5172 | and | |
726f6388 | 5173 | .SM |
ccc6cda3 JA |
5174 | .B HISTIGNORE |
5175 | variables may be set to cause the shell to save only a subset of the | |
5176 | commands entered. | |
5177 | The | |
5178 | .B cmdhist | |
5179 | shell option, if enabled, causes the shell to attempt to save each | |
5180 | line of a multi-line command in the same history entry, adding | |
5181 | semicolons where necessary to preserve syntactic correctness. | |
5182 | The | |
5183 | .B lithist | |
5184 | shell option causes the shell to save the command with embedded newlines | |
5185 | instead of semicolons. See the description of the | |
5186 | .B shopt | |
5187 | builtin below under | |
5188 | .SM | |
5189 | .B "SHELL BUILTIN COMMANDS" | |
5190 | for information on setting and unsetting shell options. | |
726f6388 JA |
5191 | .SH "HISTORY EXPANSION" |
5192 | .PP | |
5193 | The shell supports a history expansion feature that | |
5194 | is similar to the history expansion in | |
5195 | .BR csh. | |
5196 | This section describes what syntax features are available. This | |
5197 | feature is enabled by default for interactive shells, and can be | |
5198 | disabled using the | |
5199 | .B \+H | |
5200 | option to the | |
5201 | .B set | |
5202 | builtin command (see | |
5203 | .SM | |
5204 | .B SHELL BUILTIN COMMANDS | |
ccc6cda3 JA |
5205 | below). Non-interactive shells do not perform history expansion |
5206 | by default. | |
5207 | .PP | |
5208 | History expansions introduce words from the history list into | |
5209 | the input stream, making it easy to repeat commands, insert the | |
5210 | arguments to a previous command into the current input line, or | |
5211 | fix errors in previous commands quickly. | |
726f6388 JA |
5212 | .PP |
5213 | History expansion is performed immediately after a complete line | |
5214 | is read, before the shell breaks it into words. | |
ccc6cda3 | 5215 | It takes place in two parts. |
cce855bc | 5216 | The first is to determine which line from the history list |
ccc6cda3 JA |
5217 | to use during substitution. |
5218 | The second is to select portions of that line for inclusion into | |
5219 | the current one. | |
cce855bc | 5220 | The line selected from the history is the \fIevent\fP, |
ccc6cda3 JA |
5221 | and the portions of that line that are acted upon are \fIwords\fP. |
5222 | Various \fImodifiers\fP are available to manipulate the selected words. | |
5223 | The line is broken into words in the same fashion as when reading input, | |
5224 | so that several \fImetacharacter\fP-separated words surrounded by | |
cce855bc | 5225 | quotes are considered one word. |
ccc6cda3 JA |
5226 | History expansions are introduced by the appearance of the |
5227 | history expansion character, which is \^\fB!\fP\^ by default. | |
5228 | Only backslash (\^\fB\e\fP\^) and single quotes can quote | |
5229 | the history expansion character. | |
5230 | .PP | |
5231 | Several shell options settable with the | |
5232 | .B shopt | |
5233 | builtin may be used to tailor the behavior of history expansion. | |
5234 | If the | |
5235 | .B histverify | |
5236 | shell option is enabled (see the description of the | |
5237 | .B shopt | |
5238 | builtin), and | |
5239 | .B readline | |
5240 | is being used, history substitutions are not immediately passed to | |
5241 | the shell parser. | |
5242 | Instead, the expanded line is reloaded into the | |
5243 | .B readline | |
5244 | editing buffer for further modification. | |
5245 | If | |
5246 | .B readline | |
5247 | is being used, and the | |
5248 | .B histreedit | |
5249 | shell option is enabled, a failed history substitution will be reloaded | |
5250 | into the | |
5251 | .B readline | |
5252 | editing buffer for correction. | |
5253 | The | |
5254 | .B \-p | |
5255 | option to the | |
5256 | .B history | |
5257 | builtin command may be used to see what a history expansion will | |
5258 | do before using it. | |
5259 | The | |
5260 | .B \-s | |
5261 | option to the | |
5262 | .B history | |
5263 | builtin may be used to add commands to the end of the history list | |
5264 | without actually executing them, so that they are available for | |
5265 | subsequent recall. | |
726f6388 JA |
5266 | .PP |
5267 | The shell allows control of the various characters used by the | |
5268 | history expansion mechanism (see the description of | |
5269 | .B histchars | |
5270 | above under | |
5271 | .BR "Shell Variables" ). | |
5272 | .SS Event Designators | |
5273 | .PP | |
5274 | An event designator is a reference to a command line entry in the | |
5275 | history list. | |
5276 | .PP | |
5277 | .PD 0 | |
5278 | .TP | |
5279 | .B ! | |
5280 | Start a history substitution, except when followed by a | |
5281 | .BR blank , | |
5282 | newline, = or (. | |
5283 | .TP | |
726f6388 JA |
5284 | .B !\fIn\fR |
5285 | Refer to command line | |
5286 | .IR n . | |
5287 | .TP | |
5288 | .B !\-\fIn\fR | |
5289 | Refer to the current command line minus | |
5290 | .IR n . | |
5291 | .TP | |
ccc6cda3 JA |
5292 | .B !! |
5293 | Refer to the previous command. This is a synonym for `!\-1'. | |
5294 | .TP | |
726f6388 JA |
5295 | .B !\fIstring\fR |
5296 | Refer to the most recent command starting with | |
5297 | .IR string . | |
5298 | .TP | |
5299 | .B !?\fIstring\fR\fB[?]\fR | |
5300 | Refer to the most recent command containing | |
5301 | .IR string . | |
ccc6cda3 JA |
5302 | The trailing \fB?\fP may be omitted if |
5303 | .I string | |
5304 | is followed immediately by a newline. | |
726f6388 JA |
5305 | .TP |
5306 | .B \d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u | |
5307 | Quick substitution. Repeat the last command, replacing | |
5308 | .I string1 | |
5309 | with | |
5310 | .IR string2 . | |
5311 | Equivalent to | |
5312 | ``!!:s/\fIstring1\fP/\fIstring2\fP/'' | |
5313 | (see \fBModifiers\fP below). | |
5314 | .TP | |
5315 | .B !# | |
5316 | The entire command line typed so far. | |
5317 | .PD | |
5318 | .SS Word Designators | |
5319 | .PP | |
ccc6cda3 | 5320 | Word designators are used to select desired words from the event. |
726f6388 JA |
5321 | A |
5322 | .B : | |
ccc6cda3 | 5323 | separates the event specification from the word designator. |
cce855bc | 5324 | It may be omitted if the word designator begins with a |
726f6388 JA |
5325 | .BR ^ , |
5326 | .BR $ , | |
5327 | .BR * , | |
ccc6cda3 | 5328 | .BR \- , |
726f6388 JA |
5329 | or |
5330 | .BR % . | |
5331 | Words are numbered from the beginning of the line, | |
ccc6cda3 JA |
5332 | with the first word being denoted by 0 (zero). |
5333 | Words are inserted into the current line separated by single spaces. | |
726f6388 JA |
5334 | .PP |
5335 | .PD 0 | |
5336 | .TP | |
5337 | .B 0 (zero) | |
5338 | The zeroth word. For the shell, this is the command | |
5339 | word. | |
5340 | .TP | |
5341 | .I n | |
5342 | The \fIn\fRth word. | |
5343 | .TP | |
5344 | .B ^ | |
5345 | The first argument. That is, word 1. | |
5346 | .TP | |
5347 | .B $ | |
5348 | The last argument. | |
5349 | .TP | |
5350 | .B % | |
5351 | The word matched by the most recent `?\fIstring\fR?' search. | |
5352 | .TP | |
5353 | .I x\fB\-\fPy | |
5354 | A range of words; `\-\fIy\fR' abbreviates `0\-\fIy\fR'. | |
5355 | .TP | |
5356 | .B * | |
5357 | All of the words but the zeroth. This is a synonym | |
5358 | for `\fI1\-$\fP'. It is not an error to use | |
5359 | .B * | |
5360 | if there is just one | |
5361 | word in the event; the empty string is returned in that case. | |
5362 | .TP | |
5363 | .B x* | |
5364 | Abbreviates \fIx\-$\fP. | |
5365 | .TP | |
5366 | .B x\- | |
5367 | Abbreviates \fIx\-$\fP like \fBx*\fP, but omits the last word. | |
5368 | .PD | |
ccc6cda3 JA |
5369 | .PP |
5370 | If a word designator is supplied without an event specification, the | |
5371 | previous command is used as the event. | |
726f6388 JA |
5372 | .SS Modifiers |
5373 | .PP | |
ccc6cda3 JA |
5374 | After the optional word designator, there may appear a sequence of |
5375 | one or more of the following modifiers, each preceded by a `:'. | |
726f6388 JA |
5376 | .PP |
5377 | .PD 0 | |
5378 | .PP | |
5379 | .TP | |
5380 | .B h | |
ccc6cda3 JA |
5381 | Remove a trailing file name component, leaving only the head. |
5382 | .TP | |
5383 | .B t | |
5384 | Remove all leading file name components, leaving the tail. | |
726f6388 JA |
5385 | .TP |
5386 | .B r | |
5387 | Remove a trailing suffix of the form \fI.xxx\fP, leaving the | |
5388 | basename. | |
5389 | .TP | |
5390 | .B e | |
5391 | Remove all but the trailing suffix. | |
5392 | .TP | |
726f6388 JA |
5393 | .B p |
5394 | Print the new command but do not execute it. | |
5395 | .TP | |
5396 | .B q | |
5397 | Quote the substituted words, escaping further substitutions. | |
5398 | .TP | |
cce855bc JA |
5399 | .B x |
5400 | Quote the substituted words as with | |
5401 | .BR q , | |
5402 | but break into words at | |
5403 | .B blanks | |
5404 | and newlines. | |
726f6388 | 5405 | .TP |
cce855bc JA |
5406 | .B s/\fIold\fP/\fInew\fP/ |
5407 | Substitute | |
5408 | .I new | |
5409 | for the first occurrence of | |
5410 | .I old | |
5411 | in the event line. Any delimiter can be used in place of /. The | |
5412 | final delimiter is optional if it is the last character of the | |
5413 | event line. The delimiter may be quoted in | |
5414 | .I old | |
5415 | and | |
5416 | .I new | |
5417 | with a single backslash. If & appears in | |
5418 | .IR new , | |
5419 | it is replaced by | |
5420 | .IR old . | |
5421 | A single backslash will quote the &. If | |
5422 | .I old | |
5423 | is null, it is set to the last | |
5424 | .I old | |
5425 | substituted, or, if no previous history substitutions took place, | |
5426 | the last | |
5427 | .I string | |
5428 | in a | |
5429 | .B !?\fIstring\fR\fB[?]\fR | |
5430 | search. | |
ccc6cda3 | 5431 | .TP |
cce855bc JA |
5432 | .B & |
5433 | Repeat the previous substitution. | |
5434 | .TP | |
5435 | .B g | |
5436 | Cause changes to be applied over the entire event line. This is | |
5437 | used in conjunction with `\fB:s\fP' (e.g., `\fB:gs/\fIold\fP/\fInew\fP/\fR') | |
5438 | or `\fB:&\fP'. If used with | |
5439 | `\fB:s\fP', any delimiter can be used | |
5440 | in place of /, and the final delimiter is optional | |
5441 | if it is the last character of the event line. | |
726f6388 | 5442 | .PD |
726f6388 JA |
5443 | .SH "SHELL BUILTIN COMMANDS" |
5444 | .\" start of bash_builtins | |
5445 | .zZ | |
ccc6cda3 JA |
5446 | .PP |
5447 | Unless otherwise noted, each builtin command documented in this | |
5448 | section as accepting options preceded by | |
5449 | .B \- | |
5450 | accepts | |
5451 | .B \-\- | |
5452 | to signify the end of the options. | |
5453 | .sp .5 | |
726f6388 JA |
5454 | .PD 0 |
5455 | .TP | |
5456 | \fB:\fP [\fIarguments\fP] | |
5457 | .PD | |
5458 | No effect; the command does nothing beyond expanding | |
5459 | .I arguments | |
5460 | and performing any specified | |
5461 | redirections. A zero exit code is returned. | |
5462 | .TP | |
5463 | .PD 0 | |
5464 | \fB .\| \fP \fIfilename\fP [\fIarguments\fP] | |
5465 | .TP | |
5466 | \fBsource\fP \fIfilename\fP [\fIarguments\fP] | |
5467 | .PD | |
5468 | Read and execute commands from | |
5469 | .I filename | |
5470 | in the current | |
5471 | shell environment and return the exit status of the last command | |
5472 | executed from | |
5473 | .IR filename . | |
5474 | If | |
5475 | .I filename | |
ccc6cda3 | 5476 | does not contain a slash, file names in |
726f6388 JA |
5477 | .SM |
5478 | .B PATH | |
5479 | are used to find the directory containing | |
5480 | .IR filename . | |
5481 | The file searched for in | |
5482 | .SM | |
5483 | .B PATH | |
28ef6c31 JA |
5484 | need not be executable. |
5485 | When \fBbash\fP is not in \fIposix mode\fP, the current directory is | |
726f6388 JA |
5486 | searched if no file is found in |
5487 | .SM | |
5488 | .BR PATH . | |
ccc6cda3 JA |
5489 | If the |
5490 | .B sourcepath | |
5491 | option to the | |
5492 | .B shopt | |
5493 | builtin command is turned off, the | |
5494 | .SM | |
5495 | .B PATH | |
5496 | is not searched. | |
726f6388 | 5497 | If any \fIarguments\fP are supplied, they become the positional |
ccc6cda3 | 5498 | parameters when \fIfilename\fP is executed. Otherwise the positional |
726f6388 JA |
5499 | parameters are unchanged. |
5500 | The return status is the status of the last command exited within | |
5501 | the script (0 if no commands are executed), and false if | |
5502 | .I filename | |
cce855bc | 5503 | is not found or cannot be read. |
726f6388 | 5504 | .TP |
ccc6cda3 JA |
5505 | \fBalias\fP [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...] |
5506 | \fBAlias\fP with no arguments or with the | |
5507 | .B \-p | |
5508 | option prints the list of aliases in the form | |
5509 | \fBalias\fP \fIname\fP=\fIvalue\fP on standard output. | |
5510 | When arguments are supplied, an alias is defined for | |
5511 | each \fIname\fP whose \fIvalue\fP is given. | |
5512 | A trailing space in \fIvalue\fP causes the next word to be | |
5513 | checked for alias substitution when the alias is expanded. | |
5514 | For each \fIname\fP in the argument list for which no \fIvalue\fP | |
5515 | is supplied, the name and value of the alias is printed. | |
5516 | \fBAlias\fP returns true unless a \fIname\fP is given for which | |
5517 | no alias has been defined. | |
726f6388 JA |
5518 | .TP |
5519 | \fBbg\fP [\fIjobspec\fP] | |
cce855bc JA |
5520 | Resume the suspended job \fIjobspec\fP in the background, as if it |
5521 | had been started with | |
726f6388 JA |
5522 | .BR & . |
5523 | If \fIjobspec\fP is not present, the shell's notion of the | |
5524 | \fIcurrent job\fP is used. | |
5525 | .B bg | |
5526 | .I jobspec | |
5527 | returns 0 unless run when job control is disabled or, when run with | |
5528 | job control enabled, if \fIjobspec\fP was not found or started without | |
5529 | job control. | |
5530 | .TP | |
5531 | .PD 0 | |
cce855bc JA |
5532 | \fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-lpsvPSV\fP] |
5533 | .TP | |
5534 | \fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-q\fP \fIfunction\fP] [\fB\-u\fP \fIfunction\fP] [\fB\-r\fP \fIkeyseq\fP] | |
726f6388 | 5535 | .TP |
ccc6cda3 | 5536 | \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB\-f\fP \fIfilename\fP |
726f6388 | 5537 | .TP |
bb70624e JA |
5538 | \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB\-x\fP \fIkeyseq\fP:\fIshell\-command\fP |
5539 | .TP | |
ccc6cda3 | 5540 | \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fIkeyseq\fP:\fIfunction\-name\fP |
726f6388 JA |
5541 | .PD |
5542 | Display current | |
5543 | .B readline | |
5544 | key and function bindings, or bind a key sequence to a | |
5545 | .B readline | |
5546 | function or macro. The binding syntax accepted is identical to that of | |
5547 | .IR .inputrc , | |
5548 | but each binding must be passed as a separate argument; | |
ccc6cda3 | 5549 | e.g., '"\eC\-x\eC\-r": re\-read\-init\-file'. Options, if supplied, have the |
726f6388 JA |
5550 | following meanings: |
5551 | .RS | |
5552 | .PD 0 | |
5553 | .TP | |
5554 | .B \-m \fIkeymap\fP | |
5555 | Use | |
5556 | .I keymap | |
5557 | as the keymap to be affected by the subsequent bindings. | |
5558 | Acceptable | |
5559 | .I keymap | |
5560 | names are | |
ccc6cda3 | 5561 | \fIemacs, emacs\-standard, emacs\-meta, emacs\-ctlx, vi, |
28ef6c31 | 5562 | vi\-move, vi\-command\fP, and |
ccc6cda3 JA |
5563 | .IR vi\-insert . |
5564 | \fIvi\fP is equivalent to \fIvi\-command\fP; \fIemacs\fP is | |
5565 | equivalent to \fIemacs\-standard\fP. | |
726f6388 JA |
5566 | .TP |
5567 | .B \-l | |
ccc6cda3 JA |
5568 | List the names of all \fBreadline\fP functions. |
5569 | .TP | |
5570 | .B \-p | |
5571 | Display \fBreadline\fP function names and bindings in such a way | |
5572 | that they can be re-read. | |
5573 | .TP | |
5574 | .B \-P | |
5575 | List current \fBreadline\fP function names and bindings. | |
726f6388 JA |
5576 | .TP |
5577 | .B \-v | |
ccc6cda3 JA |
5578 | Display \fBreadline\fP variable names and values in such a way that they |
5579 | can be re-read. | |
726f6388 | 5580 | .TP |
ccc6cda3 JA |
5581 | .B \-V |
5582 | List current \fBreadline\fP variable names and values. | |
5583 | .TP | |
5584 | .B \-s | |
5585 | Display \fBreadline\fP key sequences bound to macros and the strings | |
5586 | they output in such a way that they can be re-read. | |
5587 | .TP | |
5588 | .B \-S | |
5589 | Display \fBreadline\fP key sequences bound to macros and the strings | |
5590 | they output. | |
726f6388 JA |
5591 | .TP |
5592 | .B \-f \fIfilename\fP | |
ccc6cda3 | 5593 | Read key bindings from \fIfilename\fP. |
726f6388 JA |
5594 | .TP |
5595 | .B \-q \fIfunction\fP | |
ccc6cda3 JA |
5596 | Query about which keys invoke the named \fIfunction\fP. |
5597 | .TP | |
cce855bc JA |
5598 | .B \-u \fIfunction\fP |
5599 | Unbind all keys bound to the named \fIfunction\fP. | |
5600 | .TP | |
ccc6cda3 JA |
5601 | .B \-r \fIkeyseq\fP |
5602 | Remove any current binding for \fIkeyseq\fP. | |
bb70624e JA |
5603 | .TP |
5604 | .B \-x \fIkeyseq\fP:\fIshell\-command\fP | |
5605 | Cause \fIshell\-command\fP to be executed whenever \fIkeyseq\fP is | |
5606 | entered. | |
726f6388 JA |
5607 | .PD |
5608 | .PP | |
5609 | The return value is 0 unless an unrecognized option is given or an | |
5610 | error occurred. | |
5611 | .RE | |
5612 | .TP | |
5613 | \fBbreak\fP [\fIn\fP] | |
5614 | Exit from within a | |
5615 | .BR for , | |
5616 | .BR while , | |
ccc6cda3 | 5617 | .BR until , |
726f6388 | 5618 | or |
ccc6cda3 | 5619 | .B select |
726f6388 JA |
5620 | loop. If \fIn\fP is specified, break \fIn\fP levels. |
5621 | .I n | |
5622 | must be \(>= 1. If | |
5623 | .I n | |
5624 | is greater than the number of enclosing loops, all enclosing loops | |
5625 | are exited. The return value is 0 unless the shell is not executing | |
5626 | a loop when | |
5627 | .B break | |
5628 | is executed. | |
5629 | .TP | |
5630 | \fBbuiltin\fP \fIshell\-builtin\fP [\fIarguments\fP] | |
5631 | Execute the specified shell builtin, passing it | |
5632 | .IR arguments , | |
5633 | and return its exit status. | |
cce855bc | 5634 | This is useful when defining a |
726f6388 | 5635 | function whose name is the same as a shell builtin, |
cce855bc JA |
5636 | retaining the functionality of the builtin within the function. |
5637 | The \fBcd\fP builtin is commonly redefined this way. | |
5638 | The return status is false if | |
726f6388 JA |
5639 | .I shell\-builtin |
5640 | is not a shell builtin command. | |
5641 | .TP | |
ccc6cda3 | 5642 | \fBcd\fP [\fB\-LP\fP] [\fIdir\fP] |
726f6388 JA |
5643 | Change the current directory to \fIdir\fP. The variable |
5644 | .SM | |
5645 | .B HOME | |
5646 | is the | |
5647 | default | |
5648 | .IR dir . | |
5649 | The variable | |
5650 | .SM | |
5651 | .B CDPATH | |
ccc6cda3 | 5652 | defines the search path for the directory containing |
726f6388 | 5653 | .IR dir . |
ccc6cda3 JA |
5654 | Alternative directory names in |
5655 | .SM | |
5656 | .B CDPATH | |
5657 | are separated by a colon (:). A null directory name in | |
726f6388 JA |
5658 | .SM |
5659 | .B CDPATH | |
ccc6cda3 | 5660 | is the same as the current directory, i.e., ``\fB.\fP''. If |
726f6388 JA |
5661 | .I dir |
5662 | begins with a slash (/), | |
5663 | then | |
5664 | .SM | |
5665 | .B CDPATH | |
ccc6cda3 JA |
5666 | is not used. The |
5667 | .B \-P | |
5668 | option says to use the physical directory structure instead of | |
5669 | following symbolic links (see also the | |
5670 | .B \-P | |
5671 | option to the | |
5672 | .B set | |
5673 | builtin command); the | |
5674 | .B \-L | |
5675 | option forces symbolic links to be followed. An argument of | |
726f6388 JA |
5676 | .B \- |
5677 | is equivalent to | |
5678 | .SM | |
5679 | .BR $OLDPWD . | |
5680 | The return value is true if the directory was successfully changed; | |
5681 | false otherwise. | |
5682 | .TP | |
ccc6cda3 | 5683 | \fBcommand\fP [\fB\-pVv\fP] \fIcommand\fP [\fIarg\fP ...] |
726f6388 JA |
5684 | Run |
5685 | .I command | |
5686 | with | |
5687 | .I args | |
5688 | suppressing the normal shell function lookup. Only builtin | |
5689 | commands or commands found in the | |
5690 | .SM | |
5691 | .B PATH | |
5692 | are executed. If the | |
5693 | .B \-p | |
5694 | option is given, the search for | |
5695 | .I command | |
5696 | is performed using a default value for | |
5697 | .B PATH | |
5698 | that is guaranteed to find all of the standard utilities. | |
5699 | If either the | |
5700 | .B \-V | |
5701 | or | |
5702 | .B \-v | |
5703 | option is supplied, a description of | |
5704 | .I command | |
5705 | is printed. The | |
5706 | .B \-v | |
ccc6cda3 | 5707 | option causes a single word indicating the command or file name |
726f6388 JA |
5708 | used to invoke |
5709 | .I command | |
cce855bc | 5710 | to be displayed; the |
726f6388 JA |
5711 | .B \-V |
5712 | option produces a more verbose description. | |
726f6388 JA |
5713 | If the |
5714 | .B \-V | |
5715 | or | |
5716 | .B \-v | |
5717 | option is supplied, the exit status is 0 if | |
5718 | .I command | |
5719 | was found, and 1 if not. If neither option is supplied and | |
5720 | an error occurred or | |
5721 | .I command | |
5722 | cannot be found, the exit status is 127. Otherwise, the exit status of the | |
5723 | .B command | |
5724 | builtin is the exit status of | |
5725 | .IR command . | |
5726 | .TP | |
bb70624e JA |
5727 | \fBcompgen\fP [\fIoption\fP] [\fIword\fP] |
5728 | Generate possible completion matches for \fIword\fP according to | |
5729 | the \fIoption\fPs, which may be any option accepted by the | |
5730 | .B complete | |
5731 | builtin with the exception of \fB\-p\fP and \fB\-r\fP, and write | |
5732 | the matches to the standard output. | |
5733 | When using the \fB\-F\fP or \fB\-C\fP options, the various shell variables | |
5734 | set by the programmable completion facilities, while available, will not | |
5735 | have useful values. | |
5736 | .sp 1 | |
5737 | The matches will be generated in the same way as if the programmable | |
5738 | completion code had generated them directly from a completion specification | |
5739 | with the same flags. | |
5740 | If \fIword\fP is specified, only those completions matching \fIword\fP | |
5741 | will be displayed. | |
5742 | .sp 1 | |
5743 | The return value is true unless an invalid option is supplied, or no | |
5744 | matches were generated. | |
5745 | .TP | |
5746 | .PD 0 | |
f73dda09 | 5747 | \fBcomplete\fP [\fB\-abcdefgjkvu\fP] [\fB\-o\fP \fIcomp-option\fP] [\fB\-A\fP \fIaction\fP] [\fB\-G\fP \fIglobpat\fP] [\fB\-W\fP \fIwordlist\fP] [\fB\-P\fP \fIprefix\fP] [\fB\-S\fP \fIsuffix\fP] |
bb70624e JA |
5748 | .br |
5749 | [\fB\-X\fP \fIfilterpat\fP] [\fB\-F\fP \fIfunction\fP] [\fB\-C\fP \fIcommand\fP] \fIname\fP [\fIname ...\fP] | |
5750 | .TP | |
5751 | \fBcomplete\fP \fB\-pr\fP [\fIname\fP ...] | |
5752 | .PD | |
5753 | Specify how arguments to each \fIname\fP should be completed. | |
5754 | If the \fB\-p\fP option is supplied, or if no options are supplied, | |
5755 | existing completion specifications are printed in a way that allows | |
5756 | them to be reused as input. | |
5757 | The \fB\-r\fP option removes a completion specification for | |
5758 | each \fIname\fP, or, if no \fIname\fPs are supplied, all | |
5759 | completion specifications. | |
5760 | .sp 1 | |
5761 | The process of applying these completion specifications when word completion | |
5762 | is attempted is described above under \fBProgrammable Completion\fP. | |
5763 | .sp 1 | |
5764 | Other options, if specified, have the following meanings. | |
5765 | The arguments to the \fB\-G\fP, \fB\-W\fP, and \fB\-X\fP options | |
5766 | (and, if necessary, the \fB\-P\fP and \fB\-S\fP options) | |
5767 | should be quoted to protect them from expansion before the | |
5768 | .B complete | |
5769 | builtin is invoked. | |
5770 | .RS | |
5771 | .PD 0 | |
5772 | .TP 8 | |
28ef6c31 JA |
5773 | \fB\-o\fP \fIcomp-option\fP |
5774 | The \fIcomp-option\fP controls several aspects of the compspec's behavior | |
5775 | beyond the simple generation of completions. | |
5776 | \fIcomp-option\fP may be one of: | |
5777 | .RS | |
5778 | .TP 8 | |
5779 | .B default | |
5780 | Use readline's default completion if the compspec generates no matches. | |
5781 | .TP 8 | |
5782 | .B dirnames | |
5783 | Perform directory name completion if the compspec generates no matches. | |
5784 | .TP 8 | |
5785 | .B filenames | |
5786 | Tell readline that the compspec generates filenames, so it can perform any | |
5787 | filename\-specific processing (like adding a slash to directory names or | |
5788 | suppressing trailing spaces). Intended to be used with shell functions. | |
5789 | .RE | |
5790 | .TP 8 | |
bb70624e JA |
5791 | \fB\-A\fP \fIaction\fP |
5792 | The \fIaction\fP may be one of the following to generate a list of possible | |
5793 | completions: | |
5794 | .RS | |
5795 | .TP 8 | |
5796 | .B alias | |
5797 | Alias names. May also be specified as \fB\-a\fP. | |
5798 | .TP 8 | |
5799 | .B arrayvar | |
5800 | Array variable names. | |
5801 | .TP 8 | |
5802 | .B binding | |
5803 | \fBReadline\fP key binding names. | |
5804 | .TP 8 | |
5805 | .B builtin | |
5806 | Names of shell builtin commands. May also be specified as \fB\-b\fP. | |
5807 | .TP 8 | |
5808 | .B command | |
5809 | Command names. May also be specified as \fB\-c\fP. | |
5810 | .TP 8 | |
5811 | .B directory | |
5812 | Directory names. May also be specified as \fB\-d\fP. | |
5813 | .TP 8 | |
5814 | .B disabled | |
5815 | Names of disabled shell builtins. | |
5816 | .TP 8 | |
5817 | .B enabled | |
5818 | Names of enabled shell builtins. | |
5819 | .TP 8 | |
5820 | .B export | |
5821 | Names of exported shell variables. May also be specified as \fB\-e\fP. | |
5822 | .TP 8 | |
5823 | .B file | |
5824 | File names. May also be specified as \fB\-f\fP. | |
5825 | .TP 8 | |
5826 | .B function | |
5827 | Names of shell functions. | |
5828 | .TP 8 | |
f73dda09 JA |
5829 | .B group |
5830 | Group names. May also be specified as \fB\-g\fP. | |
5831 | .TP 8 | |
bb70624e JA |
5832 | .B helptopic |
5833 | Help topics as accepted by the \fBhelp\fP builtin. | |
5834 | .TP 8 | |
5835 | .B hostname | |
5836 | Hostnames, as taken from the file specified by the | |
5837 | .SM | |
5838 | .B HOSTFILE | |
5839 | shell variable. | |
5840 | .TP 8 | |
5841 | .B job | |
5842 | Job names, if job control is active. May also be specified as \fB\-j\fP. | |
5843 | .TP 8 | |
5844 | .B keyword | |
5845 | Shell reserved words. May also be specified as \fB\-k\fP. | |
5846 | .TP 8 | |
5847 | .B running | |
5848 | Names of running jobs, if job control is active. | |
5849 | .TP 8 | |
5850 | .B setopt | |
5851 | Valid arguments for the \fB\-o\fP option to the \fBset\fP builtin. | |
5852 | .TP 8 | |
5853 | .B shopt | |
5854 | Shell option names as accepted by the \fBshopt\fP builtin. | |
5855 | .TP 8 | |
5856 | .B signal | |
5857 | Signal names. | |
5858 | .TP 8 | |
5859 | .B stopped | |
5860 | Names of stopped jobs, if job control is active. | |
5861 | .TP 8 | |
5862 | .B user | |
5863 | User names. May also be specified as \fB\-u\fP. | |
5864 | .TP 8 | |
5865 | .B variable | |
5866 | Names of all shell variables. May also be specified as \fB\-v\fP. | |
5867 | .RE | |
5868 | .TP 8 | |
5869 | \fB\-G\fP \fIglobpat\fP | |
5870 | The filename expansion pattern \fIglobpat\fP is expanded to generate | |
5871 | the possible completions. | |
5872 | .TP 8 | |
5873 | \fB\-W\fP \fIwordlist\fP | |
5874 | The \fIwordlist\fP is split using the characters in the | |
5875 | .SM | |
5876 | .B IFS | |
5877 | special variable as delimiters, and each resultant word is expanded. | |
5878 | The possible completions are the members of the resultant list which | |
5879 | match the word being completed. | |
5880 | .TP 8 | |
5881 | \fB\-C\fP \fIcommand\fP | |
5882 | \fIcommand\fP is executed in a subshell environment, and its output is | |
5883 | used as the possible completions. | |
5884 | .TP 8 | |
5885 | \fB\-F\fP \fIfunction\fP | |
5886 | The shell function \fIfunction\fP is executed in the current shell | |
5887 | environment. | |
5888 | When it finishes, the possible completions are retrieved from the value | |
5889 | of the | |
5890 | .SM | |
5891 | .B COMPREPLY | |
5892 | array variable. | |
5893 | .TP 8 | |
5894 | \fB\-X\fP \fIfilterpat\fP | |
5895 | \fIfilterpat\fP is a pattern as used for filename expansion. | |
5896 | It is applied to the list of possible completions generated by the | |
5897 | preceding options and arguments, and each completion matching | |
5898 | \fIfilterpat\fP is removed from the list. | |
5899 | A leading \fB!\fP in \fIfilterpat\fP negates the pattern; in this | |
5900 | case, any completion not matching \fIfilterpat\fP is removed. | |
5901 | .TP 8 | |
5902 | \fB\-P\fP \fIprefix\fP | |
5903 | \fIprefix\fP is added at the beginning of each possible completion | |
5904 | after all other options have been applied. | |
5905 | .TP 8 | |
5906 | \fB\-S\fP \fIsuffix\fP | |
5907 | \fIsuffix\fP is appended to each possible completion | |
5908 | after all other options have been applied. | |
5909 | .PD | |
5910 | .PP | |
5911 | The return value is true unless an invalid option is supplied, an option | |
5912 | other than \fB\-p\fP or \fB\-r\fP is supplied without a \fIname\fP | |
5913 | argument, an attempt is made to remove a completion specification for | |
5914 | a \fIname\fP for which no specification exists, or | |
5915 | an error occurs adding a completion specification. | |
5916 | .RE | |
5917 | .TP | |
726f6388 JA |
5918 | \fBcontinue\fP [\fIn\fP] |
5919 | Resume the next iteration of the enclosing | |
5920 | .BR for , | |
5921 | .BR while , | |
ccc6cda3 | 5922 | .BR until , |
726f6388 | 5923 | or |
ccc6cda3 | 5924 | .B select |
726f6388 JA |
5925 | loop. |
5926 | If | |
5927 | .I n | |
5928 | is specified, resume at the \fIn\fPth enclosing loop. | |
5929 | .I n | |
5930 | must be \(>= 1. If | |
5931 | .I n | |
5932 | is greater than the number of enclosing loops, the last enclosing loop | |
ccc6cda3 | 5933 | (the ``top-level'' loop) is resumed. The return value is 0 unless the |
726f6388 JA |
5934 | shell is not executing a loop when |
5935 | .B continue | |
5936 | is executed. | |
5937 | .TP | |
5938 | .PD 0 | |
ccc6cda3 | 5939 | \fBdeclare\fP [\fB\-afFirx\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP]] |
726f6388 | 5940 | .TP |
ccc6cda3 | 5941 | \fBtypeset\fP [\fB\-afFirx\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP]] |
726f6388 | 5942 | .PD |
ccc6cda3 JA |
5943 | Declare variables and/or give them attributes. |
5944 | If no \fIname\fPs are given then display the values of variables. | |
5945 | The | |
5946 | .B \-p | |
5947 | option will display the attributes and values of each | |
5948 | .IR name . | |
5949 | When | |
5950 | .B \-p | |
5951 | is used, additional options are ignored. | |
5952 | The | |
5953 | .B \-F | |
5954 | option inhibits the display of function definitions; only the | |
5955 | function name and attributes are printed. | |
5956 | The | |
5957 | .B \-F | |
5958 | option implies | |
5959 | .BR \-f . | |
5960 | The following options can | |
5961 | be used to restrict output to variables with the specified attribute or | |
5962 | to give variables attributes: | |
726f6388 JA |
5963 | .RS |
5964 | .PD 0 | |
5965 | .TP | |
ccc6cda3 JA |
5966 | .B \-a |
5967 | Each \fIname\fP is an array variable (see | |
5968 | .B Arrays | |
5969 | above). | |
5970 | .TP | |
726f6388 | 5971 | .B \-f |
ccc6cda3 JA |
5972 | Use function names only. |
5973 | .TP | |
5974 | .B \-i | |
5975 | The variable is treated as an integer; arithmetic evaluation (see | |
5976 | .SM | |
5977 | .B "ARITHMETIC EVALUATION" ") " | |
5978 | is performed when the variable is assigned a value. | |
726f6388 JA |
5979 | .TP |
5980 | .B \-r | |
5981 | Make \fIname\fPs readonly. These names cannot then be assigned values | |
cce855bc | 5982 | by subsequent assignment statements or unset. |
726f6388 JA |
5983 | .TP |
5984 | .B \-x | |
5985 | Mark \fIname\fPs for export to subsequent commands via the environment. | |
726f6388 JA |
5986 | .PD |
5987 | .PP | |
5988 | Using `+' instead of `\-' | |
ccc6cda3 JA |
5989 | turns off the attribute instead, with the exception that \fB+a\fP |
5990 | may not be used to destroy an array variable. When used in a function, | |
5991 | makes each | |
5992 | \fIname\fP local, as with the | |
726f6388 | 5993 | .B local |
cce855bc | 5994 | command. The return value is 0 unless an invalid option is encountered, |
bb70624e JA |
5995 | an attempt is made to define a function using |
5996 | .if n ``\-f foo=bar'', | |
5997 | .if t \f(CW\-f foo=bar\fP, | |
ccc6cda3 JA |
5998 | an attempt is made to assign a value to a readonly variable, |
5999 | an attempt is made to assign a value to an array variable without | |
6000 | using the compound assignment syntax (see | |
6001 | .B Arrays | |
cce855bc | 6002 | above), one of the \fInames\fP is not a valid shell variable name, |
726f6388 | 6003 | an attempt is made to turn off readonly status for a readonly variable, |
ccc6cda3 | 6004 | an attempt is made to turn off array status for an array variable, |
bb70624e | 6005 | or an attempt is made to display a non-existent function with \fB\-f\fP. |
726f6388 JA |
6006 | .RE |
6007 | .TP | |
ccc6cda3 JA |
6008 | .B dirs [\fB\-clpv\fP] [+\fIn\fP] [\-\fIn\fP] |
6009 | Without options, displays the list of currently remembered directories. | |
6010 | The default display is on a single line with directory names separated | |
6011 | by spaces. | |
6012 | Directories are added to the list with the | |
726f6388 JA |
6013 | .B pushd |
6014 | command; the | |
6015 | .B popd | |
ccc6cda3 | 6016 | command removes entries from the list. |
726f6388 JA |
6017 | .RS |
6018 | .PD 0 | |
6019 | .TP | |
ccc6cda3 JA |
6020 | \fB+\fP\fIn\fP |
6021 | Displays the \fIn\fPth entry counting from the left of the list | |
726f6388 JA |
6022 | shown by |
6023 | .B dirs | |
6024 | when invoked without options, starting with zero. | |
6025 | .TP | |
ccc6cda3 JA |
6026 | \fB\-\fP\fIn\fP |
6027 | Displays the \fIn\fPth entry counting from the right of the list | |
726f6388 JA |
6028 | shown by |
6029 | .B dirs | |
6030 | when invoked without options, starting with zero. | |
6031 | .TP | |
ccc6cda3 JA |
6032 | .B \-c |
6033 | Clears the directory stack by deleting all of the entries. | |
6034 | .TP | |
726f6388 | 6035 | .B \-l |
ccc6cda3 | 6036 | Produces a longer listing; the default listing format uses a |
726f6388 | 6037 | tilde to denote the home directory. |
ccc6cda3 JA |
6038 | .TP |
6039 | .B \-p | |
6040 | Print the directory stack with one entry per line. | |
6041 | .TP | |
6042 | .B \-v | |
6043 | Print the directory stack with one entry per line, | |
6044 | prefixing each entry with its index in the stack. | |
726f6388 JA |
6045 | .PD |
6046 | .PP | |
6047 | The return value is 0 unless an | |
cce855bc | 6048 | invalid option is supplied or \fIn\fP indexes beyond the end |
726f6388 JA |
6049 | of the directory stack. |
6050 | .RE | |
6051 | .TP | |
cce855bc | 6052 | \fBdisown\fP [\fB\-ar\fP] [\fB\-h\fP] [\fIjobspec\fP ...] |
ccc6cda3 JA |
6053 | Without options, each |
6054 | .I jobspec | |
6055 | is removed from the table of active jobs. | |
cce855bc JA |
6056 | If the \fB\-h\fP option is given, each |
6057 | .I jobspec | |
6058 | is not removed from the table, but is marked so that | |
ccc6cda3 JA |
6059 | .SM |
6060 | .B SIGHUP | |
6061 | is not sent to the job if the shell receives a | |
6062 | .SM | |
6063 | .BR SIGHUP . | |
6064 | If no | |
6065 | .I jobspec | |
cce855bc JA |
6066 | is present, and neither the |
6067 | .B \-a | |
6068 | nor the | |
6069 | .B \-r | |
6070 | option is supplied, the \fIcurrent job\fP is used. | |
6071 | If no | |
6072 | .I jobspec | |
6073 | is supplied, the | |
6074 | .B \-a | |
6075 | option means to remove or mark all jobs; the | |
6076 | .B \-r | |
6077 | option without a | |
6078 | .I jobspec | |
6079 | argument restricts operation to running jobs. | |
6080 | The return value is 0 unless a | |
ccc6cda3 JA |
6081 | .I jobspec |
6082 | does not specify a valid job. | |
6083 | .TP | |
726f6388 | 6084 | \fBecho\fP [\fB\-neE\fP] [\fIarg\fP ...] |
ccc6cda3 JA |
6085 | Output the \fIarg\fPs, separated by spaces, followed by a newline. |
6086 | The return status is always 0. | |
6087 | If \fB\-n\fP is specified, the trailing newline is | |
726f6388 JA |
6088 | suppressed. If the \fB\-e\fP option is given, interpretation of |
6089 | the following backslash-escaped characters is enabled. The | |
6090 | .B \-E | |
6091 | option disables the interpretation of these escape characters, | |
6092 | even on systems where they are interpreted by default. | |
28ef6c31 | 6093 | The \fBxpg_echo\fP shell option may be used to |
bb70624e JA |
6094 | dynamically determine whether or not \fBecho\fP expands these |
6095 | escape characters by default. | |
ccc6cda3 JA |
6096 | .B echo |
6097 | does not interpret | |
6098 | .B \-\- | |
6099 | to mean the end of options. | |
6100 | .B echo | |
6101 | interprets the following escape sequences: | |
726f6388 JA |
6102 | .RS |
6103 | .PD 0 | |
6104 | .TP | |
6105 | .B \ea | |
6106 | alert (bell) | |
6107 | .TP | |
6108 | .B \eb | |
6109 | backspace | |
6110 | .TP | |
6111 | .B \ec | |
6112 | suppress trailing newline | |
6113 | .TP | |
ccc6cda3 JA |
6114 | .B \ee |
6115 | an escape character | |
6116 | .TP | |
726f6388 JA |
6117 | .B \ef |
6118 | form feed | |
6119 | .TP | |
6120 | .B \en | |
6121 | new line | |
6122 | .TP | |
6123 | .B \er | |
6124 | carriage return | |
6125 | .TP | |
6126 | .B \et | |
6127 | horizontal tab | |
6128 | .TP | |
6129 | .B \ev | |
6130 | vertical tab | |
6131 | .TP | |
6132 | .B \e\e | |
6133 | backslash | |
6134 | .TP | |
cce855bc | 6135 | .B \e\fInnn\fP |
f73dda09 | 6136 | the eight-bit character whose value is the octal value \fInnn\fP |
cce855bc JA |
6137 | (one to three digits) |
6138 | .TP | |
f73dda09 JA |
6139 | .B \ex\fIHH\fP |
6140 | the eight-bit character whose value is the hexadecimal value \fIHH\fP | |
6141 | (one or two hex digits) | |
726f6388 JA |
6142 | .PD |
6143 | .RE | |
6144 | .TP | |
ccc6cda3 | 6145 | \fBenable\fP [\fB\-adnps\fP] [\fB\-f\fP \fIfilename\fP] [\fIname\fP ...] |
cce855bc JA |
6146 | Enable and disable builtin shell commands. |
6147 | Disabling a builtin allows a disk command which has the same name | |
bb70624e | 6148 | as a shell builtin to be executed without specifying a full pathname, |
cce855bc | 6149 | even though the shell normally searches for builtins before disk commands. |
726f6388 JA |
6150 | If \fB\-n\fP is used, each \fIname\fP |
6151 | is disabled; otherwise, | |
6152 | \fInames\fP are enabled. For example, to use the | |
6153 | .B test | |
6154 | binary found via the | |
6155 | .SM | |
6156 | .B PATH | |
ccc6cda3 | 6157 | instead of the shell builtin version, run |
28ef6c31 JA |
6158 | .if t \f(CWenable -n test\fP. |
6159 | .if n ``enable -n test''. | |
ccc6cda3 JA |
6160 | The |
6161 | .B \-f | |
6162 | option means to load the new builtin command | |
6163 | .I name | |
6164 | from shared object | |
6165 | .IR filename , | |
6166 | on systems that support dynamic loading. The | |
6167 | .B \-d | |
6168 | option will delete a builtin previously loaded with | |
6169 | .BR \-f . | |
6170 | If no \fIname\fP arguments are given, or if the | |
6171 | .B \-p | |
6172 | option is supplied, a list of shell builtins is printed. | |
6173 | With no other option arguments, the list consists of all enabled | |
6174 | shell builtins. | |
6175 | If \fB\-n\fP is supplied, only disabled builtins are printed. | |
6176 | If \fB\-a\fP is supplied, the list printed includes all builtins, with an | |
726f6388 | 6177 | indication of whether or not each is enabled. |
ccc6cda3 JA |
6178 | If \fB\-s\fP is supplied, the output is restricted to the POSIX |
6179 | \fIspecial\fP builtins. | |
726f6388 JA |
6180 | The return value is 0 unless a |
6181 | .I name | |
bb70624e | 6182 | is not a shell builtin or there is an error loading a new builtin |
ccc6cda3 | 6183 | from a shared object. |
726f6388 JA |
6184 | .TP |
6185 | \fBeval\fP [\fIarg\fP ...] | |
6186 | The \fIarg\fPs are read and concatenated together into a single | |
6187 | command. This command is then read and executed by the shell, and | |
ccc6cda3 JA |
6188 | its exit status is returned as the value of |
6189 | .BR eval . | |
6190 | If there are no | |
726f6388 JA |
6191 | .IR args , |
6192 | or only null arguments, | |
6193 | .B eval | |
ccc6cda3 | 6194 | returns 0. |
726f6388 | 6195 | .TP |
cce855bc | 6196 | \fBexec\fP [\fB\-cl\fP] [\fB\-a\fP \fIname\fP] [\fIcommand\fP [\fIarguments\fP]] |
726f6388 JA |
6197 | If |
6198 | .I command | |
6199 | is specified, it replaces the shell. | |
6200 | No new process is created. The | |
6201 | .I arguments | |
6202 | become the arguments to \fIcommand\fP. | |
ccc6cda3 JA |
6203 | If the |
6204 | .B \-l | |
6205 | option is supplied, | |
bb70624e | 6206 | the shell places a dash at the beginning of the zeroth arg passed to |
726f6388 | 6207 | .IR command . |
ccc6cda3 JA |
6208 | This is what |
6209 | .IR login (1) | |
6210 | does. The | |
6211 | .B \-c | |
6212 | option causes | |
6213 | .I command | |
6214 | to be executed with an empty environment. If | |
6215 | .B \-a | |
6216 | is supplied, the shell passes | |
6217 | .I name | |
6218 | as the zeroth argument to the executed command. If | |
6219 | .I command | |
726f6388 | 6220 | cannot be executed for some reason, a non-interactive shell exits, |
ccc6cda3 JA |
6221 | unless the shell option |
6222 | .B execfail | |
6223 | is enabled, in which case it returns failure. | |
6224 | An interactive shell returns failure if the file cannot be executed. | |
726f6388 JA |
6225 | If |
6226 | .I command | |
6227 | is not specified, any redirections take effect in the current shell, | |
cce855bc JA |
6228 | and the return status is 0. If there is a redirection error, the |
6229 | return status is 1. | |
726f6388 JA |
6230 | .TP |
6231 | \fBexit\fP [\fIn\fP] | |
6232 | Cause the shell to exit | |
6233 | with a status of \fIn\fP. If | |
6234 | .I n | |
6235 | is omitted, the exit status | |
6236 | is that of the last command executed. | |
6237 | A trap on | |
6238 | .SM | |
6239 | .B EXIT | |
6240 | is executed before the shell terminates. | |
6241 | .TP | |
6242 | .PD 0 | |
ccc6cda3 | 6243 | \fBexport\fP [\fB\-fn\fP\^] [\fIname\fP[=\fIword\fP]] ... |
726f6388 JA |
6244 | .TP |
6245 | .B export \-p | |
6246 | .PD | |
6247 | The supplied | |
6248 | .I names | |
6249 | are marked for automatic export to the environment of | |
6250 | subsequently executed commands. If the | |
6251 | .B \-f | |
6252 | option is given, | |
6253 | the | |
6254 | .I names | |
6255 | refer to functions. | |
6256 | If no | |
6257 | .I names | |
6258 | are given, or if the | |
6259 | .B \-p | |
6260 | option is supplied, a list | |
6261 | of all names that are exported in this shell is printed. | |
6262 | The | |
6263 | .B \-n | |
6264 | option causes the export property to be removed from the | |
ccc6cda3 | 6265 | named variables. |
726f6388 | 6266 | .B export |
cce855bc | 6267 | returns an exit status of 0 unless an invalid option is |
726f6388 | 6268 | encountered, |
cce855bc | 6269 | one of the \fInames\fP is not a valid shell variable name, or |
726f6388 JA |
6270 | .B \-f |
6271 | is supplied with a | |
6272 | .I name | |
6273 | that is not a function. | |
6274 | .TP | |
6275 | .PD 0 | |
6276 | \fBfc\fP [\fB\-e\fP \fIename\fP] [\fB\-nlr\fP] [\fIfirst\fP] [\fIlast\fP] | |
6277 | .TP | |
6278 | \fBfc\fP \fB\-s\fP [\fIpat\fP=\fIrep\fP] [\fIcmd\fP] | |
6279 | .PD | |
6280 | Fix Command. In the first form, a range of commands from | |
6281 | .I first | |
6282 | to | |
6283 | .I last | |
6284 | is selected from the history list. | |
6285 | .I First | |
6286 | and | |
6287 | .I last | |
6288 | may be specified as a string (to locate the last command beginning | |
6289 | with that string) or as a number (an index into the history list, | |
6290 | where a negative number is used as an offset from the current | |
6291 | command number). If | |
6292 | .I last | |
6293 | is not specified it is set to | |
6294 | the current command for listing (so that | |
bb70624e JA |
6295 | .if n ``fc \-l \-10'' |
6296 | .if t \f(CWfc \-l \-10\fP | |
726f6388 JA |
6297 | prints the last 10 commands) and to |
6298 | .I first | |
6299 | otherwise. | |
6300 | If | |
6301 | .I first | |
6302 | is not specified it is set to the previous | |
6303 | command for editing and \-16 for listing. | |
6304 | .sp 1 | |
6305 | The | |
6306 | .B \-n | |
cce855bc | 6307 | option suppresses |
726f6388 JA |
6308 | the command numbers when listing. The |
6309 | .B \-r | |
cce855bc | 6310 | option reverses the order of |
726f6388 JA |
6311 | the commands. If the |
6312 | .B \-l | |
cce855bc | 6313 | option is given, |
726f6388 JA |
6314 | the commands are listed on |
6315 | standard output. Otherwise, the editor given by | |
6316 | .I ename | |
6317 | is invoked | |
6318 | on a file containing those commands. If | |
6319 | .I ename | |
6320 | is not given, the | |
6321 | value of the | |
6322 | .SM | |
6323 | .B FCEDIT | |
6324 | variable is used, and | |
6325 | the value of | |
6326 | .SM | |
6327 | .B EDITOR | |
6328 | if | |
6329 | .SM | |
6330 | .B FCEDIT | |
6331 | is not set. If neither variable is set, | |
6332 | .FN vi | |
6333 | is used. When editing is complete, the edited commands are | |
6334 | echoed and executed. | |
6335 | .sp 1 | |
6336 | In the second form, \fIcommand\fP is re-executed after each instance | |
6337 | of \fIpat\fP is replaced by \fIrep\fP. | |
ccc6cda3 JA |
6338 | A useful alias to use with this is |
6339 | .if n ``r=fc -s'', | |
6340 | .if t \f(CWr='fc \-s'\fP, | |
6341 | so that typing | |
6342 | .if n ``r cc'' | |
6343 | .if t \f(CWr cc\fP | |
6344 | runs the last command beginning with | |
6345 | .if n ``cc'' | |
6346 | .if t \f(CWcc\fP | |
6347 | and typing | |
6348 | .if n ``r'' | |
6349 | .if t \f(CWr\fP | |
726f6388 JA |
6350 | re-executes the last command. |
6351 | .sp 1 | |
cce855bc | 6352 | If the first form is used, the return value is 0 unless an invalid |
726f6388 JA |
6353 | option is encountered or |
6354 | .I first | |
6355 | or | |
6356 | .I last | |
6357 | specify history lines out of range. | |
6358 | If the | |
6359 | .B \-e | |
6360 | option is supplied, the return value is the value of the last | |
6361 | command executed or failure if an error occurs with the temporary | |
6362 | file of commands. If the second form is used, the return status | |
6363 | is that of the command re-executed, unless | |
6364 | .I cmd | |
6365 | does not specify a valid history line, in which case | |
6366 | .B fc | |
6367 | returns failure. | |
6368 | .TP | |
6369 | \fBfg\fP [\fIjobspec\fP] | |
cce855bc | 6370 | Resume |
726f6388 | 6371 | .I jobspec |
cce855bc JA |
6372 | in the foreground, and make it the current job. |
6373 | If | |
726f6388 JA |
6374 | .I jobspec |
6375 | is not present, the shell's notion of the \fIcurrent job\fP is used. | |
6376 | The return value is that of the command placed into the foreground, | |
6377 | or failure if run when job control is disabled or, when run with | |
6378 | job control enabled, if | |
6379 | .I jobspec | |
6380 | does not specify a valid job or | |
6381 | .I jobspec | |
6382 | specifies a job that was started without job control. | |
6383 | .TP | |
6384 | \fBgetopts\fP \fIoptstring\fP \fIname\fP [\fIargs\fP] | |
6385 | .B getopts | |
6386 | is used by shell procedures to parse positional parameters. | |
6387 | .I optstring | |
bb70624e | 6388 | contains the option characters to be recognized; if a character |
726f6388 JA |
6389 | is followed by a colon, the option is expected to have an |
6390 | argument, which should be separated from it by white space. | |
bb70624e JA |
6391 | The colon and question mark characters may not be used as |
6392 | option characters. | |
726f6388 JA |
6393 | Each time it is invoked, |
6394 | .B getopts | |
6395 | places the next option in the shell variable | |
6396 | .IR name , | |
6397 | initializing | |
6398 | .I name | |
6399 | if it does not exist, | |
6400 | and the index of the next argument to be processed into the | |
6401 | variable | |
6402 | .SM | |
6403 | .BR OPTIND . | |
6404 | .SM | |
6405 | .B OPTIND | |
6406 | is initialized to 1 each time the shell or a shell script | |
6407 | is invoked. When an option requires an argument, | |
6408 | .B getopts | |
6409 | places that argument into the variable | |
6410 | .SM | |
6411 | .BR OPTARG . | |
6412 | The shell does not reset | |
6413 | .SM | |
6414 | .B OPTIND | |
6415 | automatically; it must be manually reset between multiple | |
6416 | calls to | |
6417 | .B getopts | |
6418 | within the same shell invocation if a new set of parameters | |
6419 | is to be used. | |
6420 | .sp 1 | |
cce855bc JA |
6421 | When the end of options is encountered, \fBgetopts\fP exits with a |
6422 | return value greater than zero. | |
6423 | \fBOPTIND\fP is set to the index of the first non-option argument, | |
6424 | and \fBname\fP is set to ?. | |
6425 | .sp 1 | |
6426 | .B getopts | |
6427 | normally parses the positional parameters, but if more arguments are | |
6428 | given in | |
6429 | .IR args , | |
6430 | .B getopts | |
6431 | parses those instead. | |
6432 | .sp 1 | |
726f6388 JA |
6433 | .B getopts |
6434 | can report errors in two ways. If the first character of | |
6435 | .I optstring | |
6436 | is a colon, | |
6437 | .I silent | |
6438 | error reporting is used. In normal operation diagnostic messages | |
cce855bc | 6439 | are printed when invalid options or missing option arguments are |
726f6388 JA |
6440 | encountered. |
6441 | If the variable | |
6442 | .SM | |
6443 | .B OPTERR | |
cce855bc | 6444 | is set to 0, no error messages will be displayed, even if the first |
726f6388 JA |
6445 | character of |
6446 | .I optstring | |
6447 | is not a colon. | |
6448 | .sp 1 | |
cce855bc | 6449 | If an invalid option is seen, |
726f6388 JA |
6450 | .B getopts |
6451 | places ? into | |
6452 | .I name | |
6453 | and, if not silent, | |
6454 | prints an error message and unsets | |
6455 | .SM | |
6456 | .BR OPTARG . | |
6457 | If | |
6458 | .B getopts | |
6459 | is silent, | |
6460 | the option character found is placed in | |
6461 | .SM | |
6462 | .B OPTARG | |
6463 | and no diagnostic message is printed. | |
6464 | .sp 1 | |
6465 | If a required argument is not found, and | |
6466 | .B getopts | |
6467 | is not silent, | |
6468 | a question mark (\^\fB?\fP\^) is placed in | |
6469 | .IR name , | |
f73dda09 | 6470 | .SM |
726f6388 JA |
6471 | .B OPTARG |
6472 | is unset, and a diagnostic message is printed. | |
6473 | If | |
6474 | .B getopts | |
6475 | is silent, then a colon (\^\fB:\fP\^) is placed in | |
6476 | .I name | |
6477 | and | |
6478 | .SM | |
6479 | .B OPTARG | |
6480 | is set to the option character found. | |
6481 | .sp 1 | |
6482 | .B getopts | |
726f6388 JA |
6483 | returns true if an option, specified or unspecified, is found. |
6484 | It returns false if the end of options is encountered or an | |
6485 | error occurs. | |
6486 | .TP | |
f73dda09 | 6487 | \fBhash\fP [\fB\-r\fP] [\fB\-p\fP \fIfilename\fP] [\fB\-t\fP] [\fIname\fP] |
726f6388 JA |
6488 | For each |
6489 | .IR name , | |
ccc6cda3 JA |
6490 | the full file name of the command is determined by searching |
6491 | the directories in | |
6492 | .B $PATH | |
6493 | and remembered. | |
6494 | If the | |
6495 | .B \-p | |
6496 | option is supplied, no path search is performed, and | |
6497 | .I filename | |
6498 | is used as the full file name of the command. | |
6499 | The | |
726f6388 JA |
6500 | .B \-r |
6501 | option causes the shell to forget all | |
f73dda09 JA |
6502 | remembered locations. |
6503 | If the | |
6504 | .B \-t | |
6505 | option is supplied, the full pathname to which each \fIname\fP corresponds | |
6506 | is printed. If multiple \fIname\fP arguments are supplied with \fB\-t\fP, | |
6507 | the \fIname\fP is printed before the hashed full pathname. | |
6508 | If no arguments are given, information about remembered commands is printed. | |
ccc6cda3 | 6509 | The return status is true unless a |
726f6388 | 6510 | .I name |
cce855bc | 6511 | is not found or an invalid option is supplied. |
726f6388 | 6512 | .TP |
bb70624e | 6513 | \fBhelp\fP [\fB\-s\fP] [\fIpattern\fP] |
726f6388 JA |
6514 | Display helpful information about builtin commands. If |
6515 | .I pattern | |
6516 | is specified, | |
6517 | .B help | |
6518 | gives detailed help on all commands matching | |
6519 | .IR pattern ; | |
ccc6cda3 | 6520 | otherwise help for all the builtins and shell control structures |
bb70624e JA |
6521 | is printed. |
6522 | The \fB\-s\fP option restricts the information displayed to a short | |
6523 | usage synopsis. | |
6524 | The return status is 0 unless no command matches | |
726f6388 JA |
6525 | .IR pattern . |
6526 | .TP | |
6527 | .PD 0 | |
bb70624e JA |
6528 | \fBhistory [\fIn\fP] |
6529 | .TP | |
6530 | \fBhistory\fP \fB\-c\fP | |
6531 | .TP | |
6532 | \fBhistory \-d\fP \fIoffset\fP | |
ccc6cda3 JA |
6533 | .TP |
6534 | \fBhistory\fP \fB\-anrw\fP [\fIfilename\fP] | |
726f6388 | 6535 | .TP |
ccc6cda3 JA |
6536 | \fBhistory\fP \fB\-p\fP \fIarg\fP [\fIarg ...\fP] |
6537 | .TP | |
6538 | \fBhistory\fP \fB\-s\fP \fIarg\fP [\fIarg ...\fP] | |
726f6388 JA |
6539 | .PD |
6540 | With no options, display the command | |
6541 | history list with line numbers. Lines listed | |
6542 | with a | |
6543 | .B * | |
6544 | have been modified. An argument of | |
6545 | .I n | |
6546 | lists only the last | |
6547 | .I n | |
ccc6cda3 | 6548 | lines. If \fIfilename\fP is supplied, it is used as the |
726f6388 JA |
6549 | name of the history file; if not, the value of |
6550 | .SM | |
6551 | .B HISTFILE | |
6552 | is used. Options, if supplied, have the following meanings: | |
6553 | .RS | |
6554 | .PD 0 | |
6555 | .TP | |
bb70624e JA |
6556 | .B \-c |
6557 | Clear the history list by deleting all the entries. | |
6558 | .TP | |
6559 | \fB\-d\fP \fIoffset\fP | |
6560 | Delete the history entry at position \fIoffset\fP. | |
6561 | .TP | |
726f6388 JA |
6562 | .B \-a |
6563 | Append the ``new'' history lines (history lines entered since the | |
ccc6cda3 | 6564 | beginning of the current \fBbash\fP session) to the history file. |
726f6388 JA |
6565 | .TP |
6566 | .B \-n | |
6567 | Read the history lines not already read from the history | |
6568 | file into the current history list. These are lines | |
6569 | appended to the history file since the beginning of the | |
6570 | current \fBbash\fP session. | |
6571 | .TP | |
6572 | .B \-r | |
6573 | Read the contents of the history file | |
ccc6cda3 | 6574 | and use them as the current history. |
726f6388 JA |
6575 | .TP |
6576 | .B \-w | |
6577 | Write the current history to the history file, overwriting the | |
6578 | history file's contents. | |
ccc6cda3 | 6579 | .TP |
ccc6cda3 JA |
6580 | .B \-p |
6581 | Perform history substitution on the following \fIargs\fP and display | |
6582 | the result on the standard output. | |
6583 | Does not store the results in the history list. | |
6584 | Each \fIarg\fP must be quoted to disable normal history expansion. | |
6585 | .TP | |
6586 | .B \-s | |
6587 | Store the | |
6588 | .I args | |
6589 | in the history list as a single entry. The last command in the | |
6590 | history list is removed before the | |
6591 | .I args | |
6592 | are added. | |
726f6388 JA |
6593 | .PD |
6594 | .PP | |
bb70624e JA |
6595 | The return value is 0 unless an invalid option is encountered, an |
6596 | error occurs while reading or writing the history file, an invalid | |
6597 | \fIoffset\fP is supplied as an argument to \fB\-d\fP, or the | |
6598 | history expansion supplied as an argument to \fB\-p\fP fails. | |
726f6388 JA |
6599 | .RE |
6600 | .TP | |
6601 | .PD 0 | |
ccc6cda3 | 6602 | \fBjobs\fP [\fB\-lnprs\fP] [ \fIjobspec\fP ... ] |
726f6388 JA |
6603 | .TP |
6604 | \fBjobs\fP \fB\-x\fP \fIcommand\fP [ \fIargs\fP ... ] | |
6605 | .PD | |
ccc6cda3 JA |
6606 | The first form lists the active jobs. The options have the following |
6607 | meanings: | |
6608 | .RS | |
6609 | .PD 0 | |
6610 | .TP | |
726f6388 | 6611 | .B \-l |
ccc6cda3 JA |
6612 | List process IDs |
6613 | in addition to the normal information. | |
6614 | .TP | |
726f6388 | 6615 | .B \-p |
ccc6cda3 JA |
6616 | List only the process ID of the job's process group |
6617 | leader. | |
6618 | .TP | |
726f6388 | 6619 | .B \-n |
ccc6cda3 JA |
6620 | Display information only about jobs that have changed status since |
6621 | the user was last notified of their status. | |
6622 | .TP | |
6623 | .B \-r | |
6624 | Restrict output to running jobs. | |
6625 | .TP | |
6626 | .B \-s | |
6627 | Restrict output to stopped jobs. | |
6628 | .PD | |
6629 | .PP | |
6630 | If | |
726f6388 JA |
6631 | .I jobspec |
6632 | is given, output is restricted to information about that job. | |
cce855bc JA |
6633 | The return status is 0 unless an invalid option is encountered |
6634 | or an invalid | |
726f6388 JA |
6635 | .I jobspec |
6636 | is supplied. | |
ccc6cda3 | 6637 | .PP |
726f6388 JA |
6638 | If the |
6639 | .B \-x | |
6640 | option is supplied, | |
6641 | .B jobs | |
6642 | replaces any | |
6643 | .I jobspec | |
6644 | found in | |
6645 | .I command | |
6646 | or | |
6647 | .I args | |
6648 | with the corresponding process group ID, and executes | |
6649 | .I command | |
6650 | passing it | |
6651 | .IR args , | |
6652 | returning its exit status. | |
ccc6cda3 | 6653 | .RE |
726f6388 JA |
6654 | .TP |
6655 | .PD 0 | |
ccc6cda3 | 6656 | \fBkill\fP [\fB\-s\fP \fIsigspec\fP | \fB\-n\fP \fIsignum\fP | \fB\-\fP\fIsigspec\fP] [\fIpid\fP | \fIjobspec\fP] ... |
726f6388 | 6657 | .TP |
cce855bc | 6658 | \fBkill\fP \fB\-l\fP [\fIsigspec\fP | \fIexit_status\fP] |
726f6388 JA |
6659 | .PD |
6660 | Send the signal named by | |
6661 | .I sigspec | |
ccc6cda3 JA |
6662 | or |
6663 | .I signum | |
726f6388 JA |
6664 | to the processes named by |
6665 | .I pid | |
6666 | or | |
6667 | .IR jobspec . | |
6668 | .I sigspec | |
6669 | is either a signal name such as | |
6670 | .SM | |
6671 | .B SIGKILL | |
ccc6cda3 JA |
6672 | or a signal number; |
6673 | .I signum | |
6674 | is a signal number. If | |
726f6388 | 6675 | .I sigspec |
ccc6cda3 | 6676 | is a signal name, the name may be |
726f6388 JA |
6677 | given with or without the |
6678 | .SM | |
6679 | .B SIG | |
6680 | prefix. | |
6681 | If | |
6682 | .I sigspec | |
6683 | is not present, then | |
6684 | .SM | |
6685 | .B SIGTERM | |
cce855bc JA |
6686 | is assumed. |
6687 | An argument of | |
726f6388 | 6688 | .B \-l |
cce855bc JA |
6689 | lists the signal names. |
6690 | If any arguments are supplied when | |
726f6388 | 6691 | .B \-l |
cce855bc JA |
6692 | is given, the names of the signals corresponding to the arguments are |
6693 | listed, and the return status is 0. | |
6694 | The \fIexit_status\fP argument to | |
ccc6cda3 | 6695 | .B \-l |
cce855bc JA |
6696 | is a number specifying either a signal number or the exit status of |
6697 | a process terminated by a signal. | |
726f6388 JA |
6698 | .B kill |
6699 | returns true if at least one signal was successfully sent, or false | |
cce855bc | 6700 | if an error occurs or an invalid option is encountered. |
726f6388 JA |
6701 | .TP |
6702 | \fBlet\fP \fIarg\fP [\fIarg\fP ...] | |
6703 | Each | |
6704 | .I arg | |
6705 | is an arithmetic expression to be evaluated (see | |
6706 | .SM | |
6707 | .BR "ARITHMETIC EVALUATION" ). | |
6708 | If the last | |
6709 | .I arg | |
6710 | evaluates to 0, | |
6711 | .B let | |
6712 | returns 1; 0 is returned otherwise. | |
6713 | .TP | |
bb70624e | 6714 | \fBlocal\fP [\fIoption\fP] [\fIname\fP[=\fIvalue\fP] ...] |
cce855bc JA |
6715 | For each argument, a local variable named |
6716 | .I name | |
6717 | is created, and assigned | |
726f6388 | 6718 | .IR value . |
bb70624e | 6719 | The \fIoption\fP can be any of the options accepted by \fBdeclare\fP. |
726f6388 JA |
6720 | When |
6721 | .B local | |
6722 | is used within a function, it causes the variable | |
6723 | .I name | |
6724 | to have a visible scope restricted to that function and its children. | |
6725 | With no operands, | |
6726 | .B local | |
6727 | writes a list of local variables to the standard output. It is | |
6728 | an error to use | |
6729 | .B local | |
6730 | when not within a function. The return status is 0 unless | |
6731 | .B local | |
bb70624e | 6732 | is used outside a function, an invalid |
726f6388 | 6733 | .I name |
bb70624e JA |
6734 | is supplied, or |
6735 | \fIname\fP is a readonly variable. | |
726f6388 JA |
6736 | .TP |
6737 | .B logout | |
6738 | Exit a login shell. | |
6739 | .TP | |
ccc6cda3 | 6740 | \fBpopd\fP [\-\fBn\fP] [+\fIn\fP] [\-\fIn\fP] |
726f6388 JA |
6741 | Removes entries from the directory stack. With no arguments, |
6742 | removes the top directory from the stack, and performs a | |
6743 | .B cd | |
6744 | to the new top directory. | |
ccc6cda3 | 6745 | Arguments, if supplied, have the following meanings: |
726f6388 JA |
6746 | .RS |
6747 | .PD 0 | |
6748 | .TP | |
ccc6cda3 JA |
6749 | \fB+\fP\fIn\fP |
6750 | Removes the \fIn\fPth entry counting from the left of the list | |
726f6388 JA |
6751 | shown by |
6752 | .BR dirs , | |
bb70624e JA |
6753 | starting with zero. For example: |
6754 | .if n ``popd +0'' | |
6755 | .if t \f(CWpopd +0\fP | |
6756 | removes the first directory, | |
6757 | .if n ``popd +1'' | |
6758 | .if t \f(CWpopd +1\fP | |
6759 | the second. | |
726f6388 | 6760 | .TP |
ccc6cda3 JA |
6761 | \fB\-\fP\fIn\fP |
6762 | Removes the \fIn\fPth entry counting from the right of the list | |
726f6388 JA |
6763 | shown by |
6764 | .BR dirs , | |
bb70624e JA |
6765 | starting with zero. For example: |
6766 | .if n ``popd -0'' | |
6767 | .if t \f(CWpopd -0\fP | |
6768 | removes the last directory, | |
6769 | .if n ``popd -1'' | |
6770 | .if t \f(CWpopd -1\fP | |
6771 | the next to last. | |
ccc6cda3 JA |
6772 | .TP |
6773 | .B \-n | |
6774 | Suppresses the normal change of directory when removing directories | |
6775 | from the stack, so that only the stack is manipulated. | |
726f6388 JA |
6776 | .PD |
6777 | .PP | |
6778 | If the | |
6779 | .B popd | |
6780 | command is successful, a | |
6781 | .B dirs | |
6782 | is performed as well, and the return status is 0. | |
6783 | .B popd | |
cce855bc | 6784 | returns false if an invalid option is encountered, the directory stack |
726f6388 JA |
6785 | is empty, a non-existent directory stack entry is specified, or the |
6786 | directory change fails. | |
6787 | .RE | |
6788 | .TP | |
cce855bc JA |
6789 | \fBprintf\fP \fIformat\fP [\fIarguments\fP] |
6790 | Write the formatted \fIarguments\fP to the standard output under the | |
6791 | control of the \fIformat\fP. | |
6792 | The \fIformat\fP is a character string which contains three types of objects: | |
6793 | plain characters, which are simply copied to standard output, character | |
6794 | escape sequences, which are converted and copied to the standard output, and | |
6795 | format specifications, each of which causes printing of the next successive | |
6796 | \fIargument\fP. | |
f73dda09 | 6797 | In addition to the standard \fIprintf\fP(1) formats, \fB%b\fP causes |
cce855bc | 6798 | \fBprintf\fP to expand backslash escape sequences in the corresponding |
f73dda09 | 6799 | \fIargument\fP, and \fB%q\fP causes \fBprintf\fP to output the corresponding |
cce855bc JA |
6800 | \fIargument\fP in a format that can be reused as shell input. |
6801 | .sp 1 | |
6802 | The \fIformat\fP is reused as necessary to consume all of the \fIarguments\fP. | |
6803 | If the \fIformat\fP requires more \fIarguments\fP than are supplied, the | |
6804 | extra format specifications behave as if a zero value or null string, as | |
bb70624e JA |
6805 | appropriate, had been supplied. The return value is zero on success, |
6806 | non-zero on failure. | |
cce855bc | 6807 | .TP |
726f6388 | 6808 | .PD 0 |
ccc6cda3 | 6809 | \fBpushd\fP [\fB\-n\fP] [\fIdir\fP] |
726f6388 | 6810 | .TP |
ccc6cda3 | 6811 | \fBpushd\fP [\fB\-n\fP] [+\fIn\fP] [\-\fIn\fP] |
726f6388 JA |
6812 | .PD |
6813 | Adds a directory to the top of the directory stack, or rotates | |
6814 | the stack, making the new top of the stack the current working | |
6815 | directory. With no arguments, exchanges the top two directories | |
6816 | and returns 0, unless the directory stack is empty. | |
ccc6cda3 | 6817 | Arguments, if supplied, have the following meanings: |
726f6388 JA |
6818 | .RS |
6819 | .PD 0 | |
6820 | .TP | |
ccc6cda3 | 6821 | \fB+\fP\fIn\fP |
726f6388 JA |
6822 | Rotates the stack so that the \fIn\fPth directory |
6823 | (counting from the left of the list shown by | |
d166f048 JA |
6824 | .BR dirs , |
6825 | starting with zero) | |
726f6388 JA |
6826 | is at the top. |
6827 | .TP | |
ccc6cda3 | 6828 | \fB\-\fP\fIn\fP |
726f6388 | 6829 | Rotates the stack so that the \fIn\fPth directory |
d166f048 JA |
6830 | (counting from the right of the list shown by |
6831 | .BR dirs , | |
6832 | starting with zero) is at the top. | |
726f6388 | 6833 | .TP |
ccc6cda3 JA |
6834 | .B \-n |
6835 | Suppresses the normal change of directory when adding directories | |
6836 | to the stack, so that only the stack is manipulated. | |
6837 | .TP | |
bb70624e | 6838 | .I dir |
ccc6cda3 | 6839 | Adds |
726f6388 JA |
6840 | .I dir |
6841 | to the directory stack at the top, making it the | |
6842 | new current working directory. | |
6843 | .PD | |
6844 | .PP | |
6845 | If the | |
6846 | .B pushd | |
6847 | command is successful, a | |
6848 | .B dirs | |
6849 | is performed as well. | |
6850 | If the first form is used, | |
6851 | .B pushd | |
6852 | returns 0 unless the cd to | |
6853 | .I dir | |
6854 | fails. With the second form, | |
6855 | .B pushd | |
6856 | returns 0 unless the directory stack is empty, | |
ccc6cda3 | 6857 | a non-existent directory stack element is specified, |
726f6388 JA |
6858 | or the directory change to the specified new current directory |
6859 | fails. | |
6860 | .RE | |
6861 | .TP | |
ccc6cda3 | 6862 | \fBpwd\fP [\fB\-LP\fP] |
bb70624e JA |
6863 | Print the absolute pathname of the current working directory. |
6864 | The pathname printed contains no symbolic links if the | |
726f6388 | 6865 | .B \-P |
ccc6cda3 JA |
6866 | option is supplied or the |
6867 | .B \-o physical | |
726f6388 JA |
6868 | option to the |
6869 | .B set | |
ccc6cda3 JA |
6870 | builtin command is enabled. |
6871 | If the | |
6872 | .B \-L | |
bb70624e | 6873 | option is used, the pathname printed may contain symbolic links. |
ccc6cda3 | 6874 | The return status is 0 unless an error occurs while |
cce855bc JA |
6875 | reading the name of the current directory or an |
6876 | invalid option is supplied. | |
726f6388 | 6877 | .TP |
bb70624e | 6878 | \fBread\fP [\fB\-ers\fP] [\fB\-t\fP \fItimeout\fP] [\fB\-a\fP \fIaname\fP] [\fB\-p\fP \fIprompt\fP] [\fB\-n\fP \fInchars\fP] [\fB\-d\fP \fIdelim\fP] [\fIname\fP ...] |
726f6388 JA |
6879 | One line is read from the standard input, and the first word |
6880 | is assigned to the first | |
6881 | .IR name , | |
6882 | the second word to the second | |
6883 | .IR name , | |
cce855bc JA |
6884 | and so on, with leftover words and their intervening separators assigned |
6885 | to the last | |
726f6388 | 6886 | .IR name . |
cce855bc JA |
6887 | If there are fewer words read from the standard input than names, |
6888 | the remaining names are assigned empty values. | |
6889 | The characters in | |
726f6388 JA |
6890 | .SM |
6891 | .B IFS | |
cce855bc | 6892 | are used to split the line into words. |
b72432fd JA |
6893 | The backslash character (\fB\e\fP) may be used to remove any special |
6894 | meaning for the next character read and for line continuation. | |
cce855bc | 6895 | Options, if supplied, have the following meanings: |
ccc6cda3 JA |
6896 | .RS |
6897 | .PD 0 | |
6898 | .TP | |
bb70624e | 6899 | .B \-a \fIaname\fP |
ccc6cda3 JA |
6900 | The words are assigned to sequential indices |
6901 | of the array variable | |
6902 | .IR aname , | |
6903 | starting at 0. | |
6904 | .I aname | |
6905 | is unset before any new values are assigned. | |
cce855bc | 6906 | Other \fIname\fP arguments are ignored. |
ccc6cda3 | 6907 | .TP |
bb70624e JA |
6908 | .B \-d \fIdelim\fP |
6909 | The first character of \fIdelim\fP is used to terminate the input line, | |
6910 | rather than newline. | |
6911 | .TP | |
ccc6cda3 JA |
6912 | .B \-e |
6913 | If the standard input | |
6914 | is coming from a terminal, | |
6915 | .B readline | |
6916 | (see | |
6917 | .SM | |
6918 | .B READLINE | |
6919 | above) is used to obtain the line. | |
bb70624e JA |
6920 | .TP |
6921 | .B \-n \fInchars\fP | |
6922 | \fBread\fP returns after reading \fInchars\fP characters rather than | |
6923 | waiting for a complete line of input. | |
6924 | .TP | |
6925 | .B \-p \fIprompt\fP | |
f73dda09 | 6926 | Display \fIprompt\fP on standard error, without a |
bb70624e JA |
6927 | trailing newline, before attempting to read any input. The prompt |
6928 | is displayed only if input is coming from a terminal. | |
6929 | .TP | |
6930 | .B \-r | |
6931 | Backslash does not act as an escape character. | |
6932 | The backslash is considered to be part of the line. | |
6933 | In particular, a backslash-newline pair may not be used as a line | |
6934 | continuation. | |
6935 | .TP | |
6936 | .B \-s | |
6937 | Silent mode. If input is coming from a terminal, characters are | |
6938 | not echoed. | |
6939 | .TP | |
6940 | .B \-t \fItimeout\fP | |
6941 | Cause \fBread\fP to time out and return failure if a complete line of | |
6942 | input is not read within \fItimeout\fP seconds. | |
6943 | This option has no effect if \fBread\fP is not reading input from the | |
6944 | terminal or a pipe. | |
ccc6cda3 JA |
6945 | .PD |
6946 | .PP | |
6947 | If no | |
726f6388 JA |
6948 | .I names |
6949 | are supplied, the line read is assigned to the variable | |
6950 | .SM | |
6951 | .BR REPLY . | |
bb70624e JA |
6952 | The return code is zero, unless end-of-file is encountered or \fBread\fP |
6953 | times out. | |
ccc6cda3 | 6954 | .RE |
726f6388 | 6955 | .TP |
ccc6cda3 | 6956 | \fBreadonly\fP [\fB\-apf\fP] [\fIname\fP ...] |
726f6388 JA |
6957 | .PD |
6958 | The given | |
ccc6cda3 JA |
6959 | \fInames\fP are marked readonly; the values of these |
6960 | .I names | |
726f6388 JA |
6961 | may not be changed by subsequent assignment. |
6962 | If the | |
6963 | .B \-f | |
6964 | option is supplied, the functions corresponding to the | |
6965 | \fInames\fP are so | |
ccc6cda3 JA |
6966 | marked. |
6967 | The | |
6968 | .B \-a | |
6969 | option restricts the variables to arrays. | |
6970 | If no | |
6971 | .I name | |
6972 | arguments are given, or if the | |
726f6388 | 6973 | .B \-p |
ccc6cda3 | 6974 | option is supplied, a list of all readonly names is printed. |
cce855bc JA |
6975 | The |
6976 | .B \-p | |
bb70624e JA |
6977 | option causes output to be displayed in a format that |
6978 | may be reused as input. | |
cce855bc | 6979 | The return status is 0 unless an invalid option is encountered, |
ccc6cda3 JA |
6980 | one of the |
6981 | .I names | |
cce855bc | 6982 | is not a valid shell variable name, or |
726f6388 JA |
6983 | .B \-f |
6984 | is supplied with a | |
6985 | .I name | |
6986 | that is not a function. | |
6987 | .TP | |
6988 | \fBreturn\fP [\fIn\fP] | |
6989 | Causes a function to exit with the return value specified by | |
6990 | .IR n . | |
6991 | If | |
6992 | .I n | |
6993 | is omitted, the return status is that of the last command | |
6994 | executed in the function body. If used outside a function, | |
6995 | but during execution of a script by the | |
6996 | .B . | |
6997 | (\fBsource\fP) command, it causes the shell to stop executing | |
6998 | that script and return either | |
6999 | .I n | |
7000 | or the exit status of the last command executed within the | |
7001 | script as the exit status of the script. If used outside a | |
7002 | function and not during execution of a script by \fB.\fP\^, | |
7003 | the return status is false. | |
7004 | .TP | |
ccc6cda3 JA |
7005 | \fBset\fP [\fB\-\-abefhkmnptuvxBCHP\fP] [\fB\-o\fP \fIoption\fP] [\fIarg\fP ...] |
7006 | Without options, the name and value of each shell variable are displayed | |
cce855bc JA |
7007 | in a format that can be reused as input. |
7008 | The output is sorted according to the current locale. | |
ccc6cda3 JA |
7009 | When options are specified, they set or unset shell attributes. |
7010 | Any arguments remaining after the options are processed are treated | |
7011 | as values for the positional parameters and are assigned, in order, to | |
7012 | .BR $1 , | |
7013 | .BR $2 , | |
7014 | .B ... | |
7015 | .BR $\fIn\fP . | |
7016 | Options, if specified, have the following meanings: | |
726f6388 JA |
7017 | .RS |
7018 | .PD 0 | |
7019 | .TP 8 | |
7020 | .B \-a | |
28ef6c31 JA |
7021 | Automatically mark variables and functions which are modified or created |
7022 | for export to the environment of subsequent commands. | |
726f6388 JA |
7023 | .TP 8 |
7024 | .B \-b | |
ccc6cda3 JA |
7025 | Report the status of terminated background jobs |
7026 | immediately, rather than before the next primary prompt. This is | |
7027 | effective only when job control is enabled. | |
726f6388 JA |
7028 | .TP 8 |
7029 | .B \-e | |
ccc6cda3 | 7030 | Exit immediately if a \fIsimple command\fP (see |
726f6388 JA |
7031 | .SM |
7032 | .B SHELL GRAMMAR | |
ccc6cda3 | 7033 | above) exits with a non-zero status. The shell does not exit if the |
726f6388 JA |
7034 | command that fails is part of an |
7035 | .I until | |
7036 | or | |
7037 | .I while | |
7038 | loop, | |
7039 | part of an | |
7040 | .I if | |
7041 | statement, part of a | |
7042 | .B && | |
7043 | or | |
ccc6cda3 | 7044 | .B \(bv\(bv |
726f6388 JA |
7045 | list, or if the command's return value is |
7046 | being inverted via | |
7047 | .BR ! . | |
f73dda09 | 7048 | A trap on \fBERR\fP, if set, is executed before the shell exits. |
726f6388 JA |
7049 | .TP 8 |
7050 | .B \-f | |
7051 | Disable pathname expansion. | |
7052 | .TP 8 | |
7053 | .B \-h | |
ccc6cda3 | 7054 | Remember the location of commands as they are looked up for execution. |
cce855bc | 7055 | This is enabled by default. |
726f6388 JA |
7056 | .TP 8 |
7057 | .B \-k | |
ccc6cda3 JA |
7058 | All arguments in the form of assignment statements |
7059 | are placed in the environment for a command, not just | |
7060 | those that precede the command name. | |
726f6388 JA |
7061 | .TP 8 |
7062 | .B \-m | |
cce855bc | 7063 | Monitor mode. Job control is enabled. This option is on |
726f6388 JA |
7064 | by default for interactive shells on systems that support |
7065 | it (see | |
7066 | .SM | |
7067 | .B JOB CONTROL | |
7068 | above). Background processes run in a separate process | |
7069 | group and a line containing their exit status is printed | |
7070 | upon their completion. | |
7071 | .TP 8 | |
7072 | .B \-n | |
7073 | Read commands but do not execute them. This may be used to | |
ccc6cda3 | 7074 | check a shell script for syntax errors. This is ignored by |
726f6388 JA |
7075 | interactive shells. |
7076 | .TP 8 | |
ccc6cda3 JA |
7077 | .B \-o \fIoption\-name\fP |
7078 | The \fIoption\-name\fP can be one of the following: | |
726f6388 JA |
7079 | .RS |
7080 | .TP 8 | |
7081 | .B allexport | |
7082 | Same as | |
7083 | .BR \-a . | |
7084 | .TP 8 | |
7085 | .B braceexpand | |
ccc6cda3 JA |
7086 | Same as |
7087 | .BR \-B . | |
726f6388 JA |
7088 | .TP 8 |
7089 | .B emacs | |
7090 | Use an emacs-style command line editing interface. This is enabled | |
7091 | by default when the shell is interactive, unless the shell is started | |
7092 | with the | |
ccc6cda3 | 7093 | .B \-\-noediting |
726f6388 JA |
7094 | option. |
7095 | .TP 8 | |
7096 | .B errexit | |
7097 | Same as | |
7098 | .BR \-e . | |
7099 | .TP 8 | |
ccc6cda3 JA |
7100 | .B hashall |
7101 | Same as | |
7102 | .BR \-h . | |
7103 | .TP 8 | |
726f6388 JA |
7104 | .B histexpand |
7105 | Same as | |
7106 | .BR \-H . | |
7107 | .TP 8 | |
ccc6cda3 JA |
7108 | .B history |
7109 | Enable command history, as described above under | |
7110 | .SM | |
7111 | .BR HISTORY . | |
7112 | This option is on by default in interactive shells. | |
7113 | .TP 8 | |
726f6388 | 7114 | .B ignoreeof |
28ef6c31 JA |
7115 | The effect is as if the shell command |
7116 | .if t \f(CWIGNOREEOF=10\fP | |
7117 | .if n ``IGNOREEOF=10'' | |
7118 | had been executed | |
726f6388 JA |
7119 | (see |
7120 | .B Shell Variables | |
7121 | above). | |
7122 | .TP 8 | |
ccc6cda3 JA |
7123 | .B keyword |
7124 | Same as | |
7125 | .BR \-k . | |
726f6388 JA |
7126 | .TP 8 |
7127 | .B monitor | |
7128 | Same as | |
7129 | .BR \-m . | |
7130 | .TP 8 | |
7131 | .B noclobber | |
7132 | Same as | |
7133 | .BR \-C . | |
7134 | .TP 8 | |
7135 | .B noexec | |
7136 | Same as | |
7137 | .BR \-n . | |
7138 | .TP 8 | |
7139 | .B noglob | |
7140 | Same as | |
7141 | .BR \-f . | |
f73dda09 JA |
7142 | .B nolog |
7143 | Currently ignored. | |
726f6388 | 7144 | .TP 8 |
726f6388 JA |
7145 | .B notify |
7146 | Same as | |
7147 | .BR \-b . | |
7148 | .TP 8 | |
7149 | .B nounset | |
7150 | Same as | |
7151 | .BR \-u . | |
7152 | .TP 8 | |
ccc6cda3 JA |
7153 | .B onecmd |
7154 | Same as | |
7155 | .BR \-t . | |
7156 | .TP 8 | |
726f6388 JA |
7157 | .B physical |
7158 | Same as | |
7159 | .BR \-P . | |
7160 | .TP 8 | |
7161 | .B posix | |
ccc6cda3 JA |
7162 | Change the behavior of |
7163 | .B bash | |
7164 | where the default operation differs | |
28ef6c31 | 7165 | from the POSIX 1003.2 standard to match the standard (\fIposix mode\fP). |
726f6388 JA |
7166 | .TP 8 |
7167 | .B privileged | |
7168 | Same as | |
7169 | .BR \-p . | |
7170 | .TP 8 | |
7171 | .B verbose | |
7172 | Same as | |
7173 | .BR \-v . | |
7174 | .TP 8 | |
7175 | .B vi | |
7176 | Use a vi-style command line editing interface. | |
7177 | .TP 8 | |
7178 | .B xtrace | |
7179 | Same as | |
7180 | .BR \-x . | |
ccc6cda3 | 7181 | .sp .5 |
726f6388 | 7182 | .PP |
ccc6cda3 JA |
7183 | If |
7184 | .B \-o | |
7185 | is supplied with no \fIoption\-name\fP, the values of the current options are | |
726f6388 | 7186 | printed. |
ccc6cda3 JA |
7187 | If |
7188 | .B +o | |
7189 | is supplied with no \fIoption\-name\fP, a series of | |
7190 | .B set | |
7191 | commands to recreate the current option settings is displayed on | |
7192 | the standard output. | |
726f6388 JA |
7193 | .RE |
7194 | .TP 8 | |
7195 | .B \-p | |
7196 | Turn on | |
7197 | .I privileged | |
7198 | mode. In this mode, the | |
bb70624e | 7199 | .SM |
726f6388 | 7200 | .B $ENV |
b72432fd | 7201 | and |
bb70624e | 7202 | .SM |
b72432fd JA |
7203 | .B $BASH_ENV |
7204 | files are not processed, shell functions are not inherited from the | |
bb70624e JA |
7205 | environment, and the |
7206 | .SM | |
7207 | .B SHELLOPTS | |
7208 | variable, if it appears in the environment, is ignored. | |
b72432fd JA |
7209 | If the shell is started with the effective user (group) id not equal to the |
7210 | real user (group) id, and the \fB\-p\fP option is not supplied, these actions | |
7211 | are taken and the effective user id is set to the real user id. | |
7212 | If the \fB\-p\fP option is supplied at startup, the effective user id is | |
7213 | not reset. | |
cce855bc | 7214 | Turning this option off causes the effective user |
726f6388 JA |
7215 | and group ids to be set to the real user and group ids. |
7216 | .TP 8 | |
7217 | .B \-t | |
7218 | Exit after reading and executing one command. | |
7219 | .TP 8 | |
7220 | .B \-u | |
7221 | Treat unset variables as an error when performing | |
7222 | parameter expansion. If expansion is attempted on an | |
7223 | unset variable, the shell prints an error message, and, | |
ccc6cda3 | 7224 | if not interactive, exits with a non-zero status. |
726f6388 JA |
7225 | .TP 8 |
7226 | .B \-v | |
7227 | Print shell input lines as they are read. | |
7228 | .TP 8 | |
7229 | .B \-x | |
ccc6cda3 JA |
7230 | After expanding each \fIsimple command\fP, |
7231 | display the expanded value of | |
726f6388 JA |
7232 | .SM |
7233 | .BR PS4 , | |
7234 | followed by the command and its expanded arguments. | |
7235 | .TP 8 | |
ccc6cda3 JA |
7236 | .B \-B |
7237 | The shell performs brace expansion (see | |
7238 | .B Brace Expansion | |
7239 | above). This is on by default. | |
726f6388 JA |
7240 | .TP 8 |
7241 | .B \-C | |
ccc6cda3 JA |
7242 | If set, |
7243 | .B bash | |
7244 | does not overwrite an existing file with the | |
7245 | .BR > , | |
7246 | .BR >& , | |
7247 | and | |
7248 | .B <> | |
7249 | redirection operators. This may be overridden when | |
7250 | creating output files by using the redirection operator | |
7251 | .B >| | |
7252 | instead of | |
7253 | .BR > . | |
726f6388 JA |
7254 | .TP 8 |
7255 | .B \-H | |
7256 | Enable | |
7257 | .B ! | |
cce855bc | 7258 | style history substitution. This option is on by |
726f6388 JA |
7259 | default when the shell is interactive. |
7260 | .TP 8 | |
7261 | .B \-P | |
ccc6cda3 JA |
7262 | If set, the shell does not follow symbolic links when executing |
7263 | commands such as | |
726f6388 | 7264 | .B cd |
ccc6cda3 JA |
7265 | that change the current working directory. It uses the |
7266 | physical directory structure instead. By default, | |
7267 | .B bash | |
7268 | follows the logical chain of directories when performing commands | |
7269 | which change the current directory. | |
726f6388 JA |
7270 | .TP 8 |
7271 | .B \-\- | |
cce855bc | 7272 | If no arguments follow this option, then the positional parameters are |
726f6388 JA |
7273 | unset. Otherwise, the positional parameters are set to the |
7274 | \fIarg\fPs, even if some of them begin with a | |
7275 | .BR \- . | |
7276 | .TP 8 | |
7277 | .B \- | |
7278 | Signal the end of options, cause all remaining \fIarg\fPs to be | |
7279 | assigned to the positional parameters. The | |
7280 | .B \-x | |
7281 | and | |
7282 | .B \-v | |
7283 | options are turned off. | |
7284 | If there are no \fIarg\fPs, | |
7285 | the positional parameters remain unchanged. | |
7286 | .PD | |
7287 | .PP | |
cce855bc JA |
7288 | The options are off by default unless otherwise noted. |
7289 | Using + rather than \- causes these options to be turned off. | |
7290 | The options can also be specified as arguments to an invocation of | |
7291 | the shell. | |
7292 | The current set of options may be found in | |
726f6388 | 7293 | .BR $\- . |
cce855bc | 7294 | The return status is always true unless an invalid option is encountered. |
726f6388 JA |
7295 | .RE |
7296 | .TP | |
7297 | \fBshift\fP [\fIn\fP] | |
7298 | The positional parameters from \fIn\fP+1 ... are renamed to | |
7299 | .B $1 | |
7300 | .B .... | |
7301 | Parameters represented by the numbers \fB$#\fP | |
7302 | down to \fB$#\fP\-\fIn\fP+1 are unset. | |
ccc6cda3 JA |
7303 | .I n |
7304 | must be a non-negative number less than or equal to \fB$#\fP. | |
726f6388 JA |
7305 | If |
7306 | .I n | |
7307 | is 0, no parameters are changed. | |
7308 | If | |
7309 | .I n | |
7310 | is not given, it is assumed to be 1. | |
726f6388 JA |
7311 | If |
7312 | .I n | |
7313 | is greater than \fB$#\fP, the positional parameters are not changed. | |
ccc6cda3 | 7314 | The return status is greater than zero if |
726f6388 JA |
7315 | .I n |
7316 | is greater than | |
7317 | .B $# | |
ccc6cda3 JA |
7318 | or less than zero; otherwise 0. |
7319 | .TP | |
7320 | \fBshopt\fP [\fB\-pqsu\fP] [\fB\-o\fP] [\fIoptname\fP ...] | |
7321 | Toggle the values of variables controlling optional shell behavior. | |
7322 | With no options, or with the | |
7323 | .B \-p | |
7324 | option, a list of all settable options is displayed, with | |
cce855bc JA |
7325 | an indication of whether or not each is set. |
7326 | The \fB\-p\fP option causes output to be displayed in a form that | |
7327 | may be reused as input. | |
7328 | Other options have the following meanings: | |
ccc6cda3 JA |
7329 | .RS |
7330 | .PD 0 | |
7331 | .TP | |
7332 | .B \-s | |
7333 | Enable (set) each \fIoptname\fP. | |
7334 | .TP | |
7335 | .B \-u | |
7336 | Disable (unset) each \fIoptname\fP. | |
7337 | .TP | |
7338 | .B \-q | |
7339 | Suppresses normal output (quiet mode); the return status indicates | |
7340 | whether the \fIoptname\fP is set or unset. | |
7341 | If multiple \fIoptname\fP arguments are given with | |
7342 | .BR \-q , | |
7343 | the return status is zero if all \fIoptnames\fP are enabled; non-zero | |
7344 | otherwise. | |
7345 | .TP | |
7346 | .B \-o | |
7347 | Restricts the values of \fIoptname\fP to be those defined for the | |
7348 | .B \-o | |
7349 | option to the | |
7350 | .B set | |
7351 | builtin. | |
7352 | .PD | |
7353 | .PP | |
7354 | If either | |
7355 | .B \-s | |
7356 | or | |
7357 | .B \-u | |
7358 | is used with no \fIoptname\fP arguments, the display is limited to | |
7359 | those options which are set or unset, respectively. | |
7360 | Unless otherwise noted, the \fBshopt\fP options are disabled (unset) | |
7361 | by default. | |
7362 | .PP | |
7363 | The return status when listing options is zero if all \fIoptnames\fP | |
7364 | are enabled, non-zero otherwise. When setting or unsetting options, | |
cce855bc | 7365 | the return status is zero unless an \fIoptname\fP is not a valid shell |
ccc6cda3 JA |
7366 | option. |
7367 | .PP | |
7368 | The list of \fBshopt\fP options is: | |
7369 | .if t .sp .5v | |
7370 | .if n .sp 1v | |
7371 | .PD 0 | |
7372 | .TP 8 | |
7373 | .B cdable_vars | |
7374 | If set, an argument to the | |
7375 | .B cd | |
7376 | builtin command that | |
7377 | is not a directory is assumed to be the name of a variable whose | |
7378 | value is the directory to change to. | |
7379 | .TP 8 | |
7380 | .B cdspell | |
7381 | If set, minor errors in the spelling of a directory component in a | |
7382 | .B cd | |
7383 | command will be corrected. | |
7384 | The errors checked for are transposed characters, | |
7385 | a missing character, and one character too many. | |
7386 | If a correction is found, the corrected file name is printed, | |
7387 | and the command proceeds. | |
d166f048 | 7388 | This option is only used by interactive shells. |
ccc6cda3 JA |
7389 | .TP 8 |
7390 | .B checkhash | |
7391 | If set, \fBbash\fP checks that a command found in the hash | |
7392 | table exists before trying to execute it. If a hashed command no | |
7393 | longer exists, a normal path search is performed. | |
7394 | .TP 8 | |
7395 | .B checkwinsize | |
7396 | If set, \fBbash\fP checks the window size after each command | |
7397 | and, if necessary, updates the values of | |
7398 | .SM | |
7399 | .B LINES | |
7400 | and | |
7401 | .SM | |
7402 | .BR COLUMNS . | |
7403 | .TP 8 | |
7404 | .B cmdhist | |
7405 | If set, | |
7406 | .B bash | |
7407 | attempts to save all lines of a multiple-line | |
7408 | command in the same history entry. This allows | |
7409 | easy re-editing of multi-line commands. | |
7410 | .TP 8 | |
7411 | .B dotglob | |
7412 | If set, | |
7413 | .B bash | |
7414 | includes filenames beginning with a `.' in the results of pathname | |
7415 | expansion. | |
7416 | .TP 8 | |
7417 | .B execfail | |
7418 | If set, a non-interactive shell will not exit if | |
7419 | it cannot execute the file specified as an argument to the | |
7420 | .B exec | |
7421 | builtin command. An interactive shell does not exit if | |
7422 | .B exec | |
7423 | fails. | |
7424 | .TP 8 | |
7425 | .B expand_aliases | |
7426 | If set, aliases are expanded as described above under | |
7427 | .SM | |
7428 | .BR ALIASES . | |
7429 | This option is enabled by default for interactive shells. | |
7430 | .TP 8 | |
cce855bc JA |
7431 | .B extglob |
7432 | If set, the extended pattern matching features described above under | |
7433 | \fBPathname Expansion\fP are enabled. | |
7434 | .TP 8 | |
ccc6cda3 JA |
7435 | .B histappend |
7436 | If set, the history list is appended to the file named by the value | |
7437 | of the | |
7438 | .B HISTFILE | |
7439 | variable when the shell exits, rather than overwriting the file. | |
7440 | .TP 8 | |
7441 | .B histreedit | |
7442 | If set, and | |
7443 | .B readline | |
7444 | is being used, a user is given the opportunity to re-edit a | |
7445 | failed history substitution. | |
7446 | .TP 8 | |
7447 | .B histverify | |
7448 | If set, and | |
7449 | .B readline | |
7450 | is being used, the results of history substitution are not immediately | |
7451 | passed to the shell parser. Instead, the resulting line is loaded into | |
7452 | the \fBreadline\fP editing buffer, allowing further modification. | |
7453 | .TP 8 | |
7454 | .B hostcomplete | |
7455 | If set, and | |
7456 | .B readline | |
cce855bc JA |
7457 | is being used, \fBbash\fP will attempt to perform hostname completion when a |
7458 | word containing a \fB@\fP is being completed (see | |
ccc6cda3 JA |
7459 | .B Completing |
7460 | under | |
7461 | .SM | |
7462 | .B READLINE | |
7463 | above). | |
7464 | This is enabled by default. | |
7465 | .TP 8 | |
cce855bc JA |
7466 | .B huponexit |
7467 | If set, \fBbash\fP will send | |
7468 | .SM | |
7469 | .B SIGHUP | |
7470 | to all jobs when an interactive login shell exits. | |
7471 | .TP 8 | |
ccc6cda3 JA |
7472 | .B interactive_comments |
7473 | If set, allow a word beginning with | |
7474 | .B # | |
7475 | to cause that word and all remaining characters on that | |
7476 | line to be ignored in an interactive shell (see | |
7477 | .SM | |
7478 | .B COMMENTS | |
7479 | above). This option is enabled by default. | |
7480 | .TP 8 | |
7481 | .B lithist | |
7482 | If set, and the | |
7483 | .B cmdhist | |
7484 | option is enabled, multi-line commands are saved to the history with | |
7485 | embedded newlines rather than using semicolon separators where possible. | |
7486 | .TP 8 | |
f73dda09 JA |
7487 | .B login_shell |
7488 | The shell sets this option if it is started as a login shell (see | |
7489 | .SM | |
7490 | .B "INVOCATION" | |
7491 | above). | |
7492 | The value may not be changed. | |
7493 | .TP 8 | |
ccc6cda3 JA |
7494 | .B mailwarn |
7495 | If set, and a file that \fBbash\fP is checking for mail has been | |
7496 | accessed since the last time it was checked, the message ``The mail in | |
7497 | \fImailfile\fP has been read'' is displayed. | |
7498 | .TP 8 | |
bb70624e JA |
7499 | .B no_empty_cmd_completion |
7500 | If set, and | |
7501 | .B readline | |
7502 | is being used, | |
7503 | .B bash | |
7504 | will not attempt to search the \fBPATH\fP for possible completions when | |
7505 | completion is attempted on an empty line. | |
7506 | .TP 8 | |
cce855bc JA |
7507 | .B nocaseglob |
7508 | If set, | |
7509 | .B bash | |
7510 | matches filenames in a case\-insensitive fashion when performing pathname | |
7511 | expansion (see | |
7512 | .B Pathname Expansion | |
7513 | above). | |
7514 | .TP 8 | |
ccc6cda3 JA |
7515 | .B nullglob |
7516 | If set, | |
7517 | .B bash | |
7518 | allows patterns which match no | |
7519 | files (see | |
7520 | .B Pathname Expansion | |
7521 | above) | |
7522 | to expand to a null string, rather than themselves. | |
7523 | .TP 8 | |
bb70624e JA |
7524 | .B progcomp |
7525 | If set, the programmable completion facilities (see | |
7526 | \fBProgrammable Completion\fP above) are enabled. | |
7527 | This option is enabled by default. | |
7528 | .TP 8 | |
ccc6cda3 JA |
7529 | .B promptvars |
7530 | If set, prompt strings undergo variable and parameter expansion after | |
7531 | being expanded as described in | |
7532 | .SM | |
7533 | .B PROMPTING | |
7534 | above. This option is enabled by default. | |
7535 | .TP 8 | |
b72432fd JA |
7536 | .B restricted_shell |
7537 | The shell sets this option if it is started in restricted mode (see | |
7538 | .SM | |
7539 | .B "RESTRICTED SHELL" | |
7540 | below). | |
7541 | The value may not be changed. | |
7542 | This is not reset when the startup files are executed, allowing | |
7543 | the startup files to discover whether or not a shell is restricted. | |
7544 | .TP 8 | |
ccc6cda3 JA |
7545 | .B shift_verbose |
7546 | If set, the | |
7547 | .B shift | |
7548 | builtin prints an error message when the shift count exceeds the | |
7549 | number of positional parameters. | |
7550 | .TP 8 | |
7551 | .B sourcepath | |
7552 | If set, the | |
7553 | \fBsource\fP (\fB.\fP) builtin uses the value of | |
7554 | .SM | |
7555 | .B PATH | |
7556 | to find the directory containing the file supplied as an argument. | |
cce855bc | 7557 | This option is enabled by default. |
bb70624e JA |
7558 | .TP 8 |
7559 | .B xpg_echo | |
7560 | If set, the \fBecho\fP builtin expands backslash-escape sequences | |
7561 | by default. | |
ccc6cda3 | 7562 | .RE |
726f6388 JA |
7563 | .TP |
7564 | \fBsuspend\fP [\fB\-f\fP] | |
7565 | Suspend the execution of this shell until it receives a | |
7566 | .SM | |
7567 | .B SIGCONT | |
7568 | signal. The | |
7569 | .B \-f | |
7570 | option says not to complain if this is | |
7571 | a login shell; just suspend anyway. The return status is 0 unless | |
7572 | the shell is a login shell and | |
7573 | .B \-f | |
7574 | is not supplied, or if job control is not enabled. | |
7575 | .TP | |
7576 | .PD 0 | |
7577 | \fBtest\fP \fIexpr\fP | |
7578 | .TP | |
7579 | \fB[\fP \fIexpr\fP \fB]\fP | |
ccc6cda3 | 7580 | Return a status of 0 or 1 depending on |
726f6388 JA |
7581 | the evaluation of the conditional expression |
7582 | .IR expr . | |
cce855bc JA |
7583 | Each operator and operand must be a separate argument. |
7584 | Expressions are composed of the primaries described above under | |
7585 | .SM | |
7586 | .BR "CONDITIONAL EXPRESSIONS" . | |
7587 | .if t .sp 0.5 | |
7588 | .if n .sp 1 | |
7589 | Expressions may be combined using the following operators, listed | |
7590 | in decreasing order of precedence. | |
726f6388 JA |
7591 | .RS |
7592 | .PD 0 | |
7593 | .TP | |
726f6388 JA |
7594 | .B ! \fIexpr\fP |
7595 | True if | |
7596 | .I expr | |
7597 | is false. | |
7598 | .TP | |
cce855bc JA |
7599 | .B ( \fIexpr\fP ) |
7600 | Returns the value of \fIexpr\fP. | |
7601 | This may be used to override the normal precedence of operators. | |
7602 | .TP | |
726f6388 JA |
7603 | \fIexpr1\fP \-\fBa\fP \fIexpr2\fP |
7604 | True if both | |
7605 | .I expr1 | |
cce855bc | 7606 | and |
726f6388 JA |
7607 | .I expr2 |
7608 | are true. | |
7609 | .TP | |
7610 | \fIexpr1\fP \-\fBo\fP \fIexpr2\fP | |
7611 | True if either | |
7612 | .I expr1 | |
cce855bc | 7613 | or |
726f6388 JA |
7614 | .I expr2 |
7615 | is true. | |
cce855bc JA |
7616 | .PD |
7617 | .PP | |
7618 | \fBtest\fP and \fB[\fP evaluate conditional | |
7619 | expressions using a set of rules based on the number of arguments. | |
7620 | .if t .sp 0.5 | |
7621 | .if n .sp 1 | |
7622 | .PD 0 | |
726f6388 | 7623 | .TP |
cce855bc JA |
7624 | 0 arguments |
7625 | The expression is false. | |
7626 | .TP | |
7627 | 1 argument | |
7628 | The expression is true if and only if the argument is not null. | |
7629 | .TP | |
7630 | 2 arguments | |
7631 | If the first argument is \fB!\fP, the expression is true if and | |
7632 | only if the second argument is null. | |
7633 | If the first argument is one of the unary conditional operators listed above | |
7634 | under | |
726f6388 | 7635 | .SM |
cce855bc JA |
7636 | .BR "CONDITIONAL EXPRESSIONS" , |
7637 | the expression is true if the unary test is true. | |
7638 | If the first argument is not a valid unary conditional operator, the expression | |
7639 | is false. | |
7640 | .TP | |
7641 | 3 arguments | |
7642 | If the second argument is one of the binary conditional operators listed above | |
7643 | under | |
7644 | .SM | |
7645 | .BR "CONDITIONAL EXPRESSIONS" , | |
7646 | the result of the expression is the result of the binary test using | |
7647 | the first and third arguments as operands. | |
7648 | If the first argument is \fB!\fP, the value is the negation of | |
7649 | the two-argument test using the second and third arguments. | |
7650 | If the first argument is exactly \fB(\fP and the third argument is | |
7651 | exactly \fB)\fP, the result is the one-argument test of the second | |
7652 | argument. | |
7653 | Otherwise, the expression is false. | |
7654 | The \fB\-a\fP and \fB\-o\fP operators are considered binary operators | |
7655 | in this case. | |
7656 | .TP | |
7657 | 4 arguments | |
7658 | If the first argument is \fB!\fP, the result is the negation of | |
7659 | the three-argument expression composed of the remaining arguments. | |
7660 | Otherwise, the expression is parsed and evaluated according to | |
7661 | precedence using the rules listed above. | |
7662 | .TP | |
7663 | 5 or more arguments | |
7664 | The expression is parsed and evaluated according to precedence | |
7665 | using the rules listed above. | |
726f6388 | 7666 | .RE |
cce855bc | 7667 | .PD |
726f6388 JA |
7668 | .TP |
7669 | .B times | |
7670 | Print the accumulated user and system times for the shell and | |
7671 | for processes run from the shell. The return status is 0. | |
7672 | .TP | |
d166f048 | 7673 | \fBtrap\fP [\fB\-lp\fP] [\fIarg\fP] [\fIsigspec\fP ...] |
726f6388 JA |
7674 | The command |
7675 | .I arg | |
7676 | is to be read and executed when the shell receives | |
7677 | signal(s) | |
7678 | .IR sigspec . | |
7679 | If | |
7680 | .I arg | |
7681 | is absent or | |
7682 | .BR \- , | |
7683 | all specified signals are | |
7684 | reset to their original values (the values they had | |
d166f048 JA |
7685 | upon entrance to the shell). |
7686 | If | |
726f6388 | 7687 | .I arg |
d166f048 JA |
7688 | is the null string the signal specified by each |
7689 | .I sigspec | |
7690 | is ignored by the shell and by the commands it invokes. | |
ccc6cda3 JA |
7691 | If |
7692 | .I arg | |
bb70624e | 7693 | is not present and |
ccc6cda3 | 7694 | .B \-p |
bb70624e | 7695 | has been supplied, then the trap commands associated with each |
ccc6cda3 | 7696 | .I sigspec |
bb70624e JA |
7697 | are displayed. |
7698 | If no arguments are supplied or if only | |
ccc6cda3 JA |
7699 | .B \-p |
7700 | is given, | |
7701 | .B trap | |
7702 | prints the list of commands associated with each signal number. | |
d166f048 | 7703 | Each |
726f6388 JA |
7704 | .I sigspec |
7705 | is either | |
d166f048 JA |
7706 | a signal name defined in <\fIsignal.h\fP>, or a signal number. |
7707 | If a | |
726f6388 JA |
7708 | .I sigspec |
7709 | is | |
7710 | .SM | |
7711 | .B EXIT | |
7712 | (0) the command | |
7713 | .I arg | |
f73dda09 JA |
7714 | is executed on exit from the shell. |
7715 | If a | |
ccc6cda3 JA |
7716 | .I sigspec |
7717 | is | |
7718 | .SM | |
7719 | .BR DEBUG , | |
7720 | the command | |
7721 | .I arg | |
7722 | is executed after every \fIsimple command\fP (see | |
7723 | .SM | |
7724 | .B SHELL GRAMMAR | |
7725 | above). | |
f73dda09 JA |
7726 | If a |
7727 | .I sigspec | |
7728 | is | |
7729 | .SM | |
7730 | .BR ERR , | |
7731 | the command | |
7732 | .I arg | |
7733 | is executed whenever a simple command has a non\-zero exit status. | |
7734 | The | |
7735 | .SM | |
7736 | .BR ERR | |
7737 | trap is not executed if the failed command is part of an | |
7738 | .I until | |
7739 | or | |
7740 | .I while | |
7741 | loop, | |
7742 | part of an | |
7743 | .I if | |
7744 | statement, part of a | |
7745 | .B && | |
7746 | or | |
7747 | .B \(bv\(bv | |
7748 | list, or if the command's return value is | |
7749 | being inverted via | |
7750 | .BR ! . | |
ccc6cda3 | 7751 | The |
726f6388 | 7752 | .B \-l |
ccc6cda3 JA |
7753 | option causes the shell to print a list of signal names and |
7754 | their corresponding numbers. | |
726f6388 JA |
7755 | Signals ignored upon entry to the shell cannot be trapped or reset. |
7756 | Trapped signals are reset to their original values in a child | |
d166f048 JA |
7757 | process when it is created. |
7758 | The return status is false if any | |
ccc6cda3 JA |
7759 | .I sigspec |
7760 | is invalid; otherwise | |
726f6388 JA |
7761 | .B trap |
7762 | returns true. | |
7763 | .TP | |
cce855bc | 7764 | \fBtype\fP [\fB\-atp\fP] \fIname\fP [\fIname\fP ...] |
726f6388 JA |
7765 | With no options, |
7766 | indicate how each | |
7767 | .I name | |
7768 | would be interpreted if used as a command name. | |
7769 | If the | |
cce855bc JA |
7770 | .B \-t |
7771 | option is used, | |
726f6388 | 7772 | .B type |
ccc6cda3 | 7773 | prints a string which is one of |
726f6388 JA |
7774 | .IR alias , |
7775 | .IR keyword , | |
7776 | .IR function , | |
7777 | .IR builtin , | |
7778 | or | |
7779 | .I file | |
7780 | if | |
7781 | .I name | |
7782 | is an alias, shell reserved word, function, builtin, or disk file, | |
ccc6cda3 JA |
7783 | respectively. |
7784 | If the | |
7785 | .I name | |
7786 | is not found, then nothing is printed, and an exit status of false | |
7787 | is returned. | |
726f6388 | 7788 | If the |
cce855bc JA |
7789 | .B \-p |
7790 | option is used, | |
726f6388 JA |
7791 | .B type |
7792 | either returns the name of the disk file | |
7793 | that would be executed if | |
7794 | .I name | |
7795 | were specified as a command name, | |
28ef6c31 JA |
7796 | or nothing if |
7797 | .if t \f(CWtype -t name\fP | |
7798 | .if n ``type -t name'' | |
726f6388 JA |
7799 | would not return |
7800 | .IR file . | |
7801 | If a command is hashed, | |
cce855bc | 7802 | .B \-p |
726f6388 JA |
7803 | prints the hashed value, not necessarily the file that appears |
7804 | first in | |
7805 | .SM | |
7806 | .BR PATH . | |
7807 | If the | |
cce855bc JA |
7808 | .B \-a |
7809 | option is used, | |
726f6388 JA |
7810 | .B type |
7811 | prints all of the places that contain | |
7812 | an executable named | |
7813 | .IR name . | |
7814 | This includes aliases and functions, | |
7815 | if and only if the | |
cce855bc JA |
7816 | .B \-p |
7817 | option is not also used. | |
726f6388 JA |
7818 | The table of hashed commands is not consulted |
7819 | when using | |
cce855bc | 7820 | .BR \-a . |
726f6388 JA |
7821 | .B type |
7822 | returns true if any of the arguments are found, false if | |
7823 | none are found. | |
7824 | .TP | |
ccc6cda3 JA |
7825 | \fBulimit\fP [\fB\-SHacdflmnpstuv\fP [\fIlimit\fP]] |
7826 | Provides control over the resources available to the shell and to | |
f73dda09 | 7827 | processes started by it, on systems that allow such control. |
ccc6cda3 | 7828 | The \fB\-H\fP and \fB\-S\fP options specify that the hard or soft limit is |
726f6388 JA |
7829 | set for the given resource. A hard limit cannot be increased once it |
7830 | is set; a soft limit may be increased up to the value of the hard limit. | |
ccc6cda3 JA |
7831 | If neither \fB\-H\fP nor \fB\-S\fP is specified, both the soft and hard |
7832 | limits are set. | |
f73dda09 JA |
7833 | The value of |
7834 | .I limit | |
7835 | can be a number in the unit specified for the resource | |
7836 | or one of the special values | |
7837 | .BR hard , | |
7838 | .BR soft , | |
7839 | or | |
7840 | .BR unlimited , | |
7841 | which stand for the current hard limit, the current soft limit, and | |
7842 | no limit, respectively. | |
ccc6cda3 | 7843 | If |
726f6388 JA |
7844 | .I limit |
7845 | is omitted, the current value of the soft limit of the resource is | |
ccc6cda3 JA |
7846 | printed, unless the \fB\-H\fP option is given. When more than one |
7847 | resource is specified, the limit name and unit are printed before the value. | |
726f6388 JA |
7848 | Other options are interpreted as follows: |
7849 | .RS | |
7850 | .PD 0 | |
7851 | .TP | |
7852 | .B \-a | |
ccc6cda3 | 7853 | All current limits are reported |
726f6388 JA |
7854 | .TP |
7855 | .B \-c | |
ccc6cda3 | 7856 | The maximum size of core files created |
726f6388 JA |
7857 | .TP |
7858 | .B \-d | |
ccc6cda3 | 7859 | The maximum size of a process's data segment |
726f6388 JA |
7860 | .TP |
7861 | .B \-f | |
ccc6cda3 | 7862 | The maximum size of files created by the shell |
726f6388 | 7863 | .TP |
ccc6cda3 JA |
7864 | .B \-l |
7865 | The maximum size that may be locked into memory | |
726f6388 | 7866 | .TP |
ccc6cda3 JA |
7867 | .B \-m |
7868 | The maximum resident set size | |
726f6388 | 7869 | .TP |
ccc6cda3 JA |
7870 | .B \-n |
7871 | The maximum number of open file descriptors (most systems do not | |
7872 | allow this value to be set) | |
726f6388 JA |
7873 | .TP |
7874 | .B \-p | |
ccc6cda3 | 7875 | The pipe size in 512-byte blocks (this may not be set) |
726f6388 | 7876 | .TP |
ccc6cda3 JA |
7877 | .B \-s |
7878 | The maximum stack size | |
7879 | .TP | |
7880 | .B \-t | |
7881 | The maximum amount of cpu time in seconds | |
726f6388 JA |
7882 | .TP |
7883 | .B \-u | |
ccc6cda3 | 7884 | The maximum number of processes available to a single user |
726f6388 JA |
7885 | .TP |
7886 | .B \-v | |
7887 | The maximum amount of virtual memory available to the shell | |
7888 | .PD | |
7889 | .PP | |
ccc6cda3 | 7890 | If |
726f6388 JA |
7891 | .I limit |
7892 | is given, it is the new value of the specified resource (the | |
7893 | .B \-a | |
7894 | option is display only). | |
7895 | If no option is given, then | |
7896 | .B \-f | |
7897 | is assumed. Values are in 1024-byte increments, except for | |
7898 | .BR \-t , | |
7899 | which is in seconds, | |
7900 | .BR \-p , | |
7901 | which is in units of 512-byte blocks, | |
7902 | and | |
7903 | .B \-n | |
7904 | and | |
7905 | .BR \-u , | |
f73dda09 JA |
7906 | which are unscaled values. |
7907 | The return status is 0 unless an invalid option or argument is supplied, | |
7908 | or an error occurs while setting a new limit. | |
726f6388 JA |
7909 | .RE |
7910 | .TP | |
cce855bc | 7911 | \fBumask\fP [\fB\-p\fP] [\fB\-S\fP] [\fImode\fP] |
726f6388 JA |
7912 | The user file-creation mask is set to |
7913 | .IR mode . | |
7914 | If | |
7915 | .I mode | |
7916 | begins with a digit, it | |
7917 | is interpreted as an octal number; otherwise | |
7918 | it is interpreted as a symbolic mode mask similar | |
7919 | to that accepted by | |
7920 | .IR chmod (1). | |
7921 | If | |
7922 | .I mode | |
bb70624e | 7923 | is omitted, the current value of the mask is printed. |
ccc6cda3 | 7924 | The |
726f6388 JA |
7925 | .B \-S |
7926 | option causes the mask to be printed in symbolic form; the | |
7927 | default output is an octal number. | |
cce855bc JA |
7928 | If the |
7929 | .B \-p | |
7930 | option is supplied, and | |
7931 | .I mode | |
7932 | is omitted, the output is in a form that may be reused as input. | |
ccc6cda3 | 7933 | The return status is 0 if the mode was successfully changed or if |
726f6388 JA |
7934 | no \fImode\fP argument was supplied, and false otherwise. |
7935 | .TP | |
7936 | \fBunalias\fP [\-\fBa\fP] [\fIname\fP ...] | |
bb70624e | 7937 | Remove each \fIname\fP from the list of defined aliases. If |
726f6388 JA |
7938 | .B \-a |
7939 | is supplied, all alias definitions are removed. The return | |
7940 | value is true unless a supplied | |
7941 | .I name | |
7942 | is not a defined alias. | |
7943 | .TP | |
7944 | \fBunset\fP [\-\fBfv\fP] [\fIname\fP ...] | |
7945 | For each | |
7946 | .IR name , | |
ccc6cda3 JA |
7947 | remove the corresponding variable or function. |
7948 | If no options are supplied, or the | |
7949 | .B \-v | |
7950 | option is given, each | |
7951 | .I name | |
7952 | refers to a shell variable. | |
7953 | Read-only variables may not be unset. | |
7954 | If | |
726f6388 | 7955 | .B \-f |
ccc6cda3 JA |
7956 | is specifed, |
7957 | each | |
7958 | .I name | |
7959 | refers to a shell function, and the function definition | |
7960 | is removed. | |
7961 | Each unset variable or function is removed from the environment | |
7962 | passed to subsequent commands. | |
7963 | If any of | |
726f6388 JA |
7964 | .SM |
7965 | .BR RANDOM , | |
7966 | .SM | |
7967 | .BR SECONDS , | |
7968 | .SM | |
7969 | .BR LINENO , | |
ccc6cda3 JA |
7970 | .SM |
7971 | .BR HISTCMD , | |
bb70624e JA |
7972 | .SM |
7973 | .BR FUNCNAME , | |
7974 | .SM | |
7975 | .BR GROUPS , | |
726f6388 JA |
7976 | or |
7977 | .SM | |
ccc6cda3 | 7978 | .B DIRSTACK |
726f6388 JA |
7979 | are unset, they lose their special properties, even if they are |
7980 | subsequently reset. The exit status is true unless a | |
7981 | .I name | |
ccc6cda3 | 7982 | does not exist or is readonly. |
726f6388 JA |
7983 | .TP |
7984 | \fBwait\fP [\fIn\fP] | |
7985 | Wait for the specified process and return its termination | |
7986 | status. | |
7987 | .I n | |
7988 | may be a process | |
7989 | ID or a job specification; if a job spec is given, all processes | |
7990 | in that job's pipeline are waited for. If | |
7991 | .I n | |
7992 | is not given, all currently active child processes | |
7993 | are waited for, and the return status is zero. If | |
7994 | .I n | |
ccc6cda3 | 7995 | specifies a non-existent process or job, the return status is |
726f6388 JA |
7996 | 127. Otherwise, the return status is the exit status of the last |
7997 | process or job waited for. | |
7998 | .\" bash_builtins | |
7999 | .if \n(zZ=1 .ig zZ | |
ccc6cda3 | 8000 | .SH "RESTRICTED SHELL" |
bb70624e JA |
8001 | .\" rbash.1 |
8002 | .zY | |
726f6388 | 8003 | .PP |
ccc6cda3 | 8004 | If |
726f6388 | 8005 | .B bash |
ccc6cda3 JA |
8006 | is started with the name |
8007 | .BR rbash , | |
8008 | or the | |
8009 | .B \-r | |
8010 | option is supplied at invocation, | |
8011 | the shell becomes restricted. | |
8012 | A restricted shell is used to | |
8013 | set up an environment more controlled than the standard shell. | |
8014 | It behaves identically to | |
8015 | .B bash | |
cce855bc | 8016 | with the exception that the following are disallowed or not performed: |
ccc6cda3 JA |
8017 | .IP \(bu |
8018 | changing directories with \fBcd\fP | |
8019 | .IP \(bu | |
8020 | setting or unsetting the values of | |
b72432fd JA |
8021 | .BR SHELL , |
8022 | .BR PATH , | |
8023 | .BR ENV , | |
ccc6cda3 | 8024 | or |
b72432fd | 8025 | .B BASH_ENV |
ccc6cda3 JA |
8026 | .IP \(bu |
8027 | specifying command names containing | |
8028 | .B / | |
8029 | .IP \(bu | |
8030 | specifying a file name containing a | |
8031 | .B / | |
8032 | as an argument to the | |
8033 | .B . | |
8034 | builtin command | |
8035 | .IP \(bu | |
bb70624e JA |
8036 | Specifying a filename containing a slash as an argument to the |
8037 | .B \-p | |
8038 | option to the | |
8039 | .B hash | |
8040 | builtin command | |
8041 | .IP \(bu | |
ccc6cda3 JA |
8042 | importing function definitions from the shell environment at startup |
8043 | .IP \(bu | |
cce855bc JA |
8044 | parsing the value of \fBSHELLOPTS\fP from the shell environment at startup |
8045 | .IP \(bu | |
ccc6cda3 JA |
8046 | redirecting output using the >, >|, <>, >&, &>, and >> redirection operators |
8047 | .IP \(bu | |
8048 | using the | |
8049 | .B exec | |
8050 | builtin command to replace the shell with another command | |
8051 | .IP \(bu | |
8052 | adding or deleting builtin commands with the | |
8053 | .B \-f | |
726f6388 | 8054 | and |
ccc6cda3 JA |
8055 | .B \-d |
8056 | options to the | |
8057 | .B enable | |
8058 | builtin command | |
8059 | .IP \(bu | |
8060 | specifying the | |
8061 | .B \-p | |
8062 | option to the | |
8063 | .B command | |
8064 | builtin command | |
8065 | .IP \(bu | |
8066 | turning off restricted mode with | |
cce855bc | 8067 | \fBset +r\fP or \fBset +o restricted\fP. |
726f6388 | 8068 | .PP |
ccc6cda3 JA |
8069 | These restrictions are enforced after any startup files are read. |
8070 | .PP | |
8071 | When a command that is found to be a shell script is executed (see | |
8072 | .SM | |
8073 | .B "COMMAND EXECUTION" | |
8074 | above), | |
8075 | .B rbash | |
8076 | turns off any restrictions in the shell spawned to execute the | |
8077 | script. | |
bb70624e JA |
8078 | .\" end of rbash.1 |
8079 | .if \n(zY=1 .ig zY | |
726f6388 JA |
8080 | .SH "SEE ALSO" |
8081 | .PD 0 | |
8082 | .TP | |
bb70624e | 8083 | \fIBash Reference Manual\fP, Brian Fox and Chet Ramey |
726f6388 JA |
8084 | .TP |
8085 | \fIThe Gnu Readline Library\fP, Brian Fox and Chet Ramey | |
8086 | .TP | |
8087 | \fIThe Gnu History Library\fP, Brian Fox and Chet Ramey | |
8088 | .TP | |
726f6388 JA |
8089 | \fIPortable Operating System Interface (POSIX) Part 2: Shell and Utilities\fP, IEEE |
8090 | .TP | |
8091 | \fIsh\fP(1), \fIksh\fP(1), \fIcsh\fP(1) | |
8092 | .TP | |
8093 | \fIemacs\fP(1), \fIvi\fP(1) | |
8094 | .TP | |
8095 | \fIreadline\fP(3) | |
8096 | .PD | |
8097 | .SH FILES | |
8098 | .PD 0 | |
8099 | .TP | |
8100 | .FN /bin/bash | |
8101 | The \fBbash\fP executable | |
8102 | .TP | |
8103 | .FN /etc/profile | |
8104 | The systemwide initialization file, executed for login shells | |
8105 | .TP | |
8106 | .FN ~/.bash_profile | |
8107 | The personal initialization file, executed for login shells | |
8108 | .TP | |
8109 | .FN ~/.bashrc | |
8110 | The individual per-interactive-shell startup file | |
8111 | .TP | |
b72432fd JA |
8112 | .FN ~/.bash_logout |
8113 | The individual login shell cleanup file, executed when a login shell exits | |
8114 | .TP | |
726f6388 JA |
8115 | .FN ~/.inputrc |
8116 | Individual \fIreadline\fP initialization file | |
8117 | .PD | |
8118 | .SH AUTHORS | |
ccc6cda3 | 8119 | Brian Fox, Free Software Foundation |
726f6388 | 8120 | .br |
bb70624e | 8121 | bfox@gnu.org |
726f6388 JA |
8122 | .PP |
8123 | Chet Ramey, Case Western Reserve University | |
8124 | .br | |
8125 | chet@ins.CWRU.Edu | |
8126 | .SH BUG REPORTS | |
8127 | If you find a bug in | |
8128 | .B bash, | |
8129 | you should report it. But first, you should | |
8130 | make sure that it really is a bug, and that it appears in the latest | |
8131 | version of | |
8132 | .B bash | |
8133 | that you have. | |
8134 | .PP | |
8135 | Once you have determined that a bug actually exists, use the | |
8136 | .I bashbug | |
8137 | command to submit a bug report. | |
d166f048 | 8138 | If you have a fix, you are encouraged to mail that as well! |
726f6388 | 8139 | Suggestions and `philosophical' bug reports may be mailed |
cce855bc | 8140 | to \fIbug-bash@gnu.org\fP or posted to the Usenet |
726f6388 JA |
8141 | newsgroup |
8142 | .BR gnu.bash.bug . | |
8143 | .PP | |
8144 | ALL bug reports should include: | |
8145 | .PP | |
8146 | .PD 0 | |
8147 | .TP 20 | |
8148 | The version number of \fBbash\fR | |
8149 | .TP | |
8150 | The hardware and operating system | |
8151 | .TP | |
8152 | The compiler used to compile | |
8153 | .TP | |
8154 | A description of the bug behaviour | |
8155 | .TP | |
8156 | A short script or `recipe' which exercises the bug | |
8157 | .PD | |
8158 | .PP | |
8159 | .I bashbug | |
8160 | inserts the first three items automatically into the template | |
8161 | it provides for filing a bug report. | |
8162 | .PP | |
8163 | Comments and bug reports concerning | |
8164 | this manual page should be directed to | |
8165 | .IR chet@ins.CWRU.Edu . | |
8166 | .SH BUGS | |
8167 | .PP | |
8168 | It's too big and too slow. | |
8169 | .PP | |
8170 | There are some subtle differences between | |
8171 | .B bash | |
8172 | and traditional versions of | |
8173 | .BR sh , | |
8174 | mostly because of the | |
8175 | .SM | |
8176 | .B POSIX | |
8177 | specification. | |
8178 | .PP | |
8179 | Aliases are confusing in some uses. | |
ccc6cda3 JA |
8180 | .PP |
8181 | Shell builtin commands and functions are not stoppable/restartable. | |
8182 | .PP | |
8183 | Compound commands and command sequences of the form `a ; b ; c' | |
8184 | are not handled gracefully when process suspension is attempted. | |
8185 | When a process is stopped, the shell immediately executes the next | |
8186 | command in the sequence. | |
8187 | It suffices to place the sequence of commands between | |
8188 | parentheses to force it into a subshell, which may be stopped as | |
8189 | a unit. | |
8190 | .PP | |
8191 | Commands inside of \fB$(\fP...\fB)\fP command substitution are not | |
8192 | parsed until substitution is attempted. This will delay error | |
8193 | reporting until some time after the command is entered. | |
8194 | .PP | |
8195 | Array variables may not (yet) be exported. | |
726f6388 | 8196 | .zZ |
bb70624e | 8197 | .zY |