]>
Commit | Line | Data |
---|---|---|
17345e5a JA |
1 | <HTML><HEAD> |
2 | <TITLE>BASH(1) Manual Page</TITLE> | |
3 | </HEAD> | |
4 | <BODY><TABLE WIDTH=100%> | |
5 | <TR> | |
a0c0a00f | 6 | <TH ALIGN=LEFT width=33%>BASH(1)<TH ALIGN=CENTER width=33%>2016 August 26<TH ALIGN=RIGHT width=33%>BASH(1) |
17345e5a JA |
7 | </TR> |
8 | </TABLE> | |
9 | <BR><A HREF="#index">Index</A> | |
10 | <HR> | |
11 | ||
12 | ||
13 | ||
14 | ||
15 | ||
16 | ||
17 | ||
18 | ||
19 | ||
20 | ||
21 | ||
22 | ||
23 | ||
24 | ||
25 | ||
26 | ||
27 | ||
28 | ||
29 | ||
30 | <A NAME="lbAB"> </A> | |
31 | <H3>NAME</H3> | |
32 | ||
33 | bash - GNU Bourne-Again SHell | |
34 | <A NAME="lbAC"> </A> | |
35 | <H3>SYNOPSIS</H3> | |
36 | ||
37 | <B>bash</B> | |
38 | ||
39 | [options] | |
ac50fbac | 40 | [command_string | file] |
17345e5a JA |
41 | <A NAME="lbAD"> </A> |
42 | <H3>COPYRIGHT</H3> | |
43 | ||
44 | ||
a0c0a00f | 45 | Bash is Copyright © 1989-2016 by the Free Software Foundation, Inc. |
17345e5a JA |
46 | <A NAME="lbAE"> </A> |
47 | <H3>DESCRIPTION</H3> | |
48 | ||
49 | <B>Bash</B> | |
50 | ||
51 | is an <B>sh</B>-compatible command language interpreter that | |
52 | executes commands read from the standard input or from a file. | |
53 | <B>Bash</B> | |
54 | ||
55 | also incorporates useful features from the <I>Korn</I> and <I>C</I> | |
56 | shells (<B>ksh</B> and <B>csh</B>). | |
57 | <P> | |
58 | ||
59 | <B>Bash</B> | |
60 | ||
61 | is intended to be a conformant implementation of the | |
62 | Shell and Utilities portion of the IEEE POSIX specification | |
63 | (IEEE Standard 1003.1). | |
64 | <B>Bash</B> | |
65 | ||
66 | can be configured to be POSIX-conformant by default. | |
67 | <A NAME="lbAF"> </A> | |
68 | <H3>OPTIONS</H3> | |
69 | ||
a0c0a00f | 70 | All of the single-character shell options documented in the |
495aee44 CR |
71 | description of the <B>set</B> builtin command can be used as options |
72 | when the shell is invoked. | |
73 | In addition, <B>bash</B> | |
17345e5a JA |
74 | interprets the following options when it is invoked: |
75 | <P> | |
76 | ||
77 | ||
78 | <DL COMPACT> | |
ac50fbac | 79 | <DT><B>-c</B> |
17345e5a JA |
80 | |
81 | <DD> | |
82 | If the | |
83 | <B>-c</B> | |
84 | ||
ac50fbac CR |
85 | option is present, then commands are read from the first non-option argument |
86 | <I>command_string</I>. | |
17345e5a JA |
87 | |
88 | If there are arguments after the | |
ac50fbac | 89 | <I>command_string</I>, |
17345e5a | 90 | |
a0c0a00f CR |
91 | the first argument is assigned to |
92 | <B>$0</B> | |
93 | ||
94 | and any remaining arguments are assigned to the positional parameters. | |
95 | The assignment to | |
96 | <B>$0</B> | |
17345e5a | 97 | |
a0c0a00f | 98 | sets the name of the shell, which is used in warning and error messages. |
17345e5a JA |
99 | <DT><B>-i</B> |
100 | ||
101 | <DD> | |
102 | If the | |
103 | <B>-i</B> | |
104 | ||
105 | option is present, the shell is | |
106 | <I>interactive</I>. | |
107 | ||
108 | <DT><B>-l</B> | |
109 | ||
110 | <DD> | |
111 | Make | |
112 | <B>bash</B> | |
113 | ||
114 | act as if it had been invoked as a login shell (see | |
115 | <FONT SIZE=-1><B>INVOCATION</B> | |
116 | ||
117 | </FONT> | |
118 | below). | |
119 | <DT><B>-r</B> | |
120 | ||
121 | <DD> | |
122 | If the | |
123 | <B>-r</B> | |
124 | ||
125 | option is present, the shell becomes | |
126 | <I>restricted</I> | |
127 | ||
128 | (see | |
129 | <FONT SIZE=-1><B>RESTRICTED SHELL</B> | |
130 | ||
131 | </FONT> | |
132 | below). | |
133 | <DT><B>-s</B> | |
134 | ||
135 | <DD> | |
136 | If the | |
137 | <B>-s</B> | |
138 | ||
139 | option is present, or if no arguments remain after option | |
140 | processing, then commands are read from the standard input. | |
141 | This option allows the positional parameters to be set | |
142 | when invoking an interactive shell. | |
143 | <DT><B>-D</B> | |
144 | ||
145 | <DD> | |
146 | A list of all double-quoted strings preceded by <B>$</B> | |
147 | is printed on the standard output. | |
148 | These are the strings that | |
149 | are subject to language translation when the current locale | |
150 | is not <B>C</B> or <B>POSIX</B>. | |
151 | This implies the <B>-n</B> option; no commands will be executed. | |
152 | <DT><B>[-+]O [</B><I>shopt_option</I>] | |
153 | ||
154 | <DD> | |
155 | <I>shopt_option</I> is one of the shell options accepted by the | |
156 | <B>shopt</B> builtin (see | |
157 | <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B> | |
158 | ||
159 | </FONT> | |
160 | below). | |
161 | If <I>shopt_option</I> is present, <B>-O</B> sets the value of that option; | |
162 | <B>+O</B> unsets it. | |
163 | If <I>shopt_option</I> is not supplied, the names and values of the shell | |
164 | options accepted by <B>shopt</B> are printed on the standard output. | |
165 | If the invocation option is <B>+O</B>, the output is displayed in a format | |
166 | that may be reused as input. | |
167 | <DT><B>--</B> | |
168 | ||
169 | <DD> | |
170 | A | |
171 | <B>--</B> | |
172 | ||
173 | signals the end of options and disables further option processing. | |
174 | Any arguments after the | |
175 | <B>--</B> | |
176 | ||
177 | are treated as filenames and arguments. An argument of | |
178 | <B>-</B> | |
179 | ||
180 | is equivalent to <B>--</B>. | |
181 | ||
182 | </DL> | |
183 | <P> | |
184 | ||
185 | <B>Bash</B> | |
186 | ||
187 | also interprets a number of multi-character options. | |
188 | These options must appear on the command line before the | |
189 | single-character options to be recognized. | |
190 | <P> | |
191 | ||
192 | ||
193 | <DL COMPACT> | |
194 | <DT><B>--debugger</B> | |
195 | ||
196 | <DD> | |
197 | Arrange for the debugger profile to be executed before the shell | |
198 | starts. | |
199 | Turns on extended debugging mode (see the description of the | |
200 | <B>extdebug</B> | |
201 | ||
202 | option to the | |
203 | <B>shopt</B> | |
204 | ||
17345e5a JA |
205 | builtin below). |
206 | <DT><B>--dump-po-strings</B> | |
207 | ||
208 | <DD> | |
209 | Equivalent to <B>-D</B>, but the output is in the GNU <I>gettext</I> | |
210 | <B>po</B> (portable object) file format. | |
211 | <DT><B>--dump-strings</B> | |
212 | ||
213 | <DD> | |
214 | Equivalent to <B>-D</B>. | |
215 | <DT><B>--help</B> | |
216 | ||
217 | <DD> | |
218 | Display a usage message on standard output and exit successfully. | |
219 | <DT><B>--init-file</B> <I>file</I><DD> | |
220 | ||
221 | <DT><B>--rcfile</B> <I>file</I><DD> | |
222 | ||
223 | Execute commands from | |
224 | <I>file</I> | |
225 | ||
226 | instead of the standard personal initialization file | |
227 | <A HREF="file:~/.bashrc"><I>~/.bashrc</I></A> | |
228 | ||
229 | if the shell is interactive (see | |
230 | <FONT SIZE=-1><B>INVOCATION</B> | |
231 | ||
232 | </FONT> | |
233 | below). | |
234 | <DT><B>--login</B> | |
235 | ||
236 | <DD> | |
237 | Equivalent to <B>-l</B>. | |
238 | <DT><B>--noediting</B> | |
239 | ||
240 | <DD> | |
241 | Do not use the GNU | |
242 | <B>readline</B> | |
243 | ||
244 | library to read command lines when the shell is interactive. | |
245 | <DT><B>--noprofile</B> | |
246 | ||
247 | <DD> | |
248 | Do not read either the system-wide startup file | |
249 | ||
250 | <A HREF="file:/etc/profile"><I>/etc/profile</I></A> | |
251 | ||
252 | or any of the personal initialization files | |
253 | <A HREF="file:~/.bash_profile"><I>~/.bash_profile</I></A>, | |
254 | ||
255 | <A HREF="file:~/.bash_login"><I>~/.bash_login</I></A>, | |
256 | ||
257 | or | |
258 | <A HREF="file:~/.profile"><I>~/.profile</I></A>. | |
259 | ||
260 | By default, | |
261 | <B>bash</B> | |
262 | ||
263 | reads these files when it is invoked as a login shell (see | |
264 | <FONT SIZE=-1><B>INVOCATION</B> | |
265 | ||
266 | </FONT> | |
267 | below). | |
268 | <DT><B>--norc</B> | |
269 | ||
270 | <DD> | |
271 | Do not read and execute the personal initialization file | |
272 | <A HREF="file:~/.bashrc"><I>~/.bashrc</I></A> | |
273 | ||
274 | if the shell is interactive. | |
275 | This option is on by default if the shell is invoked as | |
276 | <B>sh</B>. | |
277 | ||
278 | <DT><B>--posix</B> | |
279 | ||
280 | <DD> | |
281 | Change the behavior of <B>bash</B> where the default operation differs | |
282 | from the POSIX standard to match the standard (<I>posix mode</I>). | |
ac50fbac CR |
283 | See |
284 | <FONT SIZE=-1><B>SEE ALSO</B> | |
285 | ||
286 | </FONT> | |
287 | below for a reference to a document that details how posix mode affects | |
288 | bash's behavior. | |
17345e5a JA |
289 | <DT><B>--restricted</B> |
290 | ||
291 | <DD> | |
292 | The shell becomes restricted (see | |
293 | <FONT SIZE=-1><B>RESTRICTED SHELL</B> | |
294 | ||
295 | </FONT> | |
296 | below). | |
297 | <DT><B>--verbose</B> | |
298 | ||
299 | <DD> | |
a0c0a00f | 300 | Equivalent to <B>-v</B>. |
17345e5a JA |
301 | <DT><B>--version</B> |
302 | ||
303 | <DD> | |
304 | Show version information for this instance of | |
305 | <B>bash</B> | |
306 | ||
307 | on the standard output and exit successfully. | |
308 | ||
309 | </DL> | |
310 | <A NAME="lbAG"> </A> | |
311 | <H3>ARGUMENTS</H3> | |
312 | ||
313 | If arguments remain after option processing, and neither the | |
314 | <B>-c</B> | |
315 | ||
316 | nor the | |
317 | <B>-s</B> | |
318 | ||
319 | option has been supplied, the first argument is assumed to | |
320 | be the name of a file containing shell commands. | |
321 | If | |
322 | <B>bash</B> | |
323 | ||
a0c0a00f | 324 | is invoked in this fashion, |
17345e5a JA |
325 | <B>$0</B> |
326 | ||
327 | is set to the name of the file, and the positional parameters | |
328 | are set to the remaining arguments. | |
329 | <B>Bash</B> | |
330 | ||
331 | reads and executes commands from this file, then exits. | |
332 | <B>Bash</B>'s exit status is the exit status of the last command | |
333 | executed in the script. | |
334 | If no commands are executed, the exit status is 0. | |
335 | An attempt is first made to open the file in the current directory, and, | |
336 | if no file is found, then the shell searches the directories in | |
337 | <FONT SIZE=-1><B>PATH</B> | |
338 | ||
339 | </FONT> | |
340 | for the script. | |
341 | <A NAME="lbAH"> </A> | |
342 | <H3>INVOCATION</H3> | |
343 | ||
344 | A <I>login shell</I> is one whose first character of argument zero is a | |
345 | <B>-</B>, | |
346 | ||
a0c0a00f | 347 | or one started with the |
17345e5a JA |
348 | <B>--login</B> |
349 | ||
350 | option. | |
351 | <P> | |
352 | ||
353 | An <I>interactive</I> shell is one started without non-option arguments | |
a0c0a00f | 354 | (unless <B>-s</B> is specified) |
17345e5a JA |
355 | and without the |
356 | <B>-c</B> | |
357 | ||
358 | option | |
359 | whose standard input and error are | |
360 | both connected to terminals (as determined by | |
361 | <I>isatty</I>(3)), | |
362 | ||
363 | or one started with the | |
364 | <B>-i</B> | |
365 | ||
366 | option. | |
367 | <FONT SIZE=-1><B>PS1</B> | |
368 | ||
369 | </FONT> | |
370 | is set and | |
371 | <B>$-</B> | |
372 | ||
373 | includes | |
374 | <B>i</B> | |
375 | ||
376 | if | |
377 | <B>bash</B> | |
378 | ||
379 | is interactive, | |
380 | allowing a shell script or a startup file to test this state. | |
381 | <P> | |
382 | ||
383 | The following paragraphs describe how | |
384 | <B>bash</B> | |
385 | ||
386 | executes its startup files. | |
387 | If any of the files exist but cannot be read, | |
388 | <B>bash</B> | |
389 | ||
390 | reports an error. | |
ac50fbac | 391 | Tildes are expanded in filenames as described below under |
17345e5a JA |
392 | <B>Tilde Expansion</B> |
393 | ||
394 | in the | |
395 | <FONT SIZE=-1><B>EXPANSION</B> | |
396 | ||
397 | </FONT> | |
398 | section. | |
399 | <P> | |
400 | ||
401 | When | |
402 | <B>bash</B> | |
403 | ||
404 | is invoked as an interactive login shell, or as a non-interactive shell | |
405 | with the <B>--login</B> option, it first reads and | |
406 | executes commands from the file <A HREF="file:/etc/profile"><I>/etc/profile</I></A>, if that | |
407 | file exists. | |
408 | After reading that file, it looks for <A HREF="file:~/.bash_profile"><I>~/.bash_profile</I></A>, | |
409 | <A HREF="file:~/.bash_login"><I>~/.bash_login</I></A>, and <A HREF="file:~/.profile"><I>~/.profile</I></A>, in that order, and reads | |
410 | and executes commands from the first one that exists and is readable. | |
411 | The | |
412 | <B>--noprofile</B> | |
413 | ||
414 | option may be used when the shell is started to inhibit this behavior. | |
415 | <P> | |
416 | ||
a0c0a00f CR |
417 | When an interactive login shell exits, |
418 | or a non-interactive login shell executes the <B>exit</B> builtin command, | |
17345e5a JA |
419 | <B>bash</B> |
420 | ||
421 | reads and executes commands from the file <A HREF="file:~/.bash_logout"><I>~/.bash_logout</I></A>, if it | |
422 | exists. | |
423 | <P> | |
424 | ||
425 | When an interactive shell that is not a login shell is started, | |
426 | <B>bash</B> | |
427 | ||
428 | reads and executes commands from <A HREF="file:~/.bashrc"><I>~/.bashrc</I></A>, if that file exists. | |
429 | This may be inhibited by using the | |
430 | <B>--norc</B> | |
431 | ||
432 | option. | |
433 | The <B>--rcfile</B> <I>file</I> option will force | |
434 | <B>bash</B> | |
435 | ||
436 | to read and execute commands from <I>file</I> instead of <A HREF="file:~/.bashrc"><I>~/.bashrc</I></A>. | |
437 | <P> | |
438 | ||
439 | When | |
440 | <B>bash</B> | |
441 | ||
442 | is started non-interactively, to run a shell script, for example, it | |
443 | looks for the variable | |
444 | <FONT SIZE=-1><B>BASH_ENV</B> | |
445 | ||
446 | </FONT> | |
447 | in the environment, expands its value if it appears there, and uses the | |
448 | expanded value as the name of a file to read and execute. | |
449 | <B>Bash</B> | |
450 | ||
451 | behaves as if the following command were executed: | |
452 | <P> | |
453 | <DL COMPACT><DT><DD> | |
454 | <TT>if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi</TT> | |
455 | ||
456 | </DL> | |
457 | ||
458 | <P> | |
459 | but the value of the | |
460 | <FONT SIZE=-1><B>PATH</B> | |
461 | ||
462 | </FONT> | |
ac50fbac | 463 | variable is not used to search for the filename. |
17345e5a JA |
464 | <P> |
465 | ||
466 | If | |
467 | <B>bash</B> | |
468 | ||
469 | is invoked with the name | |
470 | <B>sh</B>, | |
471 | ||
472 | it tries to mimic the startup behavior of historical versions of | |
473 | <B>sh</B> | |
474 | ||
475 | as closely as possible, | |
476 | while conforming to the POSIX standard as well. | |
477 | When invoked as an interactive login shell, or a non-interactive | |
478 | shell with the <B>--login</B> option, it first attempts to | |
479 | read and execute commands from | |
480 | <A HREF="file:/etc/profile"><I>/etc/profile</I></A> | |
481 | ||
482 | and | |
483 | <A HREF="file:~/.profile"><I>~/.profile</I></A>, | |
484 | ||
485 | in that order. | |
486 | The | |
487 | <B>--noprofile</B> | |
488 | ||
489 | option may be used to inhibit this behavior. | |
490 | When invoked as an interactive shell with the name | |
491 | <B>sh</B>, | |
492 | ||
493 | <B>bash</B> | |
494 | ||
495 | looks for the variable | |
496 | <FONT SIZE=-1><B>ENV</B>, | |
497 | ||
498 | </FONT> | |
499 | expands its value if it is defined, and uses the | |
500 | expanded value as the name of a file to read and execute. | |
501 | Since a shell invoked as | |
502 | <B>sh</B> | |
503 | ||
504 | does not attempt to read and execute commands from any other startup | |
505 | files, the | |
506 | <B>--rcfile</B> | |
507 | ||
508 | option has no effect. | |
509 | A non-interactive shell invoked with the name | |
510 | <B>sh</B> | |
511 | ||
512 | does not attempt to read any other startup files. | |
513 | When invoked as | |
514 | <B>sh</B>, | |
515 | ||
516 | <B>bash</B> | |
517 | ||
518 | enters | |
519 | <I>posix</I> | |
520 | ||
521 | mode after the startup files are read. | |
522 | <P> | |
523 | ||
524 | When | |
525 | <B>bash</B> | |
526 | ||
527 | is started in | |
528 | <I>posix</I> | |
529 | ||
530 | mode, as with the | |
531 | <B>--posix</B> | |
532 | ||
533 | command line option, it follows the POSIX standard for startup files. | |
534 | In this mode, interactive shells expand the | |
535 | <FONT SIZE=-1><B>ENV</B> | |
536 | ||
537 | </FONT> | |
538 | variable and commands are read and executed from the file | |
539 | whose name is the expanded value. | |
540 | No other startup files are read. | |
541 | <P> | |
542 | ||
543 | <B>Bash</B> | |
544 | ||
545 | attempts to determine when it is being run with its standard input | |
495aee44 | 546 | connected to a network connection, as when executed by the remote shell |
17345e5a JA |
547 | daemon, usually <I>rshd</I>, or the secure shell daemon <I>sshd</I>. |
548 | If | |
549 | <B>bash</B> | |
550 | ||
551 | determines it is being run in this fashion, it reads and executes | |
552 | commands from <A HREF="file:~/.bashrc"><I>~/.bashrc</I></A>, if that file exists and is readable. | |
553 | It will not do this if invoked as <B>sh</B>. | |
554 | The | |
555 | <B>--norc</B> | |
556 | ||
557 | option may be used to inhibit this behavior, and the | |
558 | <B>--rcfile</B> | |
559 | ||
ac50fbac CR |
560 | option may be used to force another file to be read, but neither |
561 | <I>rshd</I> nor <I>sshd</I> generally invoke the shell with those options | |
17345e5a JA |
562 | or allow them to be specified. |
563 | <P> | |
564 | ||
565 | If the shell is started with the effective user (group) id not equal to the | |
566 | real user (group) id, and the <B>-p</B> option is not supplied, no startup | |
567 | files are read, shell functions are not inherited from the environment, the | |
0001803f CR |
568 | <FONT SIZE=-1><B>SHELLOPTS</B>, |
569 | ||
570 | </FONT> | |
571 | <FONT SIZE=-1><B>BASHOPTS</B>, | |
572 | ||
573 | </FONT> | |
574 | <FONT SIZE=-1><B>CDPATH</B>, | |
17345e5a JA |
575 | |
576 | </FONT> | |
0001803f CR |
577 | and |
578 | <FONT SIZE=-1><B>GLOBIGNORE</B> | |
579 | ||
580 | </FONT> | |
581 | variables, if they appear in the environment, are ignored, | |
17345e5a JA |
582 | and the effective user id is set to the real user id. |
583 | If the <B>-p</B> option is supplied at invocation, the startup behavior is | |
584 | the same, but the effective user id is not reset. | |
585 | <A NAME="lbAI"> </A> | |
586 | <H3>DEFINITIONS</H3> | |
587 | ||
588 | <P> | |
589 | ||
590 | The following definitions are used throughout the rest of this | |
591 | document. | |
592 | ||
593 | <DL COMPACT> | |
a0c0a00f | 594 | <DT><B>blank</B> |
17345e5a JA |
595 | |
596 | <DD> | |
597 | A space or tab. | |
598 | <DT><B>word</B> | |
599 | ||
600 | <DD> | |
601 | A sequence of characters considered as a single unit by the shell. | |
602 | Also known as a | |
603 | <B>token</B>. | |
604 | ||
605 | <DT><B>name</B> | |
606 | ||
607 | <DD> | |
a0c0a00f | 608 | A |
17345e5a JA |
609 | <I>word</I> |
610 | ||
611 | consisting only of alphanumeric characters and underscores, and | |
612 | beginning with an alphabetic character or an underscore. Also | |
613 | referred to as an | |
614 | <B>identifier</B>. | |
615 | ||
616 | <DT><B>metacharacter</B> | |
617 | ||
618 | <DD> | |
619 | A character that, when unquoted, separates words. One of the following: | |
620 | <BR> | |
621 | ||
622 | <DL COMPACT><DT><DD> | |
623 | <P> | |
624 | ||
a0c0a00f | 625 | <B>| & ; ( ) < > space tab newline</B> |
17345e5a JA |
626 | |
627 | </DL> | |
628 | ||
629 | </DL> | |
630 | <P> | |
631 | ||
632 | <DL COMPACT> | |
633 | <DT><B>control operator</B> | |
634 | ||
635 | <DD> | |
636 | A <I>token</I> that performs a control function. It is one of the following | |
637 | symbols: | |
638 | <DL COMPACT><DT><DD> | |
639 | <P> | |
640 | ||
a0c0a00f | 641 | <B>|| & && ; ;; ;& ;;& ( ) | |& <newline></B> |
17345e5a JA |
642 | |
643 | </DL> | |
644 | ||
645 | ||
646 | </DL> | |
647 | <A NAME="lbAJ"> </A> | |
648 | <H3>RESERVED WORDS</H3> | |
649 | ||
650 | <I>Reserved words</I> are words that have a special meaning to the shell. | |
651 | The following words are recognized as reserved when unquoted and either | |
652 | the first word of a simple command (see | |
653 | <FONT SIZE=-1><B>SHELL GRAMMAR</B> | |
654 | ||
655 | </FONT> | |
a0c0a00f CR |
656 | below) or the third word of a |
657 | <B>case</B> | |
17345e5a JA |
658 | |
659 | or | |
660 | <B>for</B> | |
661 | ||
662 | command: | |
663 | <DL COMPACT><DT><DD> | |
664 | ||
665 | <P> | |
666 | ||
667 | <B> | |
668 | </B> | |
669 | ||
ac50fbac | 670 | ! case coproc do done elif else esac fi for function if in select then until while { } time [[ ]] |
17345e5a JA |
671 | </DL> |
672 | ||
673 | ||
674 | <A NAME="lbAK"> </A> | |
675 | <H3>SHELL GRAMMAR</H3> | |
676 | ||
677 | <A NAME="lbAL"> </A> | |
678 | <H4>Simple Commands</H4> | |
679 | ||
680 | <P> | |
681 | ||
682 | A <I>simple command</I> is a sequence of optional variable assignments | |
683 | followed by <B>blank</B>-separated words and redirections, and | |
684 | terminated by a <I>control operator</I>. The first word | |
685 | specifies the command to be executed, and is passed as argument zero. | |
686 | The remaining words are passed as arguments to the invoked command. | |
687 | <P> | |
688 | ||
689 | The return value of a <I>simple command</I> is its exit status, or | |
690 | 128+<I>n</I> if the command is terminated by signal | |
691 | <I>n</I>. | |
692 | ||
693 | <A NAME="lbAM"> </A> | |
694 | <H4>Pipelines</H4> | |
695 | ||
696 | <P> | |
697 | ||
698 | A <I>pipeline</I> is a sequence of one or more commands separated by | |
699 | one of the control operators | |
700 | <B>|</B> | |
701 | ||
702 | or <B>|&</B>. | |
703 | The format for a pipeline is: | |
704 | <DL COMPACT><DT><DD> | |
705 | <P> | |
706 | ||
707 | [<B>time</B> [<B>-p</B>]] [ ! ] <I>command</I> [ [<B>|</B>|<B>|&</B>] <I>command2</I> ... ] | |
708 | </DL> | |
709 | ||
710 | <P> | |
711 | ||
712 | The standard output of | |
713 | <I>command</I> | |
714 | ||
715 | is connected via a pipe to the standard input of | |
716 | <I>command2</I>. | |
717 | ||
718 | This connection is performed before any redirections specified by the | |
719 | command (see | |
720 | <FONT SIZE=-1><B>REDIRECTION</B> | |
721 | ||
722 | </FONT> | |
723 | below). | |
ac50fbac CR |
724 | If <B>|&</B> is used, <I>command</I>'s standard error, in addition to its |
725 | standard output, is connected to | |
726 | <I>command2</I>'s standard input through the pipe; | |
727 | it is shorthand for <B>2>&1 |</B>. | |
728 | This implicit redirection of the standard error to the standard output is | |
729 | performed after any redirections specified by the command. | |
17345e5a JA |
730 | <P> |
731 | ||
732 | The return status of a pipeline is the exit status of the last | |
733 | command, unless the <B>pipefail</B> option is enabled. | |
734 | If <B>pipefail</B> is enabled, the pipeline's return status is the | |
735 | value of the last (rightmost) command to exit with a non-zero status, | |
736 | or zero if all commands exit successfully. | |
737 | If the reserved word | |
738 | <B>!</B> | |
739 | ||
740 | precedes a pipeline, the exit status of that pipeline is the logical | |
741 | negation of the exit status as described above. | |
742 | The shell waits for all commands in the pipeline to | |
743 | terminate before returning a value. | |
744 | <P> | |
745 | ||
746 | If the | |
747 | <B>time</B> | |
748 | ||
749 | reserved word precedes a pipeline, the elapsed as well as user and | |
750 | system time consumed by its execution are reported when the pipeline | |
751 | terminates. | |
752 | The <B>-p</B> option changes the output format to that specified by POSIX. | |
495aee44 CR |
753 | When the shell is in <I>posix mode</I>, it does not recognize |
754 | <B>time</B> as a reserved word if the next token begins with a `-'. | |
17345e5a JA |
755 | The |
756 | <FONT SIZE=-1><B>TIMEFORMAT</B> | |
757 | ||
758 | </FONT> | |
759 | variable may be set to a format string that specifies how the timing | |
760 | information should be displayed; see the description of | |
761 | <FONT SIZE=-1><B>TIMEFORMAT</B> | |
762 | ||
763 | </FONT> | |
764 | under | |
765 | <B>Shell Variables</B> | |
766 | ||
767 | below. | |
768 | <P> | |
769 | ||
495aee44 CR |
770 | When the shell is in <I>posix mode</I>, <B>time</B> |
771 | may be followed by a newline. In this case, the shell displays the | |
772 | total user and system time consumed by the shell and its children. | |
773 | The | |
774 | <FONT SIZE=-1><B>TIMEFORMAT</B> | |
775 | ||
776 | </FONT> | |
777 | variable may be used to specify the format of | |
778 | the time information. | |
779 | <P> | |
780 | ||
17345e5a JA |
781 | Each command in a pipeline is executed as a separate process (i.e., in a |
782 | subshell). | |
783 | <A NAME="lbAN"> </A> | |
784 | <H4>Lists</H4> | |
785 | ||
786 | <P> | |
787 | ||
788 | A <I>list</I> is a sequence of one or more pipelines separated by one | |
789 | of the operators | |
790 | <B>;</B>, | |
791 | ||
792 | <B>&</B>, | |
793 | ||
794 | <B>&&</B>, | |
795 | ||
796 | or | |
797 | <B>||</B>, | |
798 | ||
799 | and optionally terminated by one of | |
800 | <B>;</B>, | |
801 | ||
802 | <B>&</B>, | |
803 | ||
804 | or | |
805 | <B><newline></B>. | |
806 | ||
807 | <P> | |
808 | ||
809 | Of these list operators, | |
810 | <B>&&</B> | |
811 | ||
812 | and | |
813 | <B>||</B> | |
814 | ||
815 | have equal precedence, followed by | |
816 | <B>;</B> | |
817 | ||
818 | and | |
819 | <B>&</B>, | |
820 | ||
821 | which have equal precedence. | |
822 | <P> | |
823 | ||
824 | A sequence of one or more newlines may appear in a <I>list</I> instead | |
825 | of a semicolon to delimit commands. | |
826 | <P> | |
827 | ||
828 | If a command is terminated by the control operator | |
829 | <B>&</B>, | |
830 | ||
831 | the shell executes the command in the <I>background</I> | |
832 | in a subshell. The shell does not wait for the command to | |
833 | finish, and the return status is 0. Commands separated by a | |
834 | <B>;</B> | |
835 | ||
836 | are executed sequentially; the shell waits for each | |
837 | command to terminate in turn. The return status is the | |
838 | exit status of the last command executed. | |
839 | <P> | |
840 | ||
a0c0a00f | 841 | AND and OR lists are sequences of one or more pipelines separated by the |
17345e5a JA |
842 | <B>&&</B> and <B>||</B> control operators, respectively. |
843 | AND and OR lists are executed with left associativity. | |
844 | An AND list has the form | |
845 | <DL COMPACT><DT><DD> | |
846 | <P> | |
847 | ||
848 | <I>command1</I> <B>&&</B> <I>command2</I> | |
849 | </DL> | |
850 | ||
851 | <P> | |
852 | ||
853 | <I>command2</I> | |
854 | ||
855 | is executed if, and only if, | |
856 | <I>command1</I> | |
857 | ||
858 | returns an exit status of zero. | |
859 | <P> | |
860 | ||
861 | An OR list has the form | |
862 | <DL COMPACT><DT><DD> | |
863 | <P> | |
864 | ||
865 | <I>command1</I> <B>||</B> <I>command2</I> | |
866 | <P> | |
867 | ||
868 | </DL> | |
869 | ||
870 | <P> | |
871 | ||
872 | <I>command2</I> | |
873 | ||
874 | is executed if and only if | |
875 | <I>command1</I> | |
876 | ||
877 | returns a non-zero exit status. | |
878 | The return status of | |
879 | AND and OR lists is the exit status of the last command | |
880 | executed in the list. | |
881 | <A NAME="lbAO"> </A> | |
882 | <H4>Compound Commands</H4> | |
883 | ||
884 | <P> | |
885 | ||
ac50fbac CR |
886 | A <I>compound command</I> is one of the following. |
887 | In most cases a <I>list</I> in a command's description may be separated from | |
888 | the rest of the command by one or more newlines, and may be followed by a | |
889 | newline in place of a semicolon. | |
17345e5a JA |
890 | <DL COMPACT> |
891 | <DT>(<I>list</I>)<DD> | |
892 | <I>list</I> is executed in a subshell environment (see | |
893 | <FONT SIZE=-1><B>COMMAND EXECUTION ENVIRONMENT</B></FONT> | |
894 | below). | |
895 | Variable assignments and builtin | |
896 | commands that affect the shell's environment do not remain in effect | |
897 | after the command completes. The return status is the exit status of | |
898 | <I>list</I>. | |
899 | <DT>{ <I>list</I>; }<DD> | |
900 | <I>list</I> is simply executed in the current shell environment. | |
901 | <I>list</I> must be terminated with a newline or semicolon. | |
902 | This is known as a <I>group command</I>. | |
903 | The return status is the exit status of | |
904 | <I>list</I>. | |
905 | Note that unlike the metacharacters <B>(</B> and <B>)</B>, <B>{</B> and | |
906 | <B>}</B> are <I>reserved words</I> and must occur where a reserved | |
907 | word is permitted to be recognized. Since they do not cause a word | |
908 | break, they must be separated from <I>list</I> by whitespace or another | |
909 | shell metacharacter. | |
910 | <DT>((<I>expression</I>))<DD> | |
911 | The <I>expression</I> is evaluated according to the rules described | |
912 | below under | |
913 | <FONT SIZE=-1><B>ARITHMETIC EVALUATION</B>. | |
914 | ||
915 | </FONT> | |
916 | If the value of the expression is non-zero, the return status is 0; | |
917 | otherwise the return status is 1. This is exactly equivalent to | |
918 | <B>let "</B><I>expression</I>". | |
919 | <DT><B>[[</B> <I>expression</I> <B>]]</B><DD> | |
920 | Return a status of 0 or 1 depending on the evaluation of | |
921 | the conditional expression <I>expression</I>. | |
922 | Expressions are composed of the primaries described below under | |
923 | <FONT SIZE=-1><B>CONDITIONAL EXPRESSIONS</B>. | |
924 | ||
925 | </FONT> | |
926 | Word splitting and pathname expansion are not performed on the words | |
ac50fbac CR |
927 | between the <B>[[</B> and <B>]]</B>; tilde expansion, |
928 | parameter and variable expansion, | |
929 | arithmetic expansion, command substitution, process | |
17345e5a JA |
930 | substitution, and quote removal are performed. |
931 | Conditional operators such as <B>-f</B> must be unquoted to be recognized | |
932 | as primaries. | |
933 | <P> | |
934 | ||
935 | ||
495aee44 | 936 | When used with <B>[[</B>, the <B><</B> and <B>></B> operators sort |
0001803f CR |
937 | lexicographically using the current locale. |
938 | <P> | |
939 | ||
940 | ||
17345e5a JA |
941 | When the <B>==</B> and <B>!=</B> operators are used, the string to the |
942 | right of the operator is considered a pattern and matched according | |
ac50fbac CR |
943 | to the rules described below under <B>Pattern Matching</B>, |
944 | as if the <B>extglob</B> shell option were enabled. | |
945 | The <B>=</B> operator is equivalent to <B>==</B>. | |
a0c0a00f | 946 | If the |
17345e5a JA |
947 | <B>nocasematch</B> |
948 | ||
a0c0a00f | 949 | shell option is enabled, the match is performed without regard to the case |
17345e5a JA |
950 | of alphabetic characters. |
951 | The return value is 0 if the string matches (<B>==</B>) or does not match | |
952 | (<B>!=</B>) the pattern, and 1 otherwise. | |
ac50fbac CR |
953 | Any part of the pattern may be quoted to force the quoted portion |
954 | to be matched as a string. | |
17345e5a JA |
955 | <P> |
956 | ||
957 | ||
958 | An additional binary operator, <B>=~</B>, is available, with the same | |
959 | precedence as <B>==</B> and <B>!=</B>. | |
960 | When it is used, the string to the right of the operator is considered | |
a0c0a00f | 961 | an extended regular expression and matched accordingly (as in <I>regex</I>(3)). |
17345e5a JA |
962 | The return value is 0 if the string matches |
963 | the pattern, and 1 otherwise. | |
964 | If the regular expression is syntactically incorrect, the conditional | |
965 | expression's return value is 2. | |
a0c0a00f | 966 | If the |
17345e5a JA |
967 | <B>nocasematch</B> |
968 | ||
a0c0a00f | 969 | shell option is enabled, the match is performed without regard to the case |
17345e5a | 970 | of alphabetic characters. |
ac50fbac CR |
971 | Any part of the pattern may be quoted to force the quoted portion |
972 | to be matched as a string. | |
973 | Bracket expressions in regular expressions must be treated carefully, | |
974 | since normal quoting characters lose their meanings between brackets. | |
975 | If the pattern is stored in a shell variable, quoting the variable | |
976 | expansion forces the entire pattern to be matched as a string. | |
17345e5a | 977 | Substrings matched by parenthesized subexpressions within the regular |
0001803f CR |
978 | expression are saved in the array variable |
979 | <FONT SIZE=-1><B>BASH_REMATCH</B>. | |
980 | ||
981 | </FONT> | |
982 | The element of | |
983 | <FONT SIZE=-1><B>BASH_REMATCH</B> | |
984 | ||
985 | </FONT> | |
986 | with index 0 is the portion of the string | |
17345e5a | 987 | matching the entire regular expression. |
0001803f CR |
988 | The element of |
989 | <FONT SIZE=-1><B>BASH_REMATCH</B> | |
990 | ||
991 | </FONT> | |
992 | with index <I>n</I> is the portion of the | |
17345e5a JA |
993 | string matching the <I>n</I>th parenthesized subexpression. |
994 | <P> | |
995 | ||
996 | ||
997 | Expressions may be combined using the following operators, listed | |
998 | in decreasing order of precedence: | |
999 | <P> | |
1000 | ||
1001 | ||
1002 | <DL COMPACT><DT><DD> | |
1003 | ||
1004 | <DL COMPACT> | |
1005 | <DT><B>( </B><I>expression</I> ) | |
1006 | ||
1007 | <DD> | |
1008 | Returns the value of <I>expression</I>. | |
1009 | This may be used to override the normal precedence of operators. | |
1010 | <DT><B>! </B><I>expression</I> | |
1011 | ||
1012 | <DD> | |
1013 | True if | |
1014 | <I>expression</I> | |
1015 | ||
1016 | is false. | |
1017 | <DT><I>expression1</I> <B>&&</B> <I>expression2</I><DD> | |
1018 | True if both | |
1019 | <I>expression1</I> | |
1020 | ||
1021 | and | |
1022 | <I>expression2</I> | |
1023 | ||
1024 | are true. | |
495aee44 | 1025 | <DT><I>expression1</I> <B>||</B> <I>expression2</I><DD> |
17345e5a JA |
1026 | True if either |
1027 | <I>expression1</I> | |
1028 | ||
1029 | or | |
1030 | <I>expression2</I> | |
1031 | ||
1032 | is true. | |
1033 | ||
1034 | </DL> | |
1035 | <P> | |
1036 | ||
495aee44 | 1037 | The <B>&&</B> and <B>||</B> |
17345e5a JA |
1038 | operators do not evaluate <I>expression2</I> if the value of |
1039 | <I>expression1</I> is sufficient to determine the return value of | |
1040 | the entire conditional expression. | |
1041 | </DL> | |
1042 | ||
0001803f | 1043 | <DT><B>for</B> <I>name</I> [ [ <B>in</B> [ <I>word ...</I> ] ] ; ] <B>do</B> <I>list</I> ; <B>done</B><DD> |
17345e5a JA |
1044 | The list of words following <B>in</B> is expanded, generating a list |
1045 | of items. | |
1046 | The variable <I>name</I> is set to each element of this list | |
1047 | in turn, and <I>list</I> is executed each time. | |
1048 | If the <B>in</B> <I>word</I> is omitted, the <B>for</B> command executes | |
1049 | <I>list</I> once for each positional parameter that is set (see | |
1050 | <FONT SIZE=-1><B>PARAMETERS</B> | |
1051 | ||
1052 | </FONT> | |
1053 | below). | |
1054 | The return status is the exit status of the last command that executes. | |
1055 | If the expansion of the items following <B>in</B> results in an empty | |
1056 | list, no commands are executed, and the return status is 0. | |
1057 | <DT><B>for</B> (( <I>expr1</I> ; <I>expr2</I> ; <I>expr3</I> )) ; <B>do</B> <I>list</I> ; <B>done</B><DD> | |
1058 | First, the arithmetic expression <I>expr1</I> is evaluated according | |
1059 | to the rules described below under | |
1060 | <FONT SIZE=-1><B>ARITHMETIC EVALUATION</B>. | |
1061 | ||
1062 | </FONT> | |
1063 | The arithmetic expression <I>expr2</I> is then evaluated repeatedly | |
1064 | until it evaluates to zero. | |
1065 | Each time <I>expr2</I> evaluates to a non-zero value, <I>list</I> is | |
1066 | executed and the arithmetic expression <I>expr3</I> is evaluated. | |
1067 | If any expression is omitted, it behaves as if it evaluates to 1. | |
1068 | The return value is the exit status of the last command in <I>list</I> | |
1069 | that is executed, or false if any of the expressions is invalid. | |
1070 | <DT><B>select</B> <I>name</I> [ <B>in</B> <I>word</I> ] ; <B>do</B> <I>list</I> ; <B>done</B><DD> | |
1071 | The list of words following <B>in</B> is expanded, generating a list | |
1072 | of items. The set of expanded words is printed on the standard | |
1073 | error, each preceded by a number. If the <B>in</B> | |
1074 | <I>word</I> is omitted, the positional parameters are printed (see | |
1075 | <FONT SIZE=-1><B>PARAMETERS</B> | |
1076 | ||
1077 | </FONT> | |
1078 | below). The | |
0001803f | 1079 | <FONT SIZE=-1><B>PS3</B> |
17345e5a | 1080 | |
0001803f | 1081 | </FONT> |
17345e5a JA |
1082 | prompt is then displayed and a line read from the standard input. |
1083 | If the line consists of a number corresponding to one of | |
1084 | the displayed words, then the value of | |
1085 | <I>name</I> | |
1086 | ||
1087 | is set to that word. If the line is empty, the words and prompt | |
1088 | are displayed again. If EOF is read, the command completes. Any | |
1089 | other value read causes | |
1090 | <I>name</I> | |
1091 | ||
1092 | to be set to null. The line read is saved in the variable | |
0001803f | 1093 | <FONT SIZE=-1><B>REPLY</B>. |
17345e5a | 1094 | |
0001803f | 1095 | </FONT> |
17345e5a JA |
1096 | The |
1097 | <I>list</I> | |
1098 | ||
1099 | is executed after each selection until a | |
1100 | <B>break</B> | |
1101 | ||
1102 | command is executed. | |
1103 | The exit status of | |
1104 | <B>select</B> | |
1105 | ||
1106 | is the exit status of the last command executed in | |
1107 | <I>list</I>, | |
1108 | ||
1109 | or zero if no commands were executed. | |
1110 | <DT><B>case</B> <I>word</I> <B>in</B> [ [(] <I>pattern</I> [ <B>|</B> <I>pattern</I> ] | |
1111 | <DD> | |
1112 | A <B>case</B> command first expands <I>word</I>, and tries to match | |
1113 | it against each <I>pattern</I> in turn, using the same matching rules | |
1114 | as for pathname expansion (see | |
1115 | <B>Pathname Expansion</B> | |
1116 | ||
1117 | below). | |
1118 | The <I>word</I> is expanded using tilde | |
a0c0a00f | 1119 | expansion, parameter and variable expansion, arithmetic expansion, |
17345e5a JA |
1120 | command substitution, process substitution and quote removal. |
1121 | Each <I>pattern</I> examined is expanded using tilde | |
a0c0a00f | 1122 | expansion, parameter and variable expansion, arithmetic expansion, |
17345e5a | 1123 | command substitution, and process substitution. |
a0c0a00f | 1124 | If the |
17345e5a JA |
1125 | <B>nocasematch</B> |
1126 | ||
a0c0a00f | 1127 | shell option is enabled, the match is performed without regard to the case |
17345e5a JA |
1128 | of alphabetic characters. |
1129 | When a match is found, the corresponding <I>list</I> is executed. | |
1130 | If the <B>;;</B> operator is used, no subsequent matches are attempted after | |
1131 | the first pattern match. | |
1132 | Using <B>;&</B> in place of <B>;;</B> causes execution to continue with | |
1133 | the <I>list</I> associated with the next set of patterns. | |
1134 | Using <B>;;&</B> in place of <B>;;</B> causes the shell to test the next | |
1135 | pattern list in the statement, if any, and execute any associated <I>list</I> | |
1136 | on a successful match. | |
1137 | The exit status is zero if no | |
1138 | pattern matches. Otherwise, it is the exit status of the | |
1139 | last command executed in <I>list</I>. | |
ac50fbac | 1140 | <DT><B>if</B> <I>list</I>; <B>then</B> <I>list</I>; [ <B>elif</B> <I>list</I>; <B>then</B> <I>list</I>; ] ... [ <B>else</B> <I>list</I>; ] <B>fi</B><DD> |
17345e5a | 1141 | The |
a0c0a00f | 1142 | <B>if</B> |
17345e5a JA |
1143 | |
1144 | <I>list</I> | |
1145 | ||
1146 | is executed. If its exit status is zero, the | |
1147 | <B>then</B> <I>list</I> is executed. Otherwise, each <B>elif</B> | |
1148 | <I>list</I> is executed in turn, and if its exit status is zero, | |
1149 | the corresponding <B>then</B> <I>list</I> is executed and the | |
1150 | command completes. Otherwise, the <B>else</B> <I>list</I> is | |
1151 | executed, if present. The exit status is the exit status of the | |
1152 | last command executed, or zero if no condition tested true. | |
495aee44 | 1153 | <DT><B>while</B> <I>list-1</I>; <B>do</B> <I>list-2</I>; <B>done</B><DD> |
17345e5a | 1154 | |
495aee44 | 1155 | <DT><B>until</B> <I>list-1</I>; <B>do</B> <I>list-2</I>; <B>done</B><DD> |
17345e5a | 1156 | |
495aee44 CR |
1157 | The <B>while</B> command continuously executes the list |
1158 | <I>list-2</I> as long as the last command in the list <I>list-1</I> returns | |
17345e5a | 1159 | an exit status of zero. The <B>until</B> command is identical |
a0c0a00f | 1160 | to the <B>while</B> command, except that the test is negated: |
495aee44 | 1161 | <I>list-2</I> |
17345e5a JA |
1162 | |
1163 | is executed as long as the last command in | |
495aee44 | 1164 | <I>list-1</I> |
17345e5a JA |
1165 | |
1166 | returns a non-zero exit status. | |
1167 | The exit status of the <B>while</B> and <B>until</B> commands | |
1168 | is the exit status | |
495aee44 | 1169 | of the last command executed in <I>list-2</I>, or zero if |
17345e5a JA |
1170 | none was executed. |
1171 | </DL> | |
1172 | <A NAME="lbAP"> </A> | |
1173 | <H4>Coprocesses</H4> | |
1174 | ||
1175 | <P> | |
1176 | ||
1177 | A <I>coprocess</I> is a shell command preceded by the <B>coproc</B> reserved | |
1178 | word. | |
1179 | A coprocess is executed asynchronously in a subshell, as if the command | |
1180 | had been terminated with the <B>&</B> control operator, with a two-way pipe | |
1181 | established between the executing shell and the coprocess. | |
1182 | <P> | |
1183 | ||
1184 | The format for a coprocess is: | |
1185 | <DL COMPACT><DT><DD> | |
1186 | <P> | |
1187 | ||
1188 | <B>coproc</B> [<I>NAME</I>] <I>command</I> [<I>redirections</I>] | |
1189 | </DL> | |
1190 | ||
1191 | <P> | |
1192 | ||
1193 | This creates a coprocess named <I>NAME</I>. | |
ac50fbac | 1194 | If <I>NAME</I> is not supplied, the default name is <B>COPROC</B>. |
17345e5a JA |
1195 | <I>NAME</I> must not be supplied if <I>command</I> is a <I>simple |
1196 | command</I> (see above); otherwise, it is interpreted as the first word | |
1197 | of the simple command. | |
ac50fbac | 1198 | When the coprocess is executed, the shell creates an array variable (see |
17345e5a JA |
1199 | <B>Arrays</B> |
1200 | ||
1201 | below) named <I>NAME</I> in the context of the executing shell. | |
1202 | The standard output of | |
1203 | <I>command</I> | |
1204 | ||
1205 | is connected via a pipe to a file descriptor in the executing shell, | |
1206 | and that file descriptor is assigned to <I>NAME</I>[0]. | |
1207 | The standard input of | |
1208 | <I>command</I> | |
1209 | ||
1210 | is connected via a pipe to a file descriptor in the executing shell, | |
1211 | and that file descriptor is assigned to <I>NAME</I>[1]. | |
1212 | This pipe is established before any redirections specified by the | |
1213 | command (see | |
1214 | <FONT SIZE=-1><B>REDIRECTION</B> | |
1215 | ||
1216 | </FONT> | |
1217 | below). | |
1218 | The file descriptors can be utilized as arguments to shell commands | |
1219 | and redirections using standard word expansions. | |
ac50fbac | 1220 | The file descriptors are not available in subshells. |
495aee44 | 1221 | The process ID of the shell spawned to execute the coprocess is |
17345e5a JA |
1222 | available as the value of the variable <I>NAME</I>_PID. |
1223 | The <B>wait</B> | |
1224 | builtin command may be used to wait for the coprocess to terminate. | |
1225 | <P> | |
1226 | ||
ac50fbac CR |
1227 | Since the coprocess is created as an asynchronous command, |
1228 | the <B>coproc</B> command always returns success. | |
17345e5a JA |
1229 | The return status of a coprocess is the exit status of <I>command</I>. |
1230 | <A NAME="lbAQ"> </A> | |
1231 | <H4>Shell Function Definitions</H4> | |
1232 | ||
1233 | <P> | |
1234 | ||
1235 | A shell function is an object that is called like a simple command and | |
1236 | executes a compound command with a new set of positional parameters. | |
1237 | Shell functions are declared as follows: | |
1238 | <DL COMPACT> | |
495aee44 CR |
1239 | <DT><I>name</I> () <I>compound-command</I> [<I>redirection</I>]<DD> |
1240 | ||
1241 | <DT><B>function</B> <I>name</I> [()] <I>compound-command</I> [<I>redirection</I>]<DD> | |
1242 | ||
17345e5a JA |
1243 | This defines a function named <I>name</I>. |
1244 | The reserved word <B>function</B> is optional. | |
1245 | If the <B>function</B> reserved word is supplied, the parentheses are optional. | |
1246 | The <I>body</I> of the function is the compound command | |
a0c0a00f | 1247 | <I>compound-command</I> |
17345e5a JA |
1248 | |
1249 | (see <B>Compound Commands</B> above). | |
1250 | That command is usually a <I>list</I> of commands between { and }, but | |
a0c0a00f CR |
1251 | may be any command listed under <B>Compound Commands</B> above, |
1252 | with one exception: If the <B>function</B> reserved word is used, but the | |
1253 | parentheses are not supplied, the braces are required. | |
17345e5a JA |
1254 | <I>compound-command</I> is executed whenever <I>name</I> is specified as the |
1255 | name of a simple command. | |
ac50fbac CR |
1256 | When in <I>posix mode</I>, <I>name</I> may not be the name of one of the |
1257 | POSIX <I>special builtins</I>. | |
17345e5a JA |
1258 | Any redirections (see |
1259 | <FONT SIZE=-1><B>REDIRECTION</B> | |
1260 | ||
1261 | </FONT> | |
1262 | below) specified when a function is defined are performed | |
1263 | when the function is executed. | |
1264 | The exit status of a function definition is zero unless a syntax error | |
1265 | occurs or a readonly function with the same name already exists. | |
1266 | When executed, the exit status of a function is the exit status of the | |
1267 | last command executed in the body. (See | |
1268 | <FONT SIZE=-1><B>FUNCTIONS</B> | |
1269 | ||
1270 | </FONT> | |
1271 | below.) | |
1272 | </DL> | |
1273 | <A NAME="lbAR"> </A> | |
1274 | <H3>COMMENTS</H3> | |
1275 | ||
1276 | In a non-interactive shell, or an interactive shell in which the | |
1277 | <B>interactive_comments</B> | |
1278 | ||
1279 | option to the | |
1280 | <B>shopt</B> | |
1281 | ||
1282 | builtin is enabled (see | |
1283 | <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B> | |
1284 | ||
1285 | </FONT> | |
1286 | below), a word beginning with | |
1287 | <B>#</B> | |
1288 | ||
1289 | causes that word and all remaining characters on that line to | |
1290 | be ignored. An interactive shell without the | |
1291 | <B>interactive_comments</B> | |
1292 | ||
1293 | option enabled does not allow comments. The | |
1294 | <B>interactive_comments</B> | |
1295 | ||
1296 | option is on by default in interactive shells. | |
1297 | <A NAME="lbAS"> </A> | |
1298 | <H3>QUOTING</H3> | |
1299 | ||
1300 | <I>Quoting</I> is used to remove the special meaning of certain | |
a0c0a00f | 1301 | characters or words to the shell. Quoting can be used to |
17345e5a JA |
1302 | disable special treatment for special characters, to prevent |
1303 | reserved words from being recognized as such, and to prevent | |
1304 | parameter expansion. | |
1305 | <P> | |
1306 | ||
1307 | Each of the <I>metacharacters</I> listed above under | |
1308 | <FONT SIZE=-1><B>DEFINITIONS</B> | |
1309 | ||
1310 | </FONT> | |
1311 | has special meaning to the shell and must be quoted if it is to | |
1312 | represent itself. | |
1313 | <P> | |
1314 | ||
1315 | When the command history expansion facilities are being used | |
1316 | (see | |
1317 | <FONT SIZE=-1><B>HISTORY EXPANSION</B> | |
1318 | ||
1319 | </FONT> | |
1320 | below), the | |
1321 | <I>history expansion</I> character, usually <B>!</B>, must be quoted | |
1322 | to prevent history expansion. | |
1323 | <P> | |
1324 | ||
1325 | There are three quoting mechanisms: the | |
1326 | <I>escape character</I>, | |
1327 | ||
1328 | single quotes, and double quotes. | |
1329 | <P> | |
1330 | ||
1331 | A non-quoted backslash (<B>\</B>) is the | |
1332 | <I>escape character</I>. | |
1333 | ||
1334 | It preserves the literal value of the next character that follows, | |
1335 | with the exception of <newline>. If a <B>\</B><newline> pair | |
1336 | appears, and the backslash is not itself quoted, the <B>\</B><newline> | |
1337 | is treated as a line continuation (that is, it is removed from the | |
1338 | input stream and effectively ignored). | |
1339 | <P> | |
1340 | ||
1341 | Enclosing characters in single quotes preserves the literal value | |
1342 | of each character within the quotes. A single quote may not occur | |
1343 | between single quotes, even when preceded by a backslash. | |
1344 | <P> | |
1345 | ||
1346 | Enclosing characters in double quotes preserves the literal value | |
1347 | of all characters within the quotes, with the exception of | |
1348 | <B>$</B>, | |
1349 | ||
1350 | <B>`</B>, | |
1351 | ||
1352 | <B>\</B>, | |
1353 | ||
1354 | and, when history expansion is enabled, | |
1355 | <B>!</B>. | |
1356 | ||
a0c0a00f CR |
1357 | When the shell is in <I>posix mode</I>, the <B>!</B> has no special meaning |
1358 | within double quotes, even when history expansion is enabled. | |
17345e5a JA |
1359 | The characters |
1360 | <B>$</B> | |
1361 | ||
1362 | and | |
1363 | <B>`</B> | |
1364 | ||
1365 | retain their special meaning within double quotes. The backslash | |
1366 | retains its special meaning only when followed by one of the following | |
1367 | characters: | |
1368 | <B>$</B>, | |
1369 | ||
1370 | <B>`</B>, | |
1371 | ||
1372 | <B>"</B>, | |
1373 | <B>\</B>, | |
1374 | ||
1375 | or | |
1376 | <B><newline></B>. | |
1377 | ||
1378 | A double quote may be quoted within double quotes by preceding it with | |
1379 | a backslash. | |
1380 | If enabled, history expansion will be performed unless an | |
1381 | <B>!</B> | |
1382 | ||
1383 | appearing in double quotes is escaped using a backslash. | |
1384 | The backslash preceding the | |
1385 | <B>!</B> | |
1386 | ||
1387 | is not removed. | |
1388 | <P> | |
1389 | ||
1390 | The special parameters | |
1391 | <B>*</B> | |
1392 | ||
1393 | and | |
1394 | <B>@</B> | |
1395 | ||
1396 | have special meaning when in double | |
1397 | quotes (see | |
1398 | <FONT SIZE=-1><B>PARAMETERS</B> | |
1399 | ||
1400 | </FONT> | |
1401 | below). | |
1402 | <P> | |
1403 | ||
1404 | Words of the form <B>$</B>aq<I>string</I>aq are treated specially. The | |
1405 | word expands to <I>string</I>, with backslash-escaped characters replaced | |
1406 | as specified by the ANSI C standard. Backslash escape sequences, if | |
1407 | present, are decoded as follows: | |
1408 | <DL COMPACT><DT><DD> | |
1409 | ||
1410 | <DL COMPACT> | |
1411 | <DT><B>\a</B> | |
1412 | ||
1413 | <DD> | |
1414 | alert (bell) | |
1415 | <DT><B>\b</B> | |
1416 | ||
1417 | <DD> | |
1418 | backspace | |
1419 | <DT><B>\e</B> | |
1420 | ||
0001803f CR |
1421 | <DD> |
1422 | <DT><B>\E</B> | |
1423 | ||
17345e5a JA |
1424 | <DD> |
1425 | an escape character | |
1426 | <DT><B>\f</B> | |
1427 | ||
1428 | <DD> | |
1429 | form feed | |
1430 | <DT><B>\n</B> | |
1431 | ||
1432 | <DD> | |
1433 | new line | |
1434 | <DT><B>\r</B> | |
1435 | ||
1436 | <DD> | |
1437 | carriage return | |
1438 | <DT><B>\t</B> | |
1439 | ||
1440 | <DD> | |
1441 | horizontal tab | |
1442 | <DT><B>\v</B> | |
1443 | ||
1444 | <DD> | |
1445 | vertical tab | |
1446 | <DT><B>\\</B> | |
1447 | ||
1448 | <DD> | |
1449 | backslash | |
1450 | <DT><B>\aq</B> | |
1451 | ||
1452 | <DD> | |
1453 | single quote | |
0001803f CR |
1454 | <DT><B>\dq</B> |
1455 | ||
1456 | <DD> | |
1457 | double quote | |
a0c0a00f CR |
1458 | <DT><B>\?</B> |
1459 | ||
1460 | <DD> | |
1461 | question mark | |
17345e5a JA |
1462 | <DT><B>\</B><I>nnn</I> |
1463 | ||
1464 | <DD> | |
1465 | the eight-bit character whose value is the octal value <I>nnn</I> | |
1466 | (one to three digits) | |
1467 | <DT><B>\x</B><I>HH</I> | |
1468 | ||
1469 | <DD> | |
1470 | the eight-bit character whose value is the hexadecimal value <I>HH</I> | |
1471 | (one or two hex digits) | |
495aee44 CR |
1472 | <DT><B>\u</B><I>HHHH</I> |
1473 | ||
1474 | <DD> | |
1475 | the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value | |
1476 | <I>HHHH</I> (one to four hex digits) | |
1477 | <DT><B>\U</B><I>HHHHHHHH</I> | |
1478 | ||
1479 | <DD> | |
1480 | the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value | |
1481 | <I>HHHHHHHH</I> (one to eight hex digits) | |
17345e5a JA |
1482 | <DT><B>\c</B><I>x</I> |
1483 | ||
1484 | <DD> | |
1485 | a control-<I>x</I> character | |
1486 | ||
1487 | </DL></DL> | |
1488 | ||
1489 | <P> | |
1490 | ||
1491 | The expanded result is single-quoted, as if the dollar sign had | |
1492 | not been present. | |
1493 | <P> | |
1494 | ||
0001803f CR |
1495 | A double-quoted string preceded by a dollar sign (<B>$</B>dq<I>string</I>dq) |
1496 | will cause the string to be translated according to the current locale. | |
17345e5a JA |
1497 | If the current locale is <B>C</B> or <B>POSIX</B>, the dollar sign |
1498 | is ignored. | |
1499 | If the string is translated and replaced, the replacement is | |
1500 | double-quoted. | |
1501 | <A NAME="lbAT"> </A> | |
1502 | <H3>PARAMETERS</H3> | |
1503 | ||
1504 | A | |
1505 | <I>parameter</I> | |
1506 | ||
1507 | is an entity that stores values. | |
1508 | It can be a | |
1509 | <I>name</I>, | |
1510 | ||
1511 | a number, or one of the special characters listed below under | |
1512 | <B>Special Parameters</B>. | |
1513 | ||
1514 | A | |
1515 | <I>variable</I> | |
1516 | ||
1517 | is a parameter denoted by a | |
1518 | <I>name</I>. | |
1519 | ||
1520 | A variable has a <I>value</I> and zero or more <I>attributes</I>. | |
1521 | Attributes are assigned using the | |
1522 | <B>declare</B> | |
1523 | ||
1524 | builtin command (see | |
1525 | <B>declare</B> | |
1526 | ||
1527 | below in | |
1528 | <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>). | |
1529 | ||
1530 | </FONT> | |
1531 | <P> | |
1532 | ||
1533 | A parameter is set if it has been assigned a value. The null string is | |
1534 | a valid value. Once a variable is set, it may be unset only by using | |
1535 | the | |
1536 | <B>unset</B> | |
1537 | ||
1538 | builtin command (see | |
1539 | <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B> | |
1540 | ||
1541 | </FONT> | |
1542 | below). | |
1543 | <P> | |
1544 | ||
1545 | A | |
1546 | <I>variable</I> | |
1547 | ||
1548 | may be assigned to by a statement of the form | |
1549 | <DL COMPACT><DT><DD> | |
1550 | <P> | |
1551 | ||
1552 | <I>name</I>=[<I>value</I>] | |
1553 | </DL> | |
1554 | ||
1555 | <P> | |
1556 | ||
1557 | If | |
1558 | <I>value</I> | |
1559 | ||
1560 | is not given, the variable is assigned the null string. All | |
1561 | <I>values</I> | |
1562 | ||
1563 | undergo tilde expansion, parameter and variable expansion, | |
1564 | command substitution, arithmetic expansion, and quote | |
1565 | removal (see | |
1566 | <FONT SIZE=-1><B>EXPANSION</B> | |
1567 | ||
1568 | </FONT> | |
1569 | below). If the variable has its | |
1570 | <B>integer</B> | |
1571 | ||
1572 | attribute set, then | |
1573 | <I>value</I> | |
1574 | ||
1575 | is evaluated as an arithmetic expression even if the $((...)) expansion is | |
1576 | not used (see | |
1577 | <B>Arithmetic Expansion</B> | |
1578 | ||
1579 | below). | |
1580 | Word splitting is not performed, with the exception | |
1581 | of <B>"$@"</B> as explained below under | |
1582 | <B>Special Parameters</B>. | |
1583 | ||
1584 | Pathname expansion is not performed. | |
1585 | Assignment statements may also appear as arguments to the | |
1586 | <B>alias</B>, | |
1587 | ||
1588 | <B>declare</B>, | |
1589 | ||
1590 | <B>typeset</B>, | |
1591 | ||
1592 | <B>export</B>, | |
1593 | ||
1594 | <B>readonly</B>, | |
1595 | ||
1596 | and | |
1597 | <B>local</B> | |
1598 | ||
a0c0a00f | 1599 | builtin commands (<I>declaration</I> commands). |
ac50fbac CR |
1600 | When in <I>posix mode</I>, these builtins may appear in a command after |
1601 | one or more instances of the <B>command</B> builtin and retain these | |
1602 | assignment statement properties. | |
17345e5a JA |
1603 | <P> |
1604 | ||
1605 | In the context where an assignment statement is assigning a value | |
1606 | to a shell variable or array index, the += operator can be used to | |
1607 | append to or add to the variable's previous value. | |
a0c0a00f CR |
1608 | This includes arguments to builtin commands such as <B>declare</B> that |
1609 | accept assignment statements (<I>declaration</I> commands). | |
495aee44 | 1610 | When += is applied to a variable for which the <I>integer</I> attribute has been |
17345e5a JA |
1611 | set, <I>value</I> is evaluated as an arithmetic expression and added to the |
1612 | variable's current value, which is also evaluated. | |
1613 | When += is applied to an array variable using compound assignment (see | |
1614 | <B>Arrays</B> | |
1615 | ||
1616 | below), the | |
1617 | variable's value is not unset (as it is when using =), and new values are | |
1618 | appended to the array beginning at one greater than the array's maximum index | |
1619 | (for indexed arrays) or added as additional key-value pairs in an | |
1620 | associative array. | |
1621 | When applied to a string-valued variable, <I>value</I> is expanded and | |
1622 | appended to the variable's value. | |
ac50fbac CR |
1623 | <P> |
1624 | ||
1625 | A variable can be assigned the <I>nameref</I> attribute using the | |
1626 | <B>-n</B> option to the <B>declare</B> or <B>local</B> builtin commands | |
1627 | (see the descriptions of <B>declare</B> and <B>local</B> below) | |
1628 | to create a <I>nameref</I>, or a reference to another variable. | |
1629 | This allows variables to be manipulated indirectly. | |
a0c0a00f CR |
1630 | Whenever the nameref variable is referenced, assigned to, unset, or has |
1631 | its attributes modified (other than using or changing the <I>nameref</I> | |
1632 | attribute itself), the | |
1633 | operation is actually performed on the variable specified by the nameref | |
1634 | variable's value. | |
ac50fbac CR |
1635 | A nameref is commonly used within shell functions to refer to a variable |
1636 | whose name is passed as an argument to the function. | |
1637 | For instance, if a variable name is passed to a shell function as its first | |
1638 | argument, running | |
1639 | <P> | |
1640 | <DL COMPACT><DT><DD> | |
1641 | <TT>declare -n ref=$1</TT> | |
1642 | ||
1643 | </DL> | |
1644 | ||
1645 | <P> | |
1646 | inside the function creates a nameref variable <B>ref</B> whose value is | |
1647 | the variable name passed as the first argument. | |
a0c0a00f CR |
1648 | References and assignments to <B>ref</B>, and changes to its attributes, |
1649 | are treated as references, assignments, and attribute modifications | |
1650 | to the variable whose name was passed as <B>$1</B>. | |
ac50fbac CR |
1651 | If the control variable in a <B>for</B> loop has the nameref attribute, |
1652 | the list of words can be a list of shell variables, and a name reference | |
1653 | will be established for each word in the list, in turn, when the loop is | |
1654 | executed. | |
a0c0a00f | 1655 | Array variables cannot be given the <B>nameref</B> attribute. |
ac50fbac CR |
1656 | However, nameref variables can reference array variables and subscripted |
1657 | array variables. | |
1658 | Namerefs can be unset using the <B>-n</B> option to the <B>unset</B> builtin. | |
1659 | Otherwise, if <B>unset</B> is executed with the name of a nameref variable | |
1660 | as an argument, the variable referenced by the nameref variable will be unset. | |
17345e5a JA |
1661 | <A NAME="lbAU"> </A> |
1662 | <H4>Positional Parameters</H4> | |
1663 | ||
1664 | <P> | |
1665 | ||
1666 | A | |
1667 | <I>positional parameter</I> | |
1668 | ||
1669 | is a parameter denoted by one or more | |
1670 | digits, other than the single digit 0. Positional parameters are | |
1671 | assigned from the shell's arguments when it is invoked, | |
1672 | and may be reassigned using the | |
1673 | <B>set</B> | |
1674 | ||
1675 | builtin command. Positional parameters may not be assigned to | |
1676 | with assignment statements. The positional parameters are | |
1677 | temporarily replaced when a shell function is executed (see | |
1678 | <FONT SIZE=-1><B>FUNCTIONS</B> | |
1679 | ||
1680 | </FONT> | |
1681 | below). | |
1682 | <P> | |
1683 | ||
1684 | When a positional parameter consisting of more than a single | |
1685 | digit is expanded, it must be enclosed in braces (see | |
1686 | <FONT SIZE=-1><B>EXPANSION</B> | |
1687 | ||
1688 | </FONT> | |
1689 | below). | |
1690 | <A NAME="lbAV"> </A> | |
1691 | <H4>Special Parameters</H4> | |
1692 | ||
1693 | <P> | |
1694 | ||
1695 | The shell treats several parameters specially. These parameters may | |
1696 | only be referenced; assignment to them is not allowed. | |
1697 | ||
1698 | <DL COMPACT> | |
1699 | <DT><B>*</B> | |
1700 | ||
1701 | <DD> | |
ac50fbac CR |
1702 | Expands to the positional parameters, starting from one. |
1703 | When the expansion is not within double quotes, each positional parameter | |
1704 | expands to a separate word. | |
1705 | In contexts where it is performed, those words | |
1706 | are subject to further word splitting and pathname expansion. | |
1707 | When the expansion occurs within double quotes, it expands to a single word | |
a0c0a00f | 1708 | with the value of each parameter separated by the first character of the |
17345e5a JA |
1709 | <FONT SIZE=-1><B>IFS</B> |
1710 | ||
1711 | </FONT> | |
1712 | special variable. That is, "<B>$*</B>" is equivalent | |
1713 | to "<B>$1</B><I>c</I><B>$2</B><I>c</I><B>...</B>", where | |
1714 | <I>c</I> | |
1715 | ||
1716 | is the first character of the value of the | |
1717 | <FONT SIZE=-1><B>IFS</B> | |
1718 | ||
1719 | </FONT> | |
1720 | variable. If | |
1721 | <FONT SIZE=-1><B>IFS</B> | |
1722 | ||
1723 | </FONT> | |
1724 | is unset, the parameters are separated by spaces. | |
1725 | If | |
1726 | <FONT SIZE=-1><B>IFS</B> | |
1727 | ||
1728 | </FONT> | |
1729 | is null, the parameters are joined without intervening separators. | |
1730 | <DT><B>@</B> | |
1731 | ||
1732 | <DD> | |
1733 | Expands to the positional parameters, starting from one. When the | |
1734 | expansion occurs within double quotes, each parameter expands to a | |
1735 | separate word. That is, "<B>$@</B>" is equivalent to | |
1736 | "<B>$1</B>" "<B>$2</B>" ... | |
1737 | If the double-quoted expansion occurs within a word, the expansion of | |
1738 | the first parameter is joined with the beginning part of the original | |
1739 | word, and the expansion of the last parameter is joined with the last | |
1740 | part of the original word. | |
a0c0a00f | 1741 | When there are no positional parameters, "<B>$@</B>" and |
17345e5a JA |
1742 | <B>$@</B> |
1743 | ||
1744 | expand to nothing (i.e., they are removed). | |
1745 | <DT><B>#</B> | |
1746 | ||
1747 | <DD> | |
1748 | Expands to the number of positional parameters in decimal. | |
1749 | <DT><B>?</B> | |
1750 | ||
1751 | <DD> | |
1752 | Expands to the exit status of the most recently executed foreground | |
1753 | pipeline. | |
1754 | <DT><B>-</B> | |
1755 | ||
1756 | <DD> | |
1757 | Expands to the current option flags as specified upon invocation, | |
1758 | by the | |
1759 | <B>set</B> | |
1760 | ||
1761 | builtin command, or those set by the shell itself | |
1762 | (such as the | |
1763 | <B>-i</B> | |
1764 | ||
1765 | option). | |
1766 | <DT><B>$</B> | |
1767 | ||
1768 | <DD> | |
1769 | Expands to the process ID of the shell. In a () subshell, it | |
1770 | expands to the process ID of the current shell, not the | |
1771 | subshell. | |
1772 | <DT><B>!</B> | |
1773 | ||
1774 | <DD> | |
ac50fbac CR |
1775 | Expands to the process ID of the job most recently placed into the |
1776 | background, whether executed as an asynchronous command or using | |
1777 | the <B>bg</B> builtin (see | |
1778 | <FONT SIZE=-1><B>JOB CONTROL</B> | |
1779 | ||
1780 | </FONT> | |
1781 | below). | |
17345e5a JA |
1782 | <DT><B>0</B> |
1783 | ||
1784 | <DD> | |
1785 | Expands to the name of the shell or shell script. This is set at | |
1786 | shell initialization. If | |
1787 | <B>bash</B> | |
1788 | ||
1789 | is invoked with a file of commands, | |
1790 | <B>$0</B> | |
1791 | ||
1792 | is set to the name of that file. If | |
1793 | <B>bash</B> | |
1794 | ||
1795 | is started with the | |
1796 | <B>-c</B> | |
1797 | ||
1798 | option, then | |
1799 | <B>$0</B> | |
1800 | ||
1801 | is set to the first argument after the string to be | |
1802 | executed, if one is present. Otherwise, it is set | |
ac50fbac | 1803 | to the filename used to invoke |
17345e5a JA |
1804 | <B>bash</B>, |
1805 | ||
1806 | as given by argument zero. | |
1807 | <DT><B>_</B> | |
1808 | ||
1809 | <DD> | |
1810 | At shell startup, set to the absolute pathname used to invoke the | |
1811 | shell or shell script being executed as passed in the environment | |
1812 | or argument list. | |
1813 | Subsequently, expands to the last argument to the previous command, | |
1814 | after expansion. | |
1815 | Also set to the full pathname used to invoke each command executed | |
1816 | and placed in the environment exported to that command. | |
1817 | When checking mail, this parameter holds the name of the mail file | |
1818 | currently being checked. | |
1819 | ||
1820 | </DL> | |
1821 | <A NAME="lbAW"> </A> | |
1822 | <H4>Shell Variables</H4> | |
1823 | ||
1824 | <P> | |
1825 | ||
1826 | The following variables are set by the shell: | |
1827 | <P> | |
1828 | ||
1829 | ||
1830 | <DL COMPACT> | |
1831 | <DT><B>BASH</B> | |
1832 | ||
1833 | <DD> | |
ac50fbac | 1834 | Expands to the full filename used to invoke this instance of |
17345e5a JA |
1835 | <B>bash</B>. |
1836 | ||
0001803f CR |
1837 | <DT><B>BASHOPTS</B> |
1838 | ||
1839 | <DD> | |
1840 | A colon-separated list of enabled shell options. Each word in | |
1841 | the list is a valid argument for the | |
1842 | <B>-s</B> | |
1843 | ||
1844 | option to the | |
1845 | <B>shopt</B> | |
1846 | ||
1847 | builtin command (see | |
1848 | <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B> | |
1849 | ||
1850 | </FONT> | |
1851 | below). The options appearing in | |
1852 | <FONT SIZE=-1><B>BASHOPTS</B> | |
1853 | ||
1854 | </FONT> | |
1855 | are those reported as | |
1856 | <I>on</I> | |
1857 | ||
1858 | by <B>shopt</B>. | |
1859 | If this variable is in the environment when | |
1860 | <B>bash</B> | |
1861 | ||
1862 | starts up, each shell option in the list will be enabled before | |
1863 | reading any startup files. | |
1864 | This variable is read-only. | |
17345e5a JA |
1865 | <DT><B>BASHPID</B> |
1866 | ||
1867 | <DD> | |
495aee44 | 1868 | Expands to the process ID of the current <B>bash</B> process. |
17345e5a JA |
1869 | This differs from <B>$$</B> under certain circumstances, such as subshells |
1870 | that do not require <B>bash</B> to be re-initialized. | |
1871 | <DT><B>BASH_ALIASES</B> | |
1872 | ||
1873 | <DD> | |
1874 | An associative array variable whose members correspond to the internal | |
495aee44 | 1875 | list of aliases as maintained by the <B>alias</B> builtin. |
a0c0a00f CR |
1876 | Elements added to this array appear in the alias list; however, |
1877 | unsetting array elements currently does not cause aliases to be removed | |
1878 | from the alias list. | |
1879 | If | |
1880 | <B>BASH_ALIASES</B> | |
1881 | ||
1882 | is unset, it loses its special properties, even if it is | |
1883 | subsequently reset. | |
17345e5a JA |
1884 | <DT><B>BASH_ARGC</B> |
1885 | ||
1886 | <DD> | |
1887 | An array variable whose values are the number of parameters in each | |
1888 | frame of the current <B>bash</B> execution call stack. | |
1889 | The number of | |
1890 | parameters to the current subroutine (shell function or script executed | |
1891 | with <B>.</B> or <B>source</B>) is at the top of the stack. | |
1892 | When a subroutine is executed, the number of parameters passed is pushed onto | |
0001803f CR |
1893 | <FONT SIZE=-1><B>BASH_ARGC</B>. |
1894 | ||
1895 | </FONT> | |
1896 | The shell sets | |
1897 | <FONT SIZE=-1><B>BASH_ARGC</B> | |
1898 | ||
1899 | </FONT> | |
1900 | only when in extended debugging mode (see the description of the | |
17345e5a JA |
1901 | <B>extdebug</B> |
1902 | ||
1903 | option to the | |
1904 | <B>shopt</B> | |
1905 | ||
1906 | builtin below) | |
1907 | <DT><B>BASH_ARGV</B> | |
1908 | ||
1909 | <DD> | |
1910 | An array variable containing all of the parameters in the current <B>bash</B> | |
1911 | execution call stack. The final parameter of the last subroutine call | |
1912 | is at the top of the stack; the first parameter of the initial call is | |
1913 | at the bottom. When a subroutine is executed, the parameters supplied | |
0001803f CR |
1914 | are pushed onto |
1915 | <FONT SIZE=-1><B>BASH_ARGV</B>. | |
1916 | ||
1917 | </FONT> | |
1918 | The shell sets | |
1919 | <FONT SIZE=-1><B>BASH_ARGV</B> | |
1920 | ||
1921 | </FONT> | |
1922 | only when in extended debugging mode | |
17345e5a JA |
1923 | (see the description of the |
1924 | <B>extdebug</B> | |
1925 | ||
1926 | option to the | |
1927 | <B>shopt</B> | |
1928 | ||
1929 | builtin below) | |
1930 | <DT><B>BASH_CMDS</B> | |
1931 | ||
1932 | <DD> | |
1933 | An associative array variable whose members correspond to the internal | |
1934 | hash table of commands as maintained by the <B>hash</B> builtin. | |
a0c0a00f CR |
1935 | Elements added to this array appear in the hash table; however, |
1936 | unsetting array elements currently does not cause command names to be removed | |
1937 | from the hash table. | |
1938 | If | |
1939 | <B>BASH_CMDS</B> | |
1940 | ||
1941 | is unset, it loses its special properties, even if it is | |
1942 | subsequently reset. | |
17345e5a JA |
1943 | <DT><B>BASH_COMMAND</B> |
1944 | ||
1945 | <DD> | |
1946 | The command currently being executed or about to be executed, unless the | |
1947 | shell is executing a command as the result of a trap, | |
1948 | in which case it is the command executing at the time of the trap. | |
1949 | <DT><B>BASH_EXECUTION_STRING</B> | |
1950 | ||
1951 | <DD> | |
1952 | The command argument to the <B>-c</B> invocation option. | |
1953 | <DT><B>BASH_LINENO</B> | |
1954 | ||
1955 | <DD> | |
1956 | An array variable whose members are the line numbers in source files | |
495aee44 CR |
1957 | where each corresponding member of |
1958 | <FONT SIZE=-1><B>FUNCNAME</B> | |
0001803f CR |
1959 | |
1960 | </FONT> | |
495aee44 | 1961 | was invoked. |
17345e5a | 1962 | <B>${BASH_LINENO[</B><I>$i</I><B>]}</B> is the line number in the source |
495aee44 CR |
1963 | file (<B>${BASH_SOURCE[</B><I>$i+1</I><B>]}</B>) where |
1964 | <B>${FUNCNAME[</B><I>$i</I><B>]}</B> was called | |
17345e5a JA |
1965 | (or <B>${BASH_LINENO[</B><I>$i-1</I><B>]}</B> if referenced within another |
1966 | shell function). | |
0001803f CR |
1967 | Use |
1968 | <FONT SIZE=-1><B>LINENO</B> | |
1969 | ||
1970 | </FONT> | |
1971 | to obtain the current line number. | |
a0c0a00f CR |
1972 | <DT><B>BASH_LOADABLES_PATH</B> |
1973 | ||
1974 | <DD> | |
1975 | A colon-separated list of directories in which the shell looks for | |
1976 | dynamically loadable builtins specified by the | |
1977 | <B>enable</B> | |
1978 | ||
1979 | command. | |
17345e5a JA |
1980 | <DT><B>BASH_REMATCH</B> |
1981 | ||
1982 | <DD> | |
1983 | An array variable whose members are assigned by the <B>=~</B> binary | |
1984 | operator to the <B>[[</B> conditional command. | |
1985 | The element with index 0 is the portion of the string | |
1986 | matching the entire regular expression. | |
1987 | The element with index <I>n</I> is the portion of the | |
1988 | string matching the <I>n</I>th parenthesized subexpression. | |
1989 | This variable is read-only. | |
1990 | <DT><B>BASH_SOURCE</B> | |
1991 | ||
1992 | <DD> | |
495aee44 CR |
1993 | An array variable whose members are the source filenames |
1994 | where the corresponding shell function names in the | |
0001803f CR |
1995 | <FONT SIZE=-1><B>FUNCNAME</B> |
1996 | ||
1997 | </FONT> | |
495aee44 CR |
1998 | array variable are defined. |
1999 | The shell function | |
2000 | <B>${FUNCNAME[</B><I>$i</I><B>]}</B> is defined in the file | |
2001 | <B>${BASH_SOURCE[</B><I>$i</I><B>]}</B> and called from | |
2002 | <B>${BASH_SOURCE[</B><I>$i+1</I><B>]}</B>. | |
17345e5a JA |
2003 | <DT><B>BASH_SUBSHELL</B> |
2004 | ||
2005 | <DD> | |
ac50fbac CR |
2006 | Incremented by one within each subshell or subshell environment when |
2007 | the shell begins executing in that environment. | |
17345e5a JA |
2008 | The initial value is 0. |
2009 | <DT><B>BASH_VERSINFO</B> | |
2010 | ||
2011 | <DD> | |
2012 | A readonly array variable whose members hold version information for | |
2013 | this instance of | |
2014 | <B>bash</B>. | |
2015 | ||
2016 | The values assigned to the array members are as follows: | |
2017 | <P> | |
2018 | <DL COMPACT><DT><DD> | |
17345e5a JA |
2019 | <DL COMPACT> |
2020 | <DT><B>BASH_VERSINFO[</B>0] | |
2021 | ||
2022 | <DD> | |
2023 | The major version number (the <I>release</I>). | |
2024 | <DT><B>BASH_VERSINFO[</B>1] | |
2025 | ||
2026 | <DD> | |
2027 | The minor version number (the <I>version</I>). | |
2028 | <DT><B>BASH_VERSINFO[</B>2] | |
2029 | ||
2030 | <DD> | |
2031 | The patch level. | |
2032 | <DT><B>BASH_VERSINFO[</B>3] | |
2033 | ||
2034 | <DD> | |
2035 | The build version. | |
2036 | <DT><B>BASH_VERSINFO[</B>4] | |
2037 | ||
2038 | <DD> | |
2039 | The release status (e.g., <I>beta1</I>). | |
2040 | <DT><B>BASH_VERSINFO[</B>5] | |
2041 | ||
2042 | <DD> | |
0001803f CR |
2043 | The value of |
2044 | <FONT SIZE=-1><B>MACHTYPE</B>. | |
2045 | ||
2046 | </FONT> | |
17345e5a JA |
2047 | </DL></DL> |
2048 | ||
2049 | <DT><B>BASH_VERSION</B> | |
2050 | ||
2051 | <DD> | |
2052 | Expands to a string describing the version of this instance of | |
2053 | <B>bash</B>. | |
2054 | ||
2055 | <DT><B>COMP_CWORD</B> | |
2056 | ||
2057 | <DD> | |
2058 | An index into <B>${COMP_WORDS}</B> of the word containing the current | |
2059 | cursor position. | |
2060 | This variable is available only in shell functions invoked by the | |
2061 | programmable completion facilities (see <B>Programmable Completion</B> | |
2062 | below). | |
2063 | <DT><B>COMP_KEY</B> | |
2064 | ||
2065 | <DD> | |
2066 | The key (or final key of a key sequence) used to invoke the current | |
2067 | completion function. | |
2068 | <DT><B>COMP_LINE</B> | |
2069 | ||
2070 | <DD> | |
2071 | The current command line. | |
2072 | This variable is available only in shell functions and external | |
2073 | commands invoked by the | |
2074 | programmable completion facilities (see <B>Programmable Completion</B> | |
2075 | below). | |
2076 | <DT><B>COMP_POINT</B> | |
2077 | ||
2078 | <DD> | |
2079 | The index of the current cursor position relative to the beginning of | |
2080 | the current command. | |
2081 | If the current cursor position is at the end of the current command, | |
2082 | the value of this variable is equal to <B>${#COMP_LINE}</B>. | |
2083 | This variable is available only in shell functions and external | |
2084 | commands invoked by the | |
2085 | programmable completion facilities (see <B>Programmable Completion</B> | |
2086 | below). | |
2087 | <DT><B>COMP_TYPE</B> | |
2088 | ||
2089 | <DD> | |
2090 | Set to an integer value corresponding to the type of completion attempted | |
2091 | that caused a completion function to be called: | |
2092 | <I>TAB</I>, for normal completion, | |
2093 | <I>?</I>, for listing completions after successive tabs, | |
2094 | <I>!</I>, for listing alternatives on partial word completion, | |
2095 | <I>@</I>, to list completions if the word is not unmodified, | |
2096 | or | |
2097 | <I>%</I>, for menu completion. | |
2098 | This variable is available only in shell functions and external | |
2099 | commands invoked by the | |
2100 | programmable completion facilities (see <B>Programmable Completion</B> | |
2101 | below). | |
2102 | <DT><B>COMP_WORDBREAKS</B> | |
2103 | ||
2104 | <DD> | |
0001803f | 2105 | The set of characters that the <B>readline</B> library treats as word |
17345e5a JA |
2106 | separators when performing word completion. |
2107 | If | |
2108 | <FONT SIZE=-1><B>COMP_WORDBREAKS</B> | |
2109 | ||
2110 | </FONT> | |
2111 | is unset, it loses its special properties, even if it is | |
2112 | subsequently reset. | |
2113 | <DT><B>COMP_WORDS</B> | |
2114 | ||
2115 | <DD> | |
2116 | An array variable (see <B>Arrays</B> below) consisting of the individual | |
2117 | words in the current command line. | |
0001803f CR |
2118 | The line is split into words as <B>readline</B> would split it, using |
2119 | <FONT SIZE=-1><B>COMP_WORDBREAKS</B> | |
2120 | ||
2121 | </FONT> | |
2122 | as described above. | |
17345e5a JA |
2123 | This variable is available only in shell functions invoked by the |
2124 | programmable completion facilities (see <B>Programmable Completion</B> | |
2125 | below). | |
495aee44 CR |
2126 | <DT><B>COPROC</B> |
2127 | ||
2128 | <DD> | |
2129 | An array variable (see <B>Arrays</B> below) created to hold the file descriptors | |
2130 | for output from and input to an unnamed coprocess (see <B>Coprocesses</B> | |
2131 | above). | |
17345e5a JA |
2132 | <DT><B>DIRSTACK</B> |
2133 | ||
2134 | <DD> | |
2135 | An array variable (see | |
2136 | <B>Arrays</B> | |
2137 | ||
2138 | below) containing the current contents of the directory stack. | |
2139 | Directories appear in the stack in the order they are displayed by the | |
2140 | <B>dirs</B> | |
2141 | ||
2142 | builtin. | |
2143 | Assigning to members of this array variable may be used to modify | |
2144 | directories already in the stack, but the | |
2145 | <B>pushd</B> | |
2146 | ||
2147 | and | |
2148 | <B>popd</B> | |
2149 | ||
2150 | builtins must be used to add and remove directories. | |
2151 | Assignment to this variable will not change the current directory. | |
2152 | If | |
2153 | <FONT SIZE=-1><B>DIRSTACK</B> | |
2154 | ||
2155 | </FONT> | |
2156 | is unset, it loses its special properties, even if it is | |
2157 | subsequently reset. | |
2158 | <DT><B>EUID</B> | |
2159 | ||
2160 | <DD> | |
2161 | Expands to the effective user ID of the current user, initialized at | |
2162 | shell startup. This variable is readonly. | |
2163 | <DT><B>FUNCNAME</B> | |
2164 | ||
2165 | <DD> | |
2166 | An array variable containing the names of all shell functions | |
2167 | currently in the execution call stack. | |
2168 | The element with index 0 is the name of any currently-executing | |
2169 | shell function. | |
495aee44 | 2170 | The bottom-most element (the one with the highest index) is |
17345e5a JA |
2171 | <TT>"main"</TT>. |
2172 | ||
2173 | This variable exists only when a shell function is executing. | |
2174 | Assignments to | |
2175 | <FONT SIZE=-1><B>FUNCNAME</B> | |
2176 | ||
2177 | </FONT> | |
a0c0a00f | 2178 | have no effect. |
17345e5a JA |
2179 | If |
2180 | <FONT SIZE=-1><B>FUNCNAME</B> | |
2181 | ||
2182 | </FONT> | |
2183 | is unset, it loses its special properties, even if it is | |
2184 | subsequently reset. | |
495aee44 CR |
2185 | <P> |
2186 | ||
2187 | ||
2188 | This variable can be used with <B>BASH_LINENO</B> and <B>BASH_SOURCE</B>. | |
2189 | Each element of <B>FUNCNAME</B> has corresponding elements in | |
2190 | <B>BASH_LINENO</B> and <B>BASH_SOURCE</B> to describe the call stack. | |
2191 | For instance, <B>${FUNCNAME[</B><I>$i</I><B>]}</B> was called from the file | |
2192 | <B>${BASH_SOURCE[</B><I>$i+1</I><B>]}</B> at line number | |
2193 | <B>${BASH_LINENO[</B><I>$i</I><B>]}</B>. | |
2194 | The <B>caller</B> builtin displays the current call stack using this | |
2195 | information. | |
17345e5a JA |
2196 | <DT><B>GROUPS</B> |
2197 | ||
2198 | <DD> | |
2199 | An array variable containing the list of groups of which the current | |
2200 | user is a member. | |
a0c0a00f | 2201 | Assignments to |
17345e5a JA |
2202 | <FONT SIZE=-1><B>GROUPS</B> |
2203 | ||
2204 | </FONT> | |
a0c0a00f | 2205 | have no effect. |
17345e5a JA |
2206 | If |
2207 | <FONT SIZE=-1><B>GROUPS</B> | |
2208 | ||
2209 | </FONT> | |
2210 | is unset, it loses its special properties, even if it is | |
2211 | subsequently reset. | |
2212 | <DT><B>HISTCMD</B> | |
2213 | ||
2214 | <DD> | |
2215 | The history number, or index in the history list, of the current | |
2216 | command. | |
2217 | If | |
2218 | <FONT SIZE=-1><B>HISTCMD</B> | |
2219 | ||
2220 | </FONT> | |
2221 | is unset, it loses its special properties, even if it is | |
2222 | subsequently reset. | |
2223 | <DT><B>HOSTNAME</B> | |
2224 | ||
2225 | <DD> | |
2226 | Automatically set to the name of the current host. | |
2227 | <DT><B>HOSTTYPE</B> | |
2228 | ||
2229 | <DD> | |
2230 | Automatically set to a string that uniquely | |
2231 | describes the type of machine on which | |
2232 | <B>bash</B> | |
2233 | ||
2234 | is executing. | |
2235 | The default is system-dependent. | |
2236 | <DT><B>LINENO</B> | |
2237 | ||
2238 | <DD> | |
2239 | Each time this parameter is referenced, the shell substitutes | |
2240 | a decimal number representing the current sequential line number | |
2241 | (starting with 1) within a script or function. When not in a | |
2242 | script or function, the value substituted is not guaranteed to | |
2243 | be meaningful. | |
2244 | If | |
2245 | <FONT SIZE=-1><B>LINENO</B> | |
2246 | ||
2247 | </FONT> | |
2248 | is unset, it loses its special properties, even if it is | |
2249 | subsequently reset. | |
2250 | <DT><B>MACHTYPE</B> | |
2251 | ||
2252 | <DD> | |
2253 | Automatically set to a string that fully describes the system | |
2254 | type on which | |
2255 | <B>bash</B> | |
2256 | ||
2257 | is executing, in the standard GNU <I>cpu-company-system</I> format. | |
2258 | The default is system-dependent. | |
495aee44 CR |
2259 | <DT><B>MAPFILE</B> |
2260 | ||
2261 | <DD> | |
2262 | An array variable (see <B>Arrays</B> below) created to hold the text | |
2263 | read by the <B>mapfile</B> builtin when no variable name is supplied. | |
17345e5a JA |
2264 | <DT><B>OLDPWD</B> |
2265 | ||
2266 | <DD> | |
2267 | The previous working directory as set by the | |
2268 | <B>cd</B> | |
2269 | ||
2270 | command. | |
2271 | <DT><B>OPTARG</B> | |
2272 | ||
2273 | <DD> | |
2274 | The value of the last option argument processed by the | |
2275 | <B>getopts</B> | |
2276 | ||
2277 | builtin command (see | |
2278 | <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B> | |
2279 | ||
2280 | </FONT> | |
2281 | below). | |
2282 | <DT><B>OPTIND</B> | |
2283 | ||
2284 | <DD> | |
2285 | The index of the next argument to be processed by the | |
2286 | <B>getopts</B> | |
2287 | ||
2288 | builtin command (see | |
2289 | <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B> | |
2290 | ||
2291 | </FONT> | |
2292 | below). | |
2293 | <DT><B>OSTYPE</B> | |
2294 | ||
2295 | <DD> | |
2296 | Automatically set to a string that | |
2297 | describes the operating system on which | |
2298 | <B>bash</B> | |
2299 | ||
2300 | is executing. | |
2301 | The default is system-dependent. | |
2302 | <DT><B>PIPESTATUS</B> | |
2303 | ||
2304 | <DD> | |
2305 | An array variable (see | |
2306 | <B>Arrays</B> | |
2307 | ||
2308 | below) containing a list of exit status values from the processes | |
2309 | in the most-recently-executed foreground pipeline (which may | |
2310 | contain only a single command). | |
2311 | <DT><B>PPID</B> | |
2312 | ||
2313 | <DD> | |
2314 | The process ID of the shell's parent. This variable is readonly. | |
2315 | <DT><B>PWD</B> | |
2316 | ||
2317 | <DD> | |
2318 | The current working directory as set by the | |
2319 | <B>cd</B> | |
2320 | ||
2321 | command. | |
2322 | <DT><B>RANDOM</B> | |
2323 | ||
2324 | <DD> | |
2325 | Each time this parameter is referenced, a random integer between | |
2326 | 0 and 32767 is | |
2327 | generated. The sequence of random numbers may be initialized by assigning | |
2328 | a value to | |
2329 | <FONT SIZE=-1><B>RANDOM</B>. | |
2330 | ||
2331 | </FONT> | |
2332 | If | |
2333 | <FONT SIZE=-1><B>RANDOM</B> | |
2334 | ||
2335 | </FONT> | |
2336 | is unset, it loses its special properties, even if it is | |
2337 | subsequently reset. | |
495aee44 CR |
2338 | <DT><B>READLINE_LINE</B> |
2339 | ||
2340 | <DD> | |
2341 | The contents of the | |
2342 | <B>readline</B> | |
2343 | ||
2344 | line buffer, for use with | |
2345 | <TT>bind -x</TT> | |
2346 | ||
2347 | (see | |
2348 | <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B> | |
2349 | ||
2350 | </FONT> | |
2351 | below). | |
2352 | <DT><B>READLINE_POINT</B> | |
2353 | ||
2354 | <DD> | |
2355 | The position of the insertion point in the | |
2356 | <B>readline</B> | |
2357 | ||
2358 | line buffer, for use with | |
2359 | <TT>bind -x</TT> | |
2360 | ||
2361 | (see | |
2362 | <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B> | |
2363 | ||
2364 | </FONT> | |
2365 | below). | |
17345e5a JA |
2366 | <DT><B>REPLY</B> |
2367 | ||
2368 | <DD> | |
2369 | Set to the line of input read by the | |
2370 | <B>read</B> | |
2371 | ||
2372 | builtin command when no arguments are supplied. | |
2373 | <DT><B>SECONDS</B> | |
2374 | ||
2375 | <DD> | |
2376 | Each time this parameter is | |
2377 | referenced, the number of seconds since shell invocation is returned. If a | |
a0c0a00f | 2378 | value is assigned to |
17345e5a JA |
2379 | <FONT SIZE=-1><B>SECONDS</B>, |
2380 | ||
2381 | </FONT> | |
2382 | the value returned upon subsequent | |
2383 | references is | |
2384 | the number of seconds since the assignment plus the value assigned. | |
2385 | If | |
2386 | <FONT SIZE=-1><B>SECONDS</B> | |
2387 | ||
2388 | </FONT> | |
2389 | is unset, it loses its special properties, even if it is | |
2390 | subsequently reset. | |
2391 | <DT><B>SHELLOPTS</B> | |
2392 | ||
2393 | <DD> | |
2394 | A colon-separated list of enabled shell options. Each word in | |
2395 | the list is a valid argument for the | |
2396 | <B>-o</B> | |
2397 | ||
2398 | option to the | |
2399 | <B>set</B> | |
2400 | ||
2401 | builtin command (see | |
2402 | <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B> | |
2403 | ||
2404 | </FONT> | |
2405 | below). The options appearing in | |
2406 | <FONT SIZE=-1><B>SHELLOPTS</B> | |
2407 | ||
2408 | </FONT> | |
2409 | are those reported as | |
2410 | <I>on</I> | |
2411 | ||
2412 | by <B>set -o</B>. | |
2413 | If this variable is in the environment when | |
2414 | <B>bash</B> | |
2415 | ||
2416 | starts up, each shell option in the list will be enabled before | |
2417 | reading any startup files. | |
2418 | This variable is read-only. | |
2419 | <DT><B>SHLVL</B> | |
2420 | ||
2421 | <DD> | |
2422 | Incremented by one each time an instance of | |
2423 | <B>bash</B> | |
2424 | ||
2425 | is started. | |
2426 | <DT><B>UID</B> | |
2427 | ||
2428 | <DD> | |
2429 | Expands to the user ID of the current user, initialized at shell startup. | |
2430 | This variable is readonly. | |
2431 | ||
2432 | </DL> | |
2433 | <P> | |
2434 | ||
2435 | The following variables are used by the shell. In some cases, | |
2436 | <B>bash</B> | |
2437 | ||
2438 | assigns a default value to a variable; these cases are noted | |
2439 | below. | |
2440 | <P> | |
2441 | ||
2442 | ||
2443 | <DL COMPACT> | |
ac50fbac CR |
2444 | <DT><B>BASH_COMPAT</B> |
2445 | ||
2446 | <DD> | |
2447 | The value is used to set the shell's compatibility level. | |
2448 | See the description of the <B>shopt</B> builtin below under | |
2449 | <B>SHELL BUILTIN COMMANDS</B> | |
2450 | for a description of the various compatibility | |
2451 | levels and their effects. | |
2452 | The value may be a decimal number (e.g., 4.2) or an integer (e.g., 42) | |
2453 | corresponding to the desired compatibility level. | |
2454 | If <B>BASH_COMPAT</B> is unset or set to the empty string, the compatibility | |
2455 | level is set to the default for the current version. | |
2456 | If <B>BASH_COMPAT</B> is set to a value that is not one of the valid | |
2457 | compatibility levels, the shell prints an error message and sets the | |
2458 | compatibility level to the default for the current version. | |
2459 | The valid compatibility levels correspond to the compatibility options | |
2460 | accepted by the <B>shopt</B> builtin described below (for example, | |
2461 | <B>compat42</B> means that 4.2 and 42 are valid values). | |
2462 | The current version is also a valid value. | |
17345e5a JA |
2463 | <DT><B>BASH_ENV</B> |
2464 | ||
2465 | <DD> | |
2466 | If this parameter is set when <B>bash</B> is executing a shell script, | |
2467 | its value is interpreted as a filename containing commands to | |
2468 | initialize the shell, as in | |
2469 | <A HREF="file:~/.bashrc"><I>~/.bashrc</I></A>. | |
2470 | ||
2471 | The value of | |
2472 | <FONT SIZE=-1><B>BASH_ENV</B> | |
2473 | ||
2474 | </FONT> | |
2475 | is subjected to parameter expansion, command substitution, and arithmetic | |
ac50fbac | 2476 | expansion before being interpreted as a filename. |
17345e5a JA |
2477 | <FONT SIZE=-1><B>PATH</B> |
2478 | ||
2479 | </FONT> | |
ac50fbac | 2480 | is not used to search for the resultant filename. |
0001803f CR |
2481 | <DT><B>BASH_XTRACEFD</B> |
2482 | ||
2483 | <DD> | |
2484 | If set to an integer corresponding to a valid file descriptor, <B>bash</B> | |
2485 | will write the trace output generated when | |
2486 | <TT>set -x</TT> | |
2487 | ||
2488 | is enabled to that file descriptor. | |
2489 | The file descriptor is closed when | |
2490 | <FONT SIZE=-1><B>BASH_XTRACEFD</B> | |
2491 | ||
2492 | </FONT> | |
2493 | is unset or assigned a new value. | |
2494 | Unsetting | |
2495 | <FONT SIZE=-1><B>BASH_XTRACEFD</B> | |
2496 | ||
2497 | </FONT> | |
2498 | or assigning it the empty string causes the | |
2499 | trace output to be sent to the standard error. | |
2500 | Note that setting | |
2501 | <FONT SIZE=-1><B>BASH_XTRACEFD</B> | |
2502 | ||
2503 | </FONT> | |
2504 | to 2 (the standard error file | |
2505 | descriptor) and then unsetting it will result in the standard error | |
2506 | being closed. | |
495aee44 CR |
2507 | <DT><B>CDPATH</B> |
2508 | ||
2509 | <DD> | |
2510 | The search path for the | |
2511 | <B>cd</B> | |
2512 | ||
2513 | command. | |
2514 | This is a colon-separated list of directories in which the shell looks | |
2515 | for destination directories specified by the | |
2516 | <B>cd</B> | |
2517 | ||
2518 | command. | |
2519 | A sample value is | |
2520 | <TT>".:~:/usr"</TT>. | |
2521 | ||
ac50fbac CR |
2522 | <DT><B>CHILD_MAX</B> |
2523 | ||
2524 | <DD> | |
2525 | Set the number of exited child status values for the shell to remember. | |
2526 | Bash will not allow this value to be decreased below a POSIX-mandated | |
2527 | minimum, and there is a maximum value (currently 8192) that this may | |
2528 | not exceed. | |
2529 | The minimum value is system-dependent. | |
17345e5a JA |
2530 | <DT><B>COLUMNS</B> |
2531 | ||
2532 | <DD> | |
495aee44 | 2533 | Used by the <B>select</B> compound command to determine the terminal width |
ac50fbac CR |
2534 | when printing selection lists. |
2535 | Automatically set if the | |
2536 | <B>checkwinsize</B> | |
2537 | ||
2538 | option is enabled or in an interactive shell upon receipt of a | |
495aee44 CR |
2539 | <FONT SIZE=-1><B>SIGWINCH</B>. |
2540 | ||
2541 | </FONT> | |
17345e5a JA |
2542 | <DT><B>COMPREPLY</B> |
2543 | ||
2544 | <DD> | |
2545 | An array variable from which <B>bash</B> reads the possible completions | |
2546 | generated by a shell function invoked by the programmable completion | |
2547 | facility (see <B>Programmable Completion</B> below). | |
ac50fbac | 2548 | Each array element contains one possible completion. |
17345e5a JA |
2549 | <DT><B>EMACS</B> |
2550 | ||
2551 | <DD> | |
2552 | If <B>bash</B> finds this variable in the environment when the shell starts | |
2553 | with value | |
2554 | <TT>t</TT>, | |
2555 | ||
495aee44 | 2556 | it assumes that the shell is running in an Emacs shell buffer and disables |
17345e5a | 2557 | line editing. |
495aee44 CR |
2558 | <DT><B>ENV</B> |
2559 | ||
2560 | <DD> | |
2561 | Similar to | |
2562 | <FONT SIZE=-1><B>BASH_ENV</B>; | |
2563 | ||
2564 | </FONT> | |
2565 | used when the shell is invoked in POSIX mode. | |
a0c0a00f CR |
2566 | <DT><B>EXECIGNORE</B> |
2567 | ||
2568 | <DD> | |
2569 | A colon-separated list of shell patterns (see <B>Pattern Matching</B>) | |
2570 | defining the list of filenames to be ignored by command search using | |
2571 | <B>PATH</B>. | |
2572 | Files whose full pathnames match one of these patterns are not considered | |
2573 | executable files for the purposes of completion and command execution | |
2574 | via <B>PATH</B> lookup. | |
2575 | This does not affect the behavior of the <B>[</B>, <B>test</B>, and <B>[[</B> | |
2576 | commands. | |
2577 | Full pathnames in the command hash table are not subject to <B>EXECIGNORE</B>. | |
2578 | Use this variable to ignore shared library files that have the executable | |
2579 | bit set, but are not executable files. | |
2580 | The pattern matching honors the setting of the <B>extglob</B> shell | |
2581 | option. | |
17345e5a JA |
2582 | <DT><B>FCEDIT</B> |
2583 | ||
2584 | <DD> | |
2585 | The default editor for the | |
2586 | <B>fc</B> | |
2587 | ||
2588 | builtin command. | |
2589 | <DT><B>FIGNORE</B> | |
2590 | ||
2591 | <DD> | |
2592 | A colon-separated list of suffixes to ignore when performing | |
2593 | filename completion (see | |
2594 | <FONT SIZE=-1><B>READLINE</B> | |
2595 | ||
2596 | </FONT> | |
2597 | below). | |
2598 | A filename whose suffix matches one of the entries in | |
2599 | <FONT SIZE=-1><B>FIGNORE</B> | |
2600 | ||
2601 | </FONT> | |
2602 | is excluded from the list of matched filenames. | |
2603 | A sample value is | |
2604 | <TT>".o:~"</TT>. | |
2605 | ||
495aee44 CR |
2606 | <DT><B>FUNCNEST</B> |
2607 | ||
2608 | <DD> | |
2609 | If set to a numeric value greater than 0, defines a maximum function | |
2610 | nesting level. Function invocations that exceed this nesting level | |
2611 | will cause the current command to abort. | |
17345e5a JA |
2612 | <DT><B>GLOBIGNORE</B> |
2613 | ||
2614 | <DD> | |
2615 | A colon-separated list of patterns defining the set of filenames to | |
2616 | be ignored by pathname expansion. | |
2617 | If a filename matched by a pathname expansion pattern also matches one | |
2618 | of the patterns in | |
2619 | <FONT SIZE=-1><B>GLOBIGNORE</B>, | |
2620 | ||
2621 | </FONT> | |
2622 | it is removed from the list of matches. | |
2623 | <DT><B>HISTCONTROL</B> | |
2624 | ||
2625 | <DD> | |
2626 | A colon-separated list of values controlling how commands are saved on | |
2627 | the history list. | |
2628 | If the list of values includes | |
2629 | <I>ignorespace</I>, | |
2630 | ||
2631 | lines which begin with a | |
2632 | <B>space</B> | |
2633 | ||
2634 | character are not saved in the history list. | |
a0c0a00f | 2635 | A value of |
17345e5a JA |
2636 | <I>ignoredups</I> |
2637 | ||
2638 | causes lines matching the previous history entry to not be saved. | |
2639 | A value of | |
2640 | <I>ignoreboth</I> | |
2641 | ||
2642 | is shorthand for <I>ignorespace</I> and <I>ignoredups</I>. | |
2643 | A value of | |
2644 | <I>erasedups</I> | |
2645 | ||
2646 | causes all previous lines matching the current line to be removed from | |
2647 | the history list before that line is saved. | |
2648 | Any value not in the above list is ignored. | |
0001803f CR |
2649 | If |
2650 | <FONT SIZE=-1><B>HISTCONTROL</B> | |
2651 | ||
2652 | </FONT> | |
2653 | is unset, or does not include a valid value, | |
17345e5a JA |
2654 | all lines read by the shell parser are saved on the history list, |
2655 | subject to the value of | |
0001803f | 2656 | <FONT SIZE=-1><B>HISTIGNORE</B>. |
17345e5a | 2657 | |
0001803f | 2658 | </FONT> |
17345e5a JA |
2659 | The second and subsequent lines of a multi-line compound command are |
2660 | not tested, and are added to the history regardless of the value of | |
0001803f | 2661 | <FONT SIZE=-1><B>HISTCONTROL</B>. |
17345e5a | 2662 | |
0001803f | 2663 | </FONT> |
17345e5a JA |
2664 | <DT><B>HISTFILE</B> |
2665 | ||
2666 | <DD> | |
2667 | The name of the file in which command history is saved (see | |
2668 | <FONT SIZE=-1><B>HISTORY</B> | |
2669 | ||
2670 | </FONT> | |
2671 | below). The default value is <A HREF="file:~/.bash_history"><I>~/.bash_history</I></A>. If unset, the | |
ac50fbac | 2672 | command history is not saved when a shell exits. |
17345e5a JA |
2673 | <DT><B>HISTFILESIZE</B> |
2674 | ||
2675 | <DD> | |
2676 | The maximum number of lines contained in the history file. When this | |
2677 | variable is assigned a value, the history file is truncated, if | |
ac50fbac CR |
2678 | necessary, |
2679 | to contain no more than that number of lines by removing the oldest entries. | |
2680 | The history file is also truncated to this size after | |
2681 | writing it when a shell exits. | |
2682 | If the value is 0, the history file is truncated to zero size. | |
2683 | Non-numeric values and numeric values less than zero inhibit truncation. | |
2684 | The shell sets the default value to the value of <B>HISTSIZE</B> | |
2685 | after reading any startup files. | |
17345e5a JA |
2686 | <DT><B>HISTIGNORE</B> |
2687 | ||
2688 | <DD> | |
2689 | A colon-separated list of patterns used to decide which command lines | |
2690 | should be saved on the history list. Each pattern is anchored at the | |
2691 | beginning of the line and must match the complete line (no implicit | |
2692 | `<B>*</B>' is appended). Each pattern is tested against the line | |
2693 | after the checks specified by | |
0001803f | 2694 | <FONT SIZE=-1><B>HISTCONTROL</B> |
17345e5a | 2695 | |
0001803f | 2696 | </FONT> |
17345e5a JA |
2697 | are applied. |
2698 | In addition to the normal shell pattern matching characters, `<B>&</B>' | |
2699 | matches the previous history line. `<B>&</B>' may be escaped using a | |
2700 | backslash; the backslash is removed before attempting a match. | |
2701 | The second and subsequent lines of a multi-line compound command are | |
2702 | not tested, and are added to the history regardless of the value of | |
0001803f | 2703 | <FONT SIZE=-1><B>HISTIGNORE</B>. |
17345e5a | 2704 | |
0001803f | 2705 | </FONT> |
a0c0a00f CR |
2706 | The pattern matching honors the setting of the <B>extglob</B> shell |
2707 | option. | |
17345e5a JA |
2708 | <DT><B>HISTSIZE</B> |
2709 | ||
2710 | <DD> | |
2711 | The number of commands to remember in the command history (see | |
2712 | <FONT SIZE=-1><B>HISTORY</B> | |
2713 | ||
2714 | </FONT> | |
ac50fbac CR |
2715 | below). |
2716 | If the value is 0, commands are not saved in the history list. | |
2717 | Numeric values less than zero result in every command being saved | |
2718 | on the history list (there is no limit). | |
2719 | The shell sets the default value to 500 after reading any startup files. | |
17345e5a JA |
2720 | <DT><B>HISTTIMEFORMAT</B> |
2721 | ||
2722 | <DD> | |
2723 | If this variable is set and not null, its value is used as a format string | |
2724 | for <I>strftime</I>(3) to print the time stamp associated with each history | |
2725 | entry displayed by the <B>history</B> builtin. | |
2726 | If this variable is set, time stamps are written to the history file so | |
2727 | they may be preserved across shell sessions. | |
2728 | This uses the history comment character to distinguish timestamps from | |
2729 | other history lines. | |
2730 | <DT><B>HOME</B> | |
2731 | ||
2732 | <DD> | |
2733 | The home directory of the current user; the default argument for the | |
2734 | <B>cd</B> builtin command. | |
2735 | The value of this variable is also used when performing tilde expansion. | |
2736 | <DT><B>HOSTFILE</B> | |
2737 | ||
2738 | <DD> | |
2739 | Contains the name of a file in the same format as | |
2740 | ||
2741 | <I>/etc/hosts</I> | |
2742 | ||
2743 | that should be read when the shell needs to complete a | |
2744 | hostname. | |
2745 | The list of possible hostname completions may be changed while the | |
2746 | shell is running; | |
2747 | the next time hostname completion is attempted after the | |
2748 | value is changed, | |
2749 | <B>bash</B> | |
2750 | ||
2751 | adds the contents of the new file to the existing list. | |
2752 | If | |
2753 | <FONT SIZE=-1><B>HOSTFILE</B> | |
2754 | ||
2755 | </FONT> | |
0001803f CR |
2756 | is set, but has no value, or does not name a readable file, |
2757 | <B>bash</B> attempts to read | |
17345e5a JA |
2758 | |
2759 | <I>/etc/hosts</I> | |
2760 | ||
2761 | to obtain the list of possible hostname completions. | |
2762 | When | |
2763 | <FONT SIZE=-1><B>HOSTFILE</B> | |
2764 | ||
2765 | </FONT> | |
2766 | is unset, the hostname list is cleared. | |
2767 | <DT><B>IFS</B> | |
2768 | ||
2769 | <DD> | |
2770 | The | |
2771 | <I>Internal Field Separator</I> | |
2772 | ||
2773 | that is used | |
2774 | for word splitting after expansion and to | |
2775 | split lines into words with the | |
2776 | <B>read</B> | |
2777 | ||
2778 | builtin command. The default value is | |
2779 | ``<space><tab><newline>''. | |
2780 | <DT><B>IGNOREEOF</B> | |
2781 | ||
2782 | <DD> | |
2783 | Controls the | |
2784 | action of an interactive shell on receipt of an | |
2785 | <FONT SIZE=-1><B>EOF</B> | |
2786 | ||
2787 | </FONT> | |
2788 | character as the sole input. If set, the value is the number of | |
2789 | consecutive | |
2790 | <FONT SIZE=-1><B>EOF</B> | |
2791 | ||
2792 | </FONT> | |
2793 | characters which must be | |
2794 | typed as the first characters on an input line before | |
2795 | <B>bash</B> | |
2796 | ||
2797 | exits. If the variable exists but does not have a numeric value, or | |
2798 | has no value, the default value is 10. If it does not exist, | |
2799 | <FONT SIZE=-1><B>EOF</B> | |
2800 | ||
2801 | </FONT> | |
2802 | signifies the end of input to the shell. | |
2803 | <DT><B>INPUTRC</B> | |
2804 | ||
2805 | <DD> | |
2806 | The filename for the | |
2807 | <B>readline</B> | |
2808 | ||
2809 | startup file, overriding the default of | |
2810 | ||
2811 | <A HREF="file:~/.inputrc"><I>~/.inputrc</I></A> | |
2812 | ||
2813 | (see | |
2814 | <FONT SIZE=-1><B>READLINE</B> | |
2815 | ||
2816 | </FONT> | |
2817 | below). | |
2818 | <DT><B>LANG</B> | |
2819 | ||
2820 | <DD> | |
2821 | Used to determine the locale category for any category not specifically | |
2822 | selected with a variable starting with <B>LC_</B>. | |
2823 | <DT><B>LC_ALL</B> | |
2824 | ||
2825 | <DD> | |
0001803f CR |
2826 | This variable overrides the value of |
2827 | <FONT SIZE=-1><B>LANG</B> | |
2828 | ||
2829 | </FONT> | |
2830 | and any other | |
17345e5a JA |
2831 | <B>LC_</B> variable specifying a locale category. |
2832 | <DT><B>LC_COLLATE</B> | |
2833 | ||
2834 | <DD> | |
2835 | This variable determines the collation order used when sorting the | |
2836 | results of pathname expansion, and determines the behavior of range | |
2837 | expressions, equivalence classes, and collating sequences within | |
2838 | pathname expansion and pattern matching. | |
2839 | <DT><B>LC_CTYPE</B> | |
2840 | ||
2841 | <DD> | |
2842 | This variable determines the interpretation of characters and the | |
2843 | behavior of character classes within pathname expansion and pattern | |
2844 | matching. | |
2845 | <DT><B>LC_MESSAGES</B> | |
2846 | ||
2847 | <DD> | |
2848 | This variable determines the locale used to translate double-quoted | |
2849 | strings preceded by a <B>$</B>. | |
2850 | <DT><B>LC_NUMERIC</B> | |
2851 | ||
2852 | <DD> | |
2853 | This variable determines the locale category used for number formatting. | |
a0c0a00f CR |
2854 | <DT><B>LC_TIME</B> |
2855 | ||
2856 | <DD> | |
2857 | This variable determines the locale category used for data and time | |
2858 | formatting. | |
17345e5a JA |
2859 | <DT><B>LINES</B> |
2860 | ||
2861 | <DD> | |
495aee44 | 2862 | Used by the <B>select</B> compound command to determine the column length |
ac50fbac CR |
2863 | for printing selection lists. |
2864 | Automatically set if the | |
2865 | <B>checkwinsize</B> | |
2866 | ||
2867 | option is enabled or in an interactive shell upon receipt of a | |
0001803f CR |
2868 | <FONT SIZE=-1><B>SIGWINCH</B>. |
2869 | ||
2870 | </FONT> | |
17345e5a JA |
2871 | <DT><B>MAIL</B> |
2872 | ||
2873 | <DD> | |
495aee44 | 2874 | If this parameter is set to a file or directory name and the |
17345e5a JA |
2875 | <FONT SIZE=-1><B>MAILPATH</B> |
2876 | ||
2877 | </FONT> | |
2878 | variable is not set, | |
2879 | <B>bash</B> | |
2880 | ||
495aee44 CR |
2881 | informs the user of the arrival of mail in the specified file or |
2882 | Maildir-format directory. | |
17345e5a JA |
2883 | <DT><B>MAILCHECK</B> |
2884 | ||
2885 | <DD> | |
2886 | Specifies how | |
2887 | often (in seconds) | |
2888 | <B>bash</B> | |
2889 | ||
2890 | checks for mail. The default is 60 seconds. When it is time to check | |
2891 | for mail, the shell does so before displaying the primary prompt. | |
2892 | If this variable is unset, or set to a value that is not a number | |
2893 | greater than or equal to zero, the shell disables mail checking. | |
2894 | <DT><B>MAILPATH</B> | |
2895 | ||
2896 | <DD> | |
a0c0a00f | 2897 | A colon-separated list of filenames to be checked for mail. |
17345e5a | 2898 | The message to be printed when mail arrives in a particular file |
ac50fbac | 2899 | may be specified by separating the filename from the message with a `?'. |
17345e5a | 2900 | When used in the text of the message, <B>$_</B> expands to the name of |
a0c0a00f | 2901 | the current mailfile. |
17345e5a JA |
2902 | Example: |
2903 | <DL COMPACT><DT><DD> | |
2904 | <P> | |
2905 | ||
2906 | <B>MAILPATH</B>=aq/var/mail/bfox?"You have mail":~/shell-mail?"$_ has mail!"aq | |
2907 | <P> | |
2908 | ||
2909 | <B>Bash</B> | |
2910 | ||
a0c0a00f CR |
2911 | can be configured to supply |
2912 | a default value for this variable (there is no value by default), | |
2913 | but the location of the user | |
17345e5a JA |
2914 | mail files that it uses is system dependent (e.g., /var/mail/<B>$USER</B>). |
2915 | </DL> | |
2916 | ||
2917 | <DT><B>OPTERR</B> | |
2918 | ||
2919 | <DD> | |
2920 | If set to the value 1, | |
2921 | <B>bash</B> | |
2922 | ||
2923 | displays error messages generated by the | |
2924 | <B>getopts</B> | |
2925 | ||
2926 | builtin command (see | |
2927 | <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B> | |
2928 | ||
2929 | </FONT> | |
2930 | below). | |
2931 | <FONT SIZE=-1><B>OPTERR</B> | |
2932 | ||
2933 | </FONT> | |
2934 | is initialized to 1 each time the shell is invoked or a shell | |
2935 | script is executed. | |
2936 | <DT><B>PATH</B> | |
2937 | ||
2938 | <DD> | |
2939 | The search path for commands. It | |
2940 | is a colon-separated list of directories in which | |
2941 | the shell looks for commands (see | |
2942 | <FONT SIZE=-1><B>COMMAND EXECUTION</B> | |
2943 | ||
2944 | </FONT> | |
2945 | below). | |
0001803f CR |
2946 | A zero-length (null) directory name in the value of |
2947 | <FONT SIZE=-1><B>PATH</B> | |
2948 | ||
2949 | </FONT> | |
2950 | indicates the current directory. | |
17345e5a JA |
2951 | A null directory name may appear as two adjacent colons, or as an initial |
2952 | or trailing colon. | |
2953 | The default path is system-dependent, | |
2954 | and is set by the administrator who installs | |
2955 | <B>bash</B>. | |
2956 | ||
2957 | A common value is | |
a0c0a00f | 2958 | |
ac50fbac | 2959 | <TT>/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin</TT>. |
17345e5a | 2960 | |
a0c0a00f | 2961 | |
17345e5a JA |
2962 | <DT><B>POSIXLY_CORRECT</B> |
2963 | ||
2964 | <DD> | |
2965 | If this variable is in the environment when <B>bash</B> starts, the shell | |
2966 | enters <I>posix mode</I> before reading the startup files, as if the | |
2967 | <B>--posix</B> | |
2968 | ||
2969 | invocation option had been supplied. If it is set while the shell is | |
2970 | running, <B>bash</B> enables <I>posix mode</I>, as if the command | |
2971 | <TT>set -o posix</TT> | |
2972 | ||
2973 | had been executed. | |
2974 | <DT><B>PROMPT_COMMAND</B> | |
2975 | ||
2976 | <DD> | |
2977 | If set, the value is executed as a command prior to issuing each primary | |
2978 | prompt. | |
2979 | <DT><B>PROMPT_DIRTRIM</B> | |
2980 | ||
2981 | <DD> | |
2982 | If set to a number greater than zero, the value is used as the number of | |
0001803f CR |
2983 | trailing directory components to retain when expanding the <B>\w</B> and |
2984 | <B>\W</B> prompt string escapes (see | |
17345e5a JA |
2985 | <FONT SIZE=-1><B>PROMPTING</B> |
2986 | ||
2987 | </FONT> | |
2988 | below). Characters removed are replaced with an ellipsis. | |
a0c0a00f CR |
2989 | <DT><B>PS0</B> |
2990 | ||
2991 | <DD> | |
2992 | The value of this parameter is expanded (see | |
2993 | <FONT SIZE=-1><B>PROMPTING</B> | |
2994 | ||
2995 | </FONT> | |
2996 | below) and displayed by interactive shells after reading a command | |
2997 | and before the command is executed. | |
17345e5a JA |
2998 | <DT><B>PS1</B> |
2999 | ||
3000 | <DD> | |
3001 | The value of this parameter is expanded (see | |
3002 | <FONT SIZE=-1><B>PROMPTING</B> | |
3003 | ||
3004 | </FONT> | |
3005 | below) and used as the primary prompt string. The default value is | |
3006 | ``<B>\s-\v\$ </B>''. | |
3007 | <DT><B>PS2</B> | |
3008 | ||
3009 | <DD> | |
3010 | The value of this parameter is expanded as with | |
0001803f | 3011 | <FONT SIZE=-1><B>PS1</B> |
17345e5a | 3012 | |
0001803f | 3013 | </FONT> |
17345e5a JA |
3014 | and used as the secondary prompt string. The default is |
3015 | ``<B>> </B>''. | |
3016 | <DT><B>PS3</B> | |
3017 | ||
3018 | <DD> | |
3019 | The value of this parameter is used as the prompt for the | |
3020 | <B>select</B> | |
3021 | ||
3022 | command (see | |
3023 | <FONT SIZE=-1><B>SHELL GRAMMAR</B> | |
3024 | ||
3025 | </FONT> | |
3026 | above). | |
3027 | <DT><B>PS4</B> | |
3028 | ||
3029 | <DD> | |
3030 | The value of this parameter is expanded as with | |
0001803f | 3031 | <FONT SIZE=-1><B>PS1</B> |
17345e5a | 3032 | |
0001803f | 3033 | </FONT> |
17345e5a JA |
3034 | and the value is printed before each command |
3035 | <B>bash</B> | |
3036 | ||
3037 | displays during an execution trace. The first character of | |
3038 | <FONT SIZE=-1><B>PS4</B> | |
3039 | ||
3040 | </FONT> | |
3041 | is replicated multiple times, as necessary, to indicate multiple | |
3042 | levels of indirection. The default is ``<B>+ </B>''. | |
3043 | <DT><B>SHELL</B> | |
3044 | ||
3045 | <DD> | |
3046 | The full pathname to the shell is kept in this environment variable. | |
3047 | If it is not set when the shell starts, | |
3048 | <B>bash</B> | |
3049 | ||
3050 | assigns to it the full pathname of the current user's login shell. | |
3051 | <DT><B>TIMEFORMAT</B> | |
3052 | ||
3053 | <DD> | |
3054 | The value of this parameter is used as a format string specifying | |
3055 | how the timing information for pipelines prefixed with the | |
3056 | <B>time</B> | |
3057 | ||
3058 | reserved word should be displayed. | |
3059 | The <B>%</B> character introduces an escape sequence that is | |
3060 | expanded to a time value or other information. | |
3061 | The escape sequences and their meanings are as follows; the | |
3062 | braces denote optional portions. | |
3063 | <P> | |
3064 | <DL COMPACT><DT><DD> | |
3065 | ||
3066 | <DL COMPACT> | |
3067 | <DT><B>%%</B> | |
3068 | ||
3069 | <DD> | |
3070 | A literal <B>%</B>. | |
3071 | <DT><B>%[</B><I>p</I>][l]R | |
3072 | ||
3073 | <DD> | |
3074 | The elapsed time in seconds. | |
3075 | <DT><B>%[</B><I>p</I>][l]U | |
3076 | ||
3077 | <DD> | |
3078 | The number of CPU seconds spent in user mode. | |
3079 | <DT><B>%[</B><I>p</I>][l]S | |
3080 | ||
3081 | <DD> | |
3082 | The number of CPU seconds spent in system mode. | |
3083 | <DT><B>%P</B> | |
3084 | ||
3085 | <DD> | |
3086 | The CPU percentage, computed as (%U + %S) / %R. | |
3087 | ||
3088 | </DL></DL> | |
3089 | ||
3090 | <DT><DD> | |
3091 | The optional <I>p</I> is a digit specifying the <I>precision</I>, | |
3092 | the number of fractional digits after a decimal point. | |
3093 | A value of 0 causes no decimal point or fraction to be output. | |
3094 | At most three places after the decimal point may be specified; | |
3095 | values of <I>p</I> greater than 3 are changed to 3. | |
3096 | If <I>p</I> is not specified, the value 3 is used. | |
3097 | <DT><DD> | |
3098 | The optional <B>l</B> specifies a longer format, including | |
3099 | minutes, of the form <I>MM</I>m<I>SS</I>.<I>FF</I>s. | |
3100 | The value of <I>p</I> determines whether or not the fraction is | |
3101 | included. | |
3102 | <DT><DD> | |
3103 | If this variable is not set, <B>bash</B> acts as if it had the | |
ac50fbac | 3104 | value <B>$aq\nreal\t%3lR\nuser\t%3lU\nsys\t%3lSaq</B>. |
17345e5a JA |
3105 | If the value is null, no timing information is displayed. |
3106 | A trailing newline is added when the format string is displayed. | |
ac50fbac | 3107 | |
17345e5a JA |
3108 | <DT><B>TMOUT</B> |
3109 | ||
3110 | <DD> | |
0001803f CR |
3111 | If set to a value greater than zero, |
3112 | <FONT SIZE=-1><B>TMOUT</B> | |
3113 | ||
3114 | </FONT> | |
3115 | is treated as the | |
17345e5a JA |
3116 | default timeout for the <B>read</B> builtin. |
3117 | The <B>select</B> command terminates if input does not arrive | |
0001803f CR |
3118 | after |
3119 | <FONT SIZE=-1><B>TMOUT</B> | |
3120 | ||
3121 | </FONT> | |
3122 | seconds when input is coming from a terminal. | |
17345e5a | 3123 | In an interactive shell, the value is interpreted as the |
ac50fbac CR |
3124 | number of seconds to wait for a line of input after issuing the |
3125 | primary prompt. | |
17345e5a JA |
3126 | <B>Bash</B> |
3127 | ||
ac50fbac CR |
3128 | terminates after waiting for that number of seconds if a complete |
3129 | line of input does not arrive. | |
17345e5a JA |
3130 | <DT><B>TMPDIR</B> |
3131 | ||
3132 | <DD> | |
495aee44 CR |
3133 | If set, <B>bash</B> uses its value as the name of a directory in which |
3134 | <B>bash</B> creates temporary files for the shell's use. | |
17345e5a JA |
3135 | <DT><B>auto_resume</B> |
3136 | ||
3137 | <DD> | |
3138 | This variable controls how the shell interacts with the user and | |
3139 | job control. If this variable is set, single word simple | |
3140 | commands without redirections are treated as candidates for resumption | |
3141 | of an existing stopped job. There is no ambiguity allowed; if there is | |
3142 | more than one job beginning with the string typed, the job most recently | |
3143 | accessed is selected. The | |
3144 | <I>name</I> | |
3145 | ||
3146 | of a stopped job, in this context, is the command line used to | |
3147 | start it. | |
3148 | If set to the value | |
3149 | <I>exact</I>, | |
3150 | ||
3151 | the string supplied must match the name of a stopped job exactly; | |
3152 | if set to | |
3153 | <I>substring</I>, | |
3154 | ||
3155 | the string supplied needs to match a substring of the name of a | |
3156 | stopped job. The | |
3157 | <I>substring</I> | |
3158 | ||
3159 | value provides functionality analogous to the | |
3160 | <B>%?</B> | |
3161 | ||
3162 | job identifier (see | |
3163 | <FONT SIZE=-1><B>JOB CONTROL</B> | |
3164 | ||
3165 | </FONT> | |
3166 | below). If set to any other value, the supplied string must | |
3167 | be a prefix of a stopped job's name; this provides functionality | |
3168 | analogous to the <B>%</B><I>string</I> job identifier. | |
3169 | <DT><B>histchars</B> | |
3170 | ||
3171 | <DD> | |
3172 | The two or three characters which control history expansion | |
3173 | and tokenization (see | |
3174 | <FONT SIZE=-1><B>HISTORY EXPANSION</B> | |
3175 | ||
3176 | </FONT> | |
3177 | below). The first character is the <I>history expansion</I> character, | |
3178 | the character which signals the start of a history | |
3179 | expansion, normally `<B>!</B>'. | |
3180 | The second character is the <I>quick substitution</I> | |
3181 | character, which is used as shorthand for re-running the previous | |
3182 | command entered, substituting one string for another in the command. | |
3183 | The default is `<B>^</B>'. | |
3184 | The optional third character is the character | |
3185 | which indicates that the remainder of the line is a comment when found | |
3186 | as the first character of a word, normally `<B>#</B>'. The history | |
3187 | comment character causes history substitution to be skipped for the | |
3188 | remaining words on the line. It does not necessarily cause the shell | |
3189 | parser to treat the rest of the line as a comment. | |
3190 | ||
3191 | </DL> | |
3192 | <A NAME="lbAX"> </A> | |
3193 | <H4>Arrays</H4> | |
3194 | ||
3195 | <B>Bash</B> | |
3196 | ||
3197 | provides one-dimensional indexed and associative array variables. | |
3198 | Any variable may be used as an indexed array; the | |
3199 | <B>declare</B> | |
3200 | ||
3201 | builtin will explicitly declare an array. | |
3202 | There is no maximum | |
3203 | limit on the size of an array, nor any requirement that members | |
3204 | be indexed or assigned contiguously. | |
3205 | Indexed arrays are referenced using integers (including arithmetic | |
a0c0a00f | 3206 | expressions) and are zero-based; associative arrays are referenced |
17345e5a | 3207 | using arbitrary strings. |
ac50fbac | 3208 | Unless otherwise noted, indexed array indices must be non-negative integers. |
17345e5a JA |
3209 | <P> |
3210 | ||
3211 | An indexed array is created automatically if any variable is assigned to | |
3212 | using the syntax <I>name</I>[<I>subscript</I>]=<I>value</I>. The | |
3213 | <I>subscript</I> | |
3214 | ||
495aee44 | 3215 | is treated as an arithmetic expression that must evaluate to a number. |
495aee44 | 3216 | To explicitly declare an indexed array, use |
17345e5a JA |
3217 | <B>declare -a </B><I>name</I> |
3218 | ||
3219 | (see | |
3220 | <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B> | |
3221 | ||
3222 | </FONT> | |
3223 | below). | |
3224 | <B>declare -a </B><I>name</I>[<I>subscript</I>] | |
3225 | ||
3226 | is also accepted; the <I>subscript</I> is ignored. | |
3227 | <P> | |
3228 | ||
3229 | Associative arrays are created using | |
3230 | <B>declare -A </B><I>name</I>. | |
3231 | ||
3232 | <P> | |
3233 | ||
3234 | Attributes may be | |
3235 | specified for an array variable using the | |
3236 | <B>declare</B> | |
3237 | ||
3238 | and | |
3239 | <B>readonly</B> | |
3240 | ||
3241 | builtins. Each attribute applies to all members of an array. | |
3242 | <P> | |
3243 | ||
3244 | Arrays are assigned to using compound assignments of the form | |
3245 | <I>name</I>=<B>(</B>value<I>1</I> ... value<I>n</I><B>)</B>, where each | |
3246 | <I>value</I> is of the form [<I>subscript</I>]=<I>string</I>. | |
ac50fbac | 3247 | Indexed array assignments do not require anything but <I>string</I>. |
17345e5a JA |
3248 | When assigning to indexed arrays, if the optional brackets and subscript |
3249 | are supplied, that index is assigned to; | |
3250 | otherwise the index of the element assigned is the last index assigned | |
3251 | to by the statement plus one. Indexing starts at zero. | |
3252 | <P> | |
3253 | ||
3254 | When assigning to an associative array, the subscript is required. | |
3255 | <P> | |
3256 | ||
3257 | This syntax is also accepted by the | |
3258 | <B>declare</B> | |
3259 | ||
3260 | builtin. Individual array elements may be assigned to using the | |
3261 | <I>name</I>[<I>subscript</I>]=<I>value</I> syntax introduced above. | |
ac50fbac CR |
3262 | When assigning to an indexed array, if |
3263 | <I>name</I> | |
3264 | ||
3265 | is subscripted by a negative number, that number is | |
3266 | interpreted as relative to one greater than the maximum index of | |
3267 | <I>name</I>, so negative indices count back from the end of the | |
3268 | array, and an index of -1 references the last element. | |
17345e5a JA |
3269 | <P> |
3270 | ||
3271 | Any element of an array may be referenced using | |
3272 | ${<I>name</I>[<I>subscript</I>]}. The braces are required to avoid | |
3273 | conflicts with pathname expansion. If | |
3274 | <I>subscript</I> is <B>@</B> or <B>*</B>, the word expands to | |
3275 | all members of <I>name</I>. These subscripts differ only when the | |
3276 | word appears within double quotes. If the word is double-quoted, | |
3277 | ${<I>name</I>[*]} expands to a single | |
3278 | word with the value of each array member separated by the first | |
3279 | character of the | |
3280 | <FONT SIZE=-1><B>IFS</B> | |
3281 | ||
3282 | </FONT> | |
3283 | special variable, and ${<I>name</I>[@]} expands each element of | |
3284 | <I>name</I> to a separate word. When there are no array members, | |
3285 | ${<I>name</I>[@]} expands to nothing. | |
3286 | If the double-quoted expansion occurs within a word, the expansion of | |
3287 | the first parameter is joined with the beginning part of the original | |
3288 | word, and the expansion of the last parameter is joined with the last | |
3289 | part of the original word. | |
3290 | This is analogous to the expansion | |
3291 | of the special parameters <B>*</B> and <B>@</B> (see | |
3292 | <B>Special Parameters</B> | |
3293 | ||
3294 | above). ${#<I>name</I>[<I>subscript</I>]} expands to the length of | |
3295 | ${<I>name</I>[<I>subscript</I>]}. If <I>subscript</I> is <B>*</B> or | |
3296 | <B>@</B>, the expansion is the number of elements in the array. | |
ac50fbac CR |
3297 | If the |
3298 | <I>subscript</I> | |
3299 | ||
3300 | used to reference an element of an indexed array | |
a0c0a00f | 3301 | evaluates to a number less than zero, it is |
ac50fbac CR |
3302 | interpreted as relative to one greater than the maximum index of the array, |
3303 | so negative indices count back from the end of the | |
3304 | array, and an index of -1 references the last element. | |
17345e5a JA |
3305 | <P> |
3306 | ||
a0c0a00f CR |
3307 | Referencing an array variable without a subscript is equivalent to |
3308 | referencing the array with a subscript of 0. | |
3309 | Any reference to a variable using a valid subscript is legal, and | |
3310 | <B>bash</B> | |
3311 | ||
3312 | will create an array if necessary. | |
3313 | <P> | |
3314 | ||
0001803f CR |
3315 | An array variable is considered set if a subscript has been assigned a |
3316 | value. The null string is a valid value. | |
3317 | <P> | |
3318 | ||
ac50fbac CR |
3319 | It is possible to obtain the keys (indices) of an array as well as the values. |
3320 | ${<B>!</B><I>name</I>[<I>@</I>]} and ${<B>!</B><I>name</I>[<I>*</I>]} | |
3321 | expand to the indices assigned in array variable <I>name</I>. | |
3322 | The treatment when in double quotes is similar to the expansion of the | |
3323 | special parameters <I>@</I> and <I>*</I> within double quotes. | |
3324 | <P> | |
3325 | ||
17345e5a JA |
3326 | The |
3327 | <B>unset</B> | |
3328 | ||
3329 | builtin is used to destroy arrays. <B>unset</B> <I>name</I>[<I>subscript</I>] | |
3330 | destroys the array element at index <I>subscript</I>. | |
ac50fbac | 3331 | Negative subscripts to indexed arrays are interpreted as described above. |
0001803f CR |
3332 | Care must be taken to avoid unwanted side effects caused by pathname |
3333 | expansion. | |
17345e5a JA |
3334 | <B>unset</B> <I>name</I>, where <I>name</I> is an array, or |
3335 | <B>unset</B> <I>name</I>[<I>subscript</I>], where | |
3336 | <I>subscript</I> is <B>*</B> or <B>@</B>, removes the entire array. | |
3337 | <P> | |
3338 | ||
3339 | The | |
3340 | <B>declare</B>, | |
3341 | ||
3342 | <B>local</B>, | |
3343 | ||
3344 | and | |
3345 | <B>readonly</B> | |
3346 | ||
3347 | builtins each accept a | |
3348 | <B>-a</B> | |
3349 | ||
3350 | option to specify an indexed array and a | |
3351 | <B>-A</B> | |
3352 | ||
3353 | option to specify an associative array. | |
a0c0a00f | 3354 | If both options are supplied, |
ac50fbac CR |
3355 | <B>-A</B> |
3356 | ||
3357 | takes precedence. | |
17345e5a JA |
3358 | The |
3359 | <B>read</B> | |
3360 | ||
3361 | builtin accepts a | |
3362 | <B>-a</B> | |
3363 | ||
3364 | option to assign a list of words read from the standard input | |
3365 | to an array. The | |
3366 | <B>set</B> | |
3367 | ||
3368 | and | |
3369 | <B>declare</B> | |
3370 | ||
3371 | builtins display array values in a way that allows them to be | |
3372 | reused as assignments. | |
3373 | <A NAME="lbAY"> </A> | |
3374 | <H3>EXPANSION</H3> | |
3375 | ||
3376 | Expansion is performed on the command line after it has been split into | |
3377 | words. There are seven kinds of expansion performed: | |
3378 | <I>brace expansion</I>, | |
3379 | ||
3380 | <I>tilde expansion</I>, | |
3381 | ||
3382 | <I>parameter and variable expansion</I>, | |
3383 | ||
3384 | <I>command substitution</I>, | |
3385 | ||
3386 | <I>arithmetic expansion</I>, | |
3387 | ||
3388 | <I>word splitting</I>, | |
3389 | ||
3390 | and | |
3391 | <I>pathname expansion</I>. | |
3392 | ||
3393 | <P> | |
3394 | ||
ac50fbac CR |
3395 | The order of expansions is: |
3396 | brace expansion; | |
3397 | tilde expansion, parameter and variable expansion, arithmetic expansion, | |
3398 | and command substitution (done in a left-to-right fashion); | |
3399 | word splitting; | |
3400 | and pathname expansion. | |
17345e5a JA |
3401 | <P> |
3402 | ||
3403 | On systems that can support it, there is an additional expansion | |
3404 | available: <I>process substitution</I>. | |
ac50fbac CR |
3405 | This is performed at the |
3406 | same time as tilde, parameter, variable, and arithmetic expansion and | |
3407 | command substitution. | |
17345e5a JA |
3408 | <P> |
3409 | ||
a0c0a00f CR |
3410 | After these expansions are performed, quote characters present in the |
3411 | original word are removed unless they have been quoted themselves | |
3412 | (<I>quote removal</I>). | |
3413 | <P> | |
3414 | ||
17345e5a JA |
3415 | Only brace expansion, word splitting, and pathname expansion |
3416 | can change the number of words of the expansion; other expansions | |
3417 | expand a single word to a single word. | |
3418 | The only exceptions to this are the expansions of | |
3419 | "<B>$@</B>" and "<B>${</B><I>name</I><B>[@]}</B>" | |
3420 | as explained above (see | |
3421 | <FONT SIZE=-1><B>PARAMETERS</B>). | |
3422 | ||
3423 | </FONT> | |
3424 | <A NAME="lbAZ"> </A> | |
3425 | <H4>Brace Expansion</H4> | |
3426 | ||
3427 | <P> | |
3428 | ||
3429 | <I>Brace expansion</I> | |
3430 | ||
3431 | is a mechanism by which arbitrary strings | |
3432 | may be generated. This mechanism is similar to | |
3433 | <I>pathname expansion</I>, but the filenames generated | |
3434 | need not exist. Patterns to be brace expanded take | |
3435 | the form of an optional | |
3436 | <I>preamble</I>, | |
3437 | ||
3438 | followed by either a series of comma-separated strings or | |
3439 | a sequence expression between a pair of braces, followed by | |
3440 | an optional | |
3441 | <I>postscript</I>. | |
3442 | ||
3443 | The preamble is prefixed to each string contained | |
3444 | within the braces, and the postscript is then appended | |
3445 | to each resulting string, expanding left to right. | |
3446 | <P> | |
3447 | ||
3448 | Brace expansions may be nested. The results of each expanded | |
3449 | string are not sorted; left to right order is preserved. | |
3450 | For example, a<B>{</B>d,c,b<B>}</B>e expands into `ade ace abe'. | |
3451 | <P> | |
3452 | ||
3453 | A sequence expression takes the form | |
3454 | <B>{</B><I>x</I><B>..</B><I>y</I><B>[..</B><I>incr</I><B>]}</B>, | |
3455 | where <I>x</I> and <I>y</I> are either integers or single characters, | |
3456 | and <I>incr</I>, an optional increment, is an integer. | |
3457 | When integers are supplied, the expression expands to each number between | |
3458 | <I>x</I> and <I>y</I>, inclusive. | |
3459 | Supplied integers may be prefixed with <I>0</I> to force each term to have the | |
ac50fbac CR |
3460 | same width. |
3461 | When either <I>x</I> or y begins with a zero, the shell | |
17345e5a JA |
3462 | attempts to force all generated terms to contain the same number of digits, |
3463 | zero-padding where necessary. | |
3464 | When characters are supplied, the expression expands to each character | |
ac50fbac CR |
3465 | lexicographically between <I>x</I> and <I>y</I>, inclusive, |
3466 | using the default C locale. | |
3467 | Note that both <I>x</I> and <I>y</I> must be of the same type. | |
17345e5a JA |
3468 | When the increment is supplied, it is used as the difference between |
3469 | each term. The default increment is 1 or -1 as appropriate. | |
3470 | <P> | |
3471 | ||
3472 | Brace expansion is performed before any other expansions, | |
3473 | and any characters special to other expansions are preserved | |
3474 | in the result. It is strictly textual. | |
3475 | <B>Bash</B> | |
3476 | ||
3477 | does not apply any syntactic interpretation to the context of the | |
3478 | expansion or the text between the braces. | |
3479 | <P> | |
3480 | ||
3481 | A correctly-formed brace expansion must contain unquoted opening | |
3482 | and closing braces, and at least one unquoted comma or a valid | |
3483 | sequence expression. | |
3484 | Any incorrectly formed brace expansion is left unchanged. | |
3485 | A <B>{</B> or <B>,</B> may be quoted with a backslash to prevent its | |
3486 | being considered part of a brace expression. | |
3487 | To avoid conflicts with parameter expansion, the string <B>${</B> | |
3488 | is not considered eligible for brace expansion. | |
3489 | <P> | |
3490 | ||
3491 | This construct is typically used as shorthand when the common | |
3492 | prefix of the strings to be generated is longer than in the | |
3493 | above example: | |
3494 | <DL COMPACT><DT><DD> | |
3495 | <P> | |
3496 | ||
3497 | mkdir /usr/local/src/bash/{old,new,dist,bugs} | |
3498 | </DL> | |
3499 | ||
3500 | or | |
3501 | <DL COMPACT><DT><DD> | |
3502 | chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}} | |
3503 | </DL> | |
3504 | ||
3505 | <P> | |
3506 | ||
3507 | Brace expansion introduces a slight incompatibility with | |
3508 | historical versions of | |
3509 | <B>sh</B>. | |
3510 | ||
3511 | <B>sh</B> | |
3512 | ||
3513 | does not treat opening or closing braces specially when they | |
3514 | appear as part of a word, and preserves them in the output. | |
3515 | <B>Bash</B> | |
3516 | ||
3517 | removes braces from words as a consequence of brace | |
3518 | expansion. For example, a word entered to | |
3519 | <B>sh</B> | |
3520 | ||
3521 | as <I>file{1,2}</I> | |
3522 | appears identically in the output. The same word is | |
3523 | output as | |
3524 | <I>file1 file2</I> | |
3525 | ||
3526 | after expansion by | |
3527 | <B>bash</B>. | |
3528 | ||
3529 | If strict compatibility with | |
3530 | <B>sh</B> | |
3531 | ||
3532 | is desired, start | |
3533 | <B>bash</B> | |
3534 | ||
3535 | with the | |
a0c0a00f | 3536 | <B>+B</B> |
17345e5a JA |
3537 | |
3538 | option or disable brace expansion with the | |
3539 | <B>+B</B> | |
3540 | ||
3541 | option to the | |
3542 | <B>set</B> | |
3543 | ||
3544 | command (see | |
3545 | <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B> | |
3546 | ||
3547 | </FONT> | |
3548 | below). | |
3549 | <A NAME="lbBA"> </A> | |
3550 | <H4>Tilde Expansion</H4> | |
3551 | ||
3552 | <P> | |
3553 | ||
3554 | If a word begins with an unquoted tilde character (`<B>~</B>'), all of | |
3555 | the characters preceding the first unquoted slash (or all characters, | |
3556 | if there is no unquoted slash) are considered a <I>tilde-prefix</I>. | |
3557 | If none of the characters in the tilde-prefix are quoted, the | |
3558 | characters in the tilde-prefix following the tilde are treated as a | |
3559 | possible <I>login name</I>. | |
3560 | If this login name is the null string, the tilde is replaced with the | |
3561 | value of the shell parameter | |
3562 | <FONT SIZE=-1><B>HOME</B>. | |
3563 | ||
3564 | </FONT> | |
3565 | If | |
3566 | <FONT SIZE=-1><B>HOME</B> | |
3567 | ||
3568 | </FONT> | |
3569 | is unset, the home directory of the user executing the shell is | |
3570 | substituted instead. | |
3571 | Otherwise, the tilde-prefix is replaced with the home directory | |
3572 | associated with the specified login name. | |
3573 | <P> | |
3574 | ||
3575 | If the tilde-prefix is a `~+', the value of the shell variable | |
3576 | <FONT SIZE=-1><B>PWD</B> | |
3577 | ||
3578 | </FONT> | |
3579 | replaces the tilde-prefix. | |
3580 | If the tilde-prefix is a `~-', the value of the shell variable | |
3581 | <FONT SIZE=-1><B>OLDPWD</B>, | |
3582 | ||
3583 | </FONT> | |
3584 | if it is set, is substituted. | |
3585 | If the characters following the tilde in the tilde-prefix consist | |
3586 | of a number <I>N</I>, optionally prefixed | |
3587 | by a `+' or a `-', the tilde-prefix is replaced with the corresponding | |
3588 | element from the directory stack, as it would be displayed by the | |
3589 | <B>dirs</B> | |
3590 | ||
3591 | builtin invoked with the tilde-prefix as an argument. | |
3592 | If the characters following the tilde in the tilde-prefix consist of a | |
3593 | number without a leading `+' or `-', `+' is assumed. | |
3594 | <P> | |
3595 | ||
3596 | If the login name is invalid, or the tilde expansion fails, the word | |
3597 | is unchanged. | |
3598 | <P> | |
3599 | ||
3600 | Each variable assignment is checked for unquoted tilde-prefixes immediately | |
3601 | following a | |
3602 | <B>:</B> | |
3603 | ||
3604 | or the first | |
3605 | <B>=</B>. | |
3606 | ||
3607 | In these cases, tilde expansion is also performed. | |
ac50fbac | 3608 | Consequently, one may use filenames with tildes in assignments to |
17345e5a JA |
3609 | <FONT SIZE=-1><B>PATH</B>, |
3610 | ||
3611 | </FONT> | |
3612 | <FONT SIZE=-1><B>MAILPATH</B>, | |
3613 | ||
3614 | </FONT> | |
3615 | and | |
3616 | <FONT SIZE=-1><B>CDPATH</B>, | |
3617 | ||
3618 | </FONT> | |
3619 | and the shell assigns the expanded value. | |
3620 | <A NAME="lbBB"> </A> | |
3621 | <H4>Parameter Expansion</H4> | |
3622 | ||
3623 | <P> | |
3624 | ||
3625 | The `<B>$</B>' character introduces parameter expansion, | |
3626 | command substitution, or arithmetic expansion. The parameter name | |
3627 | or symbol to be expanded may be enclosed in braces, which | |
3628 | are optional but serve to protect the variable to be expanded from | |
3629 | characters immediately following it which could be | |
3630 | interpreted as part of the name. | |
3631 | <P> | |
3632 | ||
3633 | When braces are used, the matching ending brace is the first `<B>}</B>' | |
3634 | not escaped by a backslash or within a quoted string, and not within an | |
3635 | embedded arithmetic expansion, command substitution, or parameter | |
3636 | expansion. | |
3637 | <P> | |
3638 | ||
3639 | ||
3640 | <DL COMPACT> | |
3641 | <DT>${<I>parameter</I>}<DD> | |
3642 | The value of <I>parameter</I> is substituted. The braces are required | |
3643 | when | |
3644 | <I>parameter</I> | |
3645 | ||
3646 | is a positional parameter with more than one digit, | |
3647 | or when | |
3648 | <I>parameter</I> | |
3649 | ||
3650 | is followed by a character which is not to be | |
3651 | interpreted as part of its name. | |
ac50fbac CR |
3652 | The <I>parameter</I> is a shell parameter as described above |
3653 | <B>PARAMETERS</B>) or an array reference (<B>Arrays</B>). | |
17345e5a JA |
3654 | |
3655 | </DL> | |
3656 | <P> | |
3657 | ||
0001803f | 3658 | If the first character of <I>parameter</I> is an exclamation point (<B>!</B>), |
a0c0a00f | 3659 | and <I>parameter</I> is not a <I>nameref</I>, |
ac50fbac | 3660 | it introduces a level of variable indirection. |
17345e5a JA |
3661 | <B>Bash</B> uses the value of the variable formed from the rest of |
3662 | <I>parameter</I> as the name of the variable; this variable is then | |
3663 | expanded and that value is used in the rest of the substitution, rather | |
3664 | than the value of <I>parameter</I> itself. | |
3665 | This is known as <I>indirect expansion</I>. | |
a0c0a00f CR |
3666 | If <I>parameter</I> is a nameref, this expands to the name of the |
3667 | variable referenced by <I>parameter</I> instead of performing the | |
3668 | complete indirect expansion. | |
ac50fbac | 3669 | The exceptions to this are the expansions of ${<B>!</B><I>prefix</I><B>*</B>} and |
17345e5a JA |
3670 | ${<B>!</B><I>name</I>[<I>@</I>]} described below. |
3671 | The exclamation point must immediately follow the left brace in order to | |
3672 | introduce indirection. | |
3673 | <P> | |
3674 | ||
3675 | In each of the cases below, <I>word</I> is subject to tilde expansion, | |
3676 | parameter expansion, command substitution, and arithmetic expansion. | |
3677 | <P> | |
3678 | ||
ac50fbac CR |
3679 | When not performing substring expansion, using the forms documented below |
3680 | (e.g., <B>:-</B>), | |
17345e5a JA |
3681 | <B>bash</B> tests for a parameter that is unset or null. Omitting the colon |
3682 | results in a test only for a parameter that is unset. | |
3683 | <P> | |
3684 | ||
3685 | ||
3686 | <DL COMPACT> | |
3687 | <DT>${<I>parameter</I><B>:-</B><I>word</I>}<DD> | |
3688 | <B>Use Default Values</B>. If | |
3689 | <I>parameter</I> | |
3690 | ||
3691 | is unset or null, the expansion of | |
3692 | <I>word</I> | |
3693 | ||
3694 | is substituted. Otherwise, the value of | |
3695 | <I>parameter</I> | |
3696 | ||
3697 | is substituted. | |
3698 | <DT>${<I>parameter</I><B>:=</B><I>word</I>}<DD> | |
3699 | <B>Assign Default Values</B>. | |
3700 | If | |
3701 | <I>parameter</I> | |
3702 | ||
3703 | is unset or null, the expansion of | |
3704 | <I>word</I> | |
3705 | ||
3706 | is assigned to | |
3707 | <I>parameter</I>. | |
3708 | ||
3709 | The value of | |
3710 | <I>parameter</I> | |
3711 | ||
3712 | is then substituted. Positional parameters and special parameters may | |
3713 | not be assigned to in this way. | |
3714 | <DT>${<I>parameter</I><B>:?</B><I>word</I>}<DD> | |
3715 | <B>Display Error if Null or Unset</B>. | |
3716 | If | |
3717 | <I>parameter</I> | |
3718 | ||
3719 | is null or unset, the expansion of <I>word</I> (or a message to that effect | |
3720 | if | |
3721 | <I>word</I> | |
3722 | ||
3723 | is not present) is written to the standard error and the shell, if it | |
3724 | is not interactive, exits. Otherwise, the value of <I>parameter</I> is | |
3725 | substituted. | |
3726 | <DT>${<I>parameter</I><B>:+</B><I>word</I>}<DD> | |
3727 | <B>Use Alternate Value</B>. | |
3728 | If | |
3729 | <I>parameter</I> | |
3730 | ||
3731 | is null or unset, nothing is substituted, otherwise the expansion of | |
3732 | <I>word</I> | |
3733 | ||
3734 | is substituted. | |
3735 | <DT>${<I>parameter</I><B>:</B><I>offset</I>}<DD> | |
3736 | ||
3737 | <DT>${<I>parameter</I><B>:</B><I>offset</I><B>:</B><I>length</I>}<DD> | |
3738 | ||
495aee44 | 3739 | <B>Substring Expansion</B>. |
ac50fbac | 3740 | Expands to up to <I>length</I> characters of the value of <I>parameter</I> |
17345e5a | 3741 | starting at the character specified by <I>offset</I>. |
ac50fbac CR |
3742 | If <I>parameter</I> is <B>@</B>, an indexed array subscripted by |
3743 | <B>@</B> or <B>*</B>, or an associative array name, the results differ as | |
3744 | described below. | |
3745 | If <I>length</I> is omitted, expands to the substring of the value of | |
3746 | <I>parameter</I> starting at the character specified by <I>offset</I> | |
3747 | and extending to the end of the value. | |
17345e5a JA |
3748 | <I>length</I> and <I>offset</I> are arithmetic expressions (see |
3749 | <FONT SIZE=-1><B>ARITHMETIC EVALUATION</B> | |
3750 | ||
3751 | </FONT> | |
3752 | below). | |
ac50fbac | 3753 | <P> |
17345e5a | 3754 | If <I>offset</I> evaluates to a number less than zero, the value |
ac50fbac CR |
3755 | is used as an offset in characters |
3756 | from the end of the value of <I>parameter</I>. | |
3757 | If <I>length</I> evaluates to a number less than zero, | |
3758 | it is interpreted as an offset in characters | |
3759 | from the end of the value of <I>parameter</I> rather than | |
3760 | a number of characters, and the expansion is the characters between | |
3761 | <I>offset</I> and that result. | |
3762 | Note that a negative offset must be separated from the colon by at least | |
3763 | one space to avoid being confused with the <B>:-</B> expansion. | |
3764 | <P> | |
17345e5a JA |
3765 | If <I>parameter</I> is <B>@</B>, the result is <I>length</I> positional |
3766 | parameters beginning at <I>offset</I>. | |
ac50fbac CR |
3767 | A negative <I>offset</I> is taken relative to one greater than the greatest |
3768 | positional parameter, so an offset of -1 evaluates to the last positional | |
3769 | parameter. | |
3770 | It is an expansion error if <I>length</I> evaluates to a number less than | |
3771 | zero. | |
3772 | <P> | |
17345e5a JA |
3773 | If <I>parameter</I> is an indexed array name subscripted by @ or *, |
3774 | the result is the <I>length</I> | |
3775 | members of the array beginning with ${<I>parameter</I>[<I>offset</I>]}. | |
3776 | A negative <I>offset</I> is taken relative to one greater than the maximum | |
3777 | index of the specified array. | |
ac50fbac CR |
3778 | It is an expansion error if <I>length</I> evaluates to a number less than |
3779 | zero. | |
3780 | <P> | |
17345e5a JA |
3781 | Substring expansion applied to an associative array produces undefined |
3782 | results. | |
ac50fbac | 3783 | <P> |
a0c0a00f | 3784 | Substring indexing is zero-based unless the positional parameters |
17345e5a JA |
3785 | are used, in which case the indexing starts at 1 by default. |
3786 | If <I>offset</I> is 0, and the positional parameters are used, <B>$0</B> is | |
3787 | prefixed to the list. | |
3788 | <DT>${<B>!</B><I>prefix</I><B>*</B>}<DD> | |
3789 | ||
3790 | <DT>${<B>!</B><I>prefix</I><B>@</B>}<DD> | |
3791 | ||
495aee44 | 3792 | <B>Names matching prefix</B>. |
17345e5a JA |
3793 | Expands to the names of variables whose names begin with <I>prefix</I>, |
3794 | separated by the first character of the | |
3795 | <FONT SIZE=-1><B>IFS</B> | |
3796 | ||
3797 | </FONT> | |
3798 | special variable. | |
3799 | When <I>@</I> is used and the expansion appears within double quotes, each | |
3800 | variable name expands to a separate word. | |
3801 | <DT>${<B>!</B><I>name</I>[<I>@</I>]}<DD> | |
3802 | ||
3803 | <DT>${<B>!</B><I>name</I>[<I>*</I>]}<DD> | |
3804 | ||
495aee44 | 3805 | <B>List of array keys</B>. |
17345e5a JA |
3806 | If <I>name</I> is an array variable, expands to the list of array indices |
3807 | (keys) assigned in <I>name</I>. | |
3808 | If <I>name</I> is not an array, expands to 0 if <I>name</I> is set and null | |
3809 | otherwise. | |
3810 | When <I>@</I> is used and the expansion appears within double quotes, each | |
3811 | key expands to a separate word. | |
3812 | <DT>${<B>#</B><I>parameter</I>}<DD> | |
495aee44 | 3813 | <B>Parameter length</B>. |
17345e5a JA |
3814 | The length in characters of the value of <I>parameter</I> is substituted. |
3815 | If | |
3816 | <I>parameter</I> | |
3817 | ||
3818 | is | |
3819 | <B>*</B> | |
3820 | ||
a0c0a00f | 3821 | or |
17345e5a JA |
3822 | <B>@</B>, |
3823 | ||
3824 | the value substituted is the number of positional parameters. | |
3825 | If | |
3826 | <I>parameter</I> | |
3827 | ||
3828 | is an array name subscripted by | |
3829 | <B>*</B> | |
3830 | ||
3831 | or | |
3832 | <B>@</B>, | |
3833 | ||
3834 | the value substituted is the number of elements in the array. | |
ac50fbac CR |
3835 | If |
3836 | <I>parameter</I> | |
3837 | ||
3838 | is an indexed array name subscripted by a negative number, that number is | |
3839 | interpreted as relative to one greater than the maximum index of | |
3840 | <I>parameter</I>, so negative indices count back from the end of the | |
3841 | array, and an index of -1 references the last element. | |
17345e5a JA |
3842 | <DT>${<I>parameter</I><B>#</B><I>word</I>}<DD> |
3843 | ||
3844 | <DT>${<I>parameter</I><B>##</B><I>word</I>}<DD> | |
3845 | ||
495aee44 | 3846 | <B>Remove matching prefix pattern</B>. |
a0c0a00f | 3847 | The |
17345e5a JA |
3848 | <I>word</I> |
3849 | ||
3850 | is expanded to produce a pattern just as in pathname | |
3851 | expansion. If the pattern matches the beginning of | |
3852 | the value of | |
3853 | <I>parameter</I>, | |
3854 | ||
3855 | then the result of the expansion is the expanded value of | |
3856 | <I>parameter</I> | |
3857 | ||
3858 | with the shortest matching pattern (the ``<B>#</B>'' case) or the | |
3859 | longest matching pattern (the ``<B>##</B>'' case) deleted. | |
3860 | If | |
3861 | <I>parameter</I> | |
3862 | ||
3863 | is | |
3864 | <B>@</B> | |
3865 | ||
3866 | or | |
3867 | <B>*</B>, | |
3868 | ||
3869 | the pattern removal operation is applied to each positional | |
3870 | parameter in turn, and the expansion is the resultant list. | |
3871 | If | |
3872 | <I>parameter</I> | |
3873 | ||
3874 | is an array variable subscripted with | |
3875 | <B>@</B> | |
3876 | ||
3877 | or | |
3878 | <B>*</B>, | |
3879 | ||
3880 | the pattern removal operation is applied to each member of the | |
3881 | array in turn, and the expansion is the resultant list. | |
3882 | <DT>${<I>parameter</I><B>%</B><I>word</I>}<DD> | |
3883 | ||
3884 | <DT>${<I>parameter</I><B>%%</B><I>word</I>}<DD> | |
3885 | ||
495aee44 | 3886 | <B>Remove matching suffix pattern</B>. |
17345e5a JA |
3887 | The <I>word</I> is expanded to produce a pattern just as in |
3888 | pathname expansion. | |
3889 | If the pattern matches a trailing portion of the expanded value of | |
3890 | <I>parameter</I>, | |
3891 | ||
3892 | then the result of the expansion is the expanded value of | |
3893 | <I>parameter</I> | |
3894 | ||
3895 | with the shortest matching pattern (the ``<B>%</B>'' case) or the | |
3896 | longest matching pattern (the ``<B>%%</B>'' case) deleted. | |
3897 | If | |
3898 | <I>parameter</I> | |
3899 | ||
3900 | is | |
3901 | <B>@</B> | |
3902 | ||
3903 | or | |
3904 | <B>*</B>, | |
3905 | ||
3906 | the pattern removal operation is applied to each positional | |
3907 | parameter in turn, and the expansion is the resultant list. | |
3908 | If | |
3909 | <I>parameter</I> | |
3910 | ||
3911 | is an array variable subscripted with | |
3912 | <B>@</B> | |
3913 | ||
3914 | or | |
3915 | <B>*</B>, | |
3916 | ||
3917 | the pattern removal operation is applied to each member of the | |
3918 | array in turn, and the expansion is the resultant list. | |
3919 | <DT>${<I>parameter</I><B>/</B><I>pattern</I><B>/</B><I>string</I>}<DD> | |
495aee44 | 3920 | <B>Pattern substitution</B>. |
17345e5a JA |
3921 | The <I>pattern</I> is expanded to produce a pattern just as in |
3922 | pathname expansion. | |
3923 | <I>Parameter</I> is expanded and the longest match of <I>pattern</I> | |
3924 | against its value is replaced with <I>string</I>. | |
3925 | If <I>pattern</I> begins with <B>/</B>, all matches of <I>pattern</I> are | |
3926 | replaced with <I>string</I>. Normally only the first match is replaced. | |
3927 | If <I>pattern</I> begins with <B>#</B>, it must match at the beginning | |
3928 | of the expanded value of <I>parameter</I>. | |
3929 | If <I>pattern</I> begins with <B>%</B>, it must match at the end | |
3930 | of the expanded value of <I>parameter</I>. | |
3931 | If <I>string</I> is null, matches of <I>pattern</I> are deleted | |
3932 | and the <B>/</B> following <I>pattern</I> may be omitted. | |
a0c0a00f CR |
3933 | If the |
3934 | <B>nocasematch</B> | |
3935 | ||
3936 | shell option is enabled, the match is performed without regard to the case | |
3937 | of alphabetic characters. | |
17345e5a JA |
3938 | If |
3939 | <I>parameter</I> | |
3940 | ||
3941 | is | |
3942 | <B>@</B> | |
3943 | ||
3944 | or | |
3945 | <B>*</B>, | |
3946 | ||
3947 | the substitution operation is applied to each positional | |
3948 | parameter in turn, and the expansion is the resultant list. | |
3949 | If | |
3950 | <I>parameter</I> | |
3951 | ||
3952 | is an array variable subscripted with | |
3953 | <B>@</B> | |
3954 | ||
3955 | or | |
3956 | <B>*</B>, | |
3957 | ||
3958 | the substitution operation is applied to each member of the | |
3959 | array in turn, and the expansion is the resultant list. | |
3960 | <DT>${<I>parameter</I><B>^</B><I>pattern</I>}<DD> | |
3961 | ||
3962 | <DT>${<I>parameter</I><B>^^</B><I>pattern</I>}<DD> | |
3963 | <DT>${<I>parameter</I><B>,</B><I>pattern</I>}<DD> | |
3964 | <DT>${<I>parameter</I><B>,,</B><I>pattern</I>}<DD> | |
3965 | ||
495aee44 | 3966 | <B>Case modification</B>. |
17345e5a JA |
3967 | This expansion modifies the case of alphabetic characters in <I>parameter</I>. |
3968 | The <I>pattern</I> is expanded to produce a pattern just as in | |
3969 | pathname expansion. | |
ac50fbac CR |
3970 | Each character in the expanded value of <I>parameter</I> is tested against |
3971 | <I>pattern</I>, and, if it matches the pattern, its case is converted. | |
3972 | The pattern should not attempt to match more than one character. | |
17345e5a JA |
3973 | The <B>^</B> operator converts lowercase letters matching <I>pattern</I> |
3974 | to uppercase; the <B>,</B> operator converts matching uppercase letters | |
3975 | to lowercase. | |
3976 | The <B>^^</B> and <B>,,</B> expansions convert each matched character in the | |
3977 | expanded value; the <B>^</B> and <B>,</B> expansions match and convert only | |
495aee44 | 3978 | the first character in the expanded value. |
17345e5a JA |
3979 | If <I>pattern</I> is omitted, it is treated like a <B>?</B>, which matches |
3980 | every character. | |
3981 | If | |
3982 | <I>parameter</I> | |
3983 | ||
3984 | is | |
3985 | <B>@</B> | |
3986 | ||
3987 | or | |
3988 | <B>*</B>, | |
3989 | ||
3990 | the case modification operation is applied to each positional | |
3991 | parameter in turn, and the expansion is the resultant list. | |
3992 | If | |
3993 | <I>parameter</I> | |
3994 | ||
3995 | is an array variable subscripted with | |
3996 | <B>@</B> | |
3997 | ||
3998 | or | |
3999 | <B>*</B>, | |
4000 | ||
4001 | the case modification operation is applied to each member of the | |
4002 | array in turn, and the expansion is the resultant list. | |
a0c0a00f CR |
4003 | <DT>${<I>parameter</I><B>@</B><I>operator</I>}<DD> |
4004 | <B>Parameter transformation</B>. | |
4005 | The expansion is either a transformation of the value of <I>parameter</I> | |
4006 | or information about <I>parameter</I> itself, depending on the value of | |
4007 | <I>operator</I>. Each <I>operator</I> is a single letter: | |
4008 | <P> | |
4009 | <DL COMPACT><DT><DD> | |
4010 | ||
4011 | <DL COMPACT> | |
4012 | <DT><B>Q</B> | |
4013 | ||
4014 | <DD> | |
4015 | The expansion is a string that is the value of <I>parameter</I> quoted in a | |
4016 | format that can be reused as input. | |
4017 | <DT><B>E</B> | |
4018 | ||
4019 | <DD> | |
4020 | The expansion is a string that is the value of <I>parameter</I> with backslash | |
4021 | escape sequences expanded as with the <B>$'...'</B> quoting mechansim. | |
4022 | <DT><B>P</B> | |
4023 | ||
4024 | <DD> | |
4025 | The expansion is a string that is the result of expanding the value of | |
4026 | <I>parameter</I> as if it were a prompt string (see <B>PROMPTING</B> below). | |
4027 | <DT><B>A</B> | |
4028 | ||
4029 | <DD> | |
4030 | The expansion is a string in the form of | |
4031 | an assignment statement or <B>declare</B> command that, if | |
4032 | evaluated, will recreate <I>parameter</I> with its attributes and value. | |
4033 | <DT><B>a</B> | |
4034 | ||
4035 | <DD> | |
4036 | The expansion is a string consisting of flag values representing | |
4037 | <I>parameter</I>'s attributes. | |
4038 | ||
4039 | </DL> | |
4040 | <P> | |
4041 | ||
4042 | If | |
4043 | <I>parameter</I> | |
4044 | ||
4045 | is | |
4046 | <B>@</B> | |
4047 | ||
4048 | or | |
4049 | <B>*</B>, | |
4050 | ||
4051 | the operation is applied to each positional | |
4052 | parameter in turn, and the expansion is the resultant list. | |
4053 | If | |
4054 | <I>parameter</I> | |
4055 | ||
4056 | is an array variable subscripted with | |
4057 | <B>@</B> | |
4058 | ||
4059 | or | |
4060 | <B>*</B>, | |
4061 | ||
4062 | the case modification operation is applied to each member of the | |
4063 | array in turn, and the expansion is the resultant list. | |
4064 | <P> | |
4065 | The result of the expansion is subject to word splitting and pathname | |
4066 | expansion as described below. | |
4067 | </DL> | |
4068 | ||
17345e5a JA |
4069 | </DL> |
4070 | <A NAME="lbBC"> </A> | |
4071 | <H4>Command Substitution</H4> | |
4072 | ||
4073 | <P> | |
4074 | ||
4075 | <I>Command substitution</I> allows the output of a command to replace | |
4076 | the command name. There are two forms: | |
17345e5a JA |
4077 | <DL COMPACT><DT><DD> |
4078 | <P> | |
4079 | ||
4080 | <B>$(</B><I>command</I><B>)</B> | |
4081 | </DL> | |
4082 | ||
4083 | or | |
4084 | <DL COMPACT><DT><DD> | |
4085 | <B>`</B><I>command</I><B>`</B> | |
4086 | </DL> | |
4087 | ||
4088 | <P> | |
4089 | ||
4090 | <B>Bash</B> | |
4091 | ||
a0c0a00f CR |
4092 | performs the expansion by executing <I>command</I> in a subshell environment |
4093 | and replacing the command substitution with the standard output of the | |
17345e5a JA |
4094 | command, with any trailing newlines deleted. |
4095 | Embedded newlines are not deleted, but they may be removed during | |
4096 | word splitting. | |
4097 | The command substitution <B>$(cat </B><I>file</I>) can be replaced by | |
4098 | the equivalent but faster <B>$(< </B><I>file</I>). | |
4099 | <P> | |
4100 | ||
4101 | When the old-style backquote form of substitution is used, | |
4102 | backslash retains its literal meaning except when followed by | |
4103 | <B>$</B>, | |
4104 | ||
4105 | <B>`</B>, | |
4106 | ||
4107 | or | |
4108 | <B>\</B>. | |
4109 | ||
4110 | The first backquote not preceded by a backslash terminates the | |
4111 | command substitution. | |
4112 | When using the $(<I>command</I>) form, all characters between the | |
4113 | parentheses make up the command; none are treated specially. | |
4114 | <P> | |
4115 | ||
4116 | Command substitutions may be nested. To nest when using the backquoted form, | |
4117 | escape the inner backquotes with backslashes. | |
4118 | <P> | |
4119 | ||
4120 | If the substitution appears within double quotes, word splitting and | |
4121 | pathname expansion are not performed on the results. | |
4122 | <A NAME="lbBD"> </A> | |
4123 | <H4>Arithmetic Expansion</H4> | |
4124 | ||
4125 | <P> | |
4126 | ||
4127 | Arithmetic expansion allows the evaluation of an arithmetic expression | |
4128 | and the substitution of the result. The format for arithmetic expansion is: | |
4129 | <DL COMPACT><DT><DD> | |
4130 | <P> | |
4131 | ||
4132 | <B>$((</B><I>expression</I><B>))</B> | |
4133 | </DL> | |
4134 | ||
4135 | <P> | |
4136 | ||
4137 | The | |
4138 | <I>expression</I> | |
4139 | ||
4140 | is treated as if it were within double quotes, but a double quote | |
4141 | inside the parentheses is not treated specially. | |
ac50fbac CR |
4142 | All tokens in the expression undergo parameter and variable expansion, |
4143 | command substitution, and quote removal. | |
4144 | The result is treated as the arithmetic expression to be evaluated. | |
17345e5a JA |
4145 | Arithmetic expansions may be nested. |
4146 | <P> | |
4147 | ||
4148 | The evaluation is performed according to the rules listed below under | |
4149 | <FONT SIZE=-1><B>ARITHMETIC EVALUATION</B>. | |
4150 | ||
4151 | </FONT> | |
4152 | If | |
4153 | <I>expression</I> | |
4154 | ||
4155 | is invalid, | |
4156 | <B>bash</B> | |
4157 | ||
4158 | prints a message indicating failure and no substitution occurs. | |
4159 | <A NAME="lbBE"> </A> | |
4160 | <H4>Process Substitution</H4> | |
4161 | ||
4162 | <P> | |
4163 | ||
a0c0a00f CR |
4164 | <I>Process substitution</I> allows a process's input or output to be |
4165 | referred to using a filename. | |
17345e5a JA |
4166 | It takes the form of |
4167 | <B><(</B><I>list</I><B>)</B> | |
4168 | or | |
4169 | <B>>(</B><I>list</I><B>)</B>. | |
a0c0a00f CR |
4170 | The process <I>list</I> is run asynchronously, and its input or output |
4171 | appears as a filename. | |
4172 | This filename is | |
17345e5a | 4173 | passed as an argument to the current command as the result of the |
a0c0a00f CR |
4174 | expansion. |
4175 | If the <B>>(</B><I>list</I><B>)</B> form is used, writing to | |
17345e5a JA |
4176 | the file will provide input for <I>list</I>. If the |
4177 | <B><(</B><I>list</I><B>)</B> form is used, the file passed as an | |
4178 | argument should be read to obtain the output of <I>list</I>. | |
a0c0a00f CR |
4179 | Process substitution is supported on systems that support named |
4180 | pipes (<I>FIFOs</I>) or the <B>/dev/fd</B> method of naming open files. | |
17345e5a JA |
4181 | <P> |
4182 | ||
4183 | When available, process substitution is performed | |
a0c0a00f | 4184 | simultaneously with parameter and variable expansion, |
17345e5a JA |
4185 | command substitution, |
4186 | and arithmetic expansion. | |
4187 | <A NAME="lbBF"> </A> | |
4188 | <H4>Word Splitting</H4> | |
4189 | ||
4190 | <P> | |
4191 | ||
4192 | The shell scans the results of | |
4193 | parameter expansion, | |
4194 | command substitution, | |
4195 | and | |
4196 | arithmetic expansion | |
4197 | that did not occur within double quotes for | |
4198 | <I>word splitting</I>. | |
4199 | ||
4200 | <P> | |
4201 | ||
4202 | The shell treats each character of | |
4203 | <FONT SIZE=-1><B>IFS</B> | |
4204 | ||
4205 | </FONT> | |
4206 | as a delimiter, and splits the results of the other | |
ac50fbac CR |
4207 | expansions into words using these characters as field terminators. |
4208 | If | |
17345e5a JA |
4209 | <FONT SIZE=-1><B>IFS</B> |
4210 | ||
4211 | </FONT> | |
4212 | is unset, or its | |
4213 | value is exactly | |
4214 | <B><space><tab><newline></B>, | |
4215 | ||
4216 | the default, then | |
4217 | sequences of | |
4218 | <B><space></B>, | |
4219 | ||
4220 | <B><tab></B>, | |
4221 | ||
4222 | and | |
4223 | <B><newline></B> | |
4224 | ||
4225 | at the beginning and end of the results of the previous | |
4226 | expansions are ignored, and | |
4227 | any sequence of | |
4228 | <FONT SIZE=-1><B>IFS</B> | |
4229 | ||
4230 | </FONT> | |
4231 | characters not at the beginning or end serves to delimit words. | |
4232 | If | |
4233 | <FONT SIZE=-1><B>IFS</B> | |
4234 | ||
4235 | </FONT> | |
4236 | has a value other than the default, then sequences of | |
4237 | the whitespace characters | |
a0c0a00f CR |
4238 | <B>space</B>, |
4239 | ||
4240 | <B>tab</B>, | |
17345e5a JA |
4241 | |
4242 | and | |
a0c0a00f | 4243 | <B>newline</B> |
17345e5a JA |
4244 | |
4245 | are ignored at the beginning and end of the | |
4246 | word, as long as the whitespace character is in the | |
4247 | value of | |
4248 | <FONT SIZE=-1><B>IFS</B> | |
4249 | ||
4250 | </FONT> | |
4251 | (an | |
4252 | <FONT SIZE=-1><B>IFS</B> | |
4253 | ||
4254 | </FONT> | |
4255 | whitespace character). | |
4256 | Any character in | |
4257 | <FONT SIZE=-1><B>IFS</B> | |
4258 | ||
4259 | </FONT> | |
4260 | that is not | |
4261 | <FONT SIZE=-1><B>IFS</B> | |
4262 | ||
4263 | </FONT> | |
4264 | whitespace, along with any adjacent | |
4265 | <FONT SIZE=-1><B>IFS</B> | |
4266 | ||
4267 | </FONT> | |
4268 | whitespace characters, delimits a field. | |
4269 | A sequence of | |
4270 | <FONT SIZE=-1><B>IFS</B> | |
4271 | ||
4272 | </FONT> | |
4273 | whitespace characters is also treated as a delimiter. | |
4274 | If the value of | |
4275 | <FONT SIZE=-1><B>IFS</B> | |
4276 | ||
4277 | </FONT> | |
4278 | is null, no word splitting occurs. | |
4279 | <P> | |
4280 | ||
a0c0a00f CR |
4281 | Explicit null arguments (<B>""</B> or <B>aqaq</B>) are retained |
4282 | and passed to commands as empty strings. | |
17345e5a JA |
4283 | Unquoted implicit null arguments, resulting from the expansion of |
4284 | parameters that have no values, are removed. | |
4285 | If a parameter with no value is expanded within double quotes, a | |
a0c0a00f CR |
4286 | null argument results and is retained |
4287 | and passed to a command as an empty string. | |
4288 | When a quoted null argument appears as part of a word whose expansion is | |
4289 | non-null, the null argument is removed. | |
4290 | That is, the word | |
4291 | <TT>-daqaq</TT> becomes <TT>-d</TT> after word splitting and | |
4292 | null argument removal. | |
17345e5a JA |
4293 | <P> |
4294 | ||
4295 | Note that if no expansion occurs, no splitting | |
4296 | is performed. | |
4297 | <A NAME="lbBG"> </A> | |
4298 | <H4>Pathname Expansion</H4> | |
4299 | ||
4300 | <P> | |
4301 | ||
4302 | After word splitting, | |
4303 | unless the | |
4304 | <B>-f</B> | |
4305 | ||
4306 | option has been set, | |
4307 | <B>bash</B> | |
4308 | ||
4309 | scans each word for the characters | |
4310 | <B>*</B>, | |
4311 | ||
4312 | <B>?</B>, | |
4313 | ||
4314 | and | |
4315 | <B>[</B>. | |
4316 | ||
4317 | If one of these characters appears, then the word is | |
4318 | regarded as a | |
4319 | <I>pattern</I>, | |
4320 | ||
4321 | and replaced with an alphabetically sorted list of | |
ac50fbac CR |
4322 | filenames matching the pattern |
4323 | (see | |
4324 | <FONT SIZE=-1><B>Pattern Matching</B> | |
4325 | ||
4326 | </FONT> | |
4327 | below). | |
4328 | If no matching filenames are found, | |
17345e5a JA |
4329 | and the shell option |
4330 | <B>nullglob</B> | |
4331 | ||
4332 | is not enabled, the word is left unchanged. | |
a0c0a00f | 4333 | If the |
17345e5a JA |
4334 | <B>nullglob</B> |
4335 | ||
4336 | option is set, and no matches are found, | |
4337 | the word is removed. | |
4338 | If the | |
4339 | <B>failglob</B> | |
4340 | ||
4341 | shell option is set, and no matches are found, an error message | |
4342 | is printed and the command is not executed. | |
4343 | If the shell option | |
4344 | <B>nocaseglob</B> | |
4345 | ||
4346 | is enabled, the match is performed without regard to the case | |
4347 | of alphabetic characters. | |
4348 | When a pattern is used for pathname expansion, | |
4349 | the character | |
4350 | <B>``.''</B> | |
4351 | ||
4352 | at the start of a name or immediately following a slash | |
4353 | must be matched explicitly, unless the shell option | |
4354 | <B>dotglob</B> | |
4355 | ||
4356 | is set. | |
4357 | When matching a pathname, the slash character must always be | |
4358 | matched explicitly. | |
4359 | In other cases, the | |
4360 | <B>``.''</B> | |
4361 | ||
4362 | character is not treated specially. | |
4363 | See the description of | |
4364 | <B>shopt</B> | |
4365 | ||
4366 | below under | |
4367 | <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B> | |
4368 | ||
4369 | </FONT> | |
4370 | for a description of the | |
4371 | <B>nocaseglob</B>, | |
4372 | ||
4373 | <B>nullglob</B>, | |
4374 | ||
4375 | <B>failglob</B>, | |
4376 | ||
4377 | and | |
4378 | <B>dotglob</B> | |
4379 | ||
4380 | shell options. | |
4381 | <P> | |
4382 | ||
4383 | The | |
4384 | <FONT SIZE=-1><B>GLOBIGNORE</B> | |
4385 | ||
4386 | </FONT> | |
ac50fbac | 4387 | shell variable may be used to restrict the set of filenames matching a |
17345e5a JA |
4388 | <I>pattern</I>. |
4389 | ||
4390 | If | |
4391 | <FONT SIZE=-1><B>GLOBIGNORE</B> | |
4392 | ||
4393 | </FONT> | |
ac50fbac | 4394 | is set, each matching filename that also matches one of the patterns in |
17345e5a JA |
4395 | <FONT SIZE=-1><B>GLOBIGNORE</B> |
4396 | ||
4397 | </FONT> | |
4398 | is removed from the list of matches. | |
a0c0a00f CR |
4399 | If the <B>nocaseglob</B> option is set, the matching against the patterns in |
4400 | <FONT SIZE=-1><B>GLOBIGNORE</B> | |
4401 | ||
4402 | </FONT> | |
4403 | is performed without regard to case. | |
ac50fbac | 4404 | The filenames |
17345e5a JA |
4405 | <B>``.''</B> |
4406 | ||
4407 | and | |
4408 | <B>``..''</B> | |
4409 | ||
4410 | are always ignored when | |
4411 | <FONT SIZE=-1><B>GLOBIGNORE</B> | |
4412 | ||
4413 | </FONT> | |
4414 | is set and not null. However, setting | |
4415 | <FONT SIZE=-1><B>GLOBIGNORE</B> | |
4416 | ||
4417 | </FONT> | |
4418 | to a non-null value has the effect of enabling the | |
4419 | <B>dotglob</B> | |
4420 | ||
ac50fbac | 4421 | shell option, so all other filenames beginning with a |
17345e5a JA |
4422 | <B>``.''</B> |
4423 | ||
4424 | will match. | |
ac50fbac | 4425 | To get the old behavior of ignoring filenames beginning with a |
17345e5a JA |
4426 | <B>``.''</B>, |
4427 | ||
4428 | make | |
4429 | <B>``.*''</B> | |
4430 | ||
4431 | one of the patterns in | |
4432 | <FONT SIZE=-1><B>GLOBIGNORE</B>. | |
4433 | ||
4434 | </FONT> | |
4435 | The | |
4436 | <B>dotglob</B> | |
4437 | ||
4438 | option is disabled when | |
4439 | <FONT SIZE=-1><B>GLOBIGNORE</B> | |
4440 | ||
4441 | </FONT> | |
4442 | is unset. | |
a0c0a00f CR |
4443 | The pattern matching honors the setting of the <B>extglob</B> shell |
4444 | option. | |
17345e5a JA |
4445 | <P> |
4446 | ||
4447 | <B>Pattern Matching</B> | |
4448 | <P> | |
4449 | ||
4450 | Any character that appears in a pattern, other than the special pattern | |
4451 | characters described below, matches itself. The NUL character may not | |
4452 | occur in a pattern. A backslash escapes the following character; the | |
4453 | escaping backslash is discarded when matching. | |
4454 | The special pattern characters must be quoted if | |
4455 | they are to be matched literally. | |
4456 | <P> | |
4457 | ||
4458 | The special pattern characters have the following meanings: | |
4459 | <P> | |
4460 | ||
4461 | ||
495aee44 | 4462 | <DL COMPACT><DT><DD> |
17345e5a JA |
4463 | <DL COMPACT> |
4464 | <DT><B>*</B> | |
4465 | ||
4466 | <DD> | |
4467 | Matches any string, including the null string. | |
4468 | When the <B>globstar</B> shell option is enabled, and <B>*</B> is used in | |
0001803f | 4469 | a pathname expansion context, two adjacent <B>*</B>s used as a single |
17345e5a JA |
4470 | pattern will match all files and zero or more directories and |
4471 | subdirectories. | |
4472 | If followed by a <B>/</B>, two adjacent <B>*</B>s will match only directories | |
4473 | and subdirectories. | |
4474 | <DT><B>?</B> | |
4475 | ||
4476 | <DD> | |
4477 | Matches any single character. | |
4478 | <DT><B>[...]</B> | |
4479 | ||
4480 | <DD> | |
4481 | Matches any one of the enclosed characters. A pair of characters | |
4482 | separated by a hyphen denotes a | |
4483 | <I>range expression</I>; | |
ac50fbac | 4484 | any character that falls between those two characters, inclusive, |
17345e5a JA |
4485 | using the current locale's collating sequence and character set, |
4486 | is matched. If the first character following the | |
4487 | <B>[</B> | |
4488 | ||
4489 | is a | |
4490 | <B>!</B> | |
4491 | ||
4492 | or a | |
4493 | <B>^</B> | |
4494 | ||
4495 | then any character not enclosed is matched. | |
4496 | The sorting order of characters in range expressions is determined by | |
ac50fbac | 4497 | the current locale and the values of the |
0001803f CR |
4498 | <FONT SIZE=-1><B>LC_COLLATE</B> |
4499 | ||
4500 | </FONT> | |
ac50fbac CR |
4501 | or |
4502 | <FONT SIZE=-1><B>LC_ALL</B> | |
4503 | ||
4504 | </FONT> | |
4505 | shell variables, if set. | |
4506 | To obtain the traditional interpretation of range expressions, where | |
4507 | <B>[a-d]</B> | |
4508 | ||
4509 | is equivalent to | |
4510 | <B>[abcd]</B>, | |
4511 | ||
4512 | set value of the | |
4513 | <B>LC_ALL</B> | |
4514 | ||
4515 | shell variable to | |
4516 | <B>C</B>, | |
4517 | ||
4518 | or enable the | |
4519 | <B>globasciiranges</B> | |
4520 | ||
4521 | shell option. | |
a0c0a00f | 4522 | A |
17345e5a JA |
4523 | <B>-</B> |
4524 | ||
4525 | may be matched by including it as the first or last character | |
4526 | in the set. | |
4527 | A | |
4528 | <B>]</B> | |
4529 | ||
4530 | may be matched by including it as the first character | |
4531 | in the set. | |
4532 | <BR> | |
4533 | ||
4534 | <P> | |
4535 | ||
4536 | ||
4537 | Within | |
4538 | <B>[</B> | |
4539 | ||
4540 | and | |
4541 | <B>]</B>, | |
4542 | ||
4543 | <I>character classes</I> can be specified using the syntax | |
4544 | <B>[:</B><I>class</I><B>:]</B>, where <I>class</I> is one of the | |
4545 | following classes defined in the POSIX standard: | |
4546 | </DL> | |
4547 | <P> | |
4548 | ||
4549 | <DL COMPACT><DT><DD> | |
4550 | <B> | |
4551 | </B> | |
4552 | ||
4553 | alnum alpha ascii blank cntrl digit graph lower print punct space upper word xdigit | |
4554 | <BR> | |
4555 | ||
4556 | A character class matches any character belonging to that class. | |
4557 | The <B>word</B> character class matches letters, digits, and the character _. | |
4558 | <BR> | |
4559 | ||
4560 | <P> | |
4561 | ||
4562 | ||
4563 | Within | |
4564 | <B>[</B> | |
4565 | ||
a0c0a00f | 4566 | and |
17345e5a JA |
4567 | <B>]</B>, |
4568 | ||
4569 | an <I>equivalence class</I> can be specified using the syntax | |
4570 | <B>[=</B><I>c</I><B>=]</B>, which matches all characters with the | |
4571 | same collation weight (as defined by the current locale) as | |
4572 | the character <I>c</I>. | |
4573 | <BR> | |
4574 | ||
4575 | <P> | |
4576 | ||
4577 | ||
4578 | Within | |
4579 | <B>[</B> | |
4580 | ||
a0c0a00f | 4581 | and |
17345e5a JA |
4582 | <B>]</B>, |
4583 | ||
4584 | the syntax <B>[.</B><I>symbol</I><B>.]</B> matches the collating symbol | |
4585 | <I>symbol</I>. | |
4586 | </DL> | |
4587 | ||
495aee44 CR |
4588 | </DL> |
4589 | ||
17345e5a JA |
4590 | |
4591 | <P> | |
4592 | ||
4593 | If the <B>extglob</B> shell option is enabled using the <B>shopt</B> | |
4594 | builtin, several extended pattern matching operators are recognized. | |
4595 | In the following description, a <I>pattern-list</I> is a list of one | |
4596 | or more patterns separated by a <B>|</B>. | |
4597 | Composite patterns may be formed using one or more of the following | |
4598 | sub-patterns: | |
4599 | <P> | |
4600 | ||
4601 | <DL COMPACT><DT><DD> | |
4602 | <DL COMPACT> | |
4603 | <DT><B>?(</B><I>pattern-list</I><B>)</B><DD> | |
4604 | Matches zero or one occurrence of the given patterns | |
4605 | <DT><B>*(</B><I>pattern-list</I><B>)</B><DD> | |
4606 | Matches zero or more occurrences of the given patterns | |
4607 | <DT><B>+(</B><I>pattern-list</I><B>)</B><DD> | |
4608 | Matches one or more occurrences of the given patterns | |
4609 | <DT><B>@(</B><I>pattern-list</I><B>)</B><DD> | |
4610 | Matches one of the given patterns | |
4611 | <DT><B>!(</B><I>pattern-list</I><B>)</B><DD> | |
4612 | Matches anything except one of the given patterns | |
4613 | </DL></DL> | |
4614 | ||
4615 | ||
4616 | <A NAME="lbBH"> </A> | |
4617 | <H4>Quote Removal</H4> | |
4618 | ||
4619 | <P> | |
4620 | ||
4621 | After the preceding expansions, all unquoted occurrences of the | |
4622 | characters | |
4623 | <B>\</B>, | |
4624 | ||
4625 | <B>aq</B>, | |
4626 | ||
4627 | and <B>"</B> that did not result from one of the above | |
4628 | expansions are removed. | |
4629 | <A NAME="lbBI"> </A> | |
4630 | <H3>REDIRECTION</H3> | |
4631 | ||
4632 | Before a command is executed, its input and output | |
4633 | may be | |
4634 | <I>redirected</I> | |
4635 | ||
4636 | using a special notation interpreted by the shell. | |
ac50fbac CR |
4637 | Redirection allows commands' file handles to be |
4638 | duplicated, opened, closed, | |
4639 | made to refer to different files, | |
4640 | and can change the files the command reads from and writes to. | |
4641 | Redirection may also be used to modify file handles in the | |
4642 | current shell execution environment. | |
4643 | The following redirection | |
17345e5a JA |
4644 | operators may precede or appear anywhere within a |
4645 | <I>simple command</I> | |
4646 | ||
4647 | or may follow a | |
4648 | <I>command</I>. | |
4649 | ||
4650 | Redirections are processed in the order they appear, from | |
4651 | left to right. | |
4652 | <P> | |
4653 | ||
0001803f CR |
4654 | Each redirection that may be preceded by a file descriptor number |
4655 | may instead be preceded by a word of the form {<I>varname</I>}. | |
4656 | In this case, for each redirection operator except | |
4657 | >&- and <&-, the shell will allocate a file descriptor greater | |
ac50fbac CR |
4658 | than or equal to 10 and assign it to <I>varname</I>. |
4659 | If >&- or <&- is preceded | |
0001803f CR |
4660 | by {<I>varname</I>}, the value of <I>varname</I> defines the file |
4661 | descriptor to close. | |
4662 | <P> | |
4663 | ||
17345e5a JA |
4664 | In the following descriptions, if the file descriptor number is |
4665 | omitted, and the first character of the redirection operator is | |
4666 | <B><</B>, | |
4667 | ||
4668 | the redirection refers to the standard input (file descriptor | |
4669 | 0). If the first character of the redirection operator is | |
4670 | <B>></B>, | |
4671 | ||
4672 | the redirection refers to the standard output (file descriptor | |
4673 | 1). | |
4674 | <P> | |
4675 | ||
4676 | The word following the redirection operator in the following | |
ac50fbac CR |
4677 | descriptions, unless otherwise noted, is subjected to |
4678 | brace expansion, tilde expansion, parameter and variable expansion, | |
4679 | command substitution, arithmetic expansion, quote removal, | |
4680 | pathname expansion, and word splitting. | |
17345e5a JA |
4681 | If it expands to more than one word, |
4682 | <B>bash</B> | |
4683 | ||
4684 | reports an error. | |
4685 | <P> | |
4686 | ||
a0c0a00f | 4687 | Note that the order of redirections is significant. For example, |
17345e5a JA |
4688 | the command |
4689 | <DL COMPACT><DT><DD> | |
4690 | <P> | |
4691 | ||
4692 | ls <B>></B> dirlist 2<B>>&</B>1 | |
4693 | </DL> | |
4694 | ||
4695 | <P> | |
4696 | ||
a0c0a00f | 4697 | directs both standard output and standard error to the file |
17345e5a JA |
4698 | <I>dirlist</I>, |
4699 | ||
4700 | while the command | |
4701 | <DL COMPACT><DT><DD> | |
4702 | <P> | |
4703 | ||
4704 | ls 2<B>>&</B>1 <B>></B> dirlist | |
4705 | </DL> | |
4706 | ||
4707 | <P> | |
4708 | ||
4709 | directs only the standard output to file | |
4710 | <I>dirlist</I>, | |
4711 | ||
0001803f | 4712 | because the standard error was duplicated from the standard output |
17345e5a JA |
4713 | before the standard output was redirected to |
4714 | <I>dirlist</I>. | |
4715 | ||
4716 | <P> | |
4717 | ||
4718 | <B>Bash</B> handles several filenames specially when they are used in | |
a0c0a00f CR |
4719 | redirections, as described in the following table. |
4720 | If the operating system on which <B>bash</B> is running provides these | |
4721 | special files, bash will use them; otherwise it will emulate them | |
4722 | internally with the behavior described below. | |
17345e5a JA |
4723 | <DL COMPACT><DT><DD> |
4724 | <P> | |
4725 | ||
4726 | ||
4727 | <DL COMPACT> | |
4728 | <DT><B>/dev/fd/</B><I>fd</I> | |
4729 | ||
4730 | <DD> | |
4731 | If <I>fd</I> is a valid integer, file descriptor <I>fd</I> is duplicated. | |
4732 | <DT><B>/dev/stdin</B> | |
4733 | ||
4734 | <DD> | |
4735 | File descriptor 0 is duplicated. | |
4736 | <DT><B>/dev/stdout</B> | |
4737 | ||
4738 | <DD> | |
4739 | File descriptor 1 is duplicated. | |
4740 | <DT><B>/dev/stderr</B> | |
4741 | ||
4742 | <DD> | |
4743 | File descriptor 2 is duplicated. | |
4744 | <DT><B>/dev/tcp/</B><I>host</I>/<I>port</I> | |
4745 | ||
4746 | <DD> | |
4747 | If <I>host</I> is a valid hostname or Internet address, and <I>port</I> | |
4748 | is an integer port number or service name, <B>bash</B> attempts to open | |
ac50fbac | 4749 | the corresponding TCP socket. |
17345e5a JA |
4750 | <DT><B>/dev/udp/</B><I>host</I>/<I>port</I> |
4751 | ||
4752 | <DD> | |
4753 | If <I>host</I> is a valid hostname or Internet address, and <I>port</I> | |
4754 | is an integer port number or service name, <B>bash</B> attempts to open | |
ac50fbac | 4755 | the corresponding UDP socket. |
17345e5a JA |
4756 | |
4757 | </DL></DL> | |
4758 | ||
4759 | <P> | |
4760 | ||
4761 | A failure to open or create a file causes the redirection to fail. | |
4762 | <P> | |
4763 | ||
4764 | Redirections using file descriptors greater than 9 should be used with | |
4765 | care, as they may conflict with file descriptors the shell uses | |
4766 | internally. | |
4767 | <A NAME="lbBJ"> </A> | |
4768 | <H4>Redirecting Input</H4> | |
4769 | ||
4770 | <P> | |
4771 | ||
4772 | Redirection of input causes the file whose name results from | |
4773 | the expansion of | |
4774 | <I>word</I> | |
4775 | ||
4776 | to be opened for reading on file descriptor | |
4777 | <I>n</I>, | |
4778 | ||
4779 | or the standard input (file descriptor 0) if | |
4780 | <I>n</I> | |
4781 | ||
4782 | is not specified. | |
4783 | <P> | |
4784 | ||
4785 | The general format for redirecting input is: | |
4786 | <DL COMPACT><DT><DD> | |
4787 | <P> | |
4788 | ||
4789 | [<I>n</I>]<B><</B><I>word</I> | |
4790 | </DL> | |
4791 | ||
4792 | <A NAME="lbBK"> </A> | |
4793 | <H4>Redirecting Output</H4> | |
4794 | ||
4795 | <P> | |
4796 | ||
4797 | Redirection of output causes the file whose name results from | |
4798 | the expansion of | |
4799 | <I>word</I> | |
4800 | ||
4801 | to be opened for writing on file descriptor | |
4802 | <I>n</I>, | |
4803 | ||
4804 | or the standard output (file descriptor 1) if | |
4805 | <I>n</I> | |
4806 | ||
4807 | is not specified. If the file does not exist it is created; | |
4808 | if it does exist it is truncated to zero size. | |
4809 | <P> | |
4810 | ||
4811 | The general format for redirecting output is: | |
4812 | <DL COMPACT><DT><DD> | |
4813 | <P> | |
4814 | ||
4815 | [<I>n</I>]<B>></B><I>word</I> | |
4816 | </DL> | |
4817 | ||
4818 | <P> | |
4819 | ||
4820 | If the redirection operator is | |
4821 | <B>></B>, | |
4822 | ||
4823 | and the | |
4824 | <B>noclobber</B> | |
4825 | ||
4826 | option to the | |
4827 | <B>set</B> | |
4828 | ||
4829 | builtin has been enabled, the redirection will fail if the file | |
4830 | whose name results from the expansion of <I>word</I> exists and is | |
4831 | a regular file. | |
4832 | If the redirection operator is | |
4833 | <B>>|</B>, | |
4834 | ||
4835 | or the redirection operator is | |
4836 | <B>></B> | |
4837 | ||
4838 | and the | |
4839 | <B>noclobber</B> | |
4840 | ||
4841 | option to the | |
4842 | <B>set</B> | |
4843 | ||
4844 | builtin command is not enabled, the redirection is attempted even | |
4845 | if the file named by <I>word</I> exists. | |
4846 | <A NAME="lbBL"> </A> | |
4847 | <H4>Appending Redirected Output</H4> | |
4848 | ||
4849 | <P> | |
4850 | ||
4851 | Redirection of output in this fashion | |
4852 | causes the file whose name results from | |
4853 | the expansion of | |
4854 | <I>word</I> | |
4855 | ||
4856 | to be opened for appending on file descriptor | |
4857 | <I>n</I>, | |
4858 | ||
4859 | or the standard output (file descriptor 1) if | |
4860 | <I>n</I> | |
4861 | ||
4862 | is not specified. If the file does not exist it is created. | |
4863 | <P> | |
4864 | ||
4865 | The general format for appending output is: | |
4866 | <DL COMPACT><DT><DD> | |
4867 | <P> | |
4868 | ||
4869 | [<I>n</I>]<B>>></B><I>word</I> | |
4870 | </DL> | |
4871 | ||
4872 | <P> | |
4873 | ||
4874 | <A NAME="lbBM"> </A> | |
4875 | <H4>Redirecting Standard Output and Standard Error</H4> | |
4876 | ||
4877 | <P> | |
4878 | ||
4879 | This construct allows both the | |
4880 | standard output (file descriptor 1) and | |
4881 | the standard error output (file descriptor 2) | |
4882 | to be redirected to the file whose name is the | |
4883 | expansion of | |
4884 | <I>word</I>. | |
4885 | ||
4886 | <P> | |
4887 | ||
4888 | There are two formats for redirecting standard output and | |
4889 | standard error: | |
4890 | <DL COMPACT><DT><DD> | |
4891 | <P> | |
4892 | ||
4893 | <B>&></B><I>word</I> | |
4894 | </DL> | |
4895 | ||
4896 | and | |
4897 | <DL COMPACT><DT><DD> | |
4898 | <B>>&</B><I>word</I> | |
4899 | </DL> | |
4900 | ||
4901 | <P> | |
4902 | ||
4903 | Of the two forms, the first is preferred. | |
4904 | This is semantically equivalent to | |
4905 | <DL COMPACT><DT><DD> | |
4906 | <P> | |
4907 | ||
4908 | <B>></B><I>word</I> 2<B>>&</B>1 | |
4909 | </DL> | |
4910 | ||
4911 | <P> | |
4912 | ||
ac50fbac CR |
4913 | When using the second form, <I>word</I> may not expand to a number or |
4914 | <B>-</B>. If it does, other redirection operators apply | |
4915 | (see <B>Duplicating File Descriptors</B> below) for compatibility | |
4916 | reasons. | |
17345e5a JA |
4917 | <A NAME="lbBN"> </A> |
4918 | <H4>Appending Standard Output and Standard Error</H4> | |
4919 | ||
4920 | <P> | |
4921 | ||
4922 | This construct allows both the | |
4923 | standard output (file descriptor 1) and | |
4924 | the standard error output (file descriptor 2) | |
4925 | to be appended to the file whose name is the | |
4926 | expansion of | |
4927 | <I>word</I>. | |
4928 | ||
4929 | <P> | |
4930 | ||
4931 | The format for appending standard output and standard error is: | |
4932 | <DL COMPACT><DT><DD> | |
4933 | <P> | |
4934 | ||
4935 | <B>&>></B><I>word</I> | |
4936 | </DL> | |
4937 | ||
4938 | <P> | |
4939 | ||
4940 | This is semantically equivalent to | |
4941 | <DL COMPACT><DT><DD> | |
4942 | <P> | |
4943 | ||
4944 | <B>>></B><I>word</I> 2<B>>&</B>1 | |
4945 | </DL> | |
4946 | ||
ac50fbac CR |
4947 | <P> |
4948 | ||
4949 | (see <B>Duplicating File Descriptors</B> below). | |
17345e5a JA |
4950 | <A NAME="lbBO"> </A> |
4951 | <H4>Here Documents</H4> | |
4952 | ||
4953 | <P> | |
4954 | ||
4955 | This type of redirection instructs the shell to read input from the | |
4956 | current source until a line containing only | |
4957 | <I>delimiter</I> | |
4958 | ||
4959 | (with no trailing blanks) | |
4960 | is seen. All of | |
4961 | the lines read up to that point are then used as the standard | |
a0c0a00f | 4962 | input (or file descriptor <I>n</I> if <I>n</I> is specified) for a command. |
17345e5a JA |
4963 | <P> |
4964 | ||
4965 | The format of here-documents is: | |
4966 | <DL COMPACT><DT><DD> | |
4967 | <P> | |
4968 | ||
4969 | <PRE> | |
a0c0a00f | 4970 | [<I>n</I>]<B><<</B>[<B>-</B>]<I>word</I> |
17345e5a JA |
4971 | <I>here-document</I> |
4972 | <I>delimiter</I> | |
4973 | </PRE> | |
4974 | ||
4975 | </DL> | |
4976 | ||
4977 | <P> | |
4978 | ||
ac50fbac CR |
4979 | No parameter and variable expansion, command substitution, |
4980 | arithmetic expansion, or pathname expansion is performed on | |
17345e5a JA |
4981 | <I>word</I>. |
4982 | ||
a0c0a00f | 4983 | If any part of |
17345e5a JA |
4984 | <I>word</I> |
4985 | ||
a0c0a00f | 4986 | is quoted, the |
17345e5a JA |
4987 | <I>delimiter</I> |
4988 | ||
4989 | is the result of quote removal on | |
4990 | <I>word</I>, | |
4991 | ||
4992 | and the lines in the here-document are not expanded. | |
4993 | If <I>word</I> is unquoted, | |
ac50fbac CR |
4994 | all lines of the here-document are subjected to |
4995 | parameter expansion, command substitution, and arithmetic expansion, | |
4996 | the character sequence | |
17345e5a JA |
4997 | <B>\<newline></B> |
4998 | ||
4999 | is ignored, and | |
5000 | <B>\</B> | |
5001 | ||
5002 | must be used to quote the characters | |
5003 | <B>\</B>, | |
5004 | ||
5005 | <B>$</B>, | |
5006 | ||
5007 | and | |
5008 | <B>`</B>. | |
5009 | ||
5010 | <P> | |
5011 | ||
5012 | If the redirection operator is | |
5013 | <B><<-</B>, | |
5014 | ||
5015 | then all leading tab characters are stripped from input lines and the | |
5016 | line containing | |
5017 | <I>delimiter</I>. | |
5018 | ||
5019 | This allows | |
5020 | here-documents within shell scripts to be indented in a | |
5021 | natural fashion. | |
5022 | <A NAME="lbBP"> </A> | |
5023 | <H4>Here Strings</H4> | |
5024 | ||
5025 | A variant of here documents, the format is: | |
5026 | <DL COMPACT><DT><DD> | |
5027 | <P> | |
5028 | ||
5029 | <PRE> | |
a0c0a00f | 5030 | [<I>n</I>]<B><<<</B><I>word</I> |
17345e5a JA |
5031 | </PRE> |
5032 | ||
5033 | </DL> | |
5034 | ||
5035 | <P> | |
5036 | ||
ac50fbac CR |
5037 | The <I>word</I> undergoes |
5038 | brace expansion, tilde expansion, parameter and variable expansion, | |
5039 | command substitution, arithmetic expansion, and quote removal. | |
5040 | Pathname expansion and word splitting are not performed. | |
a0c0a00f CR |
5041 | The result is supplied as a single string, with a newline appended, |
5042 | to the command on its | |
5043 | standard input (or file descriptor <I>n</I> if <I>n</I> is specified). | |
17345e5a JA |
5044 | <A NAME="lbBQ"> </A> |
5045 | <H4>Duplicating File Descriptors</H4> | |
5046 | ||
5047 | <P> | |
5048 | ||
5049 | The redirection operator | |
5050 | <DL COMPACT><DT><DD> | |
5051 | <P> | |
5052 | ||
5053 | [<I>n</I>]<B><&</B><I>word</I> | |
5054 | </DL> | |
5055 | ||
5056 | <P> | |
5057 | ||
5058 | is used to duplicate input file descriptors. | |
5059 | If | |
5060 | <I>word</I> | |
5061 | ||
5062 | expands to one or more digits, the file descriptor denoted by | |
5063 | <I>n</I> | |
5064 | ||
5065 | is made to be a copy of that file descriptor. | |
5066 | If the digits in | |
5067 | <I>word</I> | |
5068 | ||
5069 | do not specify a file descriptor open for input, a redirection error occurs. | |
5070 | If | |
5071 | <I>word</I> | |
5072 | ||
5073 | evaluates to | |
5074 | <B>-</B>, | |
5075 | ||
5076 | file descriptor | |
5077 | <I>n</I> | |
5078 | ||
5079 | is closed. If | |
5080 | <I>n</I> | |
5081 | ||
5082 | is not specified, the standard input (file descriptor 0) is used. | |
5083 | <P> | |
5084 | ||
5085 | The operator | |
5086 | <DL COMPACT><DT><DD> | |
5087 | <P> | |
5088 | ||
5089 | [<I>n</I>]<B>>&</B><I>word</I> | |
5090 | </DL> | |
5091 | ||
5092 | <P> | |
5093 | ||
5094 | is used similarly to duplicate output file descriptors. If | |
5095 | <I>n</I> | |
5096 | ||
5097 | is not specified, the standard output (file descriptor 1) is used. | |
5098 | If the digits in | |
5099 | <I>word</I> | |
5100 | ||
5101 | do not specify a file descriptor open for output, a redirection error occurs. | |
ac50fbac CR |
5102 | If |
5103 | <I>word</I> | |
5104 | ||
5105 | evaluates to | |
5106 | <B>-</B>, | |
5107 | ||
5108 | file descriptor | |
5109 | <I>n</I> | |
5110 | ||
5111 | is closed. | |
17345e5a | 5112 | As a special case, if <I>n</I> is omitted, and <I>word</I> does not |
ac50fbac | 5113 | expand to one or more digits or <B>-</B>, the standard output and standard |
17345e5a JA |
5114 | error are redirected as described previously. |
5115 | <A NAME="lbBR"> </A> | |
5116 | <H4>Moving File Descriptors</H4> | |
5117 | ||
5118 | <P> | |
5119 | ||
5120 | The redirection operator | |
5121 | <DL COMPACT><DT><DD> | |
5122 | <P> | |
5123 | ||
5124 | [<I>n</I>]<B><&</B><I>digit</I><B>-</B> | |
5125 | </DL> | |
5126 | ||
5127 | <P> | |
5128 | ||
5129 | moves the file descriptor <I>digit</I> to file descriptor | |
5130 | <I>n</I>, | |
5131 | ||
5132 | or the standard input (file descriptor 0) if <I>n</I> is not specified. | |
5133 | <I>digit</I> is closed after being duplicated to <I>n</I>. | |
5134 | <P> | |
5135 | ||
5136 | Similarly, the redirection operator | |
5137 | <DL COMPACT><DT><DD> | |
5138 | <P> | |
5139 | ||
5140 | [<I>n</I>]<B>>&</B><I>digit</I><B>-</B> | |
5141 | </DL> | |
5142 | ||
5143 | <P> | |
5144 | ||
5145 | moves the file descriptor <I>digit</I> to file descriptor | |
5146 | <I>n</I>, | |
5147 | ||
5148 | or the standard output (file descriptor 1) if <I>n</I> is not specified. | |
5149 | <A NAME="lbBS"> </A> | |
5150 | <H4>Opening File Descriptors for Reading and Writing</H4> | |
5151 | ||
5152 | <P> | |
5153 | ||
5154 | The redirection operator | |
5155 | <DL COMPACT><DT><DD> | |
5156 | <P> | |
5157 | ||
5158 | [<I>n</I>]<B><></B><I>word</I> | |
5159 | </DL> | |
5160 | ||
5161 | <P> | |
5162 | ||
5163 | causes the file whose name is the expansion of | |
5164 | <I>word</I> | |
5165 | ||
5166 | to be opened for both reading and writing on file descriptor | |
5167 | <I>n</I>, | |
5168 | ||
5169 | or on file descriptor 0 if | |
5170 | <I>n</I> | |
5171 | ||
5172 | is not specified. If the file does not exist, it is created. | |
5173 | <A NAME="lbBT"> </A> | |
5174 | <H3>ALIASES</H3> | |
5175 | ||
5176 | <I>Aliases</I> allow a string to be substituted for a word when it is used | |
5177 | as the first word of a simple command. | |
5178 | The shell maintains a list of aliases that may be set and unset with the | |
5179 | <B>alias</B> | |
5180 | ||
5181 | and | |
5182 | <B>unalias</B> | |
5183 | ||
5184 | builtin commands (see | |
5185 | <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B> | |
5186 | ||
5187 | </FONT> | |
5188 | below). | |
5189 | The first word of each simple command, if unquoted, | |
5190 | is checked to see if it has an | |
5191 | alias. If so, that word is replaced by the text of the alias. | |
5192 | The characters <B>/</B>, <B>$</B>, <B>`</B>, and <B>=</B> and | |
5193 | any of the shell <I>metacharacters</I> or quoting characters | |
5194 | listed above may not appear in an alias name. | |
5195 | The replacement text may contain any valid shell input, | |
5196 | including shell metacharacters. | |
5197 | The first word of the replacement text is tested | |
5198 | for aliases, but a word that is identical to an alias being expanded | |
5199 | is not expanded a second time. | |
5200 | This means that one may alias | |
5201 | <B>ls</B> | |
5202 | ||
5203 | to | |
5204 | <B>ls -F</B>, | |
5205 | ||
5206 | for instance, and | |
5207 | <B>bash</B> | |
5208 | ||
5209 | does not try to recursively expand the replacement text. | |
5210 | If the last character of the alias value is a | |
5211 | <I>blank</I>, | |
5212 | ||
5213 | then the next command | |
5214 | word following the alias is also checked for alias expansion. | |
5215 | <P> | |
5216 | ||
5217 | Aliases are created and listed with the | |
5218 | <B>alias</B> | |
5219 | ||
5220 | command, and removed with the | |
5221 | <B>unalias</B> | |
5222 | ||
5223 | command. | |
5224 | <P> | |
5225 | ||
5226 | There is no mechanism for using arguments in the replacement text. | |
5227 | If arguments are needed, a shell function should be used (see | |
5228 | <FONT SIZE=-1><B>FUNCTIONS</B> | |
5229 | ||
5230 | </FONT> | |
5231 | below). | |
5232 | <P> | |
5233 | ||
5234 | Aliases are not expanded when the shell is not interactive, unless | |
5235 | the | |
5236 | <B>expand_aliases</B> | |
5237 | ||
5238 | shell option is set using | |
5239 | <B>shopt</B> | |
5240 | ||
5241 | (see the description of | |
5242 | <B>shopt</B> | |
5243 | ||
5244 | under | |
5245 | <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B></FONT> | |
5246 | below). | |
5247 | <P> | |
5248 | ||
5249 | The rules concerning the definition and use of aliases are | |
5250 | somewhat confusing. | |
5251 | <B>Bash</B> | |
5252 | ||
5253 | always reads at least one complete line | |
5254 | of input before executing any | |
5255 | of the commands on that line. Aliases are expanded when a | |
5256 | command is read, not when it is executed. Therefore, an | |
5257 | alias definition appearing on the same line as another | |
5258 | command does not take effect until the next line of input is read. | |
5259 | The commands following the alias definition | |
5260 | on that line are not affected by the new alias. | |
5261 | This behavior is also an issue when functions are executed. | |
5262 | Aliases are expanded when a function definition is read, | |
5263 | not when the function is executed, because a function definition | |
a0c0a00f | 5264 | is itself a command. As a consequence, aliases |
17345e5a JA |
5265 | defined in a function are not available until after that |
5266 | function is executed. To be safe, always put | |
5267 | alias definitions on a separate line, and do not use | |
5268 | <B>alias</B> | |
5269 | ||
5270 | in compound commands. | |
5271 | <P> | |
5272 | ||
5273 | For almost every purpose, aliases are superseded by | |
5274 | shell functions. | |
5275 | <A NAME="lbBU"> </A> | |
5276 | <H3>FUNCTIONS</H3> | |
5277 | ||
5278 | A shell function, defined as described above under | |
5279 | <FONT SIZE=-1><B>SHELL GRAMMAR</B>, | |
5280 | ||
5281 | </FONT> | |
5282 | stores a series of commands for later execution. | |
5283 | When the name of a shell function is used as a simple command name, | |
5284 | the list of commands associated with that function name is executed. | |
5285 | Functions are executed in the context of the | |
5286 | current shell; no new process is created to interpret | |
5287 | them (contrast this with the execution of a shell script). | |
5288 | When a function is executed, the arguments to the | |
5289 | function become the positional parameters | |
5290 | during its execution. | |
5291 | The special parameter | |
5292 | <B>#</B> | |
5293 | ||
495aee44 | 5294 | is updated to reflect the change. Special parameter <B>0</B> |
17345e5a JA |
5295 | is unchanged. |
5296 | The first element of the | |
5297 | <FONT SIZE=-1><B>FUNCNAME</B> | |
5298 | ||
5299 | </FONT> | |
5300 | variable is set to the name of the function while the function | |
5301 | is executing. | |
0001803f CR |
5302 | <P> |
5303 | ||
17345e5a JA |
5304 | All other aspects of the shell execution |
5305 | environment are identical between a function and its caller | |
a0c0a00f | 5306 | with these exceptions: the |
17345e5a JA |
5307 | <FONT SIZE=-1><B>DEBUG</B> |
5308 | ||
5309 | </FONT> | |
5310 | and | |
5311 | <B>RETURN</B> | |
5312 | ||
5313 | traps (see the description of the | |
5314 | <B>trap</B> | |
5315 | ||
5316 | builtin under | |
5317 | <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B> | |
5318 | ||
5319 | </FONT> | |
5320 | below) are not inherited unless the function has been given the | |
5321 | <B>trace</B> attribute (see the description of the | |
5322 | <FONT SIZE=-1><B>declare</B> | |
5323 | ||
5324 | </FONT> | |
5325 | builtin below) or the | |
5326 | <B>-o functrace</B> shell option has been enabled with | |
5327 | the <B>set</B> builtin | |
0001803f CR |
5328 | (in which case all functions inherit the <B>DEBUG</B> and <B>RETURN</B> traps), |
5329 | and the | |
5330 | <FONT SIZE=-1><B>ERR</B> | |
5331 | ||
5332 | </FONT> | |
5333 | trap is not inherited unless the <B>-o errtrace</B> shell option has | |
5334 | been enabled. | |
17345e5a JA |
5335 | <P> |
5336 | ||
5337 | Variables local to the function may be declared with the | |
5338 | <B>local</B> | |
5339 | ||
5340 | builtin command. Ordinarily, variables and their values | |
5341 | are shared between the function and its caller. | |
5342 | <P> | |
5343 | ||
495aee44 CR |
5344 | The <B>FUNCNEST</B> variable, if set to a numeric value greater |
5345 | than 0, defines a maximum function nesting level. Function | |
5346 | invocations that exceed the limit cause the entire command to | |
5347 | abort. | |
5348 | <P> | |
5349 | ||
17345e5a JA |
5350 | If the builtin command |
5351 | <B>return</B> | |
5352 | ||
5353 | is executed in a function, the function completes and | |
5354 | execution resumes with the next command after the function | |
5355 | call. | |
5356 | Any command associated with the <B>RETURN</B> trap is executed | |
5357 | before execution resumes. | |
5358 | When a function completes, the values of the | |
5359 | positional parameters and the special parameter | |
5360 | <B>#</B> | |
5361 | ||
5362 | are restored to the values they had prior to the function's | |
5363 | execution. | |
5364 | <P> | |
5365 | ||
5366 | Function names and definitions may be listed with the | |
5367 | <B>-f</B> | |
5368 | ||
5369 | option to the | |
5370 | <B>declare</B> | |
5371 | ||
5372 | or | |
5373 | <B>typeset</B> | |
5374 | ||
5375 | builtin commands. The | |
5376 | <B>-F</B> | |
5377 | ||
5378 | option to | |
5379 | <B>declare</B> | |
5380 | ||
5381 | or | |
5382 | <B>typeset</B> | |
5383 | ||
5384 | will list the function names only | |
5385 | (and optionally the source file and line number, if the <B>extdebug</B> | |
5386 | shell option is enabled). | |
5387 | Functions may be exported so that subshells | |
5388 | automatically have them defined with the | |
5389 | <B>-f</B> | |
5390 | ||
5391 | option to the | |
5392 | <B>export</B> | |
5393 | ||
5394 | builtin. | |
5395 | A function definition may be deleted using the <B>-f</B> option to | |
5396 | the | |
5397 | <B>unset</B> | |
5398 | ||
5399 | builtin. | |
5400 | Note that shell functions and variables with the same name may result | |
5401 | in multiple identically-named entries in the environment passed to the | |
5402 | shell's children. | |
5403 | Care should be taken in cases where this may cause a problem. | |
5404 | <P> | |
5405 | ||
495aee44 CR |
5406 | Functions may be recursive. |
5407 | The <B>FUNCNEST</B> variable may be used to limit the depth of the | |
5408 | function call stack and restrict the number of function invocations. | |
5409 | By default, no limit is imposed on the number of recursive calls. | |
17345e5a JA |
5410 | <A NAME="lbBV"> </A> |
5411 | <H3>ARITHMETIC EVALUATION</H3> | |
5412 | ||
5413 | The shell allows arithmetic expressions to be evaluated, under | |
5414 | certain circumstances (see the <B>let</B> and <B>declare</B> builtin | |
a0c0a00f | 5415 | commands, the <B>((</B> compound command, and <B>Arithmetic Expansion</B>). |
17345e5a JA |
5416 | Evaluation is done in fixed-width integers with no check for overflow, |
5417 | though division by 0 is trapped and flagged as an error. | |
5418 | The operators and their precedence, associativity, and values | |
5419 | are the same as in the C language. | |
5420 | The following list of operators is grouped into levels of | |
5421 | equal-precedence operators. | |
5422 | The levels are listed in order of decreasing precedence. | |
5423 | <P> | |
5424 | ||
5425 | ||
5426 | <DL COMPACT> | |
5427 | <DT><B></B><I>id</I>++ <I>id</I>-- | |
5428 | ||
5429 | <DD> | |
5430 | variable post-increment and post-decrement | |
5431 | <DT><B>++</B><I>id</I> --<I>id</I> | |
5432 | ||
5433 | <DD> | |
5434 | variable pre-increment and pre-decrement | |
5435 | <DT><B>- +</B> | |
5436 | ||
5437 | <DD> | |
5438 | unary minus and plus | |
5439 | <DT><B>! ~</B> | |
5440 | ||
5441 | <DD> | |
5442 | logical and bitwise negation | |
5443 | <DT><B>**</B> | |
5444 | ||
5445 | <DD> | |
5446 | exponentiation | |
5447 | <DT><B>* / %</B> | |
5448 | ||
5449 | <DD> | |
5450 | multiplication, division, remainder | |
5451 | <DT><B>+ -</B> | |
5452 | ||
5453 | <DD> | |
5454 | addition, subtraction | |
5455 | <DT><B><< >></B> | |
5456 | ||
5457 | <DD> | |
5458 | left and right bitwise shifts | |
5459 | <DT><B><= >= < ></B> | |
5460 | ||
5461 | <DD> | |
5462 | comparison | |
5463 | <DT><B>== !=</B> | |
5464 | ||
5465 | <DD> | |
5466 | equality and inequality | |
5467 | <DT><B>&</B> | |
5468 | ||
5469 | <DD> | |
5470 | bitwise AND | |
5471 | <DT><B>^</B> | |
5472 | ||
5473 | <DD> | |
5474 | bitwise exclusive OR | |
5475 | <DT><B>|</B> | |
5476 | ||
5477 | <DD> | |
5478 | bitwise OR | |
5479 | <DT><B>&&</B> | |
5480 | ||
5481 | <DD> | |
5482 | logical AND | |
5483 | <DT><B>||</B> | |
5484 | ||
5485 | <DD> | |
5486 | logical OR | |
5487 | <DT><B></B><I>expr</I>?<I>expr</I>:<I>expr</I> | |
5488 | ||
5489 | <DD> | |
5490 | conditional operator | |
5491 | <DT><B>= *= /= %= += -= <<= >>= &= ^= |=</B> | |
5492 | ||
5493 | <DD> | |
5494 | assignment | |
5495 | <DT><B></B><I>expr1</I> , <I>expr2</I> | |
5496 | ||
5497 | <DD> | |
5498 | comma | |
5499 | ||
5500 | </DL> | |
5501 | <P> | |
5502 | ||
5503 | Shell variables are allowed as operands; parameter expansion is | |
5504 | performed before the expression is evaluated. | |
5505 | Within an expression, shell variables may also be referenced by name | |
5506 | without using the parameter expansion syntax. | |
5507 | A shell variable that is null or unset evaluates to 0 when referenced | |
5508 | by name without using the parameter expansion syntax. | |
5509 | The value of a variable is evaluated as an arithmetic expression | |
5510 | when it is referenced, or when a variable which has been given the | |
5511 | <I>integer</I> attribute using <B>declare -i</B> is assigned a value. | |
5512 | A null value evaluates to 0. | |
495aee44 | 5513 | A shell variable need not have its <I>integer</I> attribute |
17345e5a JA |
5514 | turned on to be used in an expression. |
5515 | <P> | |
5516 | ||
5517 | Constants with a leading 0 are interpreted as octal numbers. | |
5518 | A leading 0x or 0X denotes hexadecimal. | |
495aee44 | 5519 | Otherwise, numbers take the form [<I>base#</I>]n, where the optional <I>base</I> |
17345e5a JA |
5520 | is a decimal number between 2 and 64 representing the arithmetic |
5521 | base, and <I>n</I> is a number in that base. | |
5522 | If <I>base#</I> is omitted, then base 10 is used. | |
ac50fbac | 5523 | When specifying <I>n</I>, |
a0c0a00f | 5524 | the digits greater than 9 are represented by the lowercase letters, |
17345e5a JA |
5525 | the uppercase letters, @, and _, in that order. |
5526 | If <I>base</I> is less than or equal to 36, lowercase and uppercase | |
5527 | letters may be used interchangeably to represent numbers between 10 | |
5528 | and 35. | |
5529 | <P> | |
5530 | ||
5531 | Operators are evaluated in order of precedence. Sub-expressions in | |
5532 | parentheses are evaluated first and may override the precedence | |
5533 | rules above. | |
5534 | <A NAME="lbBW"> </A> | |
5535 | <H3>CONDITIONAL EXPRESSIONS</H3> | |
5536 | ||
5537 | Conditional expressions are used by the <B>[[</B> compound command and | |
5538 | the <B>test</B> and <B>[</B> builtin commands to test file attributes | |
5539 | and perform string and arithmetic comparisons. | |
5540 | Expressions are formed from the following unary or binary primaries. | |
a0c0a00f CR |
5541 | <B>Bash</B> handles several filenames specially when they are used in |
5542 | expressions. | |
5543 | If the operating system on which <B>bash</B> is running provides these | |
5544 | special files, bash will use them; otherwise it will emulate them | |
5545 | internally with this behavior: | |
17345e5a JA |
5546 | If any <I>file</I> argument to one of the primaries is of the form |
5547 | <I>/dev/fd/n</I>, then file descriptor <I>n</I> is checked. | |
5548 | If the <I>file</I> argument to one of the primaries is one of | |
5549 | <I>/dev/stdin</I>, <I>/dev/stdout</I>, or <I>/dev/stderr</I>, file | |
5550 | descriptor 0, 1, or 2, respectively, is checked. | |
5551 | <P> | |
5552 | ||
5553 | Unless otherwise specified, primaries that operate on files follow symbolic | |
5554 | links and operate on the target of the link, rather than the link itself. | |
5555 | <P> | |
5556 | ||
0001803f | 5557 | |
495aee44 | 5558 | When used with <B>[[</B>, the <B><</B> and <B>></B> operators sort |
0001803f | 5559 | lexicographically using the current locale. |
495aee44 | 5560 | The <B>test</B> command sorts using ASCII ordering. |
0001803f CR |
5561 | <P> |
5562 | ||
17345e5a JA |
5563 | <DL COMPACT> |
5564 | <DT><B>-a </B><I>file</I> | |
5565 | ||
5566 | <DD> | |
5567 | True if <I>file</I> exists. | |
5568 | <DT><B>-b </B><I>file</I> | |
5569 | ||
5570 | <DD> | |
5571 | True if <I>file</I> exists and is a block special file. | |
5572 | <DT><B>-c </B><I>file</I> | |
5573 | ||
5574 | <DD> | |
5575 | True if <I>file</I> exists and is a character special file. | |
5576 | <DT><B>-d </B><I>file</I> | |
5577 | ||
5578 | <DD> | |
5579 | True if <I>file</I> exists and is a directory. | |
5580 | <DT><B>-e </B><I>file</I> | |
5581 | ||
5582 | <DD> | |
5583 | True if <I>file</I> exists. | |
5584 | <DT><B>-f </B><I>file</I> | |
5585 | ||
5586 | <DD> | |
5587 | True if <I>file</I> exists and is a regular file. | |
5588 | <DT><B>-g </B><I>file</I> | |
5589 | ||
5590 | <DD> | |
5591 | True if <I>file</I> exists and is set-group-id. | |
5592 | <DT><B>-h </B><I>file</I> | |
5593 | ||
5594 | <DD> | |
5595 | True if <I>file</I> exists and is a symbolic link. | |
5596 | <DT><B>-k </B><I>file</I> | |
5597 | ||
5598 | <DD> | |
5599 | True if <I>file</I> exists and its ``sticky'' bit is set. | |
5600 | <DT><B>-p </B><I>file</I> | |
5601 | ||
5602 | <DD> | |
5603 | True if <I>file</I> exists and is a named pipe (FIFO). | |
5604 | <DT><B>-r </B><I>file</I> | |
5605 | ||
5606 | <DD> | |
5607 | True if <I>file</I> exists and is readable. | |
5608 | <DT><B>-s </B><I>file</I> | |
5609 | ||
5610 | <DD> | |
5611 | True if <I>file</I> exists and has a size greater than zero. | |
5612 | <DT><B>-t </B><I>fd</I> | |
5613 | ||
5614 | <DD> | |
5615 | True if file descriptor | |
5616 | <I>fd</I> | |
5617 | ||
5618 | is open and refers to a terminal. | |
5619 | <DT><B>-u </B><I>file</I> | |
5620 | ||
5621 | <DD> | |
5622 | True if <I>file</I> exists and its set-user-id bit is set. | |
5623 | <DT><B>-w </B><I>file</I> | |
5624 | ||
5625 | <DD> | |
5626 | True if <I>file</I> exists and is writable. | |
5627 | <DT><B>-x </B><I>file</I> | |
5628 | ||
5629 | <DD> | |
5630 | True if <I>file</I> exists and is executable. | |
17345e5a JA |
5631 | <DT><B>-G </B><I>file</I> |
5632 | ||
5633 | <DD> | |
5634 | True if <I>file</I> exists and is owned by the effective group id. | |
5635 | <DT><B>-L </B><I>file</I> | |
5636 | ||
5637 | <DD> | |
5638 | True if <I>file</I> exists and is a symbolic link. | |
17345e5a JA |
5639 | <DT><B>-N </B><I>file</I> |
5640 | ||
5641 | <DD> | |
5642 | True if <I>file</I> exists and has been modified since it was last read. | |
495aee44 CR |
5643 | <DT><B>-O </B><I>file</I> |
5644 | ||
5645 | <DD> | |
5646 | True if <I>file</I> exists and is owned by the effective user id. | |
5647 | <DT><B>-S </B><I>file</I> | |
5648 | ||
5649 | <DD> | |
5650 | True if <I>file</I> exists and is a socket. | |
5651 | <DT><I>file1</I> <B>-ef</B> <I>file2</I><DD> | |
5652 | True if <I>file1</I> and <I>file2</I> refer to the same device and | |
5653 | inode numbers. | |
17345e5a JA |
5654 | <DT><I>file1</I> -<B>nt</B> <I>file2</I><DD> |
5655 | True if <I>file1</I> is newer (according to modification date) than <I>file2</I>, | |
5656 | or if <I>file1</I> exists and file2 does not. | |
5657 | <DT><I>file1</I> -<B>ot</B> <I>file2</I><DD> | |
5658 | True if <I>file1</I> is older than <I>file2</I>, or if <I>file2</I> exists | |
5659 | and <I>file1</I> does not. | |
17345e5a JA |
5660 | <DT><B>-o </B><I>optname</I> |
5661 | ||
5662 | <DD> | |
495aee44 | 5663 | True if the shell option |
17345e5a JA |
5664 | <I>optname</I> |
5665 | ||
5666 | is enabled. | |
5667 | See the list of options under the description of the | |
5668 | <B>-o</B> | |
5669 | ||
5670 | option to the | |
5671 | <B>set</B> | |
5672 | ||
5673 | builtin below. | |
495aee44 CR |
5674 | <DT><B>-v </B><I>varname</I> |
5675 | ||
5676 | <DD> | |
5677 | True if the shell variable | |
5678 | <I>varname</I> | |
5679 | ||
5680 | is set (has been assigned a value). | |
ac50fbac CR |
5681 | <DT><B>-R </B><I>varname</I> |
5682 | ||
5683 | <DD> | |
5684 | True if the shell variable | |
5685 | <I>varname</I> | |
5686 | ||
5687 | is set and is a name reference. | |
17345e5a JA |
5688 | <DT><B>-z </B><I>string</I> |
5689 | ||
5690 | <DD> | |
5691 | True if the length of <I>string</I> is zero. | |
5692 | <DT><I>string</I><DD> | |
5693 | ||
5694 | <DT><B>-n </B><I>string</I> | |
5695 | ||
5696 | <DD> | |
5697 | ||
5698 | True if the length of | |
5699 | <I>string</I> | |
5700 | ||
5701 | is non-zero. | |
5702 | <DT><I>string1</I> <B>==</B> <I>string2</I><DD> | |
0001803f CR |
5703 | |
5704 | <DT><I>string1</I> <B>=</B> <I>string2</I><DD> | |
5705 | ||
5706 | True if the strings are equal. <B>=</B> should be used | |
5707 | with the <B>test</B> command for POSIX conformance. | |
ac50fbac CR |
5708 | When used with the <B>[[</B> command, this performs pattern matching as |
5709 | described above (<B>Compound Commands</B>). | |
17345e5a JA |
5710 | <DT><I>string1</I> <B>!=</B> <I>string2</I><DD> |
5711 | True if the strings are not equal. | |
5712 | <DT><I>string1</I> <B><</B> <I>string2</I><DD> | |
0001803f | 5713 | True if <I>string1</I> sorts before <I>string2</I> lexicographically. |
17345e5a | 5714 | <DT><I>string1</I> <B>></B> <I>string2</I><DD> |
0001803f | 5715 | True if <I>string1</I> sorts after <I>string2</I> lexicographically. |
17345e5a JA |
5716 | <DT><I>arg1</I> <B>OP</B> <I>arg2</I> |
5717 | ||
5718 | <DD> | |
5719 | <FONT SIZE=-1><B>OP</B> | |
5720 | ||
5721 | </FONT> | |
5722 | is one of | |
5723 | <B>-eq</B>, | |
5724 | ||
5725 | <B>-ne</B>, | |
5726 | ||
5727 | <B>-lt</B>, | |
5728 | ||
5729 | <B>-le</B>, | |
5730 | ||
5731 | <B>-gt</B>, | |
5732 | ||
5733 | or | |
5734 | <B>-ge</B>. | |
5735 | ||
5736 | These arithmetic binary operators return true if <I>arg1</I> | |
5737 | is equal to, not equal to, less than, less than or equal to, | |
5738 | greater than, or greater than or equal to <I>arg2</I>, respectively. | |
5739 | <I>Arg1</I> | |
5740 | ||
5741 | and | |
5742 | <I>arg2</I> | |
5743 | ||
5744 | may be positive or negative integers. | |
5745 | ||
5746 | </DL> | |
5747 | <A NAME="lbBX"> </A> | |
5748 | <H3>SIMPLE COMMAND EXPANSION</H3> | |
5749 | ||
5750 | When a simple command is executed, the shell performs the following | |
5751 | expansions, assignments, and redirections, from left to right. | |
5752 | <DL COMPACT> | |
5753 | <DT>1.<DD> | |
5754 | The words that the parser has marked as variable assignments (those | |
5755 | preceding the command name) and redirections are saved for later | |
5756 | processing. | |
5757 | <DT>2.<DD> | |
5758 | The words that are not variable assignments or redirections are | |
5759 | expanded. If any words remain after expansion, the first word | |
5760 | is taken to be the name of the command and the remaining words are | |
5761 | the arguments. | |
5762 | <DT>3.<DD> | |
5763 | Redirections are performed as described above under | |
5764 | <FONT SIZE=-1><B>REDIRECTION</B>. | |
5765 | ||
5766 | </FONT> | |
5767 | <DT>4.<DD> | |
5768 | The text after the <B>=</B> in each variable assignment undergoes tilde | |
5769 | expansion, parameter expansion, command substitution, arithmetic expansion, | |
5770 | and quote removal before being assigned to the variable. | |
5771 | </DL> | |
5772 | <P> | |
5773 | ||
5774 | If no command name results, the variable assignments affect the current | |
5775 | shell environment. Otherwise, the variables are added to the environment | |
5776 | of the executed command and do not affect the current shell environment. | |
5777 | If any of the assignments attempts to assign a value to a readonly variable, | |
5778 | an error occurs, and the command exits with a non-zero status. | |
5779 | <P> | |
5780 | ||
5781 | If no command name results, redirections are performed, but do not | |
5782 | affect the current shell environment. A redirection error causes the | |
5783 | command to exit with a non-zero status. | |
5784 | <P> | |
5785 | ||
5786 | If there is a command name left after expansion, execution proceeds as | |
5787 | described below. Otherwise, the command exits. If one of the expansions | |
5788 | contained a command substitution, the exit status of the command is | |
5789 | the exit status of the last command substitution performed. If there | |
5790 | were no command substitutions, the command exits with a status of zero. | |
5791 | <A NAME="lbBY"> </A> | |
5792 | <H3>COMMAND EXECUTION</H3> | |
5793 | ||
5794 | After a command has been split into words, if it results in a | |
5795 | simple command and an optional list of arguments, the following | |
5796 | actions are taken. | |
5797 | <P> | |
5798 | ||
5799 | If the command name contains no slashes, the shell attempts to | |
5800 | locate it. If there exists a shell function by that name, that | |
5801 | function is invoked as described above in | |
5802 | <FONT SIZE=-1><B>FUNCTIONS</B>. | |
5803 | ||
5804 | </FONT> | |
5805 | If the name does not match a function, the shell searches for | |
5806 | it in the list of shell builtins. If a match is found, that | |
5807 | builtin is invoked. | |
5808 | <P> | |
5809 | ||
5810 | If the name is neither a shell function nor a builtin, | |
5811 | and contains no slashes, | |
5812 | <B>bash</B> | |
5813 | ||
5814 | searches each element of the | |
5815 | <FONT SIZE=-1><B>PATH</B> | |
5816 | ||
5817 | </FONT> | |
5818 | for a directory containing an executable file by that name. | |
5819 | <B>Bash</B> | |
5820 | ||
5821 | uses a hash table to remember the full pathnames of executable | |
5822 | files (see | |
5823 | <B>hash</B> | |
5824 | ||
5825 | under | |
5826 | <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B> | |
5827 | ||
5828 | </FONT> | |
5829 | below). | |
5830 | A full search of the directories in | |
5831 | <FONT SIZE=-1><B>PATH</B> | |
5832 | ||
5833 | </FONT> | |
5834 | is performed only if the command is not found in the hash table. | |
5835 | If the search is unsuccessful, the shell searches for a defined shell | |
5836 | function named <B>command_not_found_handle</B>. | |
5837 | If that function exists, it is invoked with the original command and | |
5838 | the original command's arguments as its arguments, and the function's | |
5839 | exit status becomes the exit status of the shell. | |
5840 | If that function is not defined, the shell prints an error | |
5841 | message and returns an exit status of 127. | |
5842 | <P> | |
5843 | ||
5844 | If the search is successful, or if the command name contains | |
5845 | one or more slashes, the shell executes the named program in a | |
5846 | separate execution environment. | |
5847 | Argument 0 is set to the name given, and the remaining arguments | |
5848 | to the command are set to the arguments given, if any. | |
5849 | <P> | |
5850 | ||
5851 | If this execution fails because the file is not in executable | |
5852 | format, and the file is not a directory, it is assumed to be | |
5853 | a <I>shell script</I>, a file | |
5854 | containing shell commands. A subshell is spawned to execute | |
5855 | it. This subshell reinitializes itself, so | |
5856 | that the effect is as if a new shell had been invoked | |
5857 | to handle the script, with the exception that the locations of | |
5858 | commands remembered by the parent (see | |
5859 | <B>hash</B> | |
5860 | ||
5861 | below under | |
5862 | <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>)</FONT> | |
5863 | are retained by the child. | |
5864 | <P> | |
5865 | ||
5866 | If the program is a file beginning with | |
5867 | <B>#!</B>, | |
5868 | ||
5869 | the remainder of the first line specifies an interpreter | |
5870 | for the program. The shell executes the | |
5871 | specified interpreter on operating systems that do not | |
a0c0a00f | 5872 | handle this executable format themselves. The arguments to the |
17345e5a JA |
5873 | interpreter consist of a single optional argument following the |
5874 | interpreter name on the first line of the program, followed | |
5875 | by the name of the program, followed by the command | |
5876 | arguments, if any. | |
5877 | <A NAME="lbBZ"> </A> | |
5878 | <H3>COMMAND EXECUTION ENVIRONMENT</H3> | |
5879 | ||
5880 | The shell has an <I>execution environment</I>, which consists of the | |
5881 | following: | |
17345e5a JA |
5882 | <DL COMPACT> |
5883 | <DT>*<DD> | |
5884 | open files inherited by the shell at invocation, as modified by | |
5885 | redirections supplied to the <B>exec</B> builtin | |
5886 | <DT>*<DD> | |
5887 | the current working directory as set by <B>cd</B>, <B>pushd</B>, or | |
5888 | <B>popd</B>, or inherited by the shell at invocation | |
5889 | <DT>*<DD> | |
5890 | the file creation mode mask as set by <B>umask</B> or inherited from | |
5891 | the shell's parent | |
5892 | <DT>*<DD> | |
5893 | current traps set by <B>trap</B> | |
5894 | <DT>*<DD> | |
5895 | shell parameters that are set by variable assignment or with <B>set</B> | |
5896 | or inherited from the shell's parent in the environment | |
5897 | <DT>*<DD> | |
5898 | shell functions defined during execution or inherited from the shell's | |
5899 | parent in the environment | |
5900 | <DT>*<DD> | |
5901 | options enabled at invocation (either by default or with command-line | |
5902 | arguments) or by <B>set</B> | |
5903 | <DT>*<DD> | |
5904 | options enabled by <B>shopt</B> | |
5905 | <DT>*<DD> | |
5906 | shell aliases defined with <B>alias</B> | |
5907 | <DT>*<DD> | |
5908 | various process IDs, including those of background jobs, the value | |
0001803f CR |
5909 | of <B>$$</B>, and the value of |
5910 | <FONT SIZE=-1><B>PPID</B> | |
5911 | ||
5912 | </FONT> | |
17345e5a JA |
5913 | </DL> |
5914 | <P> | |
5915 | ||
5916 | When a simple command other than a builtin or shell function | |
5917 | is to be executed, it | |
5918 | is invoked in a separate execution environment that consists of | |
5919 | the following. Unless otherwise noted, the values are inherited | |
5920 | from the shell. | |
0001803f | 5921 | |
17345e5a JA |
5922 | <DL COMPACT> |
5923 | <DT>*<DD> | |
5924 | the shell's open files, plus any modifications and additions specified | |
5925 | by redirections to the command | |
5926 | <DT>*<DD> | |
5927 | the current working directory | |
5928 | <DT>*<DD> | |
5929 | the file creation mode mask | |
5930 | <DT>*<DD> | |
5931 | shell variables and functions marked for export, along with variables | |
5932 | exported for the command, passed in the environment | |
5933 | <DT>*<DD> | |
5934 | traps caught by the shell are reset to the values inherited from the | |
5935 | shell's parent, and traps ignored by the shell are ignored | |
5936 | </DL> | |
5937 | <P> | |
5938 | ||
5939 | A command invoked in this separate environment cannot affect the | |
a0c0a00f | 5940 | shell's execution environment. |
17345e5a JA |
5941 | <P> |
5942 | ||
5943 | Command substitution, commands grouped with parentheses, | |
5944 | and asynchronous commands are invoked in a | |
5945 | subshell environment that is a duplicate of the shell environment, | |
5946 | except that traps caught by the shell are reset to the values | |
5947 | that the shell inherited from its parent at invocation. Builtin | |
5948 | commands that are invoked as part of a pipeline are also executed in a | |
5949 | subshell environment. Changes made to the subshell environment | |
5950 | cannot affect the shell's execution environment. | |
5951 | <P> | |
5952 | ||
5953 | Subshells spawned to execute command substitutions inherit the value of | |
495aee44 CR |
5954 | the <B>-e</B> option from the parent shell. When not in <I>posix</I> mode, |
5955 | <B>bash</B> clears the <B>-e</B> option in such subshells. | |
17345e5a JA |
5956 | <P> |
5957 | ||
5958 | If a command is followed by a <B>&</B> and job control is not active, the | |
5959 | default standard input for the command is the empty file <I>/dev/null</I>. | |
5960 | Otherwise, the invoked command inherits the file descriptors of the calling | |
5961 | shell as modified by redirections. | |
5962 | <A NAME="lbCA"> </A> | |
5963 | <H3>ENVIRONMENT</H3> | |
5964 | ||
5965 | When a program is invoked it is given an array of strings | |
5966 | called the | |
5967 | <I>environment</I>. | |
5968 | ||
a0c0a00f | 5969 | This is a list of |
17345e5a JA |
5970 | <I>name</I>-<I>value</I> pairs, of the form |
5971 | <I>name</I>=value. | |
5972 | ||
5973 | <P> | |
5974 | ||
5975 | The shell provides several ways to manipulate the environment. | |
5976 | On invocation, the shell scans its own environment and | |
5977 | creates a parameter for each name found, automatically marking | |
5978 | it for | |
5979 | <I>export</I> | |
5980 | ||
5981 | to child processes. Executed commands inherit the environment. | |
5982 | The | |
5983 | <B>export</B> | |
5984 | ||
5985 | and | |
5986 | <B>declare -x</B> | |
5987 | ||
5988 | commands allow parameters and functions to be added to and | |
5989 | deleted from the environment. If the value of a parameter | |
5990 | in the environment is modified, the new value becomes part | |
5991 | of the environment, replacing the old. The environment | |
5992 | inherited by any executed command consists of the shell's | |
5993 | initial environment, whose values may be modified in the shell, | |
5994 | less any pairs removed by the | |
5995 | <B>unset</B> | |
5996 | ||
5997 | command, plus any additions via the | |
5998 | <B>export</B> | |
5999 | ||
6000 | and | |
6001 | <B>declare -x</B> | |
6002 | ||
6003 | commands. | |
6004 | <P> | |
6005 | ||
6006 | The environment for any | |
6007 | <I>simple command</I> | |
6008 | ||
6009 | or function may be augmented temporarily by prefixing it with | |
6010 | parameter assignments, as described above in | |
6011 | <FONT SIZE=-1><B>PARAMETERS</B>. | |
6012 | ||
6013 | </FONT> | |
6014 | These assignment statements affect only the environment seen | |
6015 | by that command. | |
6016 | <P> | |
6017 | ||
a0c0a00f | 6018 | If the |
17345e5a JA |
6019 | <B>-k</B> |
6020 | ||
6021 | option is set (see the | |
6022 | <B>set</B> | |
6023 | ||
6024 | builtin command below), then | |
6025 | <I>all</I> | |
6026 | ||
6027 | parameter assignments are placed in the environment for a command, | |
6028 | not just those that precede the command name. | |
6029 | <P> | |
6030 | ||
6031 | When | |
6032 | <B>bash</B> | |
6033 | ||
6034 | invokes an external command, the variable | |
6035 | <B>_</B> | |
6036 | ||
ac50fbac | 6037 | is set to the full filename of the command and passed to that |
17345e5a JA |
6038 | command in its environment. |
6039 | <A NAME="lbCB"> </A> | |
6040 | <H3>EXIT STATUS</H3> | |
6041 | ||
6042 | <P> | |
6043 | ||
6044 | The exit status of an executed command is the value returned by the | |
6045 | <I>waitpid</I> system call or equivalent function. Exit statuses | |
6046 | fall between 0 and 255, though, as explained below, the shell may | |
6047 | use values above 125 specially. Exit statuses from shell builtins and | |
a0c0a00f | 6048 | compound commands are also limited to this range. Under certain |
17345e5a JA |
6049 | circumstances, the shell will use special values to indicate specific |
6050 | failure modes. | |
6051 | <P> | |
6052 | ||
a0c0a00f | 6053 | For the shell's purposes, a command which exits with a |
17345e5a JA |
6054 | zero exit status has succeeded. An exit status of zero |
6055 | indicates success. A non-zero exit status indicates failure. | |
6056 | When a command terminates on a fatal signal <I>N</I>, <B>bash</B> uses | |
6057 | the value of 128+<I>N</I> as the exit status. | |
6058 | <P> | |
6059 | ||
6060 | If a command is not found, the child process created to | |
6061 | execute it returns a status of 127. If a command is found | |
6062 | but is not executable, the return status is 126. | |
6063 | <P> | |
6064 | ||
6065 | If a command fails because of an error during expansion or redirection, | |
6066 | the exit status is greater than zero. | |
6067 | <P> | |
6068 | ||
6069 | Shell builtin commands return a status of 0 (<I>true</I>) if | |
6070 | successful, and non-zero (<I>false</I>) if an error occurs | |
a0c0a00f CR |
6071 | while they execute. |
6072 | All builtins return an exit status of 2 to indicate incorrect usage, | |
6073 | generally invalid options or missing arguments. | |
17345e5a JA |
6074 | <P> |
6075 | ||
6076 | <B>Bash</B> itself returns the exit status of the last command | |
6077 | executed, unless a syntax error occurs, in which case it exits | |
6078 | with a non-zero value. See also the <B>exit</B> builtin | |
6079 | command below. | |
6080 | <A NAME="lbCC"> </A> | |
6081 | <H3>SIGNALS</H3> | |
6082 | ||
6083 | When <B>bash</B> is interactive, in the absence of any traps, it ignores | |
6084 | <FONT SIZE=-1><B>SIGTERM</B> | |
6085 | ||
6086 | </FONT> | |
6087 | (so that <B>kill 0</B> does not kill an interactive shell), | |
6088 | and | |
6089 | <FONT SIZE=-1><B>SIGINT</B> | |
6090 | ||
6091 | </FONT> | |
6092 | is caught and handled (so that the <B>wait</B> builtin is interruptible). | |
6093 | In all cases, <B>bash</B> ignores | |
6094 | <FONT SIZE=-1><B>SIGQUIT</B>. | |
6095 | ||
6096 | </FONT> | |
6097 | If job control is in effect, | |
6098 | <B>bash</B> | |
6099 | ||
6100 | ignores | |
6101 | <FONT SIZE=-1><B>SIGTTIN</B>, | |
6102 | ||
6103 | </FONT> | |
6104 | <FONT SIZE=-1><B>SIGTTOU</B>, | |
6105 | ||
6106 | </FONT> | |
6107 | and | |
6108 | <FONT SIZE=-1><B>SIGTSTP</B>. | |
6109 | ||
6110 | </FONT> | |
6111 | <P> | |
6112 | ||
6113 | Non-builtin commands run by <B>bash</B> have signal handlers | |
6114 | set to the values inherited by the shell from its parent. | |
6115 | When job control is not in effect, asynchronous commands | |
6116 | ignore | |
6117 | <FONT SIZE=-1><B>SIGINT</B> | |
6118 | ||
6119 | </FONT> | |
6120 | and | |
6121 | <FONT SIZE=-1><B>SIGQUIT</B> | |
6122 | ||
6123 | </FONT> | |
6124 | in addition to these inherited handlers. | |
6125 | Commands run as a result of command substitution ignore the | |
6126 | keyboard-generated job control signals | |
6127 | <FONT SIZE=-1><B>SIGTTIN</B>, | |
6128 | ||
6129 | </FONT> | |
6130 | <FONT SIZE=-1><B>SIGTTOU</B>, | |
6131 | ||
6132 | </FONT> | |
6133 | and | |
6134 | <FONT SIZE=-1><B>SIGTSTP</B>. | |
6135 | ||
6136 | </FONT> | |
6137 | <P> | |
6138 | ||
6139 | The shell exits by default upon receipt of a | |
6140 | <FONT SIZE=-1><B>SIGHUP</B>. | |
6141 | ||
6142 | </FONT> | |
6143 | Before exiting, an interactive shell resends the | |
6144 | <FONT SIZE=-1><B>SIGHUP</B> | |
6145 | ||
6146 | </FONT> | |
6147 | to all jobs, running or stopped. | |
6148 | Stopped jobs are sent | |
6149 | <FONT SIZE=-1><B>SIGCONT</B> | |
6150 | ||
6151 | </FONT> | |
6152 | to ensure that they receive the | |
6153 | <FONT SIZE=-1><B>SIGHUP</B>. | |
6154 | ||
6155 | </FONT> | |
6156 | To prevent the shell from | |
6157 | sending the signal to a particular job, it should be removed from the | |
a0c0a00f | 6158 | jobs table with the |
17345e5a JA |
6159 | <B>disown</B> |
6160 | ||
6161 | builtin (see | |
6162 | <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B> | |
6163 | ||
6164 | </FONT> | |
a0c0a00f | 6165 | below) or marked |
17345e5a JA |
6166 | to not receive |
6167 | <FONT SIZE=-1><B>SIGHUP</B> | |
6168 | ||
6169 | </FONT> | |
6170 | using | |
6171 | <B>disown -h</B>. | |
6172 | ||
6173 | <P> | |
6174 | ||
6175 | If the | |
6176 | <B>huponexit</B> | |
6177 | ||
6178 | shell option has been set with | |
6179 | <B>shopt</B>, | |
6180 | ||
6181 | <B>bash</B> | |
6182 | ||
a0c0a00f | 6183 | sends a |
17345e5a JA |
6184 | <FONT SIZE=-1><B>SIGHUP</B> |
6185 | ||
6186 | </FONT> | |
6187 | to all jobs when an interactive login shell exits. | |
6188 | <P> | |
6189 | ||
6190 | If <B>bash</B> is waiting for a command to complete and receives a signal | |
6191 | for which a trap has been set, the trap will not be executed until | |
a0c0a00f | 6192 | the command completes. |
17345e5a JA |
6193 | When <B>bash</B> is waiting for an asynchronous command via the <B>wait</B> |
6194 | builtin, the reception of a signal for which a trap has been set will | |
6195 | cause the <B>wait</B> builtin to return immediately with an exit status | |
6196 | greater than 128, immediately after which the trap is executed. | |
6197 | <A NAME="lbCD"> </A> | |
6198 | <H3>JOB CONTROL</H3> | |
6199 | ||
6200 | <I>Job control</I> | |
6201 | ||
6202 | refers to the ability to selectively stop (<I>suspend</I>) | |
6203 | the execution of processes and continue (<I>resume</I>) | |
6204 | their execution at a later point. A user typically employs | |
6205 | this facility via an interactive interface supplied jointly | |
0001803f | 6206 | by the operating system kernel's terminal driver and |
17345e5a JA |
6207 | <B>bash</B>. |
6208 | ||
6209 | <P> | |
6210 | ||
6211 | The shell associates a | |
6212 | <I>job</I> | |
6213 | ||
6214 | with each pipeline. It keeps a table of currently executing | |
6215 | jobs, which may be listed with the | |
6216 | <B>jobs</B> | |
6217 | ||
6218 | command. When | |
6219 | <B>bash</B> | |
6220 | ||
6221 | starts a job asynchronously (in the | |
6222 | <I>background</I>), | |
6223 | ||
6224 | it prints a line that looks like: | |
6225 | <DL COMPACT><DT><DD> | |
6226 | <P> | |
6227 | ||
6228 | [1] 25647 | |
6229 | </DL> | |
6230 | ||
6231 | <P> | |
6232 | ||
6233 | indicating that this job is job number 1 and that the process ID | |
6234 | of the last process in the pipeline associated with this job is 25647. | |
6235 | All of the processes in a single pipeline are members of the same job. | |
6236 | <B>Bash</B> | |
6237 | ||
6238 | uses the | |
6239 | <I>job</I> | |
6240 | ||
6241 | abstraction as the basis for job control. | |
6242 | <P> | |
6243 | ||
6244 | To facilitate the implementation of the user interface to job | |
6245 | control, the operating system maintains the notion of a <I>current terminal | |
6246 | process group ID</I>. Members of this process group (processes whose | |
6247 | process group ID is equal to the current terminal process group ID) | |
6248 | receive keyboard-generated signals such as | |
6249 | <FONT SIZE=-1><B>SIGINT</B>. | |
6250 | ||
6251 | </FONT> | |
6252 | These processes are said to be in the | |
6253 | <I>foreground</I>. | |
6254 | ||
6255 | <I>Background</I> | |
6256 | ||
6257 | processes are those whose process group ID differs from the terminal's; | |
6258 | such processes are immune to keyboard-generated signals. | |
0001803f CR |
6259 | Only foreground processes are allowed to read from or, if the |
6260 | user so specifies with <TT>stty tostop</TT>, write to the | |
6261 | terminal. | |
6262 | Background processes which attempt to read from (write to when | |
6263 | <TT>stty tostop</TT> is in effect) the | |
a0c0a00f | 6264 | terminal are sent a |
17345e5a JA |
6265 | <FONT SIZE=-1><B>SIGTTIN (SIGTTOU)</B> |
6266 | ||
6267 | </FONT> | |
0001803f | 6268 | signal by the kernel's terminal driver, |
17345e5a JA |
6269 | which, unless caught, suspends the process. |
6270 | <P> | |
6271 | ||
6272 | If the operating system on which | |
6273 | <B>bash</B> | |
6274 | ||
6275 | is running supports | |
6276 | job control, | |
6277 | <B>bash</B> | |
6278 | ||
6279 | contains facilities to use it. | |
6280 | Typing the | |
6281 | <I>suspend</I> | |
6282 | ||
6283 | character (typically | |
6284 | <B>^Z</B>, | |
6285 | ||
6286 | Control-Z) while a process is running | |
a0c0a00f | 6287 | causes that process to be stopped and returns control to |
17345e5a JA |
6288 | <B>bash</B>. |
6289 | ||
6290 | Typing the | |
6291 | <I>delayed suspend</I> | |
6292 | ||
6293 | character (typically | |
6294 | <B>^Y</B>, | |
6295 | ||
6296 | Control-Y) causes the process to be stopped when it | |
6297 | attempts to read input from the terminal, and control to | |
6298 | be returned to | |
6299 | <B>bash</B>. | |
6300 | ||
6301 | The user may then manipulate the state of this job, using the | |
6302 | <B>bg</B> | |
6303 | ||
6304 | command to continue it in the background, the | |
6305 | <B>fg</B> | |
6306 | ||
6307 | command to continue it in the foreground, or | |
6308 | the | |
6309 | <B>kill</B> | |
6310 | ||
6311 | command to kill it. A <B>^Z</B> takes effect immediately, | |
6312 | and has the additional side effect of causing pending output | |
6313 | and typeahead to be discarded. | |
6314 | <P> | |
6315 | ||
6316 | There are a number of ways to refer to a job in the shell. | |
6317 | The character | |
6318 | <B>%</B> | |
6319 | ||
6320 | introduces a job specification (<I>jobspec</I>). Job number | |
6321 | <I>n</I> | |
6322 | ||
6323 | may be referred to as | |
6324 | <B>%n</B>. | |
6325 | ||
6326 | A job may also be referred to using a prefix of the name used to | |
6327 | start it, or using a substring that appears in its command line. | |
6328 | For example, | |
6329 | <B>%ce</B> | |
6330 | ||
6331 | refers to a stopped | |
6332 | <B>ce</B> | |
6333 | ||
6334 | job. If a prefix matches more than one job, | |
6335 | <B>bash</B> | |
6336 | ||
6337 | reports an error. Using | |
6338 | <B>%?ce</B>, | |
6339 | ||
6340 | on the other hand, refers to any job containing the string | |
6341 | <B>ce</B> | |
6342 | ||
6343 | in its command line. If the substring matches more than one job, | |
6344 | <B>bash</B> | |
6345 | ||
6346 | reports an error. The symbols | |
6347 | <B>%%</B> | |
6348 | ||
6349 | and | |
6350 | <B>%+</B> | |
6351 | ||
6352 | refer to the shell's notion of the | |
6353 | <I>current job</I>, | |
6354 | ||
6355 | which is the last job stopped while it was in | |
6356 | the foreground or started in the background. | |
a0c0a00f | 6357 | The |
17345e5a JA |
6358 | <I>previous job</I> |
6359 | ||
6360 | may be referenced using | |
6361 | <B>%-</B>. | |
6362 | ||
6363 | If there is only a single job, <B>%+</B> and <B>%-</B> can both be used | |
6364 | to refer to that job. | |
6365 | In output pertaining to jobs (e.g., the output of the | |
6366 | <B>jobs</B> | |
6367 | ||
6368 | command), the current job is always flagged with a | |
6369 | <B>+</B>, | |
6370 | ||
6371 | and the previous job with a | |
6372 | <B>-</B>. | |
6373 | ||
6374 | A single % (with no accompanying job specification) also refers to the | |
6375 | current job. | |
6376 | <P> | |
6377 | ||
6378 | Simply naming a job can be used to bring it into the | |
6379 | foreground: | |
6380 | <B>%1</B> | |
6381 | ||
6382 | is a synonym for | |
6383 | <B>``fg %1''</B>, | |
6384 | bringing job 1 from the background into the foreground. | |
6385 | Similarly, | |
6386 | <B>``%1 &''</B> | |
6387 | ||
6388 | resumes job 1 in the background, equivalent to | |
6389 | <B>``bg %1''</B>. | |
6390 | <P> | |
6391 | ||
6392 | The shell learns immediately whenever a job changes state. | |
6393 | Normally, | |
6394 | <B>bash</B> | |
6395 | ||
6396 | waits until it is about to print a prompt before reporting | |
6397 | changes in a job's status so as to not interrupt | |
a0c0a00f | 6398 | any other output. If the |
17345e5a JA |
6399 | <B>-b</B> |
6400 | ||
6401 | option to the | |
6402 | <B>set</B> | |
6403 | ||
6404 | builtin command | |
6405 | is enabled, | |
6406 | <B>bash</B> | |
6407 | ||
6408 | reports such changes immediately. | |
6409 | Any trap on | |
6410 | <FONT SIZE=-1><B>SIGCHLD</B> | |
6411 | ||
6412 | </FONT> | |
6413 | is executed for each child that exits. | |
6414 | <P> | |
6415 | ||
6416 | If an attempt to exit | |
6417 | <B>bash</B> | |
6418 | ||
6419 | is made while jobs are stopped (or, if the <B>checkjobs</B> shell option has | |
6420 | been enabled using the <B>shopt</B> builtin, running), the shell prints a | |
6421 | warning message, and, if the <B>checkjobs</B> option is enabled, lists the | |
6422 | jobs and their statuses. | |
6423 | The | |
6424 | <B>jobs</B> | |
6425 | ||
a0c0a00f | 6426 | command may then be used to inspect their status. |
17345e5a JA |
6427 | If a second attempt to exit is made without an intervening command, |
6428 | the shell does not print another warning, and any stopped | |
6429 | jobs are terminated. | |
6430 | <A NAME="lbCE"> </A> | |
6431 | <H3>PROMPTING</H3> | |
6432 | ||
a0c0a00f | 6433 | When executing interactively, |
17345e5a JA |
6434 | <B>bash</B> |
6435 | ||
6436 | displays the primary prompt | |
6437 | <FONT SIZE=-1><B>PS1</B> | |
6438 | ||
6439 | </FONT> | |
6440 | when it is ready to read a command, and the secondary prompt | |
6441 | <FONT SIZE=-1><B>PS2</B> | |
6442 | ||
6443 | </FONT> | |
6444 | when it needs more input to complete a command. | |
6445 | <B>Bash</B> | |
6446 | ||
a0c0a00f CR |
6447 | displays |
6448 | <B>PS0</B> | |
6449 | ||
6450 | after it reads a command but before executing it. | |
6451 | <B>Bash</B> | |
6452 | ||
17345e5a JA |
6453 | allows these prompt strings to be customized by inserting a number of |
6454 | backslash-escaped special characters that are decoded as follows: | |
6455 | <DL COMPACT><DT><DD> | |
6456 | ||
6457 | <DL COMPACT> | |
6458 | <DT><B>\a</B> | |
6459 | ||
6460 | <DD> | |
6461 | an ASCII bell character (07) | |
6462 | <DT><B>\d</B> | |
6463 | ||
6464 | <DD> | |
6465 | the date in "Weekday Month Date" format (e.g., "Tue May 26") | |
6466 | <DT><B>\D{</B><I>format</I>} | |
6467 | ||
6468 | <DD> | |
6469 | the <I>format</I> is passed to <I>strftime</I>(3) and the result is inserted | |
6470 | into the prompt string; an empty <I>format</I> results in a locale-specific | |
6471 | time representation. The braces are required | |
6472 | <DT><B>\e</B> | |
6473 | ||
6474 | <DD> | |
6475 | an ASCII escape character (033) | |
6476 | <DT><B>\h</B> | |
6477 | ||
6478 | <DD> | |
6479 | the hostname up to the first `.' | |
6480 | <DT><B>\H</B> | |
6481 | ||
6482 | <DD> | |
6483 | the hostname | |
6484 | <DT><B>\j</B> | |
6485 | ||
6486 | <DD> | |
6487 | the number of jobs currently managed by the shell | |
6488 | <DT><B>\l</B> | |
6489 | ||
6490 | <DD> | |
6491 | the basename of the shell's terminal device name | |
6492 | <DT><B>\n</B> | |
6493 | ||
6494 | <DD> | |
6495 | newline | |
6496 | <DT><B>\r</B> | |
6497 | ||
6498 | <DD> | |
6499 | carriage return | |
6500 | <DT><B>\s</B> | |
6501 | ||
6502 | <DD> | |
6503 | the name of the shell, the basename of | |
6504 | <B>$0</B> | |
6505 | ||
6506 | (the portion following the final slash) | |
6507 | <DT><B>\t</B> | |
6508 | ||
6509 | <DD> | |
6510 | the current time in 24-hour HH:MM:SS format | |
6511 | <DT><B>\T</B> | |
6512 | ||
6513 | <DD> | |
6514 | the current time in 12-hour HH:MM:SS format | |
6515 | <DT><B>\@</B> | |
6516 | ||
6517 | <DD> | |
6518 | the current time in 12-hour am/pm format | |
6519 | <DT><B>\A</B> | |
6520 | ||
6521 | <DD> | |
6522 | the current time in 24-hour HH:MM format | |
6523 | <DT><B>\u</B> | |
6524 | ||
6525 | <DD> | |
6526 | the username of the current user | |
6527 | <DT><B>\v</B> | |
6528 | ||
6529 | <DD> | |
6530 | the version of <B>bash</B> (e.g., 2.00) | |
6531 | <DT><B>\V</B> | |
6532 | ||
6533 | <DD> | |
6534 | the release of <B>bash</B>, version + patch level (e.g., 2.00.0) | |
6535 | <DT><B>\w</B> | |
6536 | ||
6537 | <DD> | |
0001803f CR |
6538 | the current working directory, with |
6539 | <FONT SIZE=-1><B>$HOME</B> | |
6540 | ||
6541 | </FONT> | |
6542 | abbreviated with a tilde | |
6543 | (uses the value of the | |
6544 | <FONT SIZE=-1><B>PROMPT_DIRTRIM</B> | |
6545 | ||
6546 | </FONT> | |
6547 | variable) | |
17345e5a JA |
6548 | <DT><B>\W</B> |
6549 | ||
6550 | <DD> | |
0001803f CR |
6551 | the basename of the current working directory, with |
6552 | <FONT SIZE=-1><B>$HOME</B> | |
6553 | ||
6554 | </FONT> | |
17345e5a JA |
6555 | abbreviated with a tilde |
6556 | <DT><B>\!</B> | |
6557 | ||
6558 | <DD> | |
6559 | the history number of this command | |
6560 | <DT><B>\#</B> | |
6561 | ||
6562 | <DD> | |
6563 | the command number of this command | |
6564 | <DT><B>\$</B> | |
6565 | ||
6566 | <DD> | |
6567 | if the effective UID is 0, a | |
6568 | <B>#</B>, | |
6569 | ||
6570 | otherwise a | |
6571 | <B>$</B> | |
6572 | ||
6573 | <DT><B>\</B><I>nnn</I> | |
6574 | ||
6575 | <DD> | |
6576 | the character corresponding to the octal number <I>nnn</I> | |
6577 | <DT><B>\\</B> | |
6578 | ||
6579 | <DD> | |
6580 | a backslash | |
6581 | <DT><B>\[</B> | |
6582 | ||
6583 | <DD> | |
6584 | begin a sequence of non-printing characters, which could be used to | |
6585 | embed a terminal control sequence into the prompt | |
6586 | <DT><B>\]</B> | |
6587 | ||
6588 | <DD> | |
6589 | end a sequence of non-printing characters | |
6590 | ||
6591 | </DL></DL> | |
6592 | ||
6593 | <P> | |
6594 | ||
6595 | The command number and the history number are usually different: | |
6596 | the history number of a command is its position in the history | |
6597 | list, which may include commands restored from the history file | |
6598 | (see | |
6599 | <FONT SIZE=-1><B>HISTORY</B> | |
6600 | ||
6601 | </FONT> | |
6602 | below), while the command number is the position in the sequence | |
6603 | of commands executed during the current shell session. | |
6604 | After the string is decoded, it is expanded via | |
6605 | parameter expansion, command substitution, arithmetic | |
6606 | expansion, and quote removal, subject to the value of the | |
6607 | <B>promptvars</B> | |
6608 | ||
6609 | shell option (see the description of the | |
6610 | <B>shopt</B> | |
6611 | ||
6612 | command under | |
6613 | <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B> | |
6614 | ||
6615 | </FONT> | |
6616 | below). | |
6617 | <A NAME="lbCF"> </A> | |
6618 | <H3>READLINE</H3> | |
6619 | ||
6620 | This is the library that handles reading input when using an interactive | |
6621 | shell, unless the | |
6622 | <B>--noediting</B> | |
6623 | ||
6624 | option is given at shell invocation. | |
6625 | Line editing is also used when using the <B>-e</B> option to the | |
6626 | <B>read</B> builtin. | |
495aee44 | 6627 | By default, the line editing commands are similar to those of Emacs. |
17345e5a JA |
6628 | A vi-style line editing interface is also available. |
6629 | Line editing can be enabled at any time using the | |
6630 | <B>-o emacs</B> | |
6631 | ||
6632 | or | |
6633 | <B>-o vi</B> | |
6634 | ||
6635 | options to the | |
6636 | <B>set</B> | |
6637 | ||
6638 | builtin (see | |
6639 | <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B> | |
6640 | ||
6641 | </FONT> | |
6642 | below). | |
6643 | To turn off line editing after the shell is running, use the | |
6644 | <B>+o emacs</B> | |
6645 | ||
6646 | or | |
6647 | <B>+o vi</B> | |
6648 | ||
6649 | options to the | |
6650 | <B>set</B> | |
6651 | ||
6652 | builtin. | |
6653 | <A NAME="lbCG"> </A> | |
6654 | <H4>Readline Notation</H4> | |
6655 | ||
6656 | <P> | |
6657 | ||
495aee44 | 6658 | In this section, the Emacs-style notation is used to denote |
17345e5a | 6659 | keystrokes. Control keys are denoted by C-<I>key</I>, e.g., C-n |
a0c0a00f | 6660 | means Control-N. Similarly, |
17345e5a JA |
6661 | <I>meta</I> |
6662 | ||
6663 | keys are denoted by M-<I>key</I>, so M-x means Meta-X. (On keyboards | |
a0c0a00f | 6664 | without a |
17345e5a JA |
6665 | <I>meta</I> |
6666 | ||
6667 | key, M-<I>x</I> means ESC <I>x</I>, i.e., press the Escape key | |
6668 | then the | |
6669 | <I>x</I> | |
6670 | ||
6671 | key. This makes ESC the <I>meta prefix</I>. | |
6672 | The combination M-C-<I>x</I> means ESC-Control-<I>x</I>, | |
6673 | or press the Escape key | |
6674 | then hold the Control key while pressing the | |
6675 | <I>x</I> | |
6676 | ||
6677 | key.) | |
6678 | <P> | |
6679 | ||
6680 | Readline commands may be given numeric | |
6681 | <I>arguments</I>, | |
6682 | ||
6683 | which normally act as a repeat count. | |
6684 | Sometimes, however, it is the sign of the argument that is significant. | |
6685 | Passing a negative argument to a command that acts in the forward | |
6686 | direction (e.g., <B>kill-line</B>) causes that command to act in a | |
a0c0a00f | 6687 | backward direction. |
17345e5a JA |
6688 | Commands whose behavior with arguments deviates from this are noted |
6689 | below. | |
6690 | <P> | |
6691 | ||
6692 | When a command is described as <I>killing</I> text, the text | |
6693 | deleted is saved for possible future retrieval | |
6694 | (<I>yanking</I>). The killed text is saved in a | |
6695 | <I>kill ring</I>. Consecutive kills cause the text to be | |
a0c0a00f | 6696 | accumulated into one unit, which can be yanked all at once. |
17345e5a JA |
6697 | Commands which do not kill text separate the chunks of text |
6698 | on the kill ring. | |
6699 | <A NAME="lbCH"> </A> | |
6700 | <H4>Readline Initialization</H4> | |
6701 | ||
6702 | <P> | |
6703 | ||
6704 | Readline is customized by putting commands in an initialization | |
6705 | file (the <I>inputrc</I> file). | |
6706 | The name of this file is taken from the value of the | |
6707 | <FONT SIZE=-1><B>INPUTRC</B> | |
6708 | ||
6709 | </FONT> | |
6710 | variable. If that variable is unset, the default is | |
6711 | <A HREF="file:~/.inputrc"><I>~/.inputrc</I></A>. | |
6712 | ||
6713 | When a program which uses the readline library starts up, the | |
6714 | initialization file is read, and the key bindings and variables | |
6715 | are set. | |
6716 | There are only a few basic constructs allowed in the | |
6717 | readline initialization file. | |
6718 | Blank lines are ignored. | |
6719 | Lines beginning with a <B>#</B> are comments. | |
6720 | Lines beginning with a <B>$</B> indicate conditional constructs. | |
6721 | Other lines denote key bindings and variable settings. | |
6722 | <P> | |
6723 | ||
6724 | The default key-bindings may be changed with an | |
a0c0a00f | 6725 | <I>inputrc</I> |
17345e5a JA |
6726 | |
6727 | file. | |
6728 | Other programs that use this library may add their own commands | |
6729 | and bindings. | |
6730 | <P> | |
6731 | ||
6732 | For example, placing | |
6733 | <DL COMPACT><DT><DD> | |
6734 | <P> | |
6735 | ||
6736 | M-Control-u: universal-argument | |
6737 | </DL> | |
6738 | ||
6739 | or | |
6740 | <DL COMPACT><DT><DD> | |
6741 | C-Meta-u: universal-argument | |
6742 | </DL> | |
6743 | ||
a0c0a00f | 6744 | into the |
17345e5a JA |
6745 | <I>inputrc</I> |
6746 | ||
6747 | would make M-C-u execute the readline command | |
6748 | <I>universal-argument</I>. | |
6749 | ||
6750 | <P> | |
6751 | ||
6752 | The following symbolic character names are recognized: | |
6753 | <I>RUBOUT</I>, | |
6754 | ||
6755 | <I>DEL</I>, | |
6756 | ||
6757 | <I>ESC</I>, | |
6758 | ||
6759 | <I>LFD</I>, | |
6760 | ||
6761 | <I>NEWLINE</I>, | |
6762 | ||
6763 | <I>RET</I>, | |
6764 | ||
6765 | <I>RETURN</I>, | |
6766 | ||
6767 | <I>SPC</I>, | |
6768 | ||
6769 | <I>SPACE</I>, | |
6770 | ||
6771 | and | |
6772 | <I>TAB</I>. | |
6773 | ||
6774 | <P> | |
6775 | ||
6776 | In addition to command names, readline allows keys to be bound | |
6777 | to a string that is inserted when the key is pressed (a <I>macro</I>). | |
6778 | <A NAME="lbCI"> </A> | |
6779 | <H4>Readline Key Bindings</H4> | |
6780 | ||
6781 | <P> | |
6782 | ||
6783 | The syntax for controlling key bindings in the | |
6784 | <I>inputrc</I> | |
6785 | ||
6786 | file is simple. All that is required is the name of the | |
6787 | command or the text of a macro and a key sequence to which | |
a0c0a00f | 6788 | it should be bound. The name may be specified in one of two ways: |
17345e5a JA |
6789 | as a symbolic key name, possibly with <I>Meta-</I> or <I>Control-</I> |
6790 | prefixes, or as a key sequence. | |
6791 | <P> | |
6792 | ||
6793 | When using the form <B>keyname</B>:<I>function-name</I> or <I>macro</I>, | |
6794 | <I>keyname</I> | |
6795 | ||
6796 | is the name of a key spelled out in English. For example: | |
6797 | <P> | |
6798 | <DL COMPACT><DT><DD> | |
6799 | Control-u: universal-argument | |
6800 | <BR> | |
6801 | ||
6802 | Meta-Rubout: backward-kill-word | |
6803 | <BR> | |
6804 | ||
6805 | Control-o: "> output" | |
6806 | </DL> | |
6807 | ||
6808 | <P> | |
6809 | ||
6810 | In the above example, | |
6811 | <I>C-u</I> | |
6812 | ||
6813 | is bound to the function | |
6814 | <B>universal-argument</B>, | |
6815 | ||
6816 | <I>M-DEL</I> | |
6817 | ||
6818 | is bound to the function | |
6819 | <B>backward-kill-word</B>, | |
6820 | ||
6821 | and | |
6822 | <I>C-o</I> | |
6823 | ||
6824 | is bound to run the macro | |
6825 | expressed on the right hand side (that is, to insert the text | |
6826 | <TT>> output</TT> | |
6827 | ||
6828 | into the line). | |
6829 | <P> | |
6830 | ||
6831 | In the second form, <B>"keyseq"</B>:<I>function-name</I> or <I>macro</I>, | |
6832 | <B>keyseq</B> | |
6833 | ||
6834 | differs from | |
6835 | <B>keyname</B> | |
6836 | ||
6837 | above in that strings denoting | |
6838 | an entire key sequence may be specified by placing the sequence | |
6839 | within double quotes. Some GNU Emacs style key escapes can be | |
6840 | used, as in the following example, but the symbolic character names | |
6841 | are not recognized. | |
6842 | <P> | |
6843 | <DL COMPACT><DT><DD> | |
6844 | "\C-u": universal-argument | |
6845 | <BR> | |
6846 | ||
6847 | "\C-x\C-r": re-read-init-file | |
6848 | <BR> | |
6849 | ||
6850 | "\e[11~": "Function Key 1" | |
6851 | </DL> | |
6852 | ||
6853 | <P> | |
6854 | ||
6855 | In this example, | |
6856 | <I>C-u</I> | |
6857 | ||
6858 | is again bound to the function | |
6859 | <B>universal-argument</B>. | |
6860 | ||
6861 | <I>C-x C-r</I> | |
6862 | ||
6863 | is bound to the function | |
6864 | <B>re-read-init-file</B>, | |
6865 | ||
a0c0a00f | 6866 | and |
17345e5a JA |
6867 | <I>ESC [ 1 1 ~</I> |
6868 | ||
6869 | is bound to insert the text | |
6870 | <TT>Function Key 1</TT>. | |
6871 | ||
6872 | <P> | |
6873 | ||
6874 | The full set of GNU Emacs style escape sequences is | |
6875 | <DL COMPACT><DT><DD> | |
6876 | ||
6877 | <DL COMPACT> | |
6878 | <DT><B>\C-</B> | |
6879 | ||
6880 | <DD> | |
6881 | control prefix | |
6882 | <DT><B>\M-</B> | |
6883 | ||
6884 | <DD> | |
6885 | meta prefix | |
6886 | <DT><B>\e</B> | |
6887 | ||
6888 | <DD> | |
6889 | an escape character | |
6890 | <DT><B>\\</B> | |
6891 | ||
6892 | <DD> | |
6893 | backslash | |
6894 | <DT><B>\</B> | |
6895 | ||
6896 | <DD> | |
6897 | literal " | |
6898 | <DT><B>\aq</B> | |
6899 | ||
6900 | <DD> | |
6901 | literal aq | |
6902 | </DL></DL> | |
6903 | ||
6904 | ||
6905 | <P> | |
6906 | ||
6907 | In addition to the GNU Emacs style escape sequences, a second | |
6908 | set of backslash escapes is available: | |
6909 | <DL COMPACT><DT><DD> | |
6910 | ||
6911 | <DL COMPACT> | |
6912 | <DT><B>\a</B> | |
6913 | ||
6914 | <DD> | |
6915 | alert (bell) | |
6916 | <DT><B>\b</B> | |
6917 | ||
6918 | <DD> | |
6919 | backspace | |
6920 | <DT><B>\d</B> | |
6921 | ||
6922 | <DD> | |
6923 | delete | |
6924 | <DT><B>\f</B> | |
6925 | ||
6926 | <DD> | |
6927 | form feed | |
6928 | <DT><B>\n</B> | |
6929 | ||
6930 | <DD> | |
6931 | newline | |
6932 | <DT><B>\r</B> | |
6933 | ||
6934 | <DD> | |
6935 | carriage return | |
6936 | <DT><B>\t</B> | |
6937 | ||
6938 | <DD> | |
6939 | horizontal tab | |
6940 | <DT><B>\v</B> | |
6941 | ||
6942 | <DD> | |
6943 | vertical tab | |
6944 | <DT><B>\</B><I>nnn</I> | |
6945 | ||
6946 | <DD> | |
6947 | the eight-bit character whose value is the octal value <I>nnn</I> | |
6948 | (one to three digits) | |
6949 | <DT><B>\x</B><I>HH</I> | |
6950 | ||
6951 | <DD> | |
6952 | the eight-bit character whose value is the hexadecimal value <I>HH</I> | |
6953 | (one or two hex digits) | |
6954 | </DL></DL> | |
6955 | ||
6956 | ||
6957 | <P> | |
6958 | ||
6959 | When entering the text of a macro, single or double quotes must | |
6960 | be used to indicate a macro definition. | |
6961 | Unquoted text is assumed to be a function name. | |
6962 | In the macro body, the backslash escapes described above are expanded. | |
6963 | Backslash will quote any other character in the macro text, | |
6964 | including " and aq. | |
6965 | <P> | |
6966 | ||
6967 | <B>Bash</B> | |
6968 | ||
6969 | allows the current readline key bindings to be displayed or modified | |
6970 | with the | |
6971 | <B>bind</B> | |
6972 | ||
6973 | builtin command. The editing mode may be switched during interactive | |
6974 | use by using the | |
6975 | <B>-o</B> | |
6976 | ||
6977 | option to the | |
6978 | <B>set</B> | |
6979 | ||
6980 | builtin command (see | |
6981 | <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B> | |
6982 | ||
6983 | </FONT> | |
6984 | below). | |
6985 | <A NAME="lbCJ"> </A> | |
6986 | <H4>Readline Variables</H4> | |
6987 | ||
6988 | <P> | |
6989 | ||
6990 | Readline has variables that can be used to further customize its | |
6991 | behavior. A variable may be set in the | |
6992 | <I>inputrc</I> | |
6993 | ||
6994 | file with a statement of the form | |
6995 | <DL COMPACT><DT><DD> | |
6996 | <P> | |
6997 | ||
6998 | <B>set</B> <I>variable-name</I> <I>value</I> | |
6999 | </DL> | |
7000 | ||
7001 | <P> | |
7002 | ||
7003 | Except where noted, readline variables can take the values | |
7004 | <B>On</B> | |
7005 | ||
7006 | or | |
7007 | <B>Off</B> | |
7008 | ||
7009 | (without regard to case). | |
7010 | Unrecognized variable names are ignored. | |
7011 | When a variable value is read, empty or null values, "on" (case-insensitive), | |
7012 | and "1" are equivalent to <B>On</B>. All other values are equivalent to | |
7013 | <B>Off</B>. | |
7014 | The variables and their default values are: | |
7015 | <P> | |
7016 | ||
7017 | ||
7018 | <DL COMPACT> | |
7019 | <DT><B>bell-style (audible)</B> | |
7020 | ||
7021 | <DD> | |
7022 | Controls what happens when readline wants to ring the terminal bell. | |
7023 | If set to <B>none</B>, readline never rings the bell. If set to | |
7024 | <B>visible</B>, readline uses a visible bell if one is available. | |
7025 | If set to <B>audible</B>, readline attempts to ring the terminal's bell. | |
7026 | <DT><B>bind-tty-special-chars (On)</B> | |
7027 | ||
7028 | <DD> | |
7029 | If set to <B>On</B>, readline attempts to bind the control characters | |
7030 | treated specially by the kernel's terminal driver to their readline | |
7031 | equivalents. | |
a0c0a00f CR |
7032 | <DT><B>blink-matching-paren (Off)</B> |
7033 | ||
7034 | <DD> | |
7035 | If set to <B>On</B>, readline attempts to briefly move the cursor to an | |
7036 | opening parenthesis when a closing parenthesis is inserted. | |
7037 | <DT><B>colored-completion-prefix (Off)</B> | |
7038 | ||
7039 | <DD> | |
7040 | If set to <B>On</B>, when listing completions, readline displays the | |
7041 | common prefix of the set of possible completions using a different color. | |
7042 | The color definitions are taken from the value of the <B>LS_COLORS</B> | |
7043 | environment variable. | |
ac50fbac CR |
7044 | <DT><B>colored-stats (Off)</B> |
7045 | ||
7046 | <DD> | |
7047 | If set to <B>On</B>, readline displays possible completions using different | |
a0c0a00f | 7048 | colors to indicate their file type. |
ac50fbac CR |
7049 | The color definitions are taken from the value of the <B>LS_COLORS</B> |
7050 | environment variable. | |
17345e5a JA |
7051 | <DT><B>comment-begin (``#'')</B> |
7052 | ||
7053 | <DD> | |
7054 | The string that is inserted when the readline | |
7055 | <B>insert-comment</B> | |
7056 | ||
7057 | command is executed. | |
7058 | This command is bound to | |
7059 | <B>M-#</B> | |
7060 | ||
7061 | in emacs mode and to | |
7062 | <B>#</B> | |
7063 | ||
7064 | in vi command mode. | |
a0c0a00f CR |
7065 | <DT><B>completion-display-width (-1)</B> |
7066 | ||
7067 | <DD> | |
7068 | The number of screen columns used to display possible matches | |
7069 | when performing completion. | |
7070 | The value is ignored if it is less than 0 or greater than the terminal | |
7071 | screen width. | |
7072 | A value of 0 will cause matches to be displayed one per line. | |
7073 | The default value is -1. | |
17345e5a JA |
7074 | <DT><B>completion-ignore-case (Off)</B> |
7075 | ||
7076 | <DD> | |
7077 | If set to <B>On</B>, readline performs filename matching and completion | |
7078 | in a case-insensitive fashion. | |
a0c0a00f CR |
7079 | <DT><B>completion-map-case (Off)</B> |
7080 | ||
7081 | <DD> | |
7082 | If set to <B>On</B>, and <B>completion-ignore-case</B> is enabled, readline | |
7083 | treats hyphens (<I>-</I>) and underscores (<I>_</I>) as equivalent when | |
7084 | performing case-insensitive filename matching and completion. | |
17345e5a JA |
7085 | <DT><B>completion-prefix-display-length (0)</B> |
7086 | ||
7087 | <DD> | |
7088 | The length in characters of the common prefix of a list of possible | |
7089 | completions that is displayed without modification. When set to a | |
7090 | value greater than zero, common prefixes longer than this value are | |
7091 | replaced with an ellipsis when displaying possible completions. | |
7092 | <DT><B>completion-query-items (100)</B> | |
7093 | ||
7094 | <DD> | |
7095 | This determines when the user is queried about viewing | |
7096 | the number of possible completions | |
7097 | generated by the <B>possible-completions</B> command. | |
7098 | It may be set to any integer value greater than or equal to | |
7099 | zero. If the number of possible completions is greater than | |
7100 | or equal to the value of this variable, the user is asked whether | |
7101 | or not he wishes to view them; otherwise they are simply listed | |
7102 | on the terminal. | |
7103 | <DT><B>convert-meta (On)</B> | |
7104 | ||
7105 | <DD> | |
7106 | If set to <B>On</B>, readline will convert characters with the | |
7107 | eighth bit set to an ASCII key sequence | |
7108 | by stripping the eighth bit and prefixing an | |
7109 | escape character (in effect, using escape as the <I>meta prefix</I>). | |
a0c0a00f CR |
7110 | The default is <I>On</I>, but readline will set it to <I>Off</I> if the |
7111 | locale contains eight-bit characters. | |
17345e5a JA |
7112 | <DT><B>disable-completion (Off)</B> |
7113 | ||
7114 | <DD> | |
7115 | If set to <B>On</B>, readline will inhibit word completion. Completion | |
7116 | characters will be inserted into the line as if they had been | |
7117 | mapped to <B>self-insert</B>. | |
a0c0a00f CR |
7118 | <DT><B>echo-control-characters (On)</B> |
7119 | ||
7120 | <DD> | |
7121 | When set to <B>On</B>, on operating systems that indicate they support it, | |
7122 | readline echoes a character corresponding to a signal generated from the | |
7123 | keyboard. | |
17345e5a JA |
7124 | <DT><B>editing-mode (emacs)</B> |
7125 | ||
7126 | <DD> | |
7127 | Controls whether readline begins with a set of key bindings similar | |
495aee44 | 7128 | to <I>Emacs</I> or <I>vi</I>. |
17345e5a JA |
7129 | <B>editing-mode</B> |
7130 | ||
7131 | can be set to either | |
7132 | <B>emacs</B> | |
7133 | ||
7134 | or | |
7135 | <B>vi</B>. | |
7136 | ||
a0c0a00f | 7137 | <DT><B>enable-bracketed-paste (Off)</B> |
0001803f CR |
7138 | |
7139 | <DD> | |
a0c0a00f CR |
7140 | When set to <B>On</B>, readline will configure the terminal in a way |
7141 | that will enable it to insert each paste into the editing buffer as a | |
7142 | single string of characters, instead of treating each character as if | |
7143 | it had been read from the keyboard. This can prevent pasted characters | |
7144 | from being interpreted as editing commands. | |
17345e5a JA |
7145 | <DT><B>enable-keypad (Off)</B> |
7146 | ||
7147 | <DD> | |
7148 | When set to <B>On</B>, readline will try to enable the application | |
7149 | keypad when it is called. Some systems need this to enable the | |
7150 | arrow keys. | |
0001803f CR |
7151 | <DT><B>enable-meta-key (On)</B> |
7152 | ||
7153 | <DD> | |
7154 | When set to <B>On</B>, readline will try to enable any meta modifier | |
7155 | key the terminal claims to support when it is called. On many terminals, | |
7156 | the meta key is used to send eight-bit characters. | |
17345e5a JA |
7157 | <DT><B>expand-tilde (Off)</B> |
7158 | ||
7159 | <DD> | |
495aee44 | 7160 | If set to <B>On</B>, tilde expansion is performed when readline |
17345e5a JA |
7161 | attempts word completion. |
7162 | <DT><B>history-preserve-point (Off)</B> | |
7163 | ||
7164 | <DD> | |
495aee44 | 7165 | If set to <B>On</B>, the history code attempts to place point at the |
17345e5a JA |
7166 | same location on each history line retrieved with <B>previous-history</B> |
7167 | or <B>next-history</B>. | |
a0c0a00f | 7168 | <DT><B>history-size (unset)</B> |
17345e5a JA |
7169 | |
7170 | <DD> | |
ac50fbac CR |
7171 | Set the maximum number of history entries saved in the history list. |
7172 | If set to zero, any existing history entries are deleted and no new entries | |
7173 | are saved. | |
7174 | If set to a value less than zero, the number of history entries is not | |
7175 | limited. | |
a0c0a00f CR |
7176 | By default, the number of history entries is set to the value of the |
7177 | <B>HISTSIZE</B> shell variable. | |
7178 | If an attempt is made to set <I>history-size</I> to a non-numeric value, | |
7179 | the maximum number of history entries will be set to 500. | |
17345e5a JA |
7180 | <DT><B>horizontal-scroll-mode (Off)</B> |
7181 | ||
7182 | <DD> | |
7183 | When set to <B>On</B>, makes readline use a single line for display, | |
7184 | scrolling the input horizontally on a single screen line when it | |
7185 | becomes longer than the screen width rather than wrapping to a new line. | |
7186 | <DT><B>input-meta (Off)</B> | |
7187 | ||
7188 | <DD> | |
7189 | If set to <B>On</B>, readline will enable eight-bit input (that is, | |
a0c0a00f | 7190 | it will not strip the eighth bit from the characters it reads), |
17345e5a JA |
7191 | regardless of what the terminal claims it can support. The name |
7192 | <B>meta-flag</B> | |
7193 | ||
7194 | is a synonym for this variable. | |
a0c0a00f CR |
7195 | The default is <I>Off</I>, but readline will set it to <I>On</I> if the |
7196 | locale contains eight-bit characters. | |
17345e5a JA |
7197 | <DT><B>isearch-terminators (``C-[C-J'')</B> |
7198 | ||
7199 | <DD> | |
7200 | The string of characters that should terminate an incremental | |
7201 | search without subsequently executing the character as a command. | |
7202 | If this variable has not been given a value, the characters | |
7203 | <I>ESC</I> and <I>C-J</I> will terminate an incremental search. | |
7204 | <DT><B>keymap (emacs)</B> | |
7205 | ||
7206 | <DD> | |
7207 | Set the current readline keymap. The set of valid keymap names is | |
7208 | <I>emacs, emacs-standard, emacs-meta, emacs-ctlx, vi, | |
7209 | vi-command</I>, and | |
7210 | <I>vi-insert</I>. | |
7211 | ||
7212 | <I>vi</I> is equivalent to <I>vi-command</I>; <I>emacs</I> is | |
7213 | equivalent to <I>emacs-standard</I>. The default value is | |
7214 | <I>emacs</I>; | |
7215 | ||
7216 | the value of | |
7217 | <B>editing-mode</B> | |
7218 | ||
7219 | also affects the default keymap. | |
a0c0a00f CR |
7220 | <DT><B>emacs-mode-string (@)</B> |
7221 | ||
7222 | <DD> | |
7223 | This string is displayed immediately before the last line of the primary | |
7224 | prompt when emacs editing mode is active. The value is expanded like a | |
7225 | key binding, so the standard set of meta- and control prefixes and | |
7226 | backslash escape sequences is available. | |
7227 | Use the \1 and \2 escapes to begin and end sequences of | |
7228 | non-printing characters, which can be used to embed a terminal control | |
7229 | sequence into the mode string. | |
ac50fbac CR |
7230 | <DT><B>keyseq-timeout (500)</B> |
7231 | ||
7232 | <DD> | |
7233 | Specifies the duration <I>readline</I> will wait for a character when reading an | |
7234 | ambiguous key sequence (one that can form a complete key sequence using | |
7235 | the input read so far, or can take additional input to complete a longer | |
7236 | key sequence). | |
7237 | If no input is received within the timeout, <I>readline</I> will use the shorter | |
7238 | but complete key sequence. | |
7239 | The value is specified in milliseconds, so a value of 1000 means that | |
7240 | <I>readline</I> will wait one second for additional input. | |
7241 | If this variable is set to a value less than or equal to zero, or to a | |
7242 | non-numeric value, <I>readline</I> will wait until another key is pressed to | |
7243 | decide which key sequence to complete. | |
17345e5a JA |
7244 | <DT><B>mark-directories (On)</B> |
7245 | ||
7246 | <DD> | |
7247 | If set to <B>On</B>, completed directory names have a slash | |
7248 | appended. | |
7249 | <DT><B>mark-modified-lines (Off)</B> | |
7250 | ||
7251 | <DD> | |
7252 | If set to <B>On</B>, history lines that have been modified are displayed | |
7253 | with a preceding asterisk (<B>*</B>). | |
7254 | <DT><B>mark-symlinked-directories (Off)</B> | |
7255 | ||
7256 | <DD> | |
7257 | If set to <B>On</B>, completed names which are symbolic links to directories | |
7258 | have a slash appended (subject to the value of | |
7259 | <B>mark-directories</B>). | |
7260 | <DT><B>match-hidden-files (On)</B> | |
7261 | ||
7262 | <DD> | |
7263 | This variable, when set to <B>On</B>, causes readline to match files whose | |
a0c0a00f | 7264 | names begin with a `.' (hidden files) when performing filename |
495aee44 CR |
7265 | completion. |
7266 | If set to <B>Off</B>, the leading `.' must be | |
17345e5a | 7267 | supplied by the user in the filename to be completed. |
495aee44 CR |
7268 | <DT><B>menu-complete-display-prefix (Off)</B> |
7269 | ||
7270 | <DD> | |
7271 | If set to <B>On</B>, menu completion displays the common prefix of the | |
7272 | list of possible completions (which may be empty) before cycling through | |
7273 | the list. | |
17345e5a JA |
7274 | <DT><B>output-meta (Off)</B> |
7275 | ||
7276 | <DD> | |
7277 | If set to <B>On</B>, readline will display characters with the | |
7278 | eighth bit set directly rather than as a meta-prefixed escape | |
7279 | sequence. | |
a0c0a00f CR |
7280 | The default is <I>Off</I>, but readline will set it to <I>On</I> if the |
7281 | locale contains eight-bit characters. | |
17345e5a JA |
7282 | <DT><B>page-completions (On)</B> |
7283 | ||
7284 | <DD> | |
7285 | If set to <B>On</B>, readline uses an internal <I>more</I>-like pager | |
7286 | to display a screenful of possible completions at a time. | |
7287 | <DT><B>print-completions-horizontally (Off)</B> | |
7288 | ||
7289 | <DD> | |
7290 | If set to <B>On</B>, readline will display completions with matches | |
7291 | sorted horizontally in alphabetical order, rather than down the screen. | |
7292 | <DT><B>revert-all-at-newline (Off)</B> | |
7293 | ||
7294 | <DD> | |
a0c0a00f | 7295 | If set to <B>On</B>, readline will undo all changes to history lines |
17345e5a JA |
7296 | before returning when <B>accept-line</B> is executed. By default, |
7297 | history lines may be modified and retain individual undo lists across | |
7298 | calls to <B>readline</B>. | |
7299 | <DT><B>show-all-if-ambiguous (Off)</B> | |
7300 | ||
7301 | <DD> | |
7302 | This alters the default behavior of the completion functions. If | |
7303 | set to | |
495aee44 | 7304 | <B>On</B>, |
17345e5a JA |
7305 | |
7306 | words which have more than one possible completion cause the | |
7307 | matches to be listed immediately instead of ringing the bell. | |
7308 | <DT><B>show-all-if-unmodified (Off)</B> | |
7309 | ||
7310 | <DD> | |
7311 | This alters the default behavior of the completion functions in | |
7312 | a fashion similar to <B>show-all-if-ambiguous</B>. | |
7313 | If set to | |
495aee44 | 7314 | <B>On</B>, |
17345e5a JA |
7315 | |
7316 | words which have more than one possible completion without any | |
7317 | possible partial completion (the possible completions don't share | |
7318 | a common prefix) cause the matches to be listed immediately instead | |
7319 | of ringing the bell. | |
ac50fbac CR |
7320 | <DT><B>show-mode-in-prompt (Off)</B> |
7321 | ||
7322 | <DD> | |
7323 | If set to <B>On</B>, add a character to the beginning of the prompt | |
7324 | indicating the editing mode: emacs (@), vi command (:) or vi | |
7325 | insertion (+). | |
0001803f CR |
7326 | <DT><B>skip-completed-text (Off)</B> |
7327 | ||
7328 | <DD> | |
7329 | If set to <B>On</B>, this alters the default completion behavior when | |
7330 | inserting a single match into the line. It's only active when | |
7331 | performing completion in the middle of a word. If enabled, readline | |
7332 | does not insert characters from the completion that match characters | |
7333 | after point in the word being completed, so portions of the word | |
7334 | following the cursor are not duplicated. | |
a0c0a00f CR |
7335 | <DT><B>vi-cmd-mode-string ((cmd))</B> |
7336 | ||
7337 | <DD> | |
7338 | This string is displayed immediately before the last line of the primary | |
7339 | prompt when vi editing mode is active and in command mode. | |
7340 | The value is expanded like a | |
7341 | key binding, so the standard set of meta- and control prefixes and | |
7342 | backslash escape sequences is available. | |
7343 | Use the \1 and \2 escapes to begin and end sequences of | |
7344 | non-printing characters, which can be used to embed a terminal control | |
7345 | sequence into the mode string. | |
7346 | <DT><B>vi-ins-mode-string ((ins))</B> | |
7347 | ||
7348 | <DD> | |
7349 | This string is displayed immediately before the last line of the primary | |
7350 | prompt when vi editing mode is active and in insertion mode. | |
7351 | The value is expanded like a | |
7352 | key binding, so the standard set of meta- and control prefixes and | |
7353 | backslash escape sequences is available. | |
7354 | Use the \1 and \2 escapes to begin and end sequences of | |
7355 | non-printing characters, which can be used to embed a terminal control | |
7356 | sequence into the mode string. | |
17345e5a JA |
7357 | <DT><B>visible-stats (Off)</B> |
7358 | ||
7359 | <DD> | |
7360 | If set to <B>On</B>, a character denoting a file's type as reported | |
7361 | by <I>stat</I>(2) is appended to the filename when listing possible | |
7362 | completions. | |
7363 | ||
7364 | </DL> | |
7365 | <A NAME="lbCK"> </A> | |
7366 | <H4>Readline Conditional Constructs</H4> | |
7367 | ||
7368 | <P> | |
7369 | ||
7370 | Readline implements a facility similar in spirit to the conditional | |
7371 | compilation features of the C preprocessor which allows key | |
7372 | bindings and variable settings to be performed as the result | |
7373 | of tests. There are four parser directives used. | |
7374 | <DL COMPACT> | |
7375 | <DT><B>$if</B><DD> | |
a0c0a00f | 7376 | The |
17345e5a JA |
7377 | <B>$if</B> |
7378 | ||
7379 | construct allows bindings to be made based on the | |
7380 | editing mode, the terminal being used, or the application using | |
7381 | readline. The text of the test extends to the end of the line; | |
7382 | no characters are required to isolate it. | |
7383 | <DL COMPACT><DT><DD> | |
7384 | <DL COMPACT> | |
7385 | <DT><B>mode</B><DD> | |
7386 | The <B>mode=</B> form of the <B>$if</B> directive is used to test | |
7387 | whether readline is in emacs or vi mode. | |
7388 | This may be used in conjunction | |
7389 | with the <B>set keymap</B> command, for instance, to set bindings in | |
7390 | the <I>emacs-standard</I> and <I>emacs-ctlx</I> keymaps only if | |
7391 | readline is starting out in emacs mode. | |
7392 | <DT><B>term</B><DD> | |
7393 | The <B>term=</B> form may be used to include terminal-specific | |
7394 | key bindings, perhaps to bind the key sequences output by the | |
7395 | terminal's function keys. The word on the right side of the | |
7396 | <B>=</B> | |
7397 | ||
a0c0a00f | 7398 | is tested against both the full name of the terminal and the portion |
17345e5a JA |
7399 | of the terminal name before the first <B>-</B>. This allows |
7400 | <I>sun</I> | |
7401 | ||
7402 | to match both | |
7403 | <I>sun</I> | |
7404 | ||
7405 | and | |
7406 | <I>sun-cmd</I>, | |
7407 | ||
7408 | for instance. | |
7409 | <DT><B>application</B><DD> | |
7410 | The <B>application</B> construct is used to include | |
7411 | application-specific settings. Each program using the readline | |
7412 | library sets the <I>application name</I>, and an initialization | |
7413 | file can test for a particular value. | |
7414 | This could be used to bind key sequences to functions useful for | |
7415 | a specific program. For instance, the following command adds a | |
495aee44 | 7416 | key sequence that quotes the current or previous word in <B>bash</B>: |
17345e5a JA |
7417 | <P> |
7418 | <DL COMPACT><DT><DD> | |
7419 | <PRE> | |
7420 | <B>$if</B> Bash | |
7421 | # Quote the current or previous word | |
7422 | "\C-xq": "\eb\"\ef\"" | |
7423 | <B>$endif</B> | |
7424 | </PRE> | |
7425 | ||
7426 | </DL> | |
7427 | ||
7428 | </DL></DL> | |
7429 | ||
7430 | <DT><B>$endif</B><DD> | |
7431 | This command, as seen in the previous example, terminates an | |
7432 | <B>$if</B> command. | |
7433 | <DT><B>$else</B><DD> | |
7434 | Commands in this branch of the <B>$if</B> directive are executed if | |
7435 | the test fails. | |
7436 | <DT><B>$include</B><DD> | |
7437 | This directive takes a single filename as an argument and reads commands | |
7438 | and bindings from that file. For example, the following directive | |
7439 | would read <A HREF="file:/etc/inputrc"><I>/etc/inputrc</I></A>: | |
7440 | <P> | |
7441 | <DL COMPACT><DT><DD> | |
7442 | <PRE> | |
7443 | <B>$include</B> <A HREF="file:/etc/inputrc"><I>/etc/inputrc</I></A> | |
7444 | </PRE> | |
7445 | ||
7446 | </DL> | |
7447 | ||
7448 | </DL> | |
7449 | <A NAME="lbCL"> </A> | |
7450 | <H4>Searching</H4> | |
7451 | ||
7452 | <P> | |
7453 | ||
7454 | Readline provides commands for searching through the command history | |
7455 | (see | |
7456 | <FONT SIZE=-1><B>HISTORY</B> | |
7457 | ||
7458 | </FONT> | |
7459 | below) for lines containing a specified string. | |
7460 | There are two search modes: | |
7461 | <I>incremental</I> | |
7462 | ||
7463 | and | |
7464 | <I>non-incremental</I>. | |
7465 | ||
7466 | <P> | |
7467 | ||
7468 | Incremental searches begin before the user has finished typing the | |
7469 | search string. | |
7470 | As each character of the search string is typed, readline displays | |
7471 | the next entry from the history matching the string typed so far. | |
7472 | An incremental search requires only as many characters as needed to | |
7473 | find the desired history entry. | |
7474 | The characters present in the value of the <B>isearch-terminators</B> | |
7475 | variable are used to terminate an incremental search. | |
7476 | If that variable has not been assigned a value the Escape and | |
7477 | Control-J characters will terminate an incremental search. | |
7478 | Control-G will abort an incremental search and restore the original | |
7479 | line. | |
7480 | When the search is terminated, the history entry containing the | |
7481 | search string becomes the current line. | |
7482 | <P> | |
7483 | ||
7484 | To find other matching entries in the history list, type Control-S or | |
7485 | Control-R as appropriate. | |
7486 | This will search backward or forward in the history for the next | |
7487 | entry matching the search string typed so far. | |
7488 | Any other key sequence bound to a readline command will terminate | |
7489 | the search and execute that command. | |
7490 | For instance, a <I>newline</I> will terminate the search and accept | |
7491 | the line, thereby executing the command from the history list. | |
7492 | <P> | |
7493 | ||
7494 | Readline remembers the last incremental search string. If two | |
7495 | Control-Rs are typed without any intervening characters defining a | |
7496 | new search string, any remembered search string is used. | |
7497 | <P> | |
7498 | ||
7499 | Non-incremental searches read the entire search string before starting | |
7500 | to search for matching history lines. The search string may be | |
7501 | typed by the user or be part of the contents of the current line. | |
7502 | <A NAME="lbCM"> </A> | |
7503 | <H4>Readline Command Names</H4> | |
7504 | ||
7505 | <P> | |
7506 | ||
7507 | The following is a list of the names of the commands and the default | |
7508 | key sequences to which they are bound. | |
7509 | Command names without an accompanying key sequence are unbound by default. | |
7510 | In the following descriptions, <I>point</I> refers to the current cursor | |
7511 | position, and <I>mark</I> refers to a cursor position saved by the | |
7512 | <B>set-mark</B> command. | |
7513 | The text between the point and mark is referred to as the <I>region</I>. | |
7514 | <A NAME="lbCN"> </A> | |
7515 | <H4>Commands for Moving</H4> | |
7516 | ||
7517 | <P> | |
7518 | ||
7519 | ||
7520 | <DL COMPACT> | |
7521 | <DT><B>beginning-of-line (C-a)</B> | |
7522 | ||
7523 | <DD> | |
7524 | Move to the start of the current line. | |
7525 | <DT><B>end-of-line (C-e)</B> | |
7526 | ||
7527 | <DD> | |
7528 | Move to the end of the line. | |
7529 | <DT><B>forward-char (C-f)</B> | |
7530 | ||
7531 | <DD> | |
7532 | Move forward a character. | |
7533 | <DT><B>backward-char (C-b)</B> | |
7534 | ||
7535 | <DD> | |
7536 | Move back a character. | |
7537 | <DT><B>forward-word (M-f)</B> | |
7538 | ||
7539 | <DD> | |
7540 | Move forward to the end of the next word. Words are composed of | |
7541 | alphanumeric characters (letters and digits). | |
7542 | <DT><B>backward-word (M-b)</B> | |
7543 | ||
7544 | <DD> | |
7545 | Move back to the start of the current or previous word. | |
7546 | Words are composed of alphanumeric characters (letters and digits). | |
7547 | <DT><B>shell-forward-word</B> | |
7548 | ||
7549 | <DD> | |
7550 | Move forward to the end of the next word. | |
7551 | Words are delimited by non-quoted shell metacharacters. | |
7552 | <DT><B>shell-backward-word</B> | |
7553 | ||
7554 | <DD> | |
7555 | Move back to the start of the current or previous word. | |
7556 | Words are delimited by non-quoted shell metacharacters. | |
7557 | <DT><B>clear-screen (C-l)</B> | |
7558 | ||
7559 | <DD> | |
7560 | Clear the screen leaving the current line at the top of the screen. | |
7561 | With an argument, refresh the current line without clearing the | |
7562 | screen. | |
7563 | <DT><B>redraw-current-line</B> | |
7564 | ||
7565 | <DD> | |
7566 | Refresh the current line. | |
7567 | ||
7568 | </DL> | |
7569 | <A NAME="lbCO"> </A> | |
7570 | <H4>Commands for Manipulating the History</H4> | |
7571 | ||
7572 | <P> | |
7573 | ||
7574 | ||
7575 | <DL COMPACT> | |
7576 | <DT><B>accept-line (Newline, Return)</B> | |
7577 | ||
7578 | <DD> | |
7579 | Accept the line regardless of where the cursor is. If this line is | |
7580 | non-empty, add it to the history list according to the state of the | |
7581 | <FONT SIZE=-1><B>HISTCONTROL</B> | |
7582 | ||
7583 | </FONT> | |
7584 | variable. If the line is a modified history | |
7585 | line, then restore the history line to its original state. | |
7586 | <DT><B>previous-history (C-p)</B> | |
7587 | ||
7588 | <DD> | |
7589 | Fetch the previous command from the history list, moving back in | |
7590 | the list. | |
7591 | <DT><B>next-history (C-n)</B> | |
7592 | ||
7593 | <DD> | |
7594 | Fetch the next command from the history list, moving forward in the | |
7595 | list. | |
7596 | <DT><B>beginning-of-history (M-<)</B> | |
7597 | ||
7598 | <DD> | |
7599 | Move to the first line in the history. | |
7600 | <DT><B>end-of-history (M->)</B> | |
7601 | ||
7602 | <DD> | |
7603 | Move to the end of the input history, i.e., the line currently being | |
7604 | entered. | |
7605 | <DT><B>reverse-search-history (C-r)</B> | |
7606 | ||
7607 | <DD> | |
7608 | Search backward starting at the current line and moving `up' through | |
7609 | the history as necessary. This is an incremental search. | |
7610 | <DT><B>forward-search-history (C-s)</B> | |
7611 | ||
7612 | <DD> | |
7613 | Search forward starting at the current line and moving `down' through | |
7614 | the history as necessary. This is an incremental search. | |
7615 | <DT><B>non-incremental-reverse-search-history (M-p)</B> | |
7616 | ||
7617 | <DD> | |
7618 | Search backward through the history starting at the current line | |
7619 | using a non-incremental search for a string supplied by the user. | |
7620 | <DT><B>non-incremental-forward-search-history (M-n)</B> | |
7621 | ||
7622 | <DD> | |
7623 | Search forward through the history using a non-incremental search for | |
7624 | a string supplied by the user. | |
7625 | <DT><B>history-search-forward</B> | |
7626 | ||
7627 | <DD> | |
7628 | Search forward through the history for the string of characters | |
7629 | between the start of the current line and the point. | |
7630 | This is a non-incremental search. | |
7631 | <DT><B>history-search-backward</B> | |
7632 | ||
7633 | <DD> | |
7634 | Search backward through the history for the string of characters | |
7635 | between the start of the current line and the point. | |
7636 | This is a non-incremental search. | |
7637 | <DT><B>yank-nth-arg (M-C-y)</B> | |
7638 | ||
7639 | <DD> | |
7640 | Insert the first argument to the previous command (usually | |
7641 | the second word on the previous line) at point. | |
7642 | With an argument | |
7643 | <I>n</I>, | |
7644 | ||
7645 | insert the <I>n</I>th word from the previous command (the words | |
7646 | in the previous command begin with word 0). A negative argument | |
7647 | inserts the <I>n</I>th word from the end of the previous command. | |
7648 | Once the argument <I>n</I> is computed, the argument is extracted | |
7649 | as if the "!<I>n</I>" history expansion had been specified. | |
7650 | <DT><B>yank-last-arg (M-., M-_)</B> | |
7651 | ||
7652 | <DD> | |
7653 | Insert the last argument to the previous command (the last word of | |
495aee44 CR |
7654 | the previous history entry). |
7655 | With a numeric argument, behave exactly like <B>yank-nth-arg</B>. | |
17345e5a | 7656 | Successive calls to <B>yank-last-arg</B> move back through the history |
495aee44 CR |
7657 | list, inserting the last word (or the word specified by the argument to |
7658 | the first call) of each line in turn. | |
7659 | Any numeric argument supplied to these successive calls determines | |
7660 | the direction to move through the history. A negative argument switches | |
7661 | the direction through the history (back or forward). | |
ac50fbac | 7662 | The history expansion facilities are used to extract the last word, |
17345e5a JA |
7663 | as if the "!$" history expansion had been specified. |
7664 | <DT><B>shell-expand-line (M-C-e)</B> | |
7665 | ||
7666 | <DD> | |
7667 | Expand the line as the shell does. This | |
7668 | performs alias and history expansion as well as all of the shell | |
7669 | word expansions. See | |
7670 | <FONT SIZE=-1><B>HISTORY EXPANSION</B> | |
7671 | ||
7672 | </FONT> | |
7673 | below for a description of history expansion. | |
7674 | <DT><B>history-expand-line (M-^)</B> | |
7675 | ||
7676 | <DD> | |
7677 | Perform history expansion on the current line. | |
7678 | See | |
7679 | <FONT SIZE=-1><B>HISTORY EXPANSION</B> | |
7680 | ||
7681 | </FONT> | |
7682 | below for a description of history expansion. | |
7683 | <DT><B>magic-space</B> | |
7684 | ||
7685 | <DD> | |
7686 | Perform history expansion on the current line and insert a space. | |
7687 | See | |
7688 | <FONT SIZE=-1><B>HISTORY EXPANSION</B> | |
7689 | ||
7690 | </FONT> | |
7691 | below for a description of history expansion. | |
7692 | <DT><B>alias-expand-line</B> | |
7693 | ||
7694 | <DD> | |
7695 | Perform alias expansion on the current line. | |
7696 | See | |
7697 | <FONT SIZE=-1><B>ALIASES</B> | |
7698 | ||
7699 | </FONT> | |
7700 | above for a description of alias expansion. | |
7701 | <DT><B>history-and-alias-expand-line</B> | |
7702 | ||
7703 | <DD> | |
7704 | Perform history and alias expansion on the current line. | |
7705 | <DT><B>insert-last-argument (M-., M-_)</B> | |
7706 | ||
7707 | <DD> | |
7708 | A synonym for <B>yank-last-arg</B>. | |
7709 | <DT><B>operate-and-get-next (C-o)</B> | |
7710 | ||
7711 | <DD> | |
7712 | Accept the current line for execution and fetch the next line | |
7713 | relative to the current line from the history for editing. Any | |
7714 | argument is ignored. | |
7715 | <DT><B>edit-and-execute-command (C-xC-e)</B> | |
7716 | ||
7717 | <DD> | |
7718 | Invoke an editor on the current command line, and execute the result as shell | |
7719 | commands. | |
7720 | <B>Bash</B> attempts to invoke | |
7721 | <FONT SIZE=-1><B>$VISUAL</B>, | |
7722 | ||
7723 | </FONT> | |
7724 | <FONT SIZE=-1><B>$EDITOR</B>, | |
7725 | ||
7726 | </FONT> | |
7727 | and <I>emacs</I> as the editor, in that order. | |
7728 | ||
7729 | </DL> | |
7730 | <A NAME="lbCP"> </A> | |
7731 | <H4>Commands for Changing Text</H4> | |
7732 | ||
7733 | <P> | |
7734 | ||
7735 | ||
7736 | <DL COMPACT> | |
ac50fbac | 7737 | <DT><B></B><I>end-of-file</I> (usually C-d) |
17345e5a JA |
7738 | |
7739 | <DD> | |
ac50fbac CR |
7740 | The character indicating end-of-file as set, for example, by |
7741 | <TT>stty</TT>. | |
7742 | ||
7743 | If this character is read when there are no characters | |
7744 | on the line, and point is at the beginning of the line, Readline | |
7745 | interprets it as the end of input and returns | |
17345e5a JA |
7746 | <FONT SIZE=-1><B>EOF</B>. |
7747 | ||
7748 | </FONT> | |
ac50fbac CR |
7749 | <DT><B>delete-char (C-d)</B> |
7750 | ||
7751 | <DD> | |
7752 | Delete the character at point. | |
7753 | If this function is bound to the | |
7754 | same character as the tty <B>EOF</B> character, as <B>C-d</B> | |
7755 | commonly is, see above for the effects. | |
17345e5a JA |
7756 | <DT><B>backward-delete-char (Rubout)</B> |
7757 | ||
7758 | <DD> | |
7759 | Delete the character behind the cursor. When given a numeric argument, | |
7760 | save the deleted text on the kill ring. | |
7761 | <DT><B>forward-backward-delete-char</B> | |
7762 | ||
7763 | <DD> | |
7764 | Delete the character under the cursor, unless the cursor is at the | |
7765 | end of the line, in which case the character behind the cursor is | |
7766 | deleted. | |
7767 | <DT><B>quoted-insert (C-q, C-v)</B> | |
7768 | ||
7769 | <DD> | |
7770 | Add the next character typed to the line verbatim. This is | |
7771 | how to insert characters like <B>C-q</B>, for example. | |
7772 | <DT><B>tab-insert (C-v TAB)</B> | |
7773 | ||
7774 | <DD> | |
7775 | Insert a tab character. | |
7776 | <DT><B>self-insert (a, b, A, 1, !, ...)</B> | |
7777 | ||
7778 | <DD> | |
7779 | Insert the character typed. | |
7780 | <DT><B>transpose-chars (C-t)</B> | |
7781 | ||
7782 | <DD> | |
7783 | Drag the character before point forward over the character at point, | |
7784 | moving point forward as well. | |
7785 | If point is at the end of the line, then this transposes | |
7786 | the two characters before point. | |
7787 | Negative arguments have no effect. | |
7788 | <DT><B>transpose-words (M-t)</B> | |
7789 | ||
7790 | <DD> | |
7791 | Drag the word before point past the word after point, | |
7792 | moving point over that word as well. | |
7793 | If point is at the end of the line, this transposes | |
a0c0a00f | 7794 | the last two words on the line. |
17345e5a JA |
7795 | <DT><B>upcase-word (M-u)</B> |
7796 | ||
7797 | <DD> | |
7798 | Uppercase the current (or following) word. With a negative argument, | |
7799 | uppercase the previous word, but do not move point. | |
7800 | <DT><B>downcase-word (M-l)</B> | |
7801 | ||
7802 | <DD> | |
7803 | Lowercase the current (or following) word. With a negative argument, | |
7804 | lowercase the previous word, but do not move point. | |
7805 | <DT><B>capitalize-word (M-c)</B> | |
7806 | ||
7807 | <DD> | |
7808 | Capitalize the current (or following) word. With a negative argument, | |
7809 | capitalize the previous word, but do not move point. | |
7810 | <DT><B>overwrite-mode</B> | |
7811 | ||
7812 | <DD> | |
7813 | Toggle overwrite mode. With an explicit positive numeric argument, | |
7814 | switches to overwrite mode. With an explicit non-positive numeric | |
7815 | argument, switches to insert mode. This command affects only | |
7816 | <B>emacs</B> mode; <B>vi</B> mode does overwrite differently. | |
7817 | Each call to <I>readline()</I> starts in insert mode. | |
a0c0a00f | 7818 | In overwrite mode, characters bound to <B>self-insert</B> replace |
17345e5a JA |
7819 | the text at point rather than pushing the text to the right. |
7820 | Characters bound to <B>backward-delete-char</B> replace the character | |
7821 | before point with a space. By default, this command is unbound. | |
7822 | ||
7823 | </DL> | |
7824 | <A NAME="lbCQ"> </A> | |
7825 | <H4>Killing and Yanking</H4> | |
7826 | ||
7827 | <P> | |
7828 | ||
7829 | ||
7830 | <DL COMPACT> | |
7831 | <DT><B>kill-line (C-k)</B> | |
7832 | ||
7833 | <DD> | |
7834 | Kill the text from point to the end of the line. | |
7835 | <DT><B>backward-kill-line (C-x Rubout)</B> | |
7836 | ||
7837 | <DD> | |
7838 | Kill backward to the beginning of the line. | |
7839 | <DT><B>unix-line-discard (C-u)</B> | |
7840 | ||
7841 | <DD> | |
7842 | Kill backward from point to the beginning of the line. | |
7843 | The killed text is saved on the kill-ring. | |
7844 | ||
7845 | <DT><B>kill-whole-line</B> | |
7846 | ||
7847 | <DD> | |
7848 | Kill all characters on the current line, no matter where point is. | |
a0c0a00f | 7849 | <DT><B>kill-word (M-d)</B> |
17345e5a JA |
7850 | |
7851 | <DD> | |
7852 | Kill from point to the end of the current word, or if between | |
7853 | words, to the end of the next word. | |
7854 | Word boundaries are the same as those used by <B>forward-word</B>. | |
7855 | <DT><B>backward-kill-word (M-Rubout)</B> | |
7856 | ||
7857 | <DD> | |
7858 | Kill the word behind point. | |
7859 | Word boundaries are the same as those used by <B>backward-word</B>. | |
a0c0a00f | 7860 | <DT><B>shell-kill-word</B> |
17345e5a JA |
7861 | |
7862 | <DD> | |
7863 | Kill from point to the end of the current word, or if between | |
7864 | words, to the end of the next word. | |
7865 | Word boundaries are the same as those used by <B>shell-forward-word</B>. | |
a0c0a00f | 7866 | <DT><B>shell-backward-kill-word</B> |
17345e5a JA |
7867 | |
7868 | <DD> | |
7869 | Kill the word behind point. | |
7870 | Word boundaries are the same as those used by <B>shell-backward-word</B>. | |
7871 | <DT><B>unix-word-rubout (C-w)</B> | |
7872 | ||
7873 | <DD> | |
7874 | Kill the word behind point, using white space as a word boundary. | |
7875 | The killed text is saved on the kill-ring. | |
7876 | <DT><B>unix-filename-rubout</B> | |
7877 | ||
7878 | <DD> | |
7879 | Kill the word behind point, using white space and the slash character | |
7880 | as the word boundaries. | |
7881 | The killed text is saved on the kill-ring. | |
7882 | <DT><B>delete-horizontal-space (M-\)</B> | |
7883 | ||
7884 | <DD> | |
7885 | Delete all spaces and tabs around point. | |
7886 | <DT><B>kill-region</B> | |
7887 | ||
7888 | <DD> | |
7889 | Kill the text in the current region. | |
7890 | <DT><B>copy-region-as-kill</B> | |
7891 | ||
7892 | <DD> | |
7893 | Copy the text in the region to the kill buffer. | |
7894 | <DT><B>copy-backward-word</B> | |
7895 | ||
7896 | <DD> | |
7897 | Copy the word before point to the kill buffer. | |
7898 | The word boundaries are the same as <B>backward-word</B>. | |
7899 | <DT><B>copy-forward-word</B> | |
7900 | ||
7901 | <DD> | |
7902 | Copy the word following point to the kill buffer. | |
7903 | The word boundaries are the same as <B>forward-word</B>. | |
7904 | <DT><B>yank (C-y)</B> | |
7905 | ||
7906 | <DD> | |
7907 | Yank the top of the kill ring into the buffer at point. | |
7908 | <DT><B>yank-pop (M-y)</B> | |
7909 | ||
7910 | <DD> | |
7911 | Rotate the kill ring, and yank the new top. Only works following | |
7912 | <B>yank</B> | |
7913 | ||
7914 | or | |
7915 | <B>yank-pop</B>. | |
7916 | ||
7917 | ||
7918 | </DL> | |
7919 | <A NAME="lbCR"> </A> | |
7920 | <H4>Numeric Arguments</H4> | |
7921 | ||
7922 | <P> | |
7923 | ||
7924 | ||
7925 | <DL COMPACT> | |
7926 | <DT><B>digit-argument (M-0, M-1, ..., M--)</B> | |
7927 | ||
7928 | <DD> | |
7929 | Add this digit to the argument already accumulating, or start a new | |
7930 | argument. M-- starts a negative argument. | |
7931 | <DT><B>universal-argument</B> | |
7932 | ||
7933 | <DD> | |
7934 | This is another way to specify an argument. | |
7935 | If this command is followed by one or more digits, optionally with a | |
7936 | leading minus sign, those digits define the argument. | |
7937 | If the command is followed by digits, executing | |
7938 | <B>universal-argument</B> | |
7939 | ||
7940 | again ends the numeric argument, but is otherwise ignored. | |
7941 | As a special case, if this command is immediately followed by a | |
a0c0a00f | 7942 | character that is neither a digit nor minus sign, the argument count |
17345e5a JA |
7943 | for the next command is multiplied by four. |
7944 | The argument count is initially one, so executing this function the | |
7945 | first time makes the argument count four, a second time makes the | |
7946 | argument count sixteen, and so on. | |
7947 | ||
7948 | </DL> | |
7949 | <A NAME="lbCS"> </A> | |
7950 | <H4>Completing</H4> | |
7951 | ||
7952 | <P> | |
7953 | ||
7954 | ||
7955 | <DL COMPACT> | |
7956 | <DT><B>complete (TAB)</B> | |
7957 | ||
7958 | <DD> | |
7959 | Attempt to perform completion on the text before point. | |
7960 | <B>Bash</B> | |
7961 | ||
7962 | attempts completion treating the text as a variable (if the | |
7963 | text begins with <B>$</B>), username (if the text begins with | |
7964 | <B>~</B>), hostname (if the text begins with <B>@</B>), or | |
7965 | command (including aliases and functions) in turn. If none | |
7966 | of these produces a match, filename completion is attempted. | |
7967 | <DT><B>possible-completions (M-?)</B> | |
7968 | ||
7969 | <DD> | |
7970 | List the possible completions of the text before point. | |
7971 | <DT><B>insert-completions (M-*)</B> | |
7972 | ||
7973 | <DD> | |
7974 | Insert all completions of the text before point | |
7975 | that would have been generated by | |
7976 | <B>possible-completions</B>. | |
7977 | <DT><B>menu-complete</B> | |
7978 | ||
7979 | <DD> | |
7980 | Similar to <B>complete</B>, but replaces the word to be completed | |
7981 | with a single match from the list of possible completions. | |
7982 | Repeated execution of <B>menu-complete</B> steps through the list | |
7983 | of possible completions, inserting each match in turn. | |
7984 | At the end of the list of completions, the bell is rung | |
7985 | (subject to the setting of <B>bell-style</B>) | |
7986 | and the original text is restored. | |
7987 | An argument of <I>n</I> moves <I>n</I> positions forward in the list | |
7988 | of matches; a negative argument may be used to move backward | |
7989 | through the list. | |
7990 | This command is intended to be bound to <B>TAB</B>, but is unbound | |
7991 | by default. | |
495aee44 | 7992 | <DT><B>menu-complete-backward</B> |
0001803f CR |
7993 | |
7994 | <DD> | |
7995 | Identical to <B>menu-complete</B>, but moves backward through the list | |
7996 | of possible completions, as if <B>menu-complete</B> had been given a | |
7997 | negative argument. This command is unbound by default. | |
17345e5a JA |
7998 | <DT><B>delete-char-or-list</B> |
7999 | ||
8000 | <DD> | |
8001 | Deletes the character under the cursor if not at the beginning or | |
8002 | end of the line (like <B>delete-char</B>). | |
8003 | If at the end of the line, behaves identically to | |
8004 | <B>possible-completions</B>. | |
8005 | This command is unbound by default. | |
8006 | <DT><B>complete-filename (M-/)</B> | |
8007 | ||
8008 | <DD> | |
8009 | Attempt filename completion on the text before point. | |
8010 | <DT><B>possible-filename-completions (C-x /)</B> | |
8011 | ||
8012 | <DD> | |
8013 | List the possible completions of the text before point, | |
8014 | treating it as a filename. | |
8015 | <DT><B>complete-username (M-~)</B> | |
8016 | ||
8017 | <DD> | |
8018 | Attempt completion on the text before point, treating | |
8019 | it as a username. | |
8020 | <DT><B>possible-username-completions (C-x ~)</B> | |
8021 | ||
8022 | <DD> | |
8023 | List the possible completions of the text before point, | |
8024 | treating it as a username. | |
8025 | <DT><B>complete-variable (M-$)</B> | |
8026 | ||
8027 | <DD> | |
8028 | Attempt completion on the text before point, treating | |
8029 | it as a shell variable. | |
8030 | <DT><B>possible-variable-completions (C-x $)</B> | |
8031 | ||
8032 | <DD> | |
8033 | List the possible completions of the text before point, | |
8034 | treating it as a shell variable. | |
8035 | <DT><B>complete-hostname (M-@)</B> | |
8036 | ||
8037 | <DD> | |
8038 | Attempt completion on the text before point, treating | |
8039 | it as a hostname. | |
8040 | <DT><B>possible-hostname-completions (C-x @)</B> | |
8041 | ||
8042 | <DD> | |
8043 | List the possible completions of the text before point, | |
8044 | treating it as a hostname. | |
8045 | <DT><B>complete-command (M-!)</B> | |
8046 | ||
8047 | <DD> | |
8048 | Attempt completion on the text before point, treating | |
8049 | it as a command name. Command completion attempts to | |
8050 | match the text against aliases, reserved words, shell | |
8051 | functions, shell builtins, and finally executable filenames, | |
8052 | in that order. | |
8053 | <DT><B>possible-command-completions (C-x !)</B> | |
8054 | ||
8055 | <DD> | |
8056 | List the possible completions of the text before point, | |
8057 | treating it as a command name. | |
8058 | <DT><B>dynamic-complete-history (M-TAB)</B> | |
8059 | ||
8060 | <DD> | |
8061 | Attempt completion on the text before point, comparing | |
8062 | the text against lines from the history list for possible | |
8063 | completion matches. | |
8064 | <DT><B>dabbrev-expand</B> | |
8065 | ||
8066 | <DD> | |
8067 | Attempt menu completion on the text before point, comparing | |
8068 | the text against lines from the history list for possible | |
8069 | completion matches. | |
8070 | <DT><B>complete-into-braces (M-{)</B> | |
8071 | ||
8072 | <DD> | |
8073 | Perform filename completion and insert the list of possible completions | |
8074 | enclosed within braces so the list is available to the shell (see | |
8075 | <B>Brace Expansion</B> | |
8076 | ||
8077 | above). | |
8078 | ||
8079 | </DL> | |
8080 | <A NAME="lbCT"> </A> | |
8081 | <H4>Keyboard Macros</H4> | |
8082 | ||
8083 | <P> | |
8084 | ||
8085 | ||
8086 | <DL COMPACT> | |
8087 | <DT><B>start-kbd-macro (C-x ()</B> | |
8088 | ||
8089 | <DD> | |
8090 | Begin saving the characters typed into the current keyboard macro. | |
8091 | <DT><B>end-kbd-macro (C-x ))</B> | |
8092 | ||
8093 | <DD> | |
8094 | Stop saving the characters typed into the current keyboard macro | |
8095 | and store the definition. | |
8096 | <DT><B>call-last-kbd-macro (C-x e)</B> | |
8097 | ||
8098 | <DD> | |
8099 | Re-execute the last keyboard macro defined, by making the characters | |
8100 | in the macro appear as if typed at the keyboard. | |
ac50fbac CR |
8101 | <DT><B>print-last-kbd-macro ()</B> |
8102 | ||
8103 | <DD> | |
8104 | Print the last keyboard macro defined in a format suitable for the | |
8105 | <I>inputrc</I> file. | |
17345e5a JA |
8106 | |
8107 | </DL> | |
8108 | <A NAME="lbCU"> </A> | |
8109 | <H4>Miscellaneous</H4> | |
8110 | ||
8111 | <P> | |
8112 | ||
8113 | ||
8114 | <DL COMPACT> | |
8115 | <DT><B>re-read-init-file (C-x C-r)</B> | |
8116 | ||
8117 | <DD> | |
8118 | Read in the contents of the <I>inputrc</I> file, and incorporate | |
8119 | any bindings or variable assignments found there. | |
8120 | <DT><B>abort (C-g)</B> | |
8121 | ||
8122 | <DD> | |
8123 | Abort the current editing command and | |
8124 | ring the terminal's bell (subject to the setting of | |
8125 | <B>bell-style</B>). | |
8126 | ||
8127 | <DT><B>do-uppercase-version (M-a, M-b, M-</B><I>x</I>, ...) | |
8128 | ||
8129 | <DD> | |
8130 | If the metafied character <I>x</I> is lowercase, run the command | |
8131 | that is bound to the corresponding uppercase character. | |
8132 | <DT><B>prefix-meta (ESC)</B> | |
8133 | ||
8134 | <DD> | |
8135 | Metafy the next character typed. | |
8136 | <FONT SIZE=-1><B>ESC</B> | |
8137 | ||
8138 | </FONT> | |
8139 | <B>f</B> | |
8140 | ||
8141 | is equivalent to | |
8142 | <B>Meta-f</B>. | |
8143 | ||
8144 | <DT><B>undo (C-_, C-x C-u)</B> | |
8145 | ||
8146 | <DD> | |
8147 | Incremental undo, separately remembered for each line. | |
8148 | <DT><B>revert-line (M-r)</B> | |
8149 | ||
8150 | <DD> | |
8151 | Undo all changes made to this line. This is like executing the | |
8152 | <B>undo</B> | |
8153 | ||
8154 | command enough times to return the line to its initial state. | |
8155 | <DT><B>tilde-expand (M-&)</B> | |
8156 | ||
8157 | <DD> | |
8158 | Perform tilde expansion on the current word. | |
8159 | <DT><B>set-mark (C-@, M-<space>)</B> | |
8160 | ||
8161 | <DD> | |
8162 | Set the mark to the point. If a | |
8163 | numeric argument is supplied, the mark is set to that position. | |
8164 | <DT><B>exchange-point-and-mark (C-x C-x)</B> | |
8165 | ||
8166 | <DD> | |
8167 | Swap the point with the mark. The current cursor position is set to | |
8168 | the saved position, and the old cursor position is saved as the mark. | |
8169 | <DT><B>character-search (C-])</B> | |
8170 | ||
8171 | <DD> | |
8172 | A character is read and point is moved to the next occurrence of that | |
8173 | character. A negative count searches for previous occurrences. | |
8174 | <DT><B>character-search-backward (M-C-])</B> | |
8175 | ||
8176 | <DD> | |
8177 | A character is read and point is moved to the previous occurrence of that | |
8178 | character. A negative count searches for subsequent occurrences. | |
495aee44 | 8179 | <DT><B>skip-csi-sequence</B> |
0001803f CR |
8180 | |
8181 | <DD> | |
8182 | Read enough characters to consume a multi-key sequence such as those | |
8183 | defined for keys like Home and End. Such sequences begin with a | |
8184 | Control Sequence Indicator (CSI), usually ESC-[. If this sequence is | |
8185 | bound to "\[", keys producing such sequences will have no effect | |
8186 | unless explicitly bound to a readline command, instead of inserting | |
8187 | stray characters into the editing buffer. This is unbound by default, | |
8188 | but usually bound to ESC-[. | |
17345e5a JA |
8189 | <DT><B>insert-comment (M-#)</B> |
8190 | ||
8191 | <DD> | |
8192 | Without a numeric argument, the value of the readline | |
8193 | <B>comment-begin</B> | |
8194 | ||
8195 | variable is inserted at the beginning of the current line. | |
a0c0a00f | 8196 | If a numeric argument is supplied, this command acts as a toggle: if |
17345e5a JA |
8197 | the characters at the beginning of the line do not match the value |
8198 | of <B>comment-begin</B>, the value is inserted, otherwise | |
a0c0a00f | 8199 | the characters in <B>comment-begin</B> are deleted from the beginning of |
17345e5a JA |
8200 | the line. |
8201 | In either case, the line is accepted as if a newline had been typed. | |
8202 | The default value of | |
8203 | <B>comment-begin</B> causes this command to make the current line | |
8204 | a shell comment. | |
8205 | If a numeric argument causes the comment character to be removed, the line | |
8206 | will be executed by the shell. | |
8207 | <DT><B>glob-complete-word (M-g)</B> | |
8208 | ||
8209 | <DD> | |
8210 | The word before point is treated as a pattern for pathname expansion, | |
8211 | with an asterisk implicitly appended. This pattern is used to | |
ac50fbac | 8212 | generate a list of matching filenames for possible completions. |
17345e5a JA |
8213 | <DT><B>glob-expand-word (C-x *)</B> |
8214 | ||
8215 | <DD> | |
8216 | The word before point is treated as a pattern for pathname expansion, | |
ac50fbac | 8217 | and the list of matching filenames is inserted, replacing the word. |
17345e5a JA |
8218 | If a numeric argument is supplied, an asterisk is appended before |
8219 | pathname expansion. | |
8220 | <DT><B>glob-list-expansions (C-x g)</B> | |
8221 | ||
8222 | <DD> | |
8223 | The list of expansions that would have been generated by | |
8224 | <B>glob-expand-word</B> | |
8225 | ||
8226 | is displayed, and the line is redrawn. | |
8227 | If a numeric argument is supplied, an asterisk is appended before | |
8228 | pathname expansion. | |
8229 | <DT><B>dump-functions</B> | |
8230 | ||
8231 | <DD> | |
8232 | Print all of the functions and their key bindings to the | |
8233 | readline output stream. If a numeric argument is supplied, | |
8234 | the output is formatted in such a way that it can be made part | |
8235 | of an <I>inputrc</I> file. | |
8236 | <DT><B>dump-variables</B> | |
8237 | ||
8238 | <DD> | |
8239 | Print all of the settable readline variables and their values to the | |
8240 | readline output stream. If a numeric argument is supplied, | |
8241 | the output is formatted in such a way that it can be made part | |
8242 | of an <I>inputrc</I> file. | |
8243 | <DT><B>dump-macros</B> | |
8244 | ||
8245 | <DD> | |
8246 | Print all of the readline key sequences bound to macros and the | |
8247 | strings they output. If a numeric argument is supplied, | |
8248 | the output is formatted in such a way that it can be made part | |
8249 | of an <I>inputrc</I> file. | |
8250 | <DT><B>display-shell-version (C-x C-v)</B> | |
8251 | ||
8252 | <DD> | |
8253 | Display version information about the current instance of | |
8254 | <B>bash</B>. | |
8255 | ||
8256 | ||
8257 | </DL> | |
8258 | <A NAME="lbCV"> </A> | |
8259 | <H4>Programmable Completion</H4> | |
8260 | ||
8261 | <P> | |
8262 | ||
8263 | When word completion is attempted for an argument to a command for | |
8264 | which a completion specification (a <I>compspec</I>) has been defined | |
8265 | using the <B>complete</B> builtin (see | |
8266 | <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B> | |
8267 | ||
8268 | </FONT> | |
8269 | below), the programmable completion facilities are invoked. | |
8270 | <P> | |
8271 | ||
8272 | First, the command name is identified. | |
0001803f CR |
8273 | If the command word is the empty string (completion attempted at the |
8274 | beginning of an empty line), any compspec defined with | |
8275 | the <B>-E</B> option to <B>complete</B> is used. | |
17345e5a JA |
8276 | If a compspec has been defined for that command, the |
8277 | compspec is used to generate the list of possible completions for the word. | |
8278 | If the command word is a full pathname, a compspec for the full | |
8279 | pathname is searched for first. | |
8280 | If no compspec is found for the full pathname, an attempt is made to | |
8281 | find a compspec for the portion following the final slash. | |
495aee44 | 8282 | If those searches do not result in a compspec, any compspec defined with |
0001803f | 8283 | the <B>-D</B> option to <B>complete</B> is used as the default. |
17345e5a JA |
8284 | <P> |
8285 | ||
8286 | Once a compspec has been found, it is used to generate the list of | |
8287 | matching words. | |
8288 | If a compspec is not found, the default <B>bash</B> completion as | |
8289 | described above under <B>Completing</B> is performed. | |
8290 | <P> | |
8291 | ||
8292 | First, the actions specified by the compspec are used. | |
8293 | Only matches which are prefixed by the word being completed are | |
8294 | returned. | |
8295 | When the | |
8296 | <B>-f</B> | |
8297 | ||
8298 | or | |
8299 | <B>-d</B> | |
8300 | ||
8301 | option is used for filename or directory name completion, the shell | |
8302 | variable | |
8303 | <FONT SIZE=-1><B>FIGNORE</B> | |
8304 | ||
8305 | </FONT> | |
8306 | is used to filter the matches. | |
8307 | <P> | |
8308 | ||
0001803f | 8309 | Any completions specified by a pathname expansion pattern to the |
17345e5a JA |
8310 | <B>-G</B> option are generated next. |
8311 | The words generated by the pattern need not match the word | |
8312 | being completed. | |
8313 | The | |
8314 | <FONT SIZE=-1><B>GLOBIGNORE</B> | |
8315 | ||
8316 | </FONT> | |
8317 | shell variable is not used to filter the matches, but the | |
8318 | <FONT SIZE=-1><B>FIGNORE</B> | |
8319 | ||
8320 | </FONT> | |
8321 | variable is used. | |
8322 | <P> | |
8323 | ||
8324 | Next, the string specified as the argument to the <B>-W</B> option | |
8325 | is considered. | |
8326 | The string is first split using the characters in the | |
8327 | <FONT SIZE=-1><B>IFS</B> | |
8328 | ||
8329 | </FONT> | |
8330 | special variable as delimiters. | |
8331 | Shell quoting is honored. | |
8332 | Each word is then expanded using | |
8333 | brace expansion, tilde expansion, parameter and variable expansion, | |
8334 | command substitution, and arithmetic expansion, | |
a0c0a00f | 8335 | as described above under |
17345e5a JA |
8336 | <FONT SIZE=-1><B>EXPANSION</B>. |
8337 | ||
8338 | </FONT> | |
8339 | The results are split using the rules described above under | |
8340 | <B>Word Splitting</B>. | |
8341 | The results of the expansion are prefix-matched against the word being | |
8342 | completed, and the matching words become the possible completions. | |
8343 | <P> | |
8344 | ||
8345 | After these matches have been generated, any shell function or command | |
8346 | specified with the <B>-F</B> and <B>-C</B> options is invoked. | |
8347 | When the command or function is invoked, the | |
8348 | <FONT SIZE=-1><B>COMP_LINE</B>, | |
8349 | ||
8350 | </FONT> | |
8351 | <FONT SIZE=-1><B>COMP_POINT</B>, | |
8352 | ||
8353 | </FONT> | |
8354 | <FONT SIZE=-1><B>COMP_KEY</B>, | |
8355 | ||
8356 | </FONT> | |
8357 | and | |
8358 | <FONT SIZE=-1><B>COMP_TYPE</B> | |
8359 | ||
8360 | </FONT> | |
8361 | variables are assigned values as described above under | |
8362 | <B>Shell Variables</B>. | |
a0c0a00f | 8363 | If a shell function is being invoked, the |
17345e5a JA |
8364 | <FONT SIZE=-1><B>COMP_WORDS</B> |
8365 | ||
8366 | </FONT> | |
8367 | and | |
8368 | <FONT SIZE=-1><B>COMP_CWORD</B> | |
8369 | ||
8370 | </FONT> | |
8371 | variables are also set. | |
ac50fbac CR |
8372 | When the function or command is invoked, |
8373 | the first argument (<B>$1</B>) is the name of the command whose arguments are | |
8374 | being completed, | |
8375 | the second argument (<B>$2</B>) is the word being completed, | |
8376 | and the third argument (<B>$3</B>) is the word preceding the word being | |
8377 | completed on the current command line. | |
17345e5a JA |
8378 | No filtering of the generated completions against the word being completed |
8379 | is performed; the function or command has complete freedom in generating | |
8380 | the matches. | |
8381 | <P> | |
8382 | ||
8383 | Any function specified with <B>-F</B> is invoked first. | |
8384 | The function may use any of the shell facilities, including the | |
8385 | <B>compgen</B> builtin described below, to generate the matches. | |
8386 | It must put the possible completions in the | |
8387 | <FONT SIZE=-1><B>COMPREPLY</B> | |
8388 | ||
8389 | </FONT> | |
ac50fbac | 8390 | array variable, one per array element. |
17345e5a JA |
8391 | <P> |
8392 | ||
8393 | Next, any command specified with the <B>-C</B> option is invoked | |
8394 | in an environment equivalent to command substitution. | |
8395 | It should print a list of completions, one per line, to the | |
8396 | standard output. | |
8397 | Backslash may be used to escape a newline, if necessary. | |
8398 | <P> | |
8399 | ||
8400 | After all of the possible completions are generated, any filter | |
8401 | specified with the <B>-X</B> option is applied to the list. | |
8402 | The filter is a pattern as used for pathname expansion; a <B>&</B> | |
8403 | in the pattern is replaced with the text of the word being completed. | |
8404 | A literal <B>&</B> may be escaped with a backslash; the backslash | |
8405 | is removed before attempting a match. | |
8406 | Any completion that matches the pattern will be removed from the list. | |
8407 | A leading <B>!</B> negates the pattern; in this case any completion | |
8408 | not matching the pattern will be removed. | |
a0c0a00f CR |
8409 | If the |
8410 | <B>nocasematch</B> | |
8411 | ||
8412 | shell option is enabled, the match is performed without regard to the case | |
8413 | of alphabetic characters. | |
17345e5a JA |
8414 | <P> |
8415 | ||
8416 | Finally, any prefix and suffix specified with the <B>-P</B> and <B>-S</B> | |
8417 | options are added to each member of the completion list, and the result is | |
8418 | returned to the readline completion code as the list of possible | |
8419 | completions. | |
8420 | <P> | |
8421 | ||
8422 | If the previously-applied actions do not generate any matches, and the | |
8423 | <B>-o dirnames</B> option was supplied to <B>complete</B> when the | |
8424 | compspec was defined, directory name completion is attempted. | |
8425 | <P> | |
8426 | ||
8427 | If the <B>-o plusdirs</B> option was supplied to <B>complete</B> when the | |
8428 | compspec was defined, directory name completion is attempted and any | |
8429 | matches are added to the results of the other actions. | |
8430 | <P> | |
8431 | ||
8432 | By default, if a compspec is found, whatever it generates is returned | |
8433 | to the completion code as the full set of possible completions. | |
8434 | The default <B>bash</B> completions are not attempted, and the readline | |
8435 | default of filename completion is disabled. | |
8436 | If the <B>-o bashdefault</B> option was supplied to <B>complete</B> when | |
8437 | the compspec was defined, the <B>bash</B> default completions are attempted | |
8438 | if the compspec generates no matches. | |
8439 | If the <B>-o default</B> option was supplied to <B>complete</B> when the | |
8440 | compspec was defined, readline's default completion will be performed | |
8441 | if the compspec (and, if attempted, the default <B>bash</B> completions) | |
8442 | generate no matches. | |
8443 | <P> | |
8444 | ||
8445 | When a compspec indicates that directory name completion is desired, | |
8446 | the programmable completion functions force readline to append a slash | |
a0c0a00f | 8447 | to completed names which are symbolic links to directories, subject to |
17345e5a JA |
8448 | the value of the <B>mark-directories</B> readline variable, regardless |
8449 | of the setting of the <B>mark-symlinked-directories</B> readline variable. | |
0001803f CR |
8450 | <P> |
8451 | ||
8452 | There is some support for dynamically modifying completions. This is | |
8453 | most useful when used in combination with a default completion specified | |
8454 | with <B>complete -D</B>. | |
8455 | It's possible for shell functions executed as completion | |
8456 | handlers to indicate that completion should be retried by returning an | |
8457 | exit status of 124. If a shell function returns 124, and changes | |
8458 | the compspec associated with the command on which completion is being | |
8459 | attempted (supplied as the first argument when the function is executed), | |
8460 | programmable completion restarts from the beginning, with an | |
495aee44 | 8461 | attempt to find a new compspec for that command. This allows a set of |
0001803f CR |
8462 | completions to be built dynamically as completion is attempted, rather than |
8463 | being loaded all at once. | |
8464 | <P> | |
8465 | ||
8466 | For instance, assuming that there is a library of compspecs, each kept in a | |
8467 | file corresponding to the name of the command, the following default | |
8468 | completion function would load completions dynamically: | |
8469 | <P> | |
8470 | ||
8471 | <TT>_completion_loader() | |
8472 | <BR> | |
8473 | ||
8474 | { | |
8475 | <BR> | |
8476 | ||
8477 | <TT> </TT>. "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124<BR> | |
8478 | <BR> | |
8479 | ||
8480 | } | |
8481 | <BR> | |
8482 | ||
ac50fbac | 8483 | complete -D -F _completion_loader -o bashdefault -o default |
0001803f CR |
8484 | <BR> |
8485 | ||
8486 | </TT> | |
17345e5a JA |
8487 | <A NAME="lbCW"> </A> |
8488 | <H3>HISTORY</H3> | |
8489 | ||
8490 | When the | |
8491 | <B>-o history</B> | |
8492 | ||
8493 | option to the | |
8494 | <B>set</B> | |
8495 | ||
8496 | builtin is enabled, the shell provides access to the | |
8497 | <I>command history</I>, | |
8498 | the list of commands previously typed. | |
0001803f CR |
8499 | The value of the |
8500 | <FONT SIZE=-1><B>HISTSIZE</B> | |
8501 | ||
8502 | </FONT> | |
8503 | variable is used as the | |
17345e5a JA |
8504 | number of commands to save in a history list. |
8505 | The text of the last | |
8506 | <FONT SIZE=-1><B>HISTSIZE</B> | |
8507 | ||
8508 | </FONT> | |
8509 | commands (default 500) is saved. The shell | |
8510 | stores each command in the history list prior to parameter and | |
8511 | variable expansion (see | |
8512 | <FONT SIZE=-1><B>EXPANSION</B> | |
8513 | ||
8514 | </FONT> | |
8515 | above) but after history expansion is performed, subject to the | |
8516 | values of the shell variables | |
8517 | <FONT SIZE=-1><B>HISTIGNORE</B> | |
8518 | ||
8519 | </FONT> | |
8520 | and | |
8521 | <FONT SIZE=-1><B>HISTCONTROL</B>. | |
8522 | ||
8523 | </FONT> | |
8524 | <P> | |
8525 | ||
8526 | On startup, the history is initialized from the file named by | |
8527 | the variable | |
8528 | <FONT SIZE=-1><B>HISTFILE</B> | |
8529 | ||
8530 | </FONT> | |
8531 | (default <A HREF="file:~/.bash_history"><I>~/.bash_history</I></A>). | |
8532 | The file named by the value of | |
8533 | <FONT SIZE=-1><B>HISTFILE</B> | |
8534 | ||
8535 | </FONT> | |
8536 | is truncated, if necessary, to contain no more than | |
8537 | the number of lines specified by the value of | |
8538 | <FONT SIZE=-1><B>HISTFILESIZE</B>. | |
8539 | ||
8540 | </FONT> | |
ac50fbac CR |
8541 | If <B>HISTFILESIZE</B> is unset, or set to null, a non-numeric value, |
8542 | or a numeric value less than zero, the history file is not truncated. | |
17345e5a JA |
8543 | When the history file is read, |
8544 | lines beginning with the history comment character followed immediately | |
8545 | by a digit are interpreted as timestamps for the preceding history line. | |
8546 | These timestamps are optionally displayed depending on the value of the | |
8547 | <FONT SIZE=-1><B>HISTTIMEFORMAT</B> | |
8548 | ||
8549 | </FONT> | |
8550 | variable. | |
ac50fbac | 8551 | When a shell with history enabled exits, the last |
17345e5a JA |
8552 | <FONT SIZE=-1><B>$HISTSIZE</B> |
8553 | ||
8554 | </FONT> | |
8555 | lines are copied from the history list to | |
8556 | <FONT SIZE=-1><B>$HISTFILE</B>. | |
8557 | ||
8558 | </FONT> | |
8559 | If the | |
8560 | <B>histappend</B> | |
8561 | ||
8562 | shell option is enabled | |
8563 | (see the description of | |
8564 | <B>shopt</B> | |
8565 | ||
8566 | under | |
8567 | <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B> | |
8568 | ||
8569 | </FONT> | |
8570 | below), the lines are appended to the history file, | |
8571 | otherwise the history file is overwritten. | |
8572 | If | |
8573 | <FONT SIZE=-1><B>HISTFILE</B> | |
8574 | ||
8575 | </FONT> | |
8576 | is unset, or if the history file is unwritable, the history is | |
8577 | not saved. | |
8578 | If the | |
0001803f CR |
8579 | <FONT SIZE=-1><B>HISTTIMEFORMAT</B> |
8580 | ||
17345e5a JA |
8581 | </FONT> |
8582 | variable is set, time stamps are written to the history file, marked | |
8583 | with the history comment character, so | |
8584 | they may be preserved across shell sessions. | |
8585 | This uses the history comment character to distinguish timestamps from | |
8586 | other history lines. | |
8587 | After saving the history, the history file is truncated | |
8588 | to contain no more than | |
8589 | <FONT SIZE=-1><B>HISTFILESIZE</B> | |
8590 | ||
8591 | </FONT> | |
8592 | lines. If | |
8593 | <FONT SIZE=-1><B>HISTFILESIZE</B> | |
8594 | ||
8595 | </FONT> | |
ac50fbac CR |
8596 | is unset, or set to null, a non-numeric value, |
8597 | or a numeric value less than zero, the history file is not truncated. | |
17345e5a JA |
8598 | <P> |
8599 | ||
8600 | The builtin command | |
8601 | <B>fc</B> | |
8602 | ||
8603 | (see | |
8604 | <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B> | |
8605 | ||
8606 | </FONT> | |
8607 | below) may be used to list or edit and re-execute a portion of | |
8608 | the history list. | |
8609 | The | |
8610 | <B>history</B> | |
8611 | ||
8612 | builtin may be used to display or modify the history list and | |
8613 | manipulate the history file. | |
8614 | When using command-line editing, search commands | |
8615 | are available in each editing mode that provide access to the | |
8616 | history list. | |
8617 | <P> | |
8618 | ||
8619 | The shell allows control over which commands are saved on the history | |
8620 | list. The | |
8621 | <FONT SIZE=-1><B>HISTCONTROL</B> | |
8622 | ||
8623 | </FONT> | |
8624 | and | |
8625 | <FONT SIZE=-1><B>HISTIGNORE</B> | |
8626 | ||
8627 | </FONT> | |
8628 | variables may be set to cause the shell to save only a subset of the | |
8629 | commands entered. | |
8630 | The | |
8631 | <B>cmdhist</B> | |
8632 | ||
8633 | shell option, if enabled, causes the shell to attempt to save each | |
8634 | line of a multi-line command in the same history entry, adding | |
8635 | semicolons where necessary to preserve syntactic correctness. | |
8636 | The | |
8637 | <B>lithist</B> | |
8638 | ||
8639 | shell option causes the shell to save the command with embedded newlines | |
8640 | instead of semicolons. See the description of the | |
8641 | <B>shopt</B> | |
8642 | ||
8643 | builtin below under | |
8644 | <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B> | |
8645 | ||
8646 | </FONT> | |
8647 | for information on setting and unsetting shell options. | |
8648 | <A NAME="lbCX"> </A> | |
8649 | <H3>HISTORY EXPANSION</H3> | |
8650 | ||
8651 | <P> | |
8652 | ||
8653 | The shell supports a history expansion feature that | |
8654 | is similar to the history expansion in | |
8655 | <B>csh.</B> | |
8656 | ||
8657 | This section describes what syntax features are available. This | |
8658 | feature is enabled by default for interactive shells, and can be | |
8659 | disabled using the | |
8660 | <B>+H</B> | |
8661 | ||
8662 | option to the | |
8663 | <B>set</B> | |
8664 | ||
8665 | builtin command (see | |
8666 | <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B> | |
8667 | ||
8668 | </FONT> | |
8669 | below). Non-interactive shells do not perform history expansion | |
8670 | by default. | |
8671 | <P> | |
8672 | ||
8673 | History expansions introduce words from the history list into | |
8674 | the input stream, making it easy to repeat commands, insert the | |
8675 | arguments to a previous command into the current input line, or | |
8676 | fix errors in previous commands quickly. | |
8677 | <P> | |
8678 | ||
8679 | History expansion is performed immediately after a complete line | |
8680 | is read, before the shell breaks it into words. | |
8681 | It takes place in two parts. | |
8682 | The first is to determine which line from the history list | |
8683 | to use during substitution. | |
8684 | The second is to select portions of that line for inclusion into | |
8685 | the current one. | |
8686 | The line selected from the history is the <I>event</I>, | |
8687 | and the portions of that line that are acted upon are <I>words</I>. | |
8688 | Various <I>modifiers</I> are available to manipulate the selected words. | |
8689 | The line is broken into words in the same fashion as when reading input, | |
8690 | so that several <I>metacharacter</I>-separated words surrounded by | |
8691 | quotes are considered one word. | |
8692 | History expansions are introduced by the appearance of the | |
8693 | history expansion character, which is <B>!</B> by default. | |
8694 | Only backslash (<B>\</B>) and single quotes can quote | |
a0c0a00f CR |
8695 | the history expansion character, but the history expansion character is |
8696 | also treated as quoted if it immediately precedes the closing double quote | |
8697 | in a double-quoted string. | |
17345e5a JA |
8698 | <P> |
8699 | ||
8700 | Several characters inhibit history expansion if found immediately | |
8701 | following the history expansion character, even if it is unquoted: | |
8702 | space, tab, newline, carriage return, and <B>=</B>. | |
8703 | If the <B>extglob</B> shell option is enabled, <B>(</B> will also | |
8704 | inhibit expansion. | |
8705 | <P> | |
8706 | ||
8707 | Several shell options settable with the | |
8708 | <B>shopt</B> | |
8709 | ||
8710 | builtin may be used to tailor the behavior of history expansion. | |
8711 | If the | |
8712 | <B>histverify</B> | |
8713 | ||
8714 | shell option is enabled (see the description of the | |
8715 | <B>shopt</B> | |
8716 | ||
0001803f | 8717 | builtin below), and |
17345e5a JA |
8718 | <B>readline</B> |
8719 | ||
8720 | is being used, history substitutions are not immediately passed to | |
8721 | the shell parser. | |
8722 | Instead, the expanded line is reloaded into the | |
8723 | <B>readline</B> | |
8724 | ||
8725 | editing buffer for further modification. | |
8726 | If | |
8727 | <B>readline</B> | |
8728 | ||
8729 | is being used, and the | |
8730 | <B>histreedit</B> | |
8731 | ||
8732 | shell option is enabled, a failed history substitution will be reloaded | |
8733 | into the | |
8734 | <B>readline</B> | |
8735 | ||
8736 | editing buffer for correction. | |
8737 | The | |
8738 | <B>-p</B> | |
8739 | ||
8740 | option to the | |
8741 | <B>history</B> | |
8742 | ||
8743 | builtin command may be used to see what a history expansion will | |
8744 | do before using it. | |
8745 | The | |
8746 | <B>-s</B> | |
8747 | ||
8748 | option to the | |
8749 | <B>history</B> | |
8750 | ||
8751 | builtin may be used to add commands to the end of the history list | |
8752 | without actually executing them, so that they are available for | |
8753 | subsequent recall. | |
8754 | <P> | |
8755 | ||
8756 | The shell allows control of the various characters used by the | |
8757 | history expansion mechanism (see the description of | |
8758 | <B>histchars</B> | |
8759 | ||
8760 | above under | |
8761 | <B>Shell Variables</B>). | |
8762 | ||
8763 | The shell uses | |
8764 | the history comment character to mark history timestamps when | |
8765 | writing the history file. | |
8766 | <A NAME="lbCY"> </A> | |
8767 | <H4>Event Designators</H4> | |
8768 | ||
8769 | <P> | |
8770 | ||
8771 | An event designator is a reference to a command line entry in the | |
8772 | history list. | |
495aee44 CR |
8773 | Unless the reference is absolute, events are relative to the current |
8774 | position in the history list. | |
17345e5a JA |
8775 | <P> |
8776 | ||
8777 | ||
8778 | <DL COMPACT> | |
8779 | <DT><B>!</B> | |
8780 | ||
8781 | <DD> | |
8782 | Start a history substitution, except when followed by a | |
8783 | <B>blank</B>, | |
8784 | ||
8785 | newline, carriage return, = | |
8786 | or ( (when the <B>extglob</B> shell option is enabled using | |
8787 | the <B>shopt</B> builtin). | |
8788 | <DT><B>!</B><I>n</I> | |
8789 | ||
8790 | <DD> | |
8791 | Refer to command line | |
8792 | <I>n</I>. | |
8793 | ||
8794 | <DT><B>!-</B><I>n</I> | |
8795 | ||
8796 | <DD> | |
495aee44 | 8797 | Refer to the current command minus |
17345e5a JA |
8798 | <I>n</I>. |
8799 | ||
8800 | <DT><B>!!</B> | |
8801 | ||
8802 | <DD> | |
8803 | Refer to the previous command. This is a synonym for `!-1'. | |
8804 | <DT><B>!</B><I>string</I> | |
8805 | ||
8806 | <DD> | |
495aee44 CR |
8807 | Refer to the most recent command preceding the current position in the |
8808 | history list starting with | |
17345e5a JA |
8809 | <I>string</I>. |
8810 | ||
8811 | <DT><B>!?</B><I>string</I><B>[?]</B> | |
8812 | ||
8813 | <DD> | |
ac50fbac | 8814 | Refer to the most recent command preceding the current position in the |
495aee44 | 8815 | history list containing |
17345e5a JA |
8816 | <I>string</I>. |
8817 | ||
8818 | The trailing <B>?</B> may be omitted if | |
8819 | <I>string</I> | |
8820 | ||
8821 | is followed immediately by a newline. | |
8822 | <DT><B></B><FONT SIZE=+2><B>^</B></FONT><B></B><I>string1</I><FONT SIZE=+2>^</FONT><I>string2</I><FONT SIZE=+2>^</FONT> | |
8823 | ||
8824 | <DD> | |
495aee44 | 8825 | Quick substitution. Repeat the previous command, replacing |
17345e5a JA |
8826 | <I>string1</I> |
8827 | ||
8828 | with | |
8829 | <I>string2</I>. | |
8830 | ||
8831 | Equivalent to | |
8832 | ``!!:s/<I>string1</I>/<I>string2</I>/'' | |
8833 | (see <B>Modifiers</B> below). | |
8834 | <DT><B>!#</B> | |
8835 | ||
8836 | <DD> | |
8837 | The entire command line typed so far. | |
8838 | ||
8839 | </DL> | |
8840 | <A NAME="lbCZ"> </A> | |
8841 | <H4>Word Designators</H4> | |
8842 | ||
8843 | <P> | |
8844 | ||
8845 | Word designators are used to select desired words from the event. | |
a0c0a00f | 8846 | A |
17345e5a JA |
8847 | <B>:</B> |
8848 | ||
8849 | separates the event specification from the word designator. | |
8850 | It may be omitted if the word designator begins with a | |
8851 | <B>^</B>, | |
8852 | ||
8853 | <B>$</B>, | |
8854 | ||
8855 | <B>*</B>, | |
8856 | ||
8857 | <B>-</B>, | |
8858 | ||
8859 | or | |
8860 | <B>%</B>. | |
8861 | ||
8862 | Words are numbered from the beginning of the line, | |
8863 | with the first word being denoted by 0 (zero). | |
8864 | Words are inserted into the current line separated by single spaces. | |
8865 | <P> | |
8866 | ||
8867 | ||
8868 | <DL COMPACT> | |
8869 | <DT><B>0 (zero)</B> | |
8870 | ||
8871 | <DD> | |
8872 | The zeroth word. For the shell, this is the command | |
8873 | word. | |
8874 | <DT><I>n</I> | |
8875 | ||
8876 | <DD> | |
8877 | The <I>n</I>th word. | |
8878 | <DT><B>^</B> | |
8879 | ||
8880 | <DD> | |
8881 | The first argument. That is, word 1. | |
8882 | <DT><B>$</B> | |
8883 | ||
8884 | <DD> | |
ac50fbac CR |
8885 | The last word. This is usually the last argument, but will expand to the |
8886 | zeroth word if there is only one word in the line. | |
17345e5a JA |
8887 | <DT><B>%</B> |
8888 | ||
8889 | <DD> | |
8890 | The word matched by the most recent `?<I>string</I>?' search. | |
8891 | <DT><I>x</I><B>-</B>y | |
8892 | ||
8893 | <DD> | |
8894 | A range of words; `-<I>y</I>' abbreviates `0-<I>y</I>'. | |
8895 | <DT><B>*</B> | |
8896 | ||
8897 | <DD> | |
8898 | All of the words but the zeroth. This is a synonym | |
8899 | for `<I>1-$</I>'. It is not an error to use | |
8900 | <B>*</B> | |
8901 | ||
8902 | if there is just one | |
8903 | word in the event; the empty string is returned in that case. | |
8904 | <DT><B>x*</B> | |
8905 | ||
8906 | <DD> | |
8907 | Abbreviates <I>x-$</I>. | |
8908 | <DT><B>x-</B> | |
8909 | ||
8910 | <DD> | |
8911 | Abbreviates <I>x-$</I> like <B>x*</B>, but omits the last word. | |
8912 | ||
8913 | </DL> | |
8914 | <P> | |
8915 | ||
8916 | If a word designator is supplied without an event specification, the | |
8917 | previous command is used as the event. | |
8918 | <A NAME="lbDA"> </A> | |
8919 | <H4>Modifiers</H4> | |
8920 | ||
8921 | <P> | |
8922 | ||
8923 | After the optional word designator, there may appear a sequence of | |
8924 | one or more of the following modifiers, each preceded by a `:'. | |
8925 | <P> | |
8926 | ||
8927 | ||
8928 | <P> | |
8929 | ||
8930 | <DL COMPACT> | |
8931 | <DT><B>h</B> | |
8932 | ||
8933 | <DD> | |
ac50fbac | 8934 | Remove a trailing filename component, leaving only the head. |
17345e5a JA |
8935 | <DT><B>t</B> |
8936 | ||
8937 | <DD> | |
ac50fbac | 8938 | Remove all leading filename components, leaving the tail. |
17345e5a JA |
8939 | <DT><B>r</B> |
8940 | ||
8941 | <DD> | |
8942 | Remove a trailing suffix of the form <I>.xxx</I>, leaving the | |
8943 | basename. | |
8944 | <DT><B>e</B> | |
8945 | ||
8946 | <DD> | |
8947 | Remove all but the trailing suffix. | |
8948 | <DT><B>p</B> | |
8949 | ||
8950 | <DD> | |
8951 | Print the new command but do not execute it. | |
8952 | <DT><B>q</B> | |
8953 | ||
8954 | <DD> | |
8955 | Quote the substituted words, escaping further substitutions. | |
8956 | <DT><B>x</B> | |
8957 | ||
8958 | <DD> | |
8959 | Quote the substituted words as with | |
8960 | <B>q</B>, | |
8961 | ||
8962 | but break into words at | |
8963 | <B>blanks</B> | |
8964 | ||
8965 | and newlines. | |
8966 | <DT><B>s/</B><I>old</I>/<I>new</I>/ | |
8967 | ||
8968 | <DD> | |
8969 | Substitute | |
8970 | <I>new</I> | |
8971 | ||
8972 | for the first occurrence of | |
8973 | <I>old</I> | |
8974 | ||
8975 | in the event line. Any delimiter can be used in place of /. The | |
8976 | final delimiter is optional if it is the last character of the | |
8977 | event line. The delimiter may be quoted in | |
8978 | <I>old</I> | |
8979 | ||
8980 | and | |
8981 | <I>new</I> | |
8982 | ||
8983 | with a single backslash. If & appears in | |
8984 | <I>new</I>, | |
8985 | ||
8986 | it is replaced by | |
8987 | <I>old</I>. | |
8988 | ||
8989 | A single backslash will quote the &. If | |
8990 | <I>old</I> | |
8991 | ||
8992 | is null, it is set to the last | |
8993 | <I>old</I> | |
8994 | ||
8995 | substituted, or, if no previous history substitutions took place, | |
8996 | the last | |
8997 | <I>string</I> | |
8998 | ||
8999 | in a | |
9000 | <B>!?</B><I>string</I><B>[?]</B> | |
9001 | ||
9002 | search. | |
9003 | <DT><B>&</B> | |
9004 | ||
9005 | <DD> | |
9006 | Repeat the previous substitution. | |
9007 | <DT><B>g</B> | |
9008 | ||
9009 | <DD> | |
9010 | Cause changes to be applied over the entire event line. This is | |
9011 | used in conjunction with `<B>:s</B>' (e.g., `<B>:gs/</B><I>old</I>/<I>new</I>/') | |
9012 | or `<B>:&</B>'. If used with | |
9013 | `<B>:s</B>', any delimiter can be used | |
9014 | in place of /, and the final delimiter is optional | |
9015 | if it is the last character of the event line. | |
9016 | An <B>a</B> may be used as a synonym for <B>g</B>. | |
9017 | <DT><B>G</B> | |
9018 | ||
9019 | <DD> | |
9020 | Apply the following `<B>s</B>' modifier once to each word in the event line. | |
9021 | ||
9022 | </DL> | |
9023 | <A NAME="lbDB"> </A> | |
9024 | <H3>SHELL BUILTIN COMMANDS</H3> | |
9025 | ||
9026 | ||
9027 | ||
9028 | <P> | |
9029 | ||
9030 | Unless otherwise noted, each builtin command documented in this | |
9031 | section as accepting options preceded by | |
9032 | <B>-</B> | |
9033 | ||
9034 | accepts | |
9035 | <B>--</B> | |
9036 | ||
9037 | to signify the end of the options. | |
0001803f CR |
9038 | The <B>:</B>, <B>true</B>, <B>false</B>, and <B>test</B> builtins |
9039 | do not accept options and do not treat <B>--</B> specially. | |
a0c0a00f CR |
9040 | The <B>exit</B>, <B>logout</B>, <B>return</B>, |
9041 | <B>break</B>, <B>continue</B>, <B>let</B>, | |
0001803f CR |
9042 | and <B>shift</B> builtins accept and process arguments beginning with |
9043 | <B>-</B> without requiring <B>--</B>. | |
9044 | Other builtins that accept arguments but are not specified as accepting | |
9045 | options interpret arguments beginning with <B>-</B> as invalid options and | |
9046 | require <B>--</B> to prevent this interpretation. | |
17345e5a JA |
9047 | <P> |
9048 | ||
9049 | <DL COMPACT> | |
9050 | <DT><B>:</B> [<I>arguments</I>]<DD> | |
9051 | ||
9052 | No effect; the command does nothing beyond expanding | |
9053 | <I>arguments</I> | |
9054 | ||
9055 | and performing any specified | |
a0c0a00f CR |
9056 | redirections. |
9057 | The return status is zero. | |
17345e5a JA |
9058 | <DT><B> . </B> <I>filename</I> [<I>arguments</I>]<DD> |
9059 | ||
9060 | <DT><B>source</B> <I>filename</I> [<I>arguments</I>]<DD> | |
9061 | ||
9062 | Read and execute commands from | |
9063 | <I>filename</I> | |
9064 | ||
9065 | in the current | |
9066 | shell environment and return the exit status of the last command | |
9067 | executed from | |
9068 | <I>filename</I>. | |
9069 | ||
9070 | If | |
9071 | <I>filename</I> | |
9072 | ||
ac50fbac | 9073 | does not contain a slash, filenames in |
17345e5a JA |
9074 | <FONT SIZE=-1><B>PATH</B> |
9075 | ||
9076 | </FONT> | |
9077 | are used to find the directory containing | |
9078 | <I>filename</I>. | |
9079 | ||
9080 | The file searched for in | |
9081 | <FONT SIZE=-1><B>PATH</B> | |
9082 | ||
9083 | </FONT> | |
9084 | need not be executable. | |
9085 | When <B>bash</B> is not in <I>posix mode</I>, the current directory is | |
9086 | searched if no file is found in | |
9087 | <FONT SIZE=-1><B>PATH</B>. | |
9088 | ||
9089 | </FONT> | |
9090 | If the | |
9091 | <B>sourcepath</B> | |
9092 | ||
9093 | option to the | |
9094 | <B>shopt</B> | |
9095 | ||
9096 | builtin command is turned off, the | |
9097 | <FONT SIZE=-1><B>PATH</B> | |
9098 | ||
9099 | </FONT> | |
9100 | is not searched. | |
9101 | If any <I>arguments</I> are supplied, they become the positional | |
9102 | parameters when <I>filename</I> is executed. Otherwise the positional | |
9103 | parameters are unchanged. | |
a0c0a00f CR |
9104 | If the <B>-T</B> option is enabled, <B>source</B> inherits any trap on |
9105 | <B>DEBUG</B>; if it is not, any <B>DEBUG</B> trap string is saved and | |
9106 | restored around the call to <B>source</B>, and <B>source</B> unsets the | |
9107 | <B>DEBUG</B> trap while it executes. | |
9108 | If <B>-T</B> is not set, and the sourced file changes | |
9109 | the <B>DEBUG</B> trap, the new value is retained when <B>source</B> completes. | |
17345e5a JA |
9110 | The return status is the status of the last command exited within |
9111 | the script (0 if no commands are executed), and false if | |
9112 | <I>filename</I> | |
9113 | ||
9114 | is not found or cannot be read. | |
9115 | <DT><B>alias</B> [<B>-p</B>] [<I>name</I>[=<I>value</I>] ...]<DD> | |
9116 | <B>Alias</B> with no arguments or with the | |
9117 | <B>-p</B> | |
9118 | ||
9119 | option prints the list of aliases in the form | |
9120 | <B>alias</B> <I>name</I>=<I>value</I> on standard output. | |
9121 | When arguments are supplied, an alias is defined for | |
9122 | each <I>name</I> whose <I>value</I> is given. | |
a0c0a00f | 9123 | A trailing space in <I>value</I> causes the next word to be |
17345e5a JA |
9124 | checked for alias substitution when the alias is expanded. |
9125 | For each <I>name</I> in the argument list for which no <I>value</I> | |
9126 | is supplied, the name and value of the alias is printed. | |
9127 | <B>Alias</B> returns true unless a <I>name</I> is given for which | |
9128 | no alias has been defined. | |
9129 | <DT><B>bg</B> [<I>jobspec</I> ...]<DD> | |
9130 | Resume each suspended job <I>jobspec</I> in the background, as if it | |
9131 | had been started with | |
9132 | <B>&</B>. | |
9133 | ||
9134 | If | |
9135 | <I>jobspec</I> | |
9136 | ||
9137 | is not present, the shell's notion of the <I>current job</I> is used. | |
9138 | <B>bg</B> | |
9139 | ||
9140 | <I>jobspec</I> | |
9141 | ||
9142 | returns 0 unless run when job control is disabled or, when run with | |
9143 | job control enabled, any specified <I>jobspec</I> was not found | |
9144 | or was started without job control. | |
ac50fbac | 9145 | <DT><B>bind</B> [<B>-m</B> <I>keymap</I>] [<B>-lpsvPSVX</B>]<DD> |
17345e5a JA |
9146 | |
9147 | <DT><B>bind</B> [<B>-m</B> <I>keymap</I>] [<B>-q</B> <I>function</I>] [<B>-u</B> <I>function</I>] [<B>-r</B> <I>keyseq</I>]<DD> | |
9148 | <DT><B>bind</B> [<B>-m</B> <I>keymap</I>] <B>-f</B> <I>filename</I><DD> | |
9149 | <DT><B>bind</B> [<B>-m</B> <I>keymap</I>] <B>-x</B> <I>keyseq</I>:<I>shell-command</I><DD> | |
9150 | <DT><B>bind</B> [<B>-m</B> <I>keymap</I>] <I>keyseq</I>:<I>function-name</I><DD> | |
a0c0a00f | 9151 | <DT><B>bind</B> [<B>-m</B> <I>keymap</I>] <I>keyseq</I>:<I>readline-command</I><DD> |
17345e5a JA |
9152 | |
9153 | Display current | |
9154 | <B>readline</B> | |
9155 | ||
9156 | key and function bindings, bind a key sequence to a | |
9157 | <B>readline</B> | |
9158 | ||
9159 | function or macro, or set a | |
9160 | <B>readline</B> | |
9161 | ||
9162 | variable. | |
9163 | Each non-option argument is a command as it would appear in | |
9164 | <I>.inputrc</I>, | |
9165 | ||
9166 | but each binding or command must be passed as a separate argument; | |
9167 | e.g., '"\C-x\C-r": re-read-init-file'. | |
9168 | Options, if supplied, have the following meanings: | |
9169 | <DL COMPACT><DT><DD> | |
9170 | ||
9171 | <DL COMPACT> | |
9172 | <DT><B>-m </B><I>keymap</I> | |
9173 | ||
9174 | <DD> | |
9175 | Use | |
9176 | <I>keymap</I> | |
9177 | ||
9178 | as the keymap to be affected by the subsequent bindings. | |
9179 | Acceptable | |
9180 | <I>keymap</I> | |
9181 | ||
9182 | names are | |
9183 | <I>emacs, emacs-standard, emacs-meta, emacs-ctlx, vi, | |
9184 | vi-move, vi-command</I>, and | |
9185 | <I>vi-insert</I>. | |
9186 | ||
a0c0a00f CR |
9187 | <I>vi</I> is equivalent to <I>vi-command</I> (<I>vi-move</I> is also |
9188 | a synonym); <I>emacs</I> is | |
17345e5a JA |
9189 | equivalent to <I>emacs-standard</I>. |
9190 | <DT><B>-l</B> | |
9191 | ||
9192 | <DD> | |
9193 | List the names of all <B>readline</B> functions. | |
9194 | <DT><B>-p</B> | |
9195 | ||
9196 | <DD> | |
9197 | Display <B>readline</B> function names and bindings in such a way | |
9198 | that they can be re-read. | |
9199 | <DT><B>-P</B> | |
9200 | ||
9201 | <DD> | |
9202 | List current <B>readline</B> function names and bindings. | |
9203 | <DT><B>-s</B> | |
9204 | ||
9205 | <DD> | |
9206 | Display <B>readline</B> key sequences bound to macros and the strings | |
9207 | they output in such a way that they can be re-read. | |
9208 | <DT><B>-S</B> | |
9209 | ||
9210 | <DD> | |
9211 | Display <B>readline</B> key sequences bound to macros and the strings | |
9212 | they output. | |
9213 | <DT><B>-v</B> | |
9214 | ||
9215 | <DD> | |
9216 | Display <B>readline</B> variable names and values in such a way that they | |
9217 | can be re-read. | |
9218 | <DT><B>-V</B> | |
9219 | ||
9220 | <DD> | |
9221 | List current <B>readline</B> variable names and values. | |
9222 | <DT><B>-f </B><I>filename</I> | |
9223 | ||
9224 | <DD> | |
9225 | Read key bindings from <I>filename</I>. | |
9226 | <DT><B>-q </B><I>function</I> | |
9227 | ||
9228 | <DD> | |
9229 | Query about which keys invoke the named <I>function</I>. | |
9230 | <DT><B>-u </B><I>function</I> | |
9231 | ||
9232 | <DD> | |
9233 | Unbind all keys bound to the named <I>function</I>. | |
9234 | <DT><B>-r </B><I>keyseq</I> | |
9235 | ||
9236 | <DD> | |
9237 | Remove any current binding for <I>keyseq</I>. | |
9238 | <DT><B>-x </B><I>keyseq</I>:<I>shell-command</I> | |
9239 | ||
9240 | <DD> | |
9241 | Cause <I>shell-command</I> to be executed whenever <I>keyseq</I> is | |
9242 | entered. | |
9243 | When <I>shell-command</I> is executed, the shell sets the | |
0001803f | 9244 | <FONT SIZE=-1><B>READLINE_LINE</B> |
17345e5a | 9245 | |
0001803f | 9246 | </FONT> |
17345e5a | 9247 | variable to the contents of the <B>readline</B> line buffer and the |
0001803f | 9248 | <FONT SIZE=-1><B>READLINE_POINT</B> |
17345e5a | 9249 | |
0001803f | 9250 | </FONT> |
17345e5a JA |
9251 | variable to the current location of the insertion point. |
9252 | If the executed command changes the value of | |
0001803f | 9253 | <FONT SIZE=-1><B>READLINE_LINE</B> |
17345e5a | 9254 | |
0001803f | 9255 | </FONT> |
17345e5a | 9256 | or |
0001803f | 9257 | <FONT SIZE=-1><B>READLINE_POINT</B>, |
17345e5a | 9258 | |
0001803f | 9259 | </FONT> |
17345e5a | 9260 | those new values will be reflected in the editing state. |
ac50fbac CR |
9261 | <DT><B>-X</B> |
9262 | ||
9263 | <DD> | |
9264 | List all key sequences bound to shell commands and the associated commands | |
9265 | in a format that can be reused as input. | |
17345e5a JA |
9266 | |
9267 | </DL> | |
9268 | <P> | |
9269 | ||
9270 | The return value is 0 unless an unrecognized option is given or an | |
9271 | error occurred. | |
9272 | </DL> | |
9273 | ||
9274 | <DT><B>break</B> [<I>n</I>]<DD> | |
9275 | Exit from within a | |
9276 | <B>for</B>, | |
9277 | ||
9278 | <B>while</B>, | |
9279 | ||
9280 | <B>until</B>, | |
9281 | ||
9282 | or | |
9283 | <B>select</B> | |
9284 | ||
9285 | loop. If <I>n</I> is specified, break <I>n</I> levels. | |
9286 | <I>n</I> | |
9287 | ||
9288 | must be >= 1. If | |
9289 | <I>n</I> | |
9290 | ||
9291 | is greater than the number of enclosing loops, all enclosing loops | |
9292 | are exited. | |
9293 | The return value is 0 unless <I>n</I> is not greater than or equal to 1. | |
9294 | <DT><B>builtin</B> <I>shell-builtin</I> [<I>arguments</I>]<DD> | |
9295 | Execute the specified shell builtin, passing it | |
9296 | <I>arguments</I>, | |
9297 | ||
9298 | and return its exit status. | |
9299 | This is useful when defining a | |
9300 | function whose name is the same as a shell builtin, | |
9301 | retaining the functionality of the builtin within the function. | |
9302 | The <B>cd</B> builtin is commonly redefined this way. | |
9303 | The return status is false if | |
9304 | <I>shell-builtin</I> | |
9305 | ||
9306 | is not a shell builtin command. | |
9307 | <DT><B>caller</B> [<I>expr</I>]<DD> | |
9308 | Returns the context of any active subroutine call (a shell function or | |
495aee44 | 9309 | a script executed with the <B>.</B> or <B>source</B> builtins). |
17345e5a JA |
9310 | Without <I>expr</I>, <B>caller</B> displays the line number and source |
9311 | filename of the current subroutine call. | |
a0c0a00f | 9312 | If a non-negative integer is supplied as <I>expr</I>, <B>caller</B> |
17345e5a JA |
9313 | displays the line number, subroutine name, and source file corresponding |
9314 | to that position in the current execution call stack. This extra | |
9315 | information may be used, for example, to print a stack trace. The | |
9316 | current frame is frame 0. | |
9317 | The return value is 0 unless the shell is not executing a subroutine | |
9318 | call or <I>expr</I> does not correspond to a valid position in the | |
9319 | call stack. | |
ac50fbac CR |
9320 | <DT><B>cd</B> [<B>-L</B>|[<B>-P</B> [<B>-e</B>]] [-@]] [<I>dir</I>]<DD> |
9321 | Change the current directory to <I>dir</I>. | |
9322 | if <I>dir</I> is not supplied, the value of the | |
17345e5a JA |
9323 | <FONT SIZE=-1><B>HOME</B> |
9324 | ||
9325 | </FONT> | |
ac50fbac CR |
9326 | shell variable is the default. |
9327 | Any additional arguments following <I>dir</I> are ignored. | |
17345e5a JA |
9328 | The variable |
9329 | <FONT SIZE=-1><B>CDPATH</B> | |
9330 | ||
9331 | </FONT> | |
9332 | defines the search path for the directory containing | |
ac50fbac CR |
9333 | <I>dir</I>: |
9334 | ||
9335 | each directory name in | |
9336 | <FONT SIZE=-1><B>CDPATH</B> | |
17345e5a | 9337 | |
ac50fbac CR |
9338 | </FONT> |
9339 | is searched for <I>dir</I>. | |
17345e5a JA |
9340 | Alternative directory names in |
9341 | <FONT SIZE=-1><B>CDPATH</B> | |
9342 | ||
9343 | </FONT> | |
9344 | are separated by a colon (:). A null directory name in | |
9345 | <FONT SIZE=-1><B>CDPATH</B> | |
9346 | ||
9347 | </FONT> | |
9348 | is the same as the current directory, i.e., ``<B>.</B>''. If | |
9349 | <I>dir</I> | |
9350 | ||
9351 | begins with a slash (/), | |
9352 | then | |
9353 | <FONT SIZE=-1><B>CDPATH</B> | |
9354 | ||
9355 | </FONT> | |
a0c0a00f | 9356 | is not used. The |
17345e5a JA |
9357 | <B>-P</B> |
9358 | ||
ac50fbac CR |
9359 | option causes <B>cd</B> to use the physical directory structure |
9360 | by resolving symbolic links while traversing <I>dir</I> and | |
9361 | before processing instances of <I>..</I> in <I>dir</I> (see also the | |
17345e5a JA |
9362 | <B>-P</B> |
9363 | ||
9364 | option to the | |
9365 | <B>set</B> | |
9366 | ||
9367 | builtin command); the | |
9368 | <B>-L</B> | |
9369 | ||
ac50fbac CR |
9370 | option forces symbolic links to be followed by resolving the link |
9371 | after processing instances of <I>..</I> in <I>dir</I>. | |
9372 | If <I>..</I> appears in <I>dir</I>, it is processed by removing the | |
9373 | immediately previous pathname component from <I>dir</I>, back to a slash | |
9374 | or the beginning of <I>dir</I>. | |
495aee44 CR |
9375 | If the |
9376 | <B>-e</B> | |
9377 | ||
9378 | option is supplied with | |
9379 | <B>-P</B>, | |
9380 | ||
9381 | and the current working directory cannot be successfully determined | |
9382 | after a successful directory change, <B>cd</B> will return an unsuccessful | |
9383 | status. | |
ac50fbac CR |
9384 | On systems that support it, the <B>-@</B> option presents the extended |
9385 | attributes associated with a file as a directory. | |
495aee44 | 9386 | An argument of |
17345e5a JA |
9387 | <B>-</B> |
9388 | ||
ac50fbac CR |
9389 | is converted to |
9390 | <FONT SIZE=-1><B>$OLDPWD</B> | |
17345e5a JA |
9391 | |
9392 | </FONT> | |
ac50fbac | 9393 | before the directory change is attempted. |
0001803f CR |
9394 | If a non-empty directory name from |
9395 | <FONT SIZE=-1><B>CDPATH</B> | |
9396 | ||
9397 | </FONT> | |
9398 | is used, or if | |
17345e5a JA |
9399 | <B>-</B> is the first argument, and the directory change is |
9400 | successful, the absolute pathname of the new working directory is | |
9401 | written to the standard output. | |
9402 | The return value is true if the directory was successfully changed; | |
9403 | false otherwise. | |
9404 | <DT><B>command</B> [<B>-pVv</B>] <I>command</I> [<I>arg</I> ...]<DD> | |
9405 | Run | |
9406 | <I>command</I> | |
9407 | ||
9408 | with | |
9409 | <I>args</I> | |
9410 | ||
a0c0a00f CR |
9411 | suppressing the normal shell function lookup. |
9412 | Only builtin commands or commands found in the | |
17345e5a JA |
9413 | <FONT SIZE=-1><B>PATH</B> |
9414 | ||
9415 | </FONT> | |
9416 | are executed. If the | |
9417 | <B>-p</B> | |
9418 | ||
9419 | option is given, the search for | |
9420 | <I>command</I> | |
9421 | ||
9422 | is performed using a default value for | |
0001803f | 9423 | <FONT SIZE=-1><B>PATH</B> |
17345e5a | 9424 | |
0001803f | 9425 | </FONT> |
17345e5a JA |
9426 | that is guaranteed to find all of the standard utilities. |
9427 | If either the | |
9428 | <B>-V</B> | |
9429 | ||
9430 | or | |
9431 | <B>-v</B> | |
9432 | ||
9433 | option is supplied, a description of | |
9434 | <I>command</I> | |
9435 | ||
9436 | is printed. The | |
9437 | <B>-v</B> | |
9438 | ||
ac50fbac | 9439 | option causes a single word indicating the command or filename |
17345e5a JA |
9440 | used to invoke |
9441 | <I>command</I> | |
9442 | ||
9443 | to be displayed; the | |
9444 | <B>-V</B> | |
9445 | ||
9446 | option produces a more verbose description. | |
9447 | If the | |
9448 | <B>-V</B> | |
9449 | ||
9450 | or | |
9451 | <B>-v</B> | |
9452 | ||
9453 | option is supplied, the exit status is 0 if | |
9454 | <I>command</I> | |
9455 | ||
9456 | was found, and 1 if not. If neither option is supplied and | |
9457 | an error occurred or | |
9458 | <I>command</I> | |
9459 | ||
9460 | cannot be found, the exit status is 127. Otherwise, the exit status of the | |
9461 | <B>command</B> | |
9462 | ||
9463 | builtin is the exit status of | |
9464 | <I>command</I>. | |
9465 | ||
9466 | <DT><B>compgen</B> [<I>option</I>] [<I>word</I>]<DD> | |
9467 | Generate possible completion matches for <I>word</I> according to | |
9468 | the <I>option</I>s, which may be any option accepted by the | |
9469 | <B>complete</B> | |
9470 | ||
9471 | builtin with the exception of <B>-p</B> and <B>-r</B>, and write | |
9472 | the matches to the standard output. | |
9473 | When using the <B>-F</B> or <B>-C</B> options, the various shell variables | |
9474 | set by the programmable completion facilities, while available, will not | |
9475 | have useful values. | |
9476 | <P> | |
9477 | The matches will be generated in the same way as if the programmable | |
9478 | completion code had generated them directly from a completion specification | |
9479 | with the same flags. | |
9480 | If <I>word</I> is specified, only those completions matching <I>word</I> | |
9481 | will be displayed. | |
9482 | <P> | |
9483 | The return value is true unless an invalid option is supplied, or no | |
9484 | matches were generated. | |
0001803f | 9485 | <DT><B>complete</B> [<B>-abcdefgjksuv</B>] [<B>-o</B> <I>comp-option</I>] [<B>-DE</B>] [<B>-A</B> <I>action</I>] [<B>-G</B> <I>globpat</I>] [<B>-W</B> <I>wordlist</I>] [<B>-F</B> <I>function</I>] [<B>-C</B> <I>command</I>]<DD> |
17345e5a JA |
9486 | <BR> |
9487 | ||
9488 | [<B>-X</B> <I>filterpat</I>] [<B>-P</B> <I>prefix</I>] [<B>-S</B> <I>suffix</I>] <I>name</I> [<I>name ...</I>] | |
9489 | ||
0001803f | 9490 | <DT><B>complete</B> <B>-pr</B> [<B>-DE</B>] [<I>name</I> ...]<DD> |
17345e5a JA |
9491 | |
9492 | Specify how arguments to each <I>name</I> should be completed. | |
9493 | If the <B>-p</B> option is supplied, or if no options are supplied, | |
9494 | existing completion specifications are printed in a way that allows | |
9495 | them to be reused as input. | |
9496 | The <B>-r</B> option removes a completion specification for | |
9497 | each <I>name</I>, or, if no <I>name</I>s are supplied, all | |
9498 | completion specifications. | |
0001803f CR |
9499 | The <B>-D</B> option indicates that the remaining options and actions should |
9500 | apply to the ``default'' command completion; that is, completion attempted | |
9501 | on a command for which no completion has previously been defined. | |
17345e5a JA |
9502 | The <B>-E</B> option indicates that the remaining options and actions should |
9503 | apply to ``empty'' command completion; that is, completion attempted on a | |
9504 | blank line. | |
9505 | <P> | |
9506 | The process of applying these completion specifications when word completion | |
9507 | is attempted is described above under <B>Programmable Completion</B>. | |
9508 | <P> | |
9509 | Other options, if specified, have the following meanings. | |
9510 | The arguments to the <B>-G</B>, <B>-W</B>, and <B>-X</B> options | |
9511 | (and, if necessary, the <B>-P</B> and <B>-S</B> options) | |
9512 | should be quoted to protect them from expansion before the | |
9513 | <B>complete</B> | |
9514 | ||
9515 | builtin is invoked. | |
9516 | <DL COMPACT><DT><DD> | |
9517 | ||
9518 | <DL COMPACT> | |
9519 | <DT><B>-o</B> <I>comp-option</I><DD> | |
9520 | The <I>comp-option</I> controls several aspects of the compspec's behavior | |
9521 | beyond the simple generation of completions. | |
9522 | <I>comp-option</I> may be one of: | |
9523 | <DL COMPACT><DT><DD> | |
9524 | <DL COMPACT> | |
9525 | <DT><B>bashdefault</B> | |
9526 | ||
9527 | <DD> | |
9528 | Perform the rest of the default <B>bash</B> completions if the compspec | |
9529 | generates no matches. | |
9530 | <DT><B>default</B> | |
9531 | ||
9532 | <DD> | |
9533 | Use readline's default filename completion if the compspec generates | |
9534 | no matches. | |
9535 | <DT><B>dirnames</B> | |
9536 | ||
9537 | <DD> | |
9538 | Perform directory name completion if the compspec generates no matches. | |
9539 | <DT><B>filenames</B> | |
9540 | ||
9541 | <DD> | |
9542 | Tell readline that the compspec generates filenames, so it can perform any | |
9543 | filename-specific processing (like adding a slash to directory names, | |
9544 | quoting special characters, or suppressing trailing spaces). | |
9545 | Intended to be used with shell functions. | |
ac50fbac CR |
9546 | <DT><B>noquote</B> |
9547 | ||
9548 | <DD> | |
9549 | Tell readline not to quote the completed words if they are filenames | |
9550 | (quoting filenames is the default). | |
a0c0a00f CR |
9551 | <DT><B>nosort</B> |
9552 | ||
9553 | <DD> | |
9554 | Tell readline not to sort the list of possible completions alphabetically. | |
17345e5a JA |
9555 | <DT><B>nospace</B> |
9556 | ||
9557 | <DD> | |
9558 | Tell readline not to append a space (the default) to words completed at | |
9559 | the end of the line. | |
9560 | <DT><B>plusdirs</B> | |
9561 | ||
9562 | <DD> | |
a0c0a00f | 9563 | After any matches defined by the compspec are generated, |
17345e5a JA |
9564 | directory name completion is attempted and any |
9565 | matches are added to the results of the other actions. | |
9566 | </DL></DL> | |
9567 | ||
9568 | <DT><B>-A</B> <I>action</I><DD> | |
9569 | The <I>action</I> may be one of the following to generate a list of possible | |
9570 | completions: | |
9571 | <DL COMPACT><DT><DD> | |
9572 | <DL COMPACT> | |
9573 | <DT><B>alias</B> | |
9574 | ||
9575 | <DD> | |
9576 | Alias names. May also be specified as <B>-a</B>. | |
9577 | <DT><B>arrayvar</B> | |
9578 | ||
9579 | <DD> | |
9580 | Array variable names. | |
9581 | <DT><B>binding</B> | |
9582 | ||
9583 | <DD> | |
9584 | <B>Readline</B> key binding names. | |
9585 | <DT><B>builtin</B> | |
9586 | ||
9587 | <DD> | |
9588 | Names of shell builtin commands. May also be specified as <B>-b</B>. | |
9589 | <DT><B>command</B> | |
9590 | ||
9591 | <DD> | |
9592 | Command names. May also be specified as <B>-c</B>. | |
9593 | <DT><B>directory</B> | |
9594 | ||
9595 | <DD> | |
9596 | Directory names. May also be specified as <B>-d</B>. | |
9597 | <DT><B>disabled</B> | |
9598 | ||
9599 | <DD> | |
9600 | Names of disabled shell builtins. | |
9601 | <DT><B>enabled</B> | |
9602 | ||
9603 | <DD> | |
9604 | Names of enabled shell builtins. | |
9605 | <DT><B>export</B> | |
9606 | ||
9607 | <DD> | |
9608 | Names of exported shell variables. May also be specified as <B>-e</B>. | |
9609 | <DT><B>file</B> | |
9610 | ||
9611 | <DD> | |
9612 | File names. May also be specified as <B>-f</B>. | |
9613 | <DT><B>function</B> | |
9614 | ||
9615 | <DD> | |
9616 | Names of shell functions. | |
9617 | <DT><B>group</B> | |
9618 | ||
9619 | <DD> | |
9620 | Group names. May also be specified as <B>-g</B>. | |
9621 | <DT><B>helptopic</B> | |
9622 | ||
9623 | <DD> | |
9624 | Help topics as accepted by the <B>help</B> builtin. | |
9625 | <DT><B>hostname</B> | |
9626 | ||
9627 | <DD> | |
9628 | Hostnames, as taken from the file specified by the | |
9629 | <FONT SIZE=-1><B>HOSTFILE</B> | |
9630 | ||
9631 | </FONT> | |
9632 | shell variable. | |
9633 | <DT><B>job</B> | |
9634 | ||
9635 | <DD> | |
9636 | Job names, if job control is active. May also be specified as <B>-j</B>. | |
9637 | <DT><B>keyword</B> | |
9638 | ||
9639 | <DD> | |
9640 | Shell reserved words. May also be specified as <B>-k</B>. | |
9641 | <DT><B>running</B> | |
9642 | ||
9643 | <DD> | |
9644 | Names of running jobs, if job control is active. | |
9645 | <DT><B>service</B> | |
9646 | ||
9647 | <DD> | |
9648 | Service names. May also be specified as <B>-s</B>. | |
9649 | <DT><B>setopt</B> | |
9650 | ||
9651 | <DD> | |
9652 | Valid arguments for the <B>-o</B> option to the <B>set</B> builtin. | |
9653 | <DT><B>shopt</B> | |
9654 | ||
9655 | <DD> | |
9656 | Shell option names as accepted by the <B>shopt</B> builtin. | |
9657 | <DT><B>signal</B> | |
9658 | ||
9659 | <DD> | |
9660 | Signal names. | |
9661 | <DT><B>stopped</B> | |
9662 | ||
9663 | <DD> | |
9664 | Names of stopped jobs, if job control is active. | |
9665 | <DT><B>user</B> | |
9666 | ||
9667 | <DD> | |
9668 | User names. May also be specified as <B>-u</B>. | |
9669 | <DT><B>variable</B> | |
9670 | ||
9671 | <DD> | |
9672 | Names of all shell variables. May also be specified as <B>-v</B>. | |
9673 | </DL></DL> | |
9674 | ||
17345e5a JA |
9675 | <DT><B>-C</B> <I>command</I><DD> |
9676 | <I>command</I> is executed in a subshell environment, and its output is | |
9677 | used as the possible completions. | |
9678 | <DT><B>-F</B> <I>function</I><DD> | |
9679 | The shell function <I>function</I> is executed in the current shell | |
9680 | environment. | |
ac50fbac CR |
9681 | When the function is executed, |
9682 | the first argument (<B>$1</B>) is the name of the command whose arguments are | |
9683 | being completed, | |
9684 | the second argument (<B>$2</B>) is the word being completed, | |
9685 | and the third argument (<B>$3</B>) is the word preceding the word being | |
9686 | completed on the current command line. | |
17345e5a JA |
9687 | When it finishes, the possible completions are retrieved from the value |
9688 | of the | |
9689 | <FONT SIZE=-1><B>COMPREPLY</B> | |
9690 | ||
9691 | </FONT> | |
9692 | array variable. | |
495aee44 CR |
9693 | <DT><B>-G</B> <I>globpat</I><DD> |
9694 | The pathname expansion pattern <I>globpat</I> is expanded to generate | |
9695 | the possible completions. | |
9696 | <DT><B>-P</B> <I>prefix</I><DD> | |
9697 | <I>prefix</I> is added at the beginning of each possible completion | |
9698 | after all other options have been applied. | |
9699 | <DT><B>-S</B> <I>suffix</I><DD> | |
9700 | <I>suffix</I> is appended to each possible completion | |
9701 | after all other options have been applied. | |
9702 | <DT><B>-W</B> <I>wordlist</I><DD> | |
9703 | The <I>wordlist</I> is split using the characters in the | |
9704 | <FONT SIZE=-1><B>IFS</B> | |
9705 | ||
9706 | </FONT> | |
9707 | special variable as delimiters, and each resultant word is expanded. | |
9708 | The possible completions are the members of the resultant list which | |
9709 | match the word being completed. | |
17345e5a | 9710 | <DT><B>-X</B> <I>filterpat</I><DD> |
0001803f | 9711 | <I>filterpat</I> is a pattern as used for pathname expansion. |
17345e5a JA |
9712 | It is applied to the list of possible completions generated by the |
9713 | preceding options and arguments, and each completion matching | |
9714 | <I>filterpat</I> is removed from the list. | |
9715 | A leading <B>!</B> in <I>filterpat</I> negates the pattern; in this | |
9716 | case, any completion not matching <I>filterpat</I> is removed. | |
17345e5a JA |
9717 | |
9718 | </DL> | |
9719 | <P> | |
9720 | ||
9721 | The return value is true unless an invalid option is supplied, an option | |
9722 | other than <B>-p</B> or <B>-r</B> is supplied without a <I>name</I> | |
9723 | argument, an attempt is made to remove a completion specification for | |
9724 | a <I>name</I> for which no specification exists, or | |
9725 | an error occurs adding a completion specification. | |
9726 | </DL> | |
9727 | ||
0001803f | 9728 | <DT><B>compopt</B> [<B>-o</B> <I>option</I>] [<B>-DE</B>] [<B>+o</B> <I>option</I>] [<I>name</I>]<DD> |
17345e5a JA |
9729 | Modify completion options for each <I>name</I> according to the |
9730 | <I>option</I>s, or for the | |
495aee44 | 9731 | currently-executing completion if no <I>name</I>s are supplied. |
17345e5a JA |
9732 | If no <I>option</I>s are given, display the completion options for each |
9733 | <I>name</I> or the current completion. | |
9734 | The possible values of <I>option</I> are those valid for the <B>complete</B> | |
9735 | builtin described above. | |
0001803f CR |
9736 | The <B>-D</B> option indicates that the remaining options should |
9737 | apply to the ``default'' command completion; that is, completion attempted | |
9738 | on a command for which no completion has previously been defined. | |
9739 | The <B>-E</B> option indicates that the remaining options should | |
9740 | apply to ``empty'' command completion; that is, completion attempted on a | |
9741 | blank line. | |
17345e5a | 9742 | <P> |
17345e5a JA |
9743 | The return value is true unless an invalid option is supplied, an attempt |
9744 | is made to modify the options for a <I>name</I> for which no completion | |
9745 | specification exists, or an output error occurs. | |
17345e5a JA |
9746 | <DT><B>continue</B> [<I>n</I>]<DD> |
9747 | Resume the next iteration of the enclosing | |
9748 | <B>for</B>, | |
9749 | ||
9750 | <B>while</B>, | |
9751 | ||
9752 | <B>until</B>, | |
9753 | ||
9754 | or | |
9755 | <B>select</B> | |
9756 | ||
9757 | loop. | |
9758 | If | |
9759 | <I>n</I> | |
9760 | ||
9761 | is specified, resume at the <I>n</I>th enclosing loop. | |
9762 | <I>n</I> | |
9763 | ||
9764 | must be >= 1. If | |
9765 | <I>n</I> | |
9766 | ||
9767 | is greater than the number of enclosing loops, the last enclosing loop | |
9768 | (the ``top-level'' loop) is resumed. | |
9769 | The return value is 0 unless <I>n</I> is not greater than or equal to 1. | |
ac50fbac | 9770 | <DT><B>declare</B> [<B>-aAfFgilnrtux</B>] [<B>-p</B>] [<I>name</I>[=<I>value</I>] ...]<DD> |
17345e5a | 9771 | |
ac50fbac | 9772 | <DT><B>typeset</B> [<B>-aAfFgilnrtux</B>] [<B>-p</B>] [<I>name</I>[=<I>value</I>] ...]<DD> |
17345e5a JA |
9773 | |
9774 | Declare variables and/or give them attributes. | |
9775 | If no <I>name</I>s are given then display the values of variables. | |
9776 | The | |
9777 | <B>-p</B> | |
9778 | ||
9779 | option will display the attributes and values of each | |
9780 | <I>name</I>. | |
9781 | ||
9782 | When | |
9783 | <B>-p</B> | |
9784 | ||
ac50fbac CR |
9785 | is used with <I>name</I> arguments, additional options, |
9786 | other than <B>-f</B> and <B>-F</B>, are ignored. | |
17345e5a JA |
9787 | When |
9788 | <B>-p</B> | |
9789 | ||
9790 | is supplied without <I>name</I> arguments, it will display the attributes | |
9791 | and values of all variables having the attributes specified by the | |
9792 | additional options. | |
9793 | If no other options are supplied with <B>-p</B>, <B>declare</B> will display | |
9794 | the attributes and values of all shell variables. The <B>-f</B> option | |
9795 | will restrict the display to shell functions. | |
9796 | The | |
9797 | <B>-F</B> | |
9798 | ||
9799 | option inhibits the display of function definitions; only the | |
9800 | function name and attributes are printed. | |
9801 | If the <B>extdebug</B> shell option is enabled using <B>shopt</B>, | |
a0c0a00f CR |
9802 | the source file name and line number where each <I>name</I> |
9803 | is defined are displayed as well. The | |
17345e5a JA |
9804 | <B>-F</B> |
9805 | ||
9806 | option implies | |
9807 | <B>-f</B>. | |
9808 | ||
495aee44 CR |
9809 | The |
9810 | <B>-g</B> | |
9811 | ||
9812 | option forces variables to be created or modified at the global scope, | |
9813 | even when <B>declare</B> is executed in a shell function. | |
9814 | It is ignored in all other cases. | |
17345e5a JA |
9815 | The following options can |
9816 | be used to restrict output to variables with the specified attribute or | |
9817 | to give variables attributes: | |
9818 | <DL COMPACT><DT><DD> | |
9819 | ||
9820 | <DL COMPACT> | |
9821 | <DT><B>-a</B> | |
9822 | ||
9823 | <DD> | |
9824 | Each <I>name</I> is an indexed array variable (see | |
9825 | <B>Arrays</B> | |
9826 | ||
9827 | above). | |
9828 | <DT><B>-A</B> | |
9829 | ||
9830 | <DD> | |
9831 | Each <I>name</I> is an associative array variable (see | |
9832 | <B>Arrays</B> | |
9833 | ||
9834 | above). | |
9835 | <DT><B>-f</B> | |
9836 | ||
9837 | <DD> | |
9838 | Use function names only. | |
9839 | <DT><B>-i</B> | |
9840 | ||
9841 | <DD> | |
9842 | The variable is treated as an integer; arithmetic evaluation (see | |
0001803f | 9843 | <FONT SIZE=-1><B>ARITHMETIC EVALUATION</B> |
17345e5a JA |
9844 | |
9845 | </FONT> | |
0001803f | 9846 | above) is performed when the variable is assigned a value. |
17345e5a JA |
9847 | <DT><B>-l</B> |
9848 | ||
9849 | <DD> | |
9850 | When the variable is assigned a value, all upper-case characters are | |
9851 | converted to lower-case. | |
9852 | The upper-case attribute is disabled. | |
ac50fbac CR |
9853 | <DT><B>-n</B> |
9854 | ||
9855 | <DD> | |
9856 | Give each <I>name</I> the <I>nameref</I> attribute, making | |
9857 | it a name reference to another variable. | |
9858 | That other variable is defined by the value of <I>name</I>. | |
a0c0a00f CR |
9859 | All references, assignments, and attribute modifications |
9860 | to <I>name</I>, except those using or changing the | |
ac50fbac CR |
9861 | <B>-n</B> attribute itself, are performed on the variable referenced by |
9862 | <I>name</I>'s value. | |
a0c0a00f | 9863 | The nameref attribute cannot be applied to array variables. |
17345e5a JA |
9864 | <DT><B>-r</B> |
9865 | ||
9866 | <DD> | |
9867 | Make <I>name</I>s readonly. These names cannot then be assigned values | |
9868 | by subsequent assignment statements or unset. | |
9869 | <DT><B>-t</B> | |
9870 | ||
9871 | <DD> | |
9872 | Give each <I>name</I> the <I>trace</I> attribute. | |
9873 | Traced functions inherit the <B>DEBUG</B> and <B>RETURN</B> traps from | |
9874 | the calling shell. | |
9875 | The trace attribute has no special meaning for variables. | |
9876 | <DT><B>-u</B> | |
9877 | ||
9878 | <DD> | |
9879 | When the variable is assigned a value, all lower-case characters are | |
9880 | converted to upper-case. | |
9881 | The lower-case attribute is disabled. | |
9882 | <DT><B>-x</B> | |
9883 | ||
9884 | <DD> | |
9885 | Mark <I>name</I>s for export to subsequent commands via the environment. | |
9886 | ||
9887 | </DL> | |
9888 | <P> | |
9889 | ||
9890 | Using `+' instead of `-' | |
9891 | turns off the attribute instead, | |
9892 | with the exceptions that <B>+a</B> | |
0001803f | 9893 | may not be used to destroy an array variable and <B>+r</B> will not |
17345e5a | 9894 | remove the readonly attribute. |
ac50fbac CR |
9895 | When used in a function, |
9896 | <B>declare</B> | |
9897 | ||
9898 | and | |
9899 | <B>typeset</B> | |
9900 | ||
9901 | make each | |
9902 | <I>name</I> local, as with the | |
17345e5a JA |
9903 | <B>local</B> |
9904 | ||
495aee44 | 9905 | command, |
ac50fbac CR |
9906 | unless the <B>-g</B> option is supplied. |
9907 | If a variable name is followed by =<I>value</I>, the value of | |
17345e5a | 9908 | the variable is set to <I>value</I>. |
ac50fbac CR |
9909 | When using <B>-a</B> or <B>-A</B> and the compound assignment syntax to |
9910 | create array variables, additional attributes do not take effect until | |
9911 | subsequent assignments. | |
17345e5a JA |
9912 | The return value is 0 unless an invalid option is encountered, |
9913 | an attempt is made to define a function using | |
9914 | ||
9915 | <TT>-f foo=bar</TT>, | |
9916 | an attempt is made to assign a value to a readonly variable, | |
9917 | an attempt is made to assign a value to an array variable without | |
9918 | using the compound assignment syntax (see | |
9919 | <B>Arrays</B> | |
9920 | ||
9921 | above), one of the <I>names</I> is not a valid shell variable name, | |
9922 | an attempt is made to turn off readonly status for a readonly variable, | |
9923 | an attempt is made to turn off array status for an array variable, | |
9924 | or an attempt is made to display a non-existent function with <B>-f</B>. | |
9925 | </DL> | |
9926 | ||
ac50fbac | 9927 | <DT><B>dirs [-clpv</B>] [+<I>n</I>] [-<I>n</I>] |
17345e5a JA |
9928 | |
9929 | <DD> | |
9930 | Without options, displays the list of currently remembered directories. | |
9931 | The default display is on a single line with directory names separated | |
9932 | by spaces. | |
a0c0a00f | 9933 | Directories are added to the list with the |
17345e5a JA |
9934 | <B>pushd</B> |
9935 | ||
9936 | command; the | |
9937 | <B>popd</B> | |
9938 | ||
9939 | command removes entries from the list. | |
a0c0a00f | 9940 | The current directory is always the first directory in the stack. |
17345e5a JA |
9941 | <DL COMPACT><DT><DD> |
9942 | ||
9943 | <DL COMPACT> | |
17345e5a JA |
9944 | <DT><B>-c</B> |
9945 | ||
9946 | <DD> | |
9947 | Clears the directory stack by deleting all of the entries. | |
9948 | <DT><B>-l</B> | |
9949 | ||
9950 | <DD> | |
ac50fbac CR |
9951 | Produces a listing using full pathnames; |
9952 | the default listing format uses a tilde to denote the home directory. | |
17345e5a JA |
9953 | <DT><B>-p</B> |
9954 | ||
9955 | <DD> | |
9956 | Print the directory stack with one entry per line. | |
9957 | <DT><B>-v</B> | |
9958 | ||
9959 | <DD> | |
9960 | Print the directory stack with one entry per line, | |
9961 | prefixing each entry with its index in the stack. | |
ac50fbac CR |
9962 | <DT><B>+</B><I>n</I><DD> |
9963 | Displays the <I>n</I>th entry counting from the left of the list | |
9964 | shown by | |
9965 | <B>dirs</B> | |
9966 | ||
9967 | when invoked without options, starting with zero. | |
9968 | <DT><B>-</B><I>n</I><DD> | |
9969 | Displays the <I>n</I>th entry counting from the right of the list | |
9970 | shown by | |
9971 | <B>dirs</B> | |
9972 | ||
9973 | when invoked without options, starting with zero. | |
17345e5a JA |
9974 | |
9975 | </DL> | |
9976 | <P> | |
9977 | ||
9978 | The return value is 0 unless an | |
9979 | invalid option is supplied or <I>n</I> indexes beyond the end | |
9980 | of the directory stack. | |
9981 | </DL> | |
9982 | ||
a0c0a00f | 9983 | <DT><B>disown</B> [<B>-ar</B>] [<B>-h</B>] [<I>jobspec</I> ... | <I>pid</I> ... ]<DD> |
ac50fbac | 9984 | Without options, remove each |
17345e5a JA |
9985 | <I>jobspec</I> |
9986 | ||
ac50fbac | 9987 | from the table of active jobs. |
17345e5a JA |
9988 | If |
9989 | <I>jobspec</I> | |
9990 | ||
ac50fbac CR |
9991 | is not present, and neither the <B>-a</B> nor the <B>-r</B> option |
9992 | is supplied, the <I>current job</I> is used. | |
17345e5a JA |
9993 | If the <B>-h</B> option is given, each |
9994 | <I>jobspec</I> | |
9995 | ||
9996 | is not removed from the table, but is marked so that | |
9997 | <FONT SIZE=-1><B>SIGHUP</B> | |
9998 | ||
9999 | </FONT> | |
10000 | is not sent to the job if the shell receives a | |
10001 | <FONT SIZE=-1><B>SIGHUP</B>. | |
10002 | ||
10003 | </FONT> | |
10004 | If no | |
10005 | <I>jobspec</I> | |
10006 | ||
17345e5a JA |
10007 | is supplied, the |
10008 | <B>-a</B> | |
10009 | ||
10010 | option means to remove or mark all jobs; the | |
10011 | <B>-r</B> | |
10012 | ||
10013 | option without a | |
10014 | <I>jobspec</I> | |
10015 | ||
10016 | argument restricts operation to running jobs. | |
10017 | The return value is 0 unless a | |
10018 | <I>jobspec</I> | |
10019 | ||
10020 | does not specify a valid job. | |
10021 | <DT><B>echo</B> [<B>-neE</B>] [<I>arg</I> ...]<DD> | |
10022 | Output the <I>arg</I>s, separated by spaces, followed by a newline. | |
ac50fbac | 10023 | The return status is 0 unless a write error occurs. |
17345e5a JA |
10024 | If <B>-n</B> is specified, the trailing newline is |
10025 | suppressed. If the <B>-e</B> option is given, interpretation of | |
10026 | the following backslash-escaped characters is enabled. The | |
10027 | <B>-E</B> | |
10028 | ||
10029 | option disables the interpretation of these escape characters, | |
10030 | even on systems where they are interpreted by default. | |
10031 | The <B>xpg_echo</B> shell option may be used to | |
10032 | dynamically determine whether or not <B>echo</B> expands these | |
10033 | escape characters by default. | |
10034 | <B>echo</B> | |
10035 | ||
10036 | does not interpret <B>--</B> to mean the end of options. | |
10037 | <B>echo</B> | |
10038 | ||
10039 | interprets the following escape sequences: | |
10040 | <DL COMPACT><DT><DD> | |
10041 | ||
10042 | <DL COMPACT> | |
10043 | <DT><B>\a</B> | |
10044 | ||
10045 | <DD> | |
10046 | alert (bell) | |
10047 | <DT><B>\b</B> | |
10048 | ||
10049 | <DD> | |
10050 | backspace | |
10051 | <DT><B>\c</B> | |
10052 | ||
10053 | <DD> | |
10054 | suppress further output | |
10055 | <DT><B>\e</B> | |
10056 | ||
495aee44 CR |
10057 | <DD> |
10058 | <DT><B>\E</B> | |
10059 | ||
17345e5a JA |
10060 | <DD> |
10061 | an escape character | |
10062 | <DT><B>\f</B> | |
10063 | ||
10064 | <DD> | |
10065 | form feed | |
10066 | <DT><B>\n</B> | |
10067 | ||
10068 | <DD> | |
10069 | new line | |
10070 | <DT><B>\r</B> | |
10071 | ||
10072 | <DD> | |
10073 | carriage return | |
10074 | <DT><B>\t</B> | |
10075 | ||
10076 | <DD> | |
10077 | horizontal tab | |
10078 | <DT><B>\v</B> | |
10079 | ||
10080 | <DD> | |
10081 | vertical tab | |
10082 | <DT><B>\\</B> | |
10083 | ||
10084 | <DD> | |
10085 | backslash | |
10086 | <DT><B>\0</B><I>nnn</I> | |
10087 | ||
10088 | <DD> | |
10089 | the eight-bit character whose value is the octal value <I>nnn</I> | |
10090 | (zero to three octal digits) | |
10091 | <DT><B>\x</B><I>HH</I> | |
10092 | ||
10093 | <DD> | |
10094 | the eight-bit character whose value is the hexadecimal value <I>HH</I> | |
10095 | (one or two hex digits) | |
495aee44 CR |
10096 | <DT><B>\u</B><I>HHHH</I> |
10097 | ||
10098 | <DD> | |
10099 | the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value | |
10100 | <I>HHHH</I> (one to four hex digits) | |
10101 | <DT><B>\U</B><I>HHHHHHHH</I> | |
10102 | ||
10103 | <DD> | |
10104 | the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value | |
10105 | <I>HHHHHHHH</I> (one to eight hex digits) | |
17345e5a JA |
10106 | |
10107 | </DL></DL> | |
10108 | ||
10109 | <DT><B>enable</B> [<B>-a</B>] [<B>-dnps</B>] [<B>-f</B> <I>filename</I>] [<I>name</I> ...]<DD> | |
10110 | Enable and disable builtin shell commands. | |
10111 | Disabling a builtin allows a disk command which has the same name | |
10112 | as a shell builtin to be executed without specifying a full pathname, | |
10113 | even though the shell normally searches for builtins before disk commands. | |
10114 | If <B>-n</B> is used, each <I>name</I> | |
10115 | is disabled; otherwise, | |
10116 | <I>names</I> are enabled. For example, to use the | |
10117 | <B>test</B> | |
10118 | ||
10119 | binary found via the | |
10120 | <FONT SIZE=-1><B>PATH</B> | |
10121 | ||
10122 | </FONT> | |
10123 | instead of the shell builtin version, run | |
10124 | <TT>enable -n test</TT>. | |
10125 | ||
10126 | The | |
10127 | <B>-f</B> | |
10128 | ||
10129 | option means to load the new builtin command | |
10130 | <I>name</I> | |
10131 | ||
10132 | from shared object | |
10133 | <I>filename</I>, | |
10134 | ||
10135 | on systems that support dynamic loading. The | |
10136 | <B>-d</B> | |
10137 | ||
10138 | option will delete a builtin previously loaded with | |
10139 | <B>-f</B>. | |
10140 | ||
10141 | If no <I>name</I> arguments are given, or if the | |
10142 | <B>-p</B> | |
10143 | ||
10144 | option is supplied, a list of shell builtins is printed. | |
10145 | With no other option arguments, the list consists of all enabled | |
10146 | shell builtins. | |
10147 | If <B>-n</B> is supplied, only disabled builtins are printed. | |
10148 | If <B>-a</B> is supplied, the list printed includes all builtins, with an | |
10149 | indication of whether or not each is enabled. | |
10150 | If <B>-s</B> is supplied, the output is restricted to the POSIX | |
10151 | <I>special</I> builtins. | |
10152 | The return value is 0 unless a | |
10153 | <I>name</I> | |
10154 | ||
10155 | is not a shell builtin or there is an error loading a new builtin | |
10156 | from a shared object. | |
10157 | <DT><B>eval</B> [<I>arg</I> ...]<DD> | |
10158 | The <I>arg</I>s are read and concatenated together into a single | |
10159 | command. This command is then read and executed by the shell, and | |
10160 | its exit status is returned as the value of | |
10161 | <B>eval</B>. | |
10162 | ||
10163 | If there are no | |
10164 | <I>args</I>, | |
10165 | ||
10166 | or only null arguments, | |
10167 | <B>eval</B> | |
10168 | ||
10169 | returns 0. | |
10170 | <DT><B>exec</B> [<B>-cl</B>] [<B>-a</B> <I>name</I>] [<I>command</I> [<I>arguments</I>]]<DD> | |
10171 | If | |
10172 | <I>command</I> | |
10173 | ||
10174 | is specified, it replaces the shell. | |
10175 | No new process is created. The | |
10176 | <I>arguments</I> | |
10177 | ||
10178 | become the arguments to <I>command</I>. | |
10179 | If the | |
10180 | <B>-l</B> | |
10181 | ||
10182 | option is supplied, | |
a0c0a00f | 10183 | the shell places a dash at the beginning of the zeroth argument passed to |
17345e5a JA |
10184 | <I>command</I>. |
10185 | ||
10186 | This is what | |
10187 | <I>login</I>(1) | |
10188 | ||
10189 | does. The | |
10190 | <B>-c</B> | |
10191 | ||
10192 | option causes | |
10193 | <I>command</I> | |
10194 | ||
10195 | to be executed with an empty environment. If | |
10196 | <B>-a</B> | |
10197 | ||
10198 | is supplied, the shell passes | |
10199 | <I>name</I> | |
10200 | ||
ac50fbac CR |
10201 | as the zeroth argument to the executed command. |
10202 | If | |
17345e5a JA |
10203 | <I>command</I> |
10204 | ||
10205 | cannot be executed for some reason, a non-interactive shell exits, | |
ac50fbac | 10206 | unless the |
17345e5a JA |
10207 | <B>execfail</B> |
10208 | ||
ac50fbac CR |
10209 | shell option |
10210 | is enabled. In that case, it returns failure. | |
17345e5a JA |
10211 | An interactive shell returns failure if the file cannot be executed. |
10212 | If | |
10213 | <I>command</I> | |
10214 | ||
10215 | is not specified, any redirections take effect in the current shell, | |
10216 | and the return status is 0. If there is a redirection error, the | |
10217 | return status is 1. | |
10218 | <DT><B>exit</B> [<I>n</I>]<DD> | |
10219 | Cause the shell to exit | |
10220 | with a status of <I>n</I>. If | |
10221 | <I>n</I> | |
10222 | ||
10223 | is omitted, the exit status | |
10224 | is that of the last command executed. | |
10225 | A trap on | |
10226 | <FONT SIZE=-1><B>EXIT</B> | |
10227 | ||
10228 | </FONT> | |
10229 | is executed before the shell terminates. | |
10230 | <DT><B>export</B> [<B>-fn</B>] [<I>name</I>[=<I>word</I>]] ...<DD> | |
10231 | ||
10232 | <DT><B>export -p</B> | |
10233 | ||
10234 | <DD> | |
10235 | ||
10236 | The supplied | |
10237 | <I>names</I> | |
10238 | ||
10239 | are marked for automatic export to the environment of | |
a0c0a00f | 10240 | subsequently executed commands. If the |
17345e5a JA |
10241 | <B>-f</B> |
10242 | ||
a0c0a00f | 10243 | option is given, the |
17345e5a JA |
10244 | <I>names</I> |
10245 | ||
10246 | refer to functions. | |
10247 | If no | |
10248 | <I>names</I> | |
10249 | ||
10250 | are given, or if the | |
10251 | <B>-p</B> | |
10252 | ||
10253 | option is supplied, a list | |
ac50fbac | 10254 | of names of all exported variables is printed. |
17345e5a JA |
10255 | The |
10256 | <B>-n</B> | |
10257 | ||
10258 | option causes the export property to be removed from each | |
10259 | <I>name</I>. | |
10260 | If a variable name is followed by =<I>word</I>, the value of | |
10261 | the variable is set to <I>word</I>. | |
10262 | <B>export</B> | |
10263 | ||
10264 | returns an exit status of 0 unless an invalid option is | |
10265 | encountered, | |
10266 | one of the <I>names</I> is not a valid shell variable name, or | |
10267 | <B>-f</B> | |
10268 | ||
10269 | is supplied with a | |
10270 | <I>name</I> | |
10271 | ||
10272 | that is not a function. | |
10273 | <DT><B>fc</B> [<B>-e</B> <I>ename</I>] [<B>-lnr</B>] [<I>first</I>] [<I>last</I>]<DD> | |
10274 | ||
10275 | <DT><B>fc</B> <B>-s</B> [<I>pat</I>=<I>rep</I>] [<I>cmd</I>]<DD> | |
10276 | ||
ac50fbac | 10277 | The first form selects a range of commands from |
17345e5a JA |
10278 | <I>first</I> |
10279 | ||
10280 | to | |
10281 | <I>last</I> | |
10282 | ||
ac50fbac | 10283 | from the history list and displays or edits and re-executes them. |
17345e5a JA |
10284 | <I>First</I> |
10285 | ||
10286 | and | |
10287 | <I>last</I> | |
10288 | ||
10289 | may be specified as a string (to locate the last command beginning | |
10290 | with that string) or as a number (an index into the history list, | |
10291 | where a negative number is used as an offset from the current | |
a0c0a00f | 10292 | command number). If |
17345e5a JA |
10293 | <I>last</I> |
10294 | ||
10295 | is not specified it is set to | |
10296 | the current command for listing (so that | |
10297 | ||
10298 | <TT>fc -l -10</TT> | |
10299 | prints the last 10 commands) and to | |
10300 | <I>first</I> | |
10301 | ||
10302 | otherwise. | |
10303 | If | |
10304 | <I>first</I> | |
10305 | ||
10306 | is not specified it is set to the previous | |
10307 | command for editing and -16 for listing. | |
10308 | <P> | |
10309 | The | |
10310 | <B>-n</B> | |
10311 | ||
10312 | option suppresses | |
10313 | the command numbers when listing. The | |
10314 | <B>-r</B> | |
10315 | ||
10316 | option reverses the order of | |
10317 | the commands. If the | |
10318 | <B>-l</B> | |
10319 | ||
10320 | option is given, | |
10321 | the commands are listed on | |
10322 | standard output. Otherwise, the editor given by | |
10323 | <I>ename</I> | |
10324 | ||
10325 | is invoked | |
10326 | on a file containing those commands. If | |
10327 | <I>ename</I> | |
10328 | ||
10329 | is not given, the | |
10330 | value of the | |
10331 | <FONT SIZE=-1><B>FCEDIT</B> | |
10332 | ||
10333 | </FONT> | |
10334 | variable is used, and | |
10335 | the value of | |
10336 | <FONT SIZE=-1><B>EDITOR</B> | |
10337 | ||
10338 | </FONT> | |
10339 | if | |
10340 | <FONT SIZE=-1><B>FCEDIT</B> | |
10341 | ||
10342 | </FONT> | |
10343 | is not set. If neither variable is set, | |
10344 | ||
10345 | <I>vi</I> | |
10346 | ||
10347 | is used. When editing is complete, the edited commands are | |
10348 | echoed and executed. | |
10349 | <P> | |
10350 | In the second form, <I>command</I> is re-executed after each instance | |
10351 | of <I>pat</I> is replaced by <I>rep</I>. | |
ac50fbac | 10352 | <I>Command</I> is intepreted the same as <I>first</I> above. |
17345e5a JA |
10353 | A useful alias to use with this is |
10354 | ||
10355 | <TT>r='fc -s'</TT>, | |
10356 | so that typing | |
10357 | ||
10358 | <TT>r cc</TT> | |
10359 | runs the last command beginning with | |
10360 | ||
10361 | <TT>cc</TT> | |
10362 | and typing | |
10363 | ||
10364 | <TT>r</TT> | |
10365 | re-executes the last command. | |
10366 | <P> | |
10367 | If the first form is used, the return value is 0 unless an invalid | |
10368 | option is encountered or | |
10369 | <I>first</I> | |
10370 | ||
10371 | or | |
10372 | <I>last</I> | |
10373 | ||
10374 | specify history lines out of range. | |
10375 | If the | |
10376 | <B>-e</B> | |
10377 | ||
10378 | option is supplied, the return value is the value of the last | |
10379 | command executed or failure if an error occurs with the temporary | |
10380 | file of commands. If the second form is used, the return status | |
10381 | is that of the command re-executed, unless | |
10382 | <I>cmd</I> | |
10383 | ||
10384 | does not specify a valid history line, in which case | |
10385 | <B>fc</B> | |
10386 | ||
10387 | returns failure. | |
10388 | <DT><B>fg</B> [<I>jobspec</I>]<DD> | |
10389 | Resume | |
10390 | <I>jobspec</I> | |
10391 | ||
10392 | in the foreground, and make it the current job. | |
10393 | If | |
10394 | <I>jobspec</I> | |
10395 | ||
10396 | is not present, the shell's notion of the <I>current job</I> is used. | |
10397 | The return value is that of the command placed into the foreground, | |
10398 | or failure if run when job control is disabled or, when run with | |
10399 | job control enabled, if | |
10400 | <I>jobspec</I> | |
10401 | ||
10402 | does not specify a valid job or | |
10403 | <I>jobspec</I> | |
10404 | ||
10405 | specifies a job that was started without job control. | |
10406 | <DT><B>getopts</B> <I>optstring</I> <I>name</I> [<I>args</I>]<DD> | |
10407 | <B>getopts</B> | |
10408 | ||
10409 | is used by shell procedures to parse positional parameters. | |
10410 | <I>optstring</I> | |
10411 | ||
10412 | contains the option characters to be recognized; if a character | |
10413 | is followed by a colon, the option is expected to have an | |
10414 | argument, which should be separated from it by white space. | |
10415 | The colon and question mark characters may not be used as | |
10416 | option characters. | |
10417 | Each time it is invoked, | |
10418 | <B>getopts</B> | |
10419 | ||
10420 | places the next option in the shell variable | |
10421 | <I>name</I>, | |
10422 | ||
10423 | initializing | |
10424 | <I>name</I> | |
10425 | ||
10426 | if it does not exist, | |
10427 | and the index of the next argument to be processed into the | |
10428 | variable | |
10429 | <FONT SIZE=-1><B>OPTIND</B>. | |
10430 | ||
10431 | </FONT> | |
10432 | <FONT SIZE=-1><B>OPTIND</B> | |
10433 | ||
10434 | </FONT> | |
10435 | is initialized to 1 each time the shell or a shell script | |
10436 | is invoked. When an option requires an argument, | |
10437 | <B>getopts</B> | |
10438 | ||
10439 | places that argument into the variable | |
10440 | <FONT SIZE=-1><B>OPTARG</B>. | |
10441 | ||
10442 | </FONT> | |
10443 | The shell does not reset | |
10444 | <FONT SIZE=-1><B>OPTIND</B> | |
10445 | ||
10446 | </FONT> | |
10447 | automatically; it must be manually reset between multiple | |
10448 | calls to | |
10449 | <B>getopts</B> | |
10450 | ||
10451 | within the same shell invocation if a new set of parameters | |
10452 | is to be used. | |
10453 | <P> | |
10454 | When the end of options is encountered, <B>getopts</B> exits with a | |
10455 | return value greater than zero. | |
0001803f CR |
10456 | <FONT SIZE=-1><B>OPTIND</B> |
10457 | ||
10458 | </FONT> | |
10459 | is set to the index of the first non-option argument, | |
495aee44 | 10460 | and <I>name</I> is set to ?. |
17345e5a JA |
10461 | <P> |
10462 | <B>getopts</B> | |
10463 | ||
10464 | normally parses the positional parameters, but if more arguments are | |
10465 | given in | |
10466 | <I>args</I>, | |
10467 | ||
10468 | <B>getopts</B> | |
10469 | ||
10470 | parses those instead. | |
10471 | <P> | |
10472 | <B>getopts</B> | |
10473 | ||
10474 | can report errors in two ways. If the first character of | |
10475 | <I>optstring</I> | |
10476 | ||
10477 | is a colon, | |
10478 | <I>silent</I> | |
10479 | ||
ac50fbac | 10480 | error reporting is used. In normal operation, diagnostic messages |
17345e5a JA |
10481 | are printed when invalid options or missing option arguments are |
10482 | encountered. | |
10483 | If the variable | |
10484 | <FONT SIZE=-1><B>OPTERR</B> | |
10485 | ||
10486 | </FONT> | |
10487 | is set to 0, no error messages will be displayed, even if the first | |
a0c0a00f | 10488 | character of |
17345e5a JA |
10489 | <I>optstring</I> |
10490 | ||
10491 | is not a colon. | |
10492 | <P> | |
10493 | If an invalid option is seen, | |
10494 | <B>getopts</B> | |
10495 | ||
10496 | places ? into | |
10497 | <I>name</I> | |
10498 | ||
10499 | and, if not silent, | |
10500 | prints an error message and unsets | |
10501 | <FONT SIZE=-1><B>OPTARG</B>. | |
10502 | ||
10503 | </FONT> | |
10504 | If | |
10505 | <B>getopts</B> | |
10506 | ||
10507 | is silent, | |
10508 | the option character found is placed in | |
10509 | <FONT SIZE=-1><B>OPTARG</B> | |
10510 | ||
10511 | </FONT> | |
10512 | and no diagnostic message is printed. | |
10513 | <P> | |
10514 | If a required argument is not found, and | |
10515 | <B>getopts</B> | |
10516 | ||
10517 | is not silent, | |
10518 | a question mark (<B>?</B>) is placed in | |
10519 | <I>name</I>, | |
10520 | ||
10521 | <FONT SIZE=-1><B>OPTARG</B> | |
10522 | ||
10523 | </FONT> | |
10524 | is unset, and a diagnostic message is printed. | |
10525 | If | |
10526 | <B>getopts</B> | |
10527 | ||
10528 | is silent, then a colon (<B>:</B>) is placed in | |
10529 | <I>name</I> | |
10530 | ||
10531 | and | |
10532 | <FONT SIZE=-1><B>OPTARG</B> | |
10533 | ||
10534 | </FONT> | |
10535 | is set to the option character found. | |
10536 | <P> | |
10537 | <B>getopts</B> | |
10538 | ||
10539 | returns true if an option, specified or unspecified, is found. | |
10540 | It returns false if the end of options is encountered or an | |
10541 | error occurs. | |
10542 | <DT><B>hash</B> [<B>-lr</B>] [<B>-p</B> <I>filename</I>] [<B>-dt</B>] [<I>name</I>]<DD> | |
495aee44 | 10543 | Each time <B>hash</B> is invoked, |
a0c0a00f | 10544 | the full pathname of the command |
495aee44 | 10545 | <I>name</I> |
17345e5a | 10546 | |
495aee44 | 10547 | is determined by searching |
17345e5a JA |
10548 | the directories in |
10549 | <B>$PATH</B> | |
10550 | ||
495aee44 | 10551 | and remembered. Any previously-remembered pathname is discarded. |
17345e5a JA |
10552 | If the |
10553 | <B>-p</B> | |
10554 | ||
10555 | option is supplied, no path search is performed, and | |
10556 | <I>filename</I> | |
10557 | ||
ac50fbac | 10558 | is used as the full filename of the command. |
17345e5a JA |
10559 | The |
10560 | <B>-r</B> | |
10561 | ||
10562 | option causes the shell to forget all | |
10563 | remembered locations. | |
10564 | The | |
10565 | <B>-d</B> | |
10566 | ||
10567 | option causes the shell to forget the remembered location of each <I>name</I>. | |
10568 | If the | |
10569 | <B>-t</B> | |
10570 | ||
10571 | option is supplied, the full pathname to which each <I>name</I> corresponds | |
10572 | is printed. If multiple <I>name</I> arguments are supplied with <B>-t</B>, | |
10573 | the <I>name</I> is printed before the hashed full pathname. | |
10574 | The | |
10575 | <B>-l</B> | |
10576 | ||
10577 | option causes output to be displayed in a format that may be reused as input. | |
10578 | If no arguments are given, or if only <B>-l</B> is supplied, | |
10579 | information about remembered commands is printed. | |
10580 | The return status is true unless a | |
10581 | <I>name</I> | |
10582 | ||
10583 | is not found or an invalid option is supplied. | |
10584 | <DT><B>help</B> [<B>-dms</B>] [<I>pattern</I>]<DD> | |
10585 | Display helpful information about builtin commands. If | |
10586 | <I>pattern</I> | |
10587 | ||
10588 | is specified, | |
10589 | <B>help</B> | |
10590 | ||
10591 | gives detailed help on all commands matching | |
10592 | <I>pattern</I>; | |
10593 | ||
10594 | otherwise help for all the builtins and shell control structures | |
10595 | is printed. | |
10596 | <DL COMPACT><DT><DD> | |
10597 | ||
10598 | <DL COMPACT> | |
10599 | <DT><B>-d</B> | |
10600 | ||
10601 | <DD> | |
10602 | Display a short description of each <I>pattern</I> | |
0001803f | 10603 | <DT><B>-m</B> |
17345e5a JA |
10604 | |
10605 | <DD> | |
10606 | Display the description of each <I>pattern</I> in a manpage-like format | |
10607 | <DT><B>-s</B> | |
10608 | ||
10609 | <DD> | |
10610 | Display only a short usage synopsis for each <I>pattern</I> | |
10611 | ||
ac50fbac CR |
10612 | </DL> |
10613 | <P> | |
17345e5a JA |
10614 | |
10615 | The return status is 0 unless no command matches | |
10616 | <I>pattern</I>. | |
10617 | ||
ac50fbac CR |
10618 | </DL> |
10619 | ||
17345e5a JA |
10620 | <DT><B>history [</B><I>n</I>]<DD> |
10621 | ||
10622 | <DT><B>history</B> <B>-c</B><DD> | |
10623 | <DT><B>history -d</B> <I>offset</I><DD> | |
10624 | <DT><B>history</B> <B>-anrw</B> [<I>filename</I>]<DD> | |
10625 | <DT><B>history</B> <B>-p</B> <I>arg</I> [<I>arg ...</I>]<DD> | |
10626 | <DT><B>history</B> <B>-s</B> <I>arg</I> [<I>arg ...</I>]<DD> | |
10627 | ||
10628 | With no options, display the command | |
10629 | history list with line numbers. Lines listed | |
a0c0a00f | 10630 | with a |
17345e5a JA |
10631 | <B>*</B> |
10632 | ||
10633 | have been modified. An argument of | |
10634 | <I>n</I> | |
10635 | ||
10636 | lists only the last | |
10637 | <I>n</I> | |
10638 | ||
10639 | lines. | |
0001803f CR |
10640 | If the shell variable |
10641 | <FONT SIZE=-1><B>HISTTIMEFORMAT</B> | |
10642 | ||
10643 | </FONT> | |
10644 | is set and not null, | |
17345e5a JA |
10645 | it is used as a format string for <I>strftime</I>(3) to display |
10646 | the time stamp associated with each displayed history entry. | |
10647 | No intervening blank is printed between the formatted time stamp | |
10648 | and the history line. | |
10649 | If <I>filename</I> is supplied, it is used as the | |
10650 | name of the history file; if not, the value of | |
10651 | <FONT SIZE=-1><B>HISTFILE</B> | |
10652 | ||
10653 | </FONT> | |
10654 | is used. Options, if supplied, have the following meanings: | |
10655 | <DL COMPACT><DT><DD> | |
10656 | ||
10657 | <DL COMPACT> | |
10658 | <DT><B>-c</B> | |
10659 | ||
10660 | <DD> | |
10661 | Clear the history list by deleting all the entries. | |
10662 | <DT><B>-d</B> <I>offset</I><DD> | |
10663 | Delete the history entry at position <I>offset</I>. | |
10664 | <DT><B>-a</B> | |
10665 | ||
10666 | <DD> | |
a0c0a00f CR |
10667 | Append the ``new'' history lines to the history file. |
10668 | These are history lines entered since the beginning of the current | |
10669 | <B>bash</B> session, but not already appended to the history file. | |
17345e5a JA |
10670 | <DT><B>-n</B> |
10671 | ||
10672 | <DD> | |
10673 | Read the history lines not already read from the history | |
10674 | file into the current history list. These are lines | |
10675 | appended to the history file since the beginning of the | |
10676 | current <B>bash</B> session. | |
10677 | <DT><B>-r</B> | |
10678 | ||
10679 | <DD> | |
10680 | Read the contents of the history file | |
ac50fbac | 10681 | and append them to the current history list. |
17345e5a JA |
10682 | <DT><B>-w</B> |
10683 | ||
10684 | <DD> | |
ac50fbac | 10685 | Write the current history list to the history file, overwriting the |
17345e5a JA |
10686 | history file's contents. |
10687 | <DT><B>-p</B> | |
10688 | ||
10689 | <DD> | |
10690 | Perform history substitution on the following <I>args</I> and display | |
10691 | the result on the standard output. | |
10692 | Does not store the results in the history list. | |
10693 | Each <I>arg</I> must be quoted to disable normal history expansion. | |
10694 | <DT><B>-s</B> | |
10695 | ||
10696 | <DD> | |
10697 | Store the | |
10698 | <I>args</I> | |
10699 | ||
10700 | in the history list as a single entry. The last command in the | |
10701 | history list is removed before the | |
10702 | <I>args</I> | |
10703 | ||
10704 | are added. | |
10705 | ||
10706 | </DL> | |
10707 | <P> | |
10708 | ||
0001803f CR |
10709 | If the |
10710 | <FONT SIZE=-1><B>HISTTIMEFORMAT</B> | |
10711 | ||
10712 | </FONT> | |
10713 | variable is set, the time stamp information | |
17345e5a JA |
10714 | associated with each history entry is written to the history file, |
10715 | marked with the history comment character. | |
10716 | When the history file is read, lines beginning with the history | |
10717 | comment character followed immediately by a digit are interpreted | |
a0c0a00f | 10718 | as timestamps for the following history entry. |
17345e5a JA |
10719 | The return value is 0 unless an invalid option is encountered, an |
10720 | error occurs while reading or writing the history file, an invalid | |
10721 | <I>offset</I> is supplied as an argument to <B>-d</B>, or the | |
10722 | history expansion supplied as an argument to <B>-p</B> fails. | |
10723 | </DL> | |
10724 | ||
10725 | <DT><B>jobs</B> [<B>-lnprs</B>] [ <I>jobspec</I> ... ]<DD> | |
10726 | ||
10727 | <DT><B>jobs</B> <B>-x</B> <I>command</I> [ <I>args</I> ... ]<DD> | |
10728 | ||
10729 | The first form lists the active jobs. The options have the following | |
10730 | meanings: | |
10731 | <DL COMPACT><DT><DD> | |
10732 | ||
10733 | <DL COMPACT> | |
10734 | <DT><B>-l</B> | |
10735 | ||
10736 | <DD> | |
10737 | List process IDs | |
10738 | in addition to the normal information. | |
17345e5a JA |
10739 | <DT><B>-n</B> |
10740 | ||
10741 | <DD> | |
10742 | Display information only about jobs that have changed status since | |
10743 | the user was last notified of their status. | |
495aee44 CR |
10744 | <DT><B>-p</B> |
10745 | ||
10746 | <DD> | |
10747 | List only the process ID of the job's process group | |
10748 | leader. | |
17345e5a JA |
10749 | <DT><B>-r</B> |
10750 | ||
10751 | <DD> | |
ac50fbac | 10752 | Display only running jobs. |
17345e5a JA |
10753 | <DT><B>-s</B> |
10754 | ||
10755 | <DD> | |
ac50fbac | 10756 | Display only stopped jobs. |
17345e5a JA |
10757 | |
10758 | </DL> | |
10759 | <P> | |
10760 | ||
10761 | If | |
10762 | <I>jobspec</I> | |
10763 | ||
10764 | is given, output is restricted to information about that job. | |
10765 | The return status is 0 unless an invalid option is encountered | |
10766 | or an invalid | |
10767 | <I>jobspec</I> | |
10768 | ||
10769 | is supplied. | |
10770 | <P> | |
10771 | ||
10772 | If the | |
10773 | <B>-x</B> | |
10774 | ||
10775 | option is supplied, | |
10776 | <B>jobs</B> | |
10777 | ||
10778 | replaces any | |
10779 | <I>jobspec</I> | |
10780 | ||
10781 | found in | |
10782 | <I>command</I> | |
10783 | ||
10784 | or | |
10785 | <I>args</I> | |
10786 | ||
10787 | with the corresponding process group ID, and executes | |
10788 | <I>command</I> | |
10789 | ||
10790 | passing it | |
10791 | <I>args</I>, | |
10792 | ||
10793 | returning its exit status. | |
10794 | </DL> | |
10795 | ||
10796 | <DT><B>kill</B> [<B>-s</B> <I>sigspec</I> | <B>-n</B> <I>signum</I> | <B>-</B><I>sigspec</I>] [<I>pid</I> | <I>jobspec</I>] ...<DD> | |
10797 | ||
a0c0a00f | 10798 | <DT><B>kill</B> <B>-l</B>|<B>-L</B> [<I>sigspec</I> | <I>exit_status</I>]<DD> |
17345e5a JA |
10799 | |
10800 | Send the signal named by | |
10801 | <I>sigspec</I> | |
10802 | ||
10803 | or | |
10804 | <I>signum</I> | |
10805 | ||
10806 | to the processes named by | |
10807 | <I>pid</I> | |
10808 | ||
10809 | or | |
10810 | <I>jobspec</I>. | |
10811 | ||
10812 | <I>sigspec</I> | |
10813 | ||
10814 | is either a case-insensitive signal name such as | |
10815 | <FONT SIZE=-1><B>SIGKILL</B> | |
10816 | ||
10817 | </FONT> | |
10818 | (with or without the | |
10819 | <FONT SIZE=-1><B>SIG</B> | |
10820 | ||
10821 | </FONT> | |
10822 | prefix) or a signal number; | |
10823 | <I>signum</I> | |
10824 | ||
10825 | is a signal number. | |
10826 | If | |
10827 | <I>sigspec</I> | |
10828 | ||
10829 | is not present, then | |
10830 | <FONT SIZE=-1><B>SIGTERM</B> | |
10831 | ||
10832 | </FONT> | |
10833 | is assumed. | |
10834 | An argument of | |
10835 | <B>-l</B> | |
10836 | ||
10837 | lists the signal names. | |
10838 | If any arguments are supplied when | |
10839 | <B>-l</B> | |
10840 | ||
10841 | is given, the names of the signals corresponding to the arguments are | |
10842 | listed, and the return status is 0. | |
10843 | The <I>exit_status</I> argument to | |
10844 | <B>-l</B> | |
10845 | ||
10846 | is a number specifying either a signal number or the exit status of | |
10847 | a process terminated by a signal. | |
a0c0a00f CR |
10848 | The |
10849 | <B>-L</B> | |
10850 | ||
10851 | option is equivalent to <B>-l</B>. | |
17345e5a JA |
10852 | <B>kill</B> |
10853 | ||
10854 | returns true if at least one signal was successfully sent, or false | |
10855 | if an error occurs or an invalid option is encountered. | |
10856 | <DT><B>let</B> <I>arg</I> [<I>arg</I> ...]<DD> | |
10857 | Each | |
10858 | <I>arg</I> | |
10859 | ||
10860 | is an arithmetic expression to be evaluated (see | |
0001803f | 10861 | <FONT SIZE=-1><B>ARITHMETIC EVALUATION</B> |
17345e5a JA |
10862 | |
10863 | </FONT> | |
0001803f | 10864 | above). |
17345e5a JA |
10865 | If the last |
10866 | <I>arg</I> | |
10867 | ||
10868 | evaluates to 0, | |
10869 | <B>let</B> | |
10870 | ||
10871 | returns 1; 0 is returned otherwise. | |
a0c0a00f | 10872 | <DT><B>local</B> [<I>option</I>] [<I>name</I>[=<I>value</I>] ... | - ]<DD> |
17345e5a | 10873 | For each argument, a local variable named |
a0c0a00f | 10874 | <I>name</I> |
17345e5a JA |
10875 | |
10876 | is created, and assigned | |
10877 | <I>value</I>. | |
10878 | ||
10879 | The <I>option</I> can be any of the options accepted by <B>declare</B>. | |
10880 | When | |
10881 | <B>local</B> | |
10882 | ||
10883 | is used within a function, it causes the variable | |
10884 | <I>name</I> | |
10885 | ||
10886 | to have a visible scope restricted to that function and its children. | |
a0c0a00f CR |
10887 | If <I>name</I> is -, the set of shell options is made local to the function |
10888 | in which <B>local</B> is invoked: shell options changed using the | |
10889 | <B>set</B> builtin inside the function are restored to their original values | |
10890 | when the function returns. | |
17345e5a JA |
10891 | With no operands, |
10892 | <B>local</B> | |
10893 | ||
10894 | writes a list of local variables to the standard output. It is | |
10895 | an error to use | |
10896 | <B>local</B> | |
10897 | ||
10898 | when not within a function. The return status is 0 unless | |
10899 | <B>local</B> | |
10900 | ||
10901 | is used outside a function, an invalid | |
10902 | <I>name</I> | |
10903 | ||
10904 | is supplied, or | |
10905 | <I>name</I> is a readonly variable. | |
10906 | <DT><B>logout</B> | |
10907 | ||
10908 | <DD> | |
10909 | Exit a login shell. | |
a0c0a00f | 10910 | <DT><B>mapfile</B> [<B>-d</B> <I>delim</I>] [<B>-n</B> <I>count</I>] [<B>-O</B> <I>origin</I>] [<B>-s</B> <I>count</I>] [<B>-t</B>] [<B>-u</B> <I>fd</I>] [<B>-C</B> <I>callback</I>] [<B>-c</B> <I>quantum</I>] [<I>array</I>]<DD> |
17345e5a | 10911 | |
a0c0a00f | 10912 | <DT><B>readarray</B> [<B>-d</B> <I>delim</I>] [<B>-n</B> <I>count</I>] [<B>-O</B> <I>origin</I>] [<B>-s</B> <I>count</I>] [<B>-t</B>] [<B>-u</B> <I>fd</I>] [<B>-C</B> <I>callback</I>] [<B>-c</B> <I>quantum</I>] [<I>array</I>]<DD> |
17345e5a | 10913 | |
0001803f | 10914 | Read lines from the standard input into the indexed array variable |
17345e5a JA |
10915 | <I>array</I>, |
10916 | ||
a0c0a00f | 10917 | or from file descriptor |
17345e5a JA |
10918 | <I>fd</I> |
10919 | ||
a0c0a00f | 10920 | if the |
17345e5a JA |
10921 | <B>-u</B> |
10922 | ||
10923 | option is supplied. | |
0001803f CR |
10924 | The variable |
10925 | <FONT SIZE=-1><B>MAPFILE</B> | |
10926 | ||
10927 | </FONT> | |
10928 | is the default <I>array</I>. | |
17345e5a JA |
10929 | Options, if supplied, have the following meanings: |
10930 | <DL COMPACT><DT><DD> | |
10931 | ||
10932 | <DL COMPACT> | |
a0c0a00f CR |
10933 | <DT><B>-d</B> |
10934 | ||
10935 | <DD> | |
10936 | The first character of <I>delim</I> is used to terminate each input line, | |
10937 | rather than newline. | |
17345e5a JA |
10938 | <DT><B>-n</B> |
10939 | ||
10940 | <DD> | |
10941 | Copy at most | |
10942 | <I>count</I> | |
10943 | ||
10944 | lines. If <I>count</I> is 0, all lines are copied. | |
10945 | <DT><B>-O</B> | |
10946 | ||
10947 | <DD> | |
10948 | Begin assigning to | |
10949 | <I>array</I> | |
10950 | ||
10951 | at index | |
10952 | <I>origin</I>. | |
10953 | ||
10954 | The default index is 0. | |
10955 | <DT><B>-s</B> | |
10956 | ||
10957 | <DD> | |
10958 | Discard the first <I>count</I> lines read. | |
10959 | <DT><B>-t</B> | |
10960 | ||
10961 | <DD> | |
a0c0a00f | 10962 | Remove a trailing <I>delim</I> (default newline) from each line read. |
17345e5a JA |
10963 | <DT><B>-u</B> |
10964 | ||
10965 | <DD> | |
10966 | Read lines from file descriptor <I>fd</I> instead of the standard input. | |
10967 | <DT><B>-C</B> | |
10968 | ||
10969 | <DD> | |
10970 | Evaluate | |
10971 | <I>callback</I> | |
10972 | ||
10973 | each time <I>quantum</I> lines are read. The <B>-c</B> option specifies | |
10974 | <I>quantum</I>. | |
10975 | ||
10976 | <DT><B>-c</B> | |
10977 | ||
10978 | <DD> | |
10979 | Specify the number of lines read between each call to | |
10980 | <I>callback</I>. | |
10981 | ||
10982 | ||
10983 | </DL> | |
10984 | <P> | |
10985 | ||
10986 | If | |
10987 | <B>-C</B> | |
10988 | ||
a0c0a00f | 10989 | is specified without |
17345e5a JA |
10990 | <B>-c</B>, |
10991 | ||
10992 | the default quantum is 5000. | |
10993 | When <I>callback</I> is evaluated, it is supplied the index of the next | |
495aee44 CR |
10994 | array element to be assigned and the line to be assigned to that element |
10995 | as additional arguments. | |
a0c0a00f | 10996 | <I>callback</I> is evaluated after the line is read but before the |
17345e5a JA |
10997 | array element is assigned. |
10998 | <P> | |
10999 | ||
11000 | If not supplied with an explicit origin, <B>mapfile</B> will clear <I>array</I> | |
11001 | before assigning to it. | |
11002 | <P> | |
11003 | ||
11004 | <B>mapfile</B> returns successfully unless an invalid option or option | |
0001803f CR |
11005 | argument is supplied, <I>array</I> is invalid or unassignable, or if |
11006 | <I>array</I> is not an indexed array. | |
17345e5a JA |
11007 | </DL> |
11008 | ||
11009 | <DT><B>popd</B> [-<B>n</B>] [+<I>n</I>] [-<I>n</I>]<DD> | |
11010 | Removes entries from the directory stack. With no arguments, | |
11011 | removes the top directory from the stack, and performs a | |
11012 | <B>cd</B> | |
11013 | ||
11014 | to the new top directory. | |
11015 | Arguments, if supplied, have the following meanings: | |
11016 | <DL COMPACT><DT><DD> | |
11017 | ||
11018 | <DL COMPACT> | |
11019 | <DT><B>-n</B> | |
11020 | ||
11021 | <DD> | |
11022 | Suppresses the normal change of directory when removing directories | |
11023 | from the stack, so that only the stack is manipulated. | |
11024 | <DT><B>+</B><I>n</I><DD> | |
11025 | Removes the <I>n</I>th entry counting from the left of the list | |
11026 | shown by | |
11027 | <B>dirs</B>, | |
11028 | ||
11029 | starting with zero. For example: | |
11030 | ||
11031 | <TT>popd +0</TT> | |
11032 | removes the first directory, | |
11033 | ||
11034 | <TT>popd +1</TT> | |
11035 | the second. | |
11036 | <DT><B>-</B><I>n</I><DD> | |
11037 | Removes the <I>n</I>th entry counting from the right of the list | |
11038 | shown by | |
11039 | <B>dirs</B>, | |
11040 | ||
11041 | starting with zero. For example: | |
11042 | ||
11043 | <TT>popd -0</TT> | |
11044 | removes the last directory, | |
11045 | ||
11046 | <TT>popd -1</TT> | |
11047 | the next to last. | |
11048 | ||
11049 | </DL> | |
11050 | <P> | |
11051 | ||
11052 | If the | |
11053 | <B>popd</B> | |
11054 | ||
a0c0a00f | 11055 | command is successful, a |
17345e5a JA |
11056 | <B>dirs</B> |
11057 | ||
11058 | is performed as well, and the return status is 0. | |
11059 | <B>popd</B> | |
11060 | ||
11061 | returns false if an invalid option is encountered, the directory stack | |
11062 | is empty, a non-existent directory stack entry is specified, or the | |
11063 | directory change fails. | |
11064 | </DL> | |
11065 | ||
11066 | <DT><B>printf</B> [<B>-v</B> <I>var</I>] <I>format</I> [<I>arguments</I>]<DD> | |
11067 | Write the formatted <I>arguments</I> to the standard output under the | |
11068 | control of the <I>format</I>. | |
495aee44 CR |
11069 | The <B>-v</B> option causes the output to be assigned to the variable |
11070 | <I>var</I> rather than being printed to the standard output. | |
11071 | <P> | |
17345e5a JA |
11072 | The <I>format</I> is a character string which contains three types of objects: |
11073 | plain characters, which are simply copied to standard output, character | |
11074 | escape sequences, which are converted and copied to the standard output, and | |
11075 | format specifications, each of which causes printing of the next successive | |
11076 | <I>argument</I>. | |
495aee44 CR |
11077 | In addition to the standard <I>printf</I>(1) format specifications, |
11078 | <B>printf</B> interprets the following extensions: | |
11079 | <DL COMPACT><DT><DD> | |
11080 | ||
11081 | <DL COMPACT> | |
11082 | <DT><B>%b</B> | |
11083 | ||
11084 | <DD> | |
11085 | causes | |
17345e5a | 11086 | <B>printf</B> to expand backslash escape sequences in the corresponding |
a0c0a00f CR |
11087 | <I>argument</I> |
11088 | in the same way as <B>echo -e</B>. | |
495aee44 CR |
11089 | <DT><B>%q</B> |
11090 | ||
11091 | <DD> | |
11092 | causes <B>printf</B> to output the corresponding | |
17345e5a | 11093 | <I>argument</I> in a format that can be reused as shell input. |
495aee44 CR |
11094 | <DT><B>%(</B><I>datefmt</I>)T |
11095 | ||
11096 | <DD> | |
11097 | causes <B>printf</B> to output the date-time string resulting from using | |
ac50fbac CR |
11098 | <I>datefmt</I> as a format string for <I>strftime</I>(3). |
11099 | The corresponding <I>argument</I> is an integer representing the number of | |
11100 | seconds since the epoch. | |
11101 | Two special argument values may be used: -1 represents the current | |
495aee44 | 11102 | time, and -2 represents the time the shell was invoked. |
ac50fbac CR |
11103 | If no argument is specified, conversion behaves as if -1 had been given. |
11104 | This is an exception to the usual <B>printf</B> behavior. | |
495aee44 CR |
11105 | |
11106 | </DL> | |
17345e5a | 11107 | <P> |
495aee44 CR |
11108 | |
11109 | Arguments to non-string format specifiers are treated as C constants, | |
11110 | except that a leading plus or minus sign is allowed, and if the leading | |
11111 | character is a single or double quote, the value is the ASCII value of | |
11112 | the following character. | |
17345e5a | 11113 | <P> |
495aee44 | 11114 | |
17345e5a JA |
11115 | The <I>format</I> is reused as necessary to consume all of the <I>arguments</I>. |
11116 | If the <I>format</I> requires more <I>arguments</I> than are supplied, the | |
11117 | extra format specifications behave as if a zero value or null string, as | |
495aee44 CR |
11118 | appropriate, had been supplied. |
11119 | The return value is zero on success, non-zero on failure. | |
11120 | </DL> | |
11121 | ||
17345e5a JA |
11122 | <DT><B>pushd</B> [<B>-n</B>] [+<I>n</I>] [-<I>n</I>]<DD> |
11123 | ||
11124 | <DT><B>pushd</B> [<B>-n</B>] [<I>dir</I>]<DD> | |
11125 | ||
11126 | Adds a directory to the top of the directory stack, or rotates | |
11127 | the stack, making the new top of the stack the current working | |
a0c0a00f | 11128 | directory. With no arguments, <B>pushd</B> exchanges the top two directories |
17345e5a JA |
11129 | and returns 0, unless the directory stack is empty. |
11130 | Arguments, if supplied, have the following meanings: | |
11131 | <DL COMPACT><DT><DD> | |
11132 | ||
11133 | <DL COMPACT> | |
11134 | <DT><B>-n</B> | |
11135 | ||
11136 | <DD> | |
a0c0a00f CR |
11137 | Suppresses the normal change of directory when rotating or |
11138 | adding directories to the stack, so that only the stack is manipulated. | |
17345e5a JA |
11139 | <DT><B>+</B><I>n</I><DD> |
11140 | Rotates the stack so that the <I>n</I>th directory | |
11141 | (counting from the left of the list shown by | |
11142 | <B>dirs</B>, | |
11143 | ||
11144 | starting with zero) | |
11145 | is at the top. | |
11146 | <DT><B>-</B><I>n</I><DD> | |
11147 | Rotates the stack so that the <I>n</I>th directory | |
11148 | (counting from the right of the list shown by | |
11149 | <B>dirs</B>, | |
11150 | ||
11151 | starting with zero) is at the top. | |
11152 | <DT><I>dir</I> | |
11153 | ||
11154 | <DD> | |
11155 | Adds | |
11156 | <I>dir</I> | |
11157 | ||
11158 | to the directory stack at the top, making it the | |
ac50fbac CR |
11159 | new current working directory as if it had been supplied as the argument |
11160 | to the <B>cd</B> builtin. | |
17345e5a JA |
11161 | |
11162 | </DL> | |
11163 | <P> | |
11164 | ||
11165 | If the | |
11166 | <B>pushd</B> | |
11167 | ||
a0c0a00f | 11168 | command is successful, a |
17345e5a JA |
11169 | <B>dirs</B> |
11170 | ||
11171 | is performed as well. | |
11172 | If the first form is used, | |
11173 | <B>pushd</B> | |
11174 | ||
11175 | returns 0 unless the cd to | |
11176 | <I>dir</I> | |
11177 | ||
11178 | fails. With the second form, | |
11179 | <B>pushd</B> | |
11180 | ||
11181 | returns 0 unless the directory stack is empty, | |
11182 | a non-existent directory stack element is specified, | |
11183 | or the directory change to the specified new current directory | |
11184 | fails. | |
11185 | </DL> | |
11186 | ||
11187 | <DT><B>pwd</B> [<B>-LP</B>]<DD> | |
11188 | Print the absolute pathname of the current working directory. | |
11189 | The pathname printed contains no symbolic links if the | |
11190 | <B>-P</B> | |
11191 | ||
a0c0a00f | 11192 | option is supplied or the |
17345e5a JA |
11193 | <B>-o physical</B> |
11194 | ||
11195 | option to the | |
11196 | <B>set</B> | |
11197 | ||
11198 | builtin command is enabled. | |
11199 | If the | |
11200 | <B>-L</B> | |
11201 | ||
11202 | option is used, the pathname printed may contain symbolic links. | |
11203 | The return status is 0 unless an error occurs while | |
11204 | reading the name of the current directory or an | |
11205 | invalid option is supplied. | |
0001803f | 11206 | <DT><B>read</B> [<B>-ers</B>] [<B>-a</B> <I>aname</I>] [<B>-d</B> <I>delim</I>] [<B>-i</B> <I>text</I>] [<B>-n</B> <I>nchars</I>] [<B>-N</B> <I>nchars</I>] [<B>-p</B> <I>prompt</I>] [<B>-t</B> <I>timeout</I>] [<B>-u</B> <I>fd</I>] [<I>name</I> ...]<DD> |
17345e5a | 11207 | One line is read from the standard input, or from the file descriptor |
a0c0a00f CR |
11208 | <I>fd</I> supplied as an argument to the <B>-u</B> option, |
11209 | split into words as described above under <B>Word Splitting</B>, | |
11210 | and the first word | |
17345e5a JA |
11211 | is assigned to the first |
11212 | <I>name</I>, | |
11213 | ||
11214 | the second word to the second | |
11215 | <I>name</I>, | |
11216 | ||
a0c0a00f CR |
11217 | and so on. |
11218 | If there are more words than names, the remaining words and their | |
11219 | intervening delimiters are assigned to the last | |
17345e5a JA |
11220 | <I>name</I>. |
11221 | ||
11222 | If there are fewer words read from the input stream than names, | |
11223 | the remaining names are assigned empty values. | |
a0c0a00f | 11224 | The characters in |
17345e5a JA |
11225 | <FONT SIZE=-1><B>IFS</B> |
11226 | ||
11227 | </FONT> | |
ac50fbac CR |
11228 | are used to split the line into words using the same rules the shell |
11229 | uses for expansion (described above under <B>Word Splitting</B>). | |
17345e5a JA |
11230 | The backslash character (<B>\</B>) may be used to remove any special |
11231 | meaning for the next character read and for line continuation. | |
11232 | Options, if supplied, have the following meanings: | |
11233 | <DL COMPACT><DT><DD> | |
11234 | ||
11235 | <DL COMPACT> | |
11236 | <DT><B>-a </B><I>aname</I> | |
11237 | ||
11238 | <DD> | |
11239 | The words are assigned to sequential indices | |
11240 | of the array variable | |
11241 | <I>aname</I>, | |
11242 | ||
11243 | starting at 0. | |
11244 | <I>aname</I> | |
11245 | ||
11246 | is unset before any new values are assigned. | |
11247 | Other <I>name</I> arguments are ignored. | |
11248 | <DT><B>-d </B><I>delim</I> | |
11249 | ||
11250 | <DD> | |
11251 | The first character of <I>delim</I> is used to terminate the input line, | |
11252 | rather than newline. | |
11253 | <DT><B>-e</B> | |
11254 | ||
11255 | <DD> | |
11256 | If the standard input | |
11257 | is coming from a terminal, | |
11258 | <B>readline</B> | |
11259 | ||
11260 | (see | |
11261 | <FONT SIZE=-1><B>READLINE</B> | |
11262 | ||
11263 | </FONT> | |
11264 | above) is used to obtain the line. | |
11265 | Readline uses the current (or default, if line editing was not previously | |
11266 | active) editing settings. | |
11267 | <DT><B>-i </B><I>text</I> | |
11268 | ||
11269 | <DD> | |
11270 | If | |
11271 | <B>readline</B> | |
11272 | ||
11273 | is being used to read the line, <I>text</I> is placed into the editing | |
11274 | buffer before editing begins. | |
11275 | <DT><B>-n </B><I>nchars</I> | |
11276 | ||
11277 | <DD> | |
11278 | <B>read</B> returns after reading <I>nchars</I> characters rather than | |
a0c0a00f | 11279 | waiting for a complete line of input, but honors a delimiter if fewer |
0001803f CR |
11280 | than <I>nchars</I> characters are read before the delimiter. |
11281 | <DT><B>-N </B><I>nchars</I> | |
11282 | ||
11283 | <DD> | |
11284 | <B>read</B> returns after reading exactly <I>nchars</I> characters rather | |
11285 | than waiting for a complete line of input, unless EOF is encountered or | |
11286 | <B>read</B> times out. | |
11287 | Delimiter characters encountered in the input are | |
11288 | not treated specially and do not cause <B>read</B> to return until | |
11289 | <I>nchars</I> characters are read. | |
a0c0a00f CR |
11290 | The result is not split on the characters in <B>IFS</B>; the intent is |
11291 | that the variable is assigned exactly the characters read | |
11292 | (with the exception of backslash; see the <B>-r</B> option below). | |
17345e5a JA |
11293 | <DT><B>-p </B><I>prompt</I> |
11294 | ||
11295 | <DD> | |
11296 | Display <I>prompt</I> on standard error, without a | |
11297 | trailing newline, before attempting to read any input. The prompt | |
11298 | is displayed only if input is coming from a terminal. | |
11299 | <DT><B>-r</B> | |
11300 | ||
11301 | <DD> | |
11302 | Backslash does not act as an escape character. | |
11303 | The backslash is considered to be part of the line. | |
11304 | In particular, a backslash-newline pair may not be used as a line | |
11305 | continuation. | |
11306 | <DT><B>-s</B> | |
11307 | ||
11308 | <DD> | |
11309 | Silent mode. If input is coming from a terminal, characters are | |
11310 | not echoed. | |
11311 | <DT><B>-t </B><I>timeout</I> | |
11312 | ||
11313 | <DD> | |
11314 | Cause <B>read</B> to time out and return failure if a complete line of | |
ac50fbac CR |
11315 | input (or a specified number of characters) |
11316 | is not read within <I>timeout</I> seconds. | |
17345e5a JA |
11317 | <I>timeout</I> may be a decimal number with a fractional portion following |
11318 | the decimal point. | |
11319 | This option is only effective if <B>read</B> is reading input from a | |
11320 | terminal, pipe, or other special file; it has no effect when reading | |
11321 | from regular files. | |
ac50fbac CR |
11322 | If <B>read</B> times out, <B>read</B> saves any partial input read into |
11323 | the specified variable <I>name</I>. | |
11324 | If <I>timeout</I> is 0, <B>read</B> returns immediately, without trying to | |
11325 | read any data. The exit status is 0 if input is available on | |
11326 | the specified file descriptor, non-zero otherwise. | |
17345e5a JA |
11327 | The exit status is greater than 128 if the timeout is exceeded. |
11328 | <DT><B>-u </B><I>fd</I> | |
11329 | ||
11330 | <DD> | |
11331 | Read input from file descriptor <I>fd</I>. | |
11332 | ||
11333 | </DL> | |
11334 | <P> | |
11335 | ||
11336 | If no | |
11337 | <I>names</I> | |
11338 | ||
11339 | are supplied, the line read is assigned to the variable | |
11340 | <FONT SIZE=-1><B>REPLY</B>. | |
11341 | ||
11342 | </FONT> | |
a0c0a00f CR |
11343 | The exit status is zero, unless end-of-file is encountered, <B>read</B> |
11344 | times out (in which case the status is greater than 128), | |
ac50fbac CR |
11345 | a variable assignment error (such as assigning to a readonly variable) occurs, |
11346 | or an invalid file descriptor is supplied as the argument to <B>-u</B>. | |
17345e5a JA |
11347 | </DL> |
11348 | ||
ac50fbac | 11349 | <DT><B>readonly</B> [<B>-aAf</B>] [<B>-p</B>] [<I>name</I>[=<I>word</I>] ...]<DD> |
17345e5a JA |
11350 | |
11351 | The given | |
11352 | <I>names</I> are marked readonly; the values of these | |
11353 | <I>names</I> | |
11354 | ||
11355 | may not be changed by subsequent assignment. | |
11356 | If the | |
11357 | <B>-f</B> | |
11358 | ||
11359 | option is supplied, the functions corresponding to the | |
11360 | <I>names</I> are so | |
11361 | marked. | |
11362 | The | |
11363 | <B>-a</B> | |
11364 | ||
11365 | option restricts the variables to indexed arrays; the | |
11366 | <B>-A</B> | |
11367 | ||
11368 | option restricts the variables to associative arrays. | |
ac50fbac CR |
11369 | If both options are supplied, |
11370 | <B>-A</B> | |
11371 | ||
11372 | takes precedence. | |
17345e5a JA |
11373 | If no |
11374 | <I>name</I> | |
11375 | ||
11376 | arguments are given, or if the | |
11377 | <B>-p</B> | |
11378 | ||
11379 | option is supplied, a list of all readonly names is printed. | |
ac50fbac CR |
11380 | The other options may be used to restrict the output to a subset of |
11381 | the set of readonly names. | |
17345e5a JA |
11382 | The |
11383 | <B>-p</B> | |
11384 | ||
11385 | option causes output to be displayed in a format that | |
11386 | may be reused as input. | |
11387 | If a variable name is followed by =<I>word</I>, the value of | |
11388 | the variable is set to <I>word</I>. | |
11389 | The return status is 0 unless an invalid option is encountered, | |
11390 | one of the | |
11391 | <I>names</I> | |
11392 | ||
11393 | is not a valid shell variable name, or | |
11394 | <B>-f</B> | |
11395 | ||
11396 | is supplied with a | |
11397 | <I>name</I> | |
11398 | ||
11399 | that is not a function. | |
11400 | <DT><B>return</B> [<I>n</I>]<DD> | |
ac50fbac CR |
11401 | Causes a function to stop executing and return the value specified by |
11402 | <I>n</I> | |
17345e5a | 11403 | |
ac50fbac | 11404 | to its caller. |
a0c0a00f | 11405 | If |
17345e5a JA |
11406 | <I>n</I> |
11407 | ||
11408 | is omitted, the return status is that of the last command | |
a0c0a00f CR |
11409 | executed in the function body. |
11410 | If <B>return</B> is executed by a trap handler, the last command used to | |
11411 | determine the status is the last command executed before the trap handler. | |
11412 | if <B>return</B> is executed during a <B>DEBUG</B> trap, the last command | |
11413 | used to determine the status is the last command executed by the trap | |
11414 | handler before <B>return</B> was invoked. | |
11415 | If | |
ac50fbac CR |
11416 | <B>return</B> |
11417 | ||
11418 | is used outside a function, | |
a0c0a00f | 11419 | but during execution of a script by the |
17345e5a JA |
11420 | <B>.</B> |
11421 | ||
11422 | (<B>source</B>) command, it causes the shell to stop executing | |
11423 | that script and return either | |
11424 | <I>n</I> | |
11425 | ||
11426 | or the exit status of the last command executed within the | |
ac50fbac CR |
11427 | script as the exit status of the script. |
11428 | If <I>n</I> is supplied, the return value is its least significant | |
11429 | 8 bits. | |
11430 | The return status is non-zero if | |
11431 | <B>return</B> | |
11432 | ||
11433 | is supplied a non-numeric argument, or | |
11434 | is used outside a | |
11435 | function and not during execution of a script by <B>.</B> or <B>source</B>. | |
17345e5a JA |
11436 | Any command associated with the <B>RETURN</B> trap is executed |
11437 | before execution resumes after the function or script. | |
495aee44 | 11438 | <DT><B>set</B> [<B>--abefhkmnptuvxBCEHPT</B>] [<B>-o</B> <I>option-name</I>] [<I>arg</I> ...]<DD> |
17345e5a | 11439 | |
495aee44 | 11440 | <DT><B>set</B> [<B>+abefhkmnptuvxBCEHPT</B>] [<B>+o</B> <I>option-name</I>] [<I>arg</I> ...]<DD> |
17345e5a JA |
11441 | |
11442 | Without options, the name and value of each shell variable are displayed | |
11443 | in a format that can be reused as input | |
11444 | for setting or resetting the currently-set variables. | |
11445 | Read-only variables cannot be reset. | |
ac50fbac | 11446 | In <I>posix</I> mode, only shell variables are listed. |
17345e5a JA |
11447 | The output is sorted according to the current locale. |
11448 | When options are specified, they set or unset shell attributes. | |
11449 | Any arguments remaining after option processing are treated | |
a0c0a00f | 11450 | as values for the positional parameters and are assigned, in order, to |
17345e5a JA |
11451 | <B>$1</B>, |
11452 | ||
11453 | <B>$2</B>, | |
11454 | ||
11455 | <B>...</B> | |
11456 | ||
11457 | <B>$</B><I>n</I>. | |
11458 | ||
11459 | Options, if specified, have the following meanings: | |
11460 | <DL COMPACT><DT><DD> | |
11461 | ||
11462 | <DL COMPACT> | |
11463 | <DT><B>-a</B> | |
11464 | ||
11465 | <DD> | |
a0c0a00f CR |
11466 | Each variable or function that is created or modified is given the |
11467 | export attribute and marked for export to the environment of | |
11468 | subsequent commands. | |
17345e5a JA |
11469 | <DT><B>-b</B> |
11470 | ||
11471 | <DD> | |
11472 | Report the status of terminated background jobs | |
11473 | immediately, rather than before the next primary prompt. This is | |
11474 | effective only when job control is enabled. | |
11475 | <DT><B>-e</B> | |
11476 | ||
11477 | <DD> | |
ac50fbac CR |
11478 | Exit immediately if a |
11479 | <I>pipeline</I> (which may consist of a single <I>simple command</I>), | |
11480 | a <I>list</I>, | |
11481 | or a <I>compound command</I> | |
11482 | (see | |
17345e5a JA |
11483 | <FONT SIZE=-1><B>SHELL GRAMMAR</B> |
11484 | ||
11485 | </FONT> | |
a0c0a00f | 11486 | above), exits with a non-zero status. |
17345e5a JA |
11487 | The shell does not exit if the |
11488 | command that fails is part of the command list immediately following a | |
11489 | <B>while</B> | |
11490 | ||
11491 | or | |
11492 | <B>until</B> | |
11493 | ||
a0c0a00f | 11494 | keyword, |
0001803f | 11495 | part of the test following the |
17345e5a JA |
11496 | <B>if</B> |
11497 | ||
0001803f CR |
11498 | or |
11499 | <B>elif</B> | |
11500 | ||
11501 | reserved words, part of any command executed in a | |
17345e5a JA |
11502 | <B>&&</B> |
11503 | ||
11504 | or | |
11505 | <B>||</B> | |
11506 | ||
0001803f | 11507 | list except the command following the final <B>&&</B> or <B>||</B>, |
17345e5a JA |
11508 | any command in a pipeline but the last, |
11509 | or if the command's return value is | |
0001803f | 11510 | being inverted with |
17345e5a JA |
11511 | <B>!</B>. |
11512 | ||
ac50fbac CR |
11513 | If a compound command other than a subshell |
11514 | returns a non-zero status because a command failed | |
11515 | while <B>-e</B> was being ignored, the shell does not exit. | |
17345e5a | 11516 | A trap on <B>ERR</B>, if set, is executed before the shell exits. |
0001803f CR |
11517 | This option applies to the shell environment and each subshell environment |
11518 | separately (see | |
11519 | <FONT SIZE=-1><B>COMMAND EXECUTION ENVIRONMENT</B> | |
11520 | ||
11521 | </FONT> | |
11522 | above), and may cause | |
11523 | subshells to exit before executing all the commands in the subshell. | |
ac50fbac CR |
11524 | <P> |
11525 | ||
11526 | ||
11527 | If a compound command or shell function executes in a context | |
11528 | where <B>-e</B> is being ignored, | |
11529 | none of the commands executed within the compound command or function body | |
11530 | will be affected by the <B>-e</B> setting, even if <B>-e</B> is set | |
11531 | and a command returns a failure status. | |
11532 | If a compound command or shell function sets <B>-e</B> while executing in | |
11533 | a context where <B>-e</B> is ignored, that setting will not have any | |
11534 | effect until the compound command or the command containing the function | |
11535 | call completes. | |
17345e5a JA |
11536 | <DT><B>-f</B> |
11537 | ||
11538 | <DD> | |
11539 | Disable pathname expansion. | |
11540 | <DT><B>-h</B> | |
11541 | ||
11542 | <DD> | |
11543 | Remember the location of commands as they are looked up for execution. | |
11544 | This is enabled by default. | |
11545 | <DT><B>-k</B> | |
11546 | ||
11547 | <DD> | |
11548 | All arguments in the form of assignment statements | |
11549 | are placed in the environment for a command, not just | |
11550 | those that precede the command name. | |
11551 | <DT><B>-m</B> | |
11552 | ||
11553 | <DD> | |
11554 | Monitor mode. Job control is enabled. This option is on | |
11555 | by default for interactive shells on systems that support | |
11556 | it (see | |
11557 | <FONT SIZE=-1><B>JOB CONTROL</B> | |
11558 | ||
11559 | </FONT> | |
ac50fbac CR |
11560 | above). |
11561 | All processes run in a separate process group. | |
11562 | When a background job completes, the shell prints a line | |
11563 | containing its exit status. | |
17345e5a JA |
11564 | <DT><B>-n</B> |
11565 | ||
11566 | <DD> | |
a0c0a00f CR |
11567 | Read commands but do not execute them. |
11568 | This may be used to check a shell script for syntax errors. | |
11569 | This is ignored by interactive shells. | |
17345e5a JA |
11570 | <DT><B>-o </B><I>option-name</I> |
11571 | ||
11572 | <DD> | |
11573 | The <I>option-name</I> can be one of the following: | |
11574 | <DL COMPACT><DT><DD> | |
11575 | <DL COMPACT> | |
11576 | <DT><B>allexport</B> | |
11577 | ||
11578 | <DD> | |
11579 | Same as | |
11580 | <B>-a</B>. | |
11581 | ||
11582 | <DT><B>braceexpand</B> | |
11583 | ||
11584 | <DD> | |
11585 | Same as | |
11586 | <B>-B</B>. | |
11587 | ||
11588 | <DT><B>emacs</B> | |
11589 | ||
11590 | <DD> | |
11591 | Use an emacs-style command line editing interface. This is enabled | |
11592 | by default when the shell is interactive, unless the shell is started | |
11593 | with the | |
11594 | <B>--noediting</B> | |
11595 | ||
11596 | option. | |
11597 | This also affects the editing interface used for <B>read -e</B>. | |
0001803f | 11598 | <DT><B>errexit</B> |
17345e5a JA |
11599 | |
11600 | <DD> | |
11601 | Same as | |
0001803f | 11602 | <B>-e</B>. |
17345e5a | 11603 | |
0001803f | 11604 | <DT><B>errtrace</B> |
17345e5a JA |
11605 | |
11606 | <DD> | |
11607 | Same as | |
0001803f | 11608 | <B>-E</B>. |
17345e5a | 11609 | |
0001803f | 11610 | <DT><B>functrace</B> |
17345e5a JA |
11611 | |
11612 | <DD> | |
11613 | Same as | |
0001803f | 11614 | <B>-T</B>. |
17345e5a JA |
11615 | |
11616 | <DT><B>hashall</B> | |
11617 | ||
11618 | <DD> | |
11619 | Same as | |
11620 | <B>-h</B>. | |
11621 | ||
11622 | <DT><B>histexpand</B> | |
11623 | ||
11624 | <DD> | |
11625 | Same as | |
11626 | <B>-H</B>. | |
11627 | ||
11628 | <DT><B>history</B> | |
11629 | ||
11630 | <DD> | |
11631 | Enable command history, as described above under | |
11632 | <FONT SIZE=-1><B>HISTORY</B>. | |
11633 | ||
11634 | </FONT> | |
11635 | This option is on by default in interactive shells. | |
11636 | <DT><B>ignoreeof</B> | |
11637 | ||
11638 | <DD> | |
11639 | The effect is as if the shell command | |
11640 | <TT>IGNOREEOF=10</TT> | |
11641 | ||
11642 | had been executed | |
11643 | (see | |
11644 | <B>Shell Variables</B> | |
11645 | ||
11646 | above). | |
11647 | <DT><B>keyword</B> | |
11648 | ||
11649 | <DD> | |
11650 | Same as | |
11651 | <B>-k</B>. | |
11652 | ||
11653 | <DT><B>monitor</B> | |
11654 | ||
11655 | <DD> | |
11656 | Same as | |
11657 | <B>-m</B>. | |
11658 | ||
11659 | <DT><B>noclobber</B> | |
11660 | ||
11661 | <DD> | |
11662 | Same as | |
11663 | <B>-C</B>. | |
11664 | ||
11665 | <DT><B>noexec</B> | |
11666 | ||
11667 | <DD> | |
11668 | Same as | |
11669 | <B>-n</B>. | |
11670 | ||
11671 | <DT><B>noglob</B> | |
11672 | ||
11673 | <DD> | |
11674 | Same as | |
11675 | <B>-f</B>. | |
11676 | ||
11677 | <DT><B>nolog</B> | |
11678 | ||
11679 | <DD> | |
11680 | Currently ignored. | |
11681 | <DT><B>notify</B> | |
11682 | ||
11683 | <DD> | |
11684 | Same as | |
11685 | <B>-b</B>. | |
11686 | ||
11687 | <DT><B>nounset</B> | |
11688 | ||
11689 | <DD> | |
11690 | Same as | |
11691 | <B>-u</B>. | |
11692 | ||
11693 | <DT><B>onecmd</B> | |
11694 | ||
11695 | <DD> | |
11696 | Same as | |
11697 | <B>-t</B>. | |
11698 | ||
11699 | <DT><B>physical</B> | |
11700 | ||
11701 | <DD> | |
11702 | Same as | |
11703 | <B>-P</B>. | |
11704 | ||
11705 | <DT><B>pipefail</B> | |
11706 | ||
11707 | <DD> | |
11708 | If set, the return value of a pipeline is the value of the last | |
11709 | (rightmost) command to exit with a non-zero status, or zero if all | |
11710 | commands in the pipeline exit successfully. | |
11711 | This option is disabled by default. | |
11712 | <DT><B>posix</B> | |
11713 | ||
11714 | <DD> | |
11715 | Change the behavior of | |
11716 | <B>bash</B> | |
11717 | ||
11718 | where the default operation differs | |
11719 | from the POSIX standard to match the standard (<I>posix mode</I>). | |
ac50fbac CR |
11720 | See |
11721 | <FONT SIZE=-1><B>SEE ALSO</B> | |
11722 | ||
11723 | </FONT> | |
11724 | below for a reference to a document that details how posix mode affects | |
11725 | bash's behavior. | |
17345e5a JA |
11726 | <DT><B>privileged</B> |
11727 | ||
11728 | <DD> | |
11729 | Same as | |
11730 | <B>-p</B>. | |
11731 | ||
11732 | <DT><B>verbose</B> | |
11733 | ||
11734 | <DD> | |
11735 | Same as | |
11736 | <B>-v</B>. | |
11737 | ||
11738 | <DT><B>vi</B> | |
11739 | ||
11740 | <DD> | |
11741 | Use a vi-style command line editing interface. | |
11742 | This also affects the editing interface used for <B>read -e</B>. | |
11743 | <DT><B>xtrace</B> | |
11744 | ||
11745 | <DD> | |
11746 | Same as | |
11747 | <B>-x</B>. | |
11748 | ||
11749 | <P> | |
11750 | </DL> | |
11751 | <P> | |
11752 | ||
11753 | If | |
11754 | <B>-o</B> | |
11755 | ||
11756 | is supplied with no <I>option-name</I>, the values of the current options are | |
11757 | printed. | |
11758 | If | |
11759 | <B>+o</B> | |
11760 | ||
11761 | is supplied with no <I>option-name</I>, a series of | |
11762 | <B>set</B> | |
11763 | ||
11764 | commands to recreate the current option settings is displayed on | |
11765 | the standard output. | |
11766 | </DL> | |
11767 | ||
11768 | <DT><B>-p</B> | |
11769 | ||
11770 | <DD> | |
11771 | Turn on | |
11772 | <I>privileged</I> | |
11773 | ||
11774 | mode. In this mode, the | |
11775 | <FONT SIZE=-1><B>$ENV</B> | |
11776 | ||
11777 | </FONT> | |
11778 | and | |
11779 | <FONT SIZE=-1><B>$BASH_ENV</B> | |
11780 | ||
11781 | </FONT> | |
11782 | files are not processed, shell functions are not inherited from the | |
11783 | environment, and the | |
11784 | <FONT SIZE=-1><B>SHELLOPTS</B>, | |
11785 | ||
11786 | </FONT> | |
0001803f CR |
11787 | <FONT SIZE=-1><B>BASHOPTS</B>, |
11788 | ||
11789 | </FONT> | |
11790 | <FONT SIZE=-1><B>CDPATH</B>, | |
17345e5a | 11791 | |
0001803f | 11792 | </FONT> |
17345e5a | 11793 | and |
0001803f | 11794 | <FONT SIZE=-1><B>GLOBIGNORE</B> |
17345e5a | 11795 | |
0001803f | 11796 | </FONT> |
17345e5a JA |
11797 | variables, if they appear in the environment, are ignored. |
11798 | If the shell is started with the effective user (group) id not equal to the | |
11799 | real user (group) id, and the <B>-p</B> option is not supplied, these actions | |
11800 | are taken and the effective user id is set to the real user id. | |
11801 | If the <B>-p</B> option is supplied at startup, the effective user id is | |
11802 | not reset. | |
11803 | Turning this option off causes the effective user | |
11804 | and group ids to be set to the real user and group ids. | |
11805 | <DT><B>-t</B> | |
11806 | ||
11807 | <DD> | |
11808 | Exit after reading and executing one command. | |
11809 | <DT><B>-u</B> | |
11810 | ||
11811 | <DD> | |
0001803f CR |
11812 | Treat unset variables and parameters other than the special |
11813 | parameters "@" and "*" as an error when performing | |
17345e5a | 11814 | parameter expansion. If expansion is attempted on an |
0001803f | 11815 | unset variable or parameter, the shell prints an error message, and, |
17345e5a JA |
11816 | if not interactive, exits with a non-zero status. |
11817 | <DT><B>-v</B> | |
11818 | ||
11819 | <DD> | |
11820 | Print shell input lines as they are read. | |
11821 | <DT><B>-x</B> | |
11822 | ||
11823 | <DD> | |
11824 | After expanding each <I>simple command</I>, | |
11825 | <B>for</B> command, <B>case</B> command, <B>select</B> command, or | |
11826 | arithmetic <B>for</B> command, display the expanded value of | |
11827 | <FONT SIZE=-1><B>PS4</B>, | |
11828 | ||
11829 | </FONT> | |
11830 | followed by the command and its expanded arguments | |
11831 | or associated word list. | |
11832 | <DT><B>-B</B> | |
11833 | ||
11834 | <DD> | |
11835 | The shell performs brace expansion (see | |
11836 | <B>Brace Expansion</B> | |
11837 | ||
11838 | above). This is on by default. | |
11839 | <DT><B>-C</B> | |
11840 | ||
11841 | <DD> | |
11842 | If set, | |
11843 | <B>bash</B> | |
11844 | ||
11845 | does not overwrite an existing file with the | |
11846 | <B>></B>, | |
11847 | ||
11848 | <B>>&</B>, | |
11849 | ||
11850 | and | |
11851 | <B><></B> | |
11852 | ||
a0c0a00f | 11853 | redirection operators. This may be overridden when |
17345e5a JA |
11854 | creating output files by using the redirection operator |
11855 | <B>>|</B> | |
11856 | ||
11857 | instead of | |
11858 | <B>></B>. | |
11859 | ||
11860 | <DT><B>-E</B> | |
11861 | ||
11862 | <DD> | |
11863 | If set, any trap on <B>ERR</B> is inherited by shell functions, command | |
11864 | substitutions, and commands executed in a subshell environment. | |
11865 | The <B>ERR</B> trap is normally not inherited in such cases. | |
11866 | <DT><B>-H</B> | |
11867 | ||
11868 | <DD> | |
11869 | Enable | |
11870 | <B>!</B> | |
11871 | ||
11872 | style history substitution. This option is on by | |
11873 | default when the shell is interactive. | |
11874 | <DT><B>-P</B> | |
11875 | ||
11876 | <DD> | |
ac50fbac | 11877 | If set, the shell does not resolve symbolic links when executing |
17345e5a JA |
11878 | commands such as |
11879 | <B>cd</B> | |
11880 | ||
11881 | that change the current working directory. It uses the | |
11882 | physical directory structure instead. By default, | |
11883 | <B>bash</B> | |
11884 | ||
11885 | follows the logical chain of directories when performing commands | |
11886 | which change the current directory. | |
11887 | <DT><B>-T</B> | |
11888 | ||
11889 | <DD> | |
11890 | If set, any traps on <B>DEBUG</B> and <B>RETURN</B> are inherited by shell | |
11891 | functions, command substitutions, and commands executed in a | |
11892 | subshell environment. | |
11893 | The <B>DEBUG</B> and <B>RETURN</B> traps are normally not inherited | |
11894 | in such cases. | |
11895 | <DT><B>--</B> | |
11896 | ||
11897 | <DD> | |
11898 | If no arguments follow this option, then the positional parameters are | |
11899 | unset. Otherwise, the positional parameters are set to the | |
11900 | <I>arg</I>s, even if some of them begin with a | |
11901 | <B>-</B>. | |
11902 | ||
11903 | <DT><B>-</B> | |
11904 | ||
11905 | <DD> | |
11906 | Signal the end of options, cause all remaining <I>arg</I>s to be | |
11907 | assigned to the positional parameters. The | |
11908 | <B>-x</B> | |
11909 | ||
11910 | and | |
11911 | <B>-v</B> | |
11912 | ||
11913 | options are turned off. | |
11914 | If there are no <I>arg</I>s, | |
11915 | the positional parameters remain unchanged. | |
11916 | ||
11917 | </DL> | |
11918 | <P> | |
11919 | ||
11920 | The options are off by default unless otherwise noted. | |
11921 | Using + rather than - causes these options to be turned off. | |
11922 | The options can also be specified as arguments to an invocation of | |
11923 | the shell. | |
11924 | The current set of options may be found in | |
11925 | <B>$-</B>. | |
11926 | ||
11927 | The return status is always true unless an invalid option is encountered. | |
11928 | </DL> | |
11929 | ||
11930 | <DT><B>shift</B> [<I>n</I>]<DD> | |
11931 | The positional parameters from <I>n</I>+1 ... are renamed to | |
11932 | <B>$1</B> | |
11933 | ||
11934 | <B>....</B> | |
11935 | ||
11936 | Parameters represented by the numbers <B>$#</B> | |
11937 | down to <B>$#</B>-<I>n</I>+1 are unset. | |
11938 | <I>n</I> | |
11939 | ||
11940 | must be a non-negative number less than or equal to <B>$#</B>. | |
11941 | If | |
11942 | <I>n</I> | |
11943 | ||
11944 | is 0, no parameters are changed. | |
11945 | If | |
a0c0a00f | 11946 | <I>n</I> |
17345e5a JA |
11947 | |
11948 | is not given, it is assumed to be 1. | |
11949 | If | |
11950 | <I>n</I> | |
11951 | ||
11952 | is greater than <B>$#</B>, the positional parameters are not changed. | |
11953 | The return status is greater than zero if | |
11954 | <I>n</I> | |
11955 | ||
11956 | is greater than | |
11957 | <B>$#</B> | |
11958 | ||
11959 | or less than zero; otherwise 0. | |
11960 | <DT><B>shopt</B> [<B>-pqsu</B>] [<B>-o</B>] [<I>optname</I> ...]<DD> | |
ac50fbac CR |
11961 | Toggle the values of settings controlling optional shell behavior. |
11962 | The settings can be either those listed below, or, if the | |
11963 | <B>-o</B> | |
11964 | ||
11965 | option is used, those available with the | |
11966 | <B>-o</B> | |
11967 | ||
11968 | option to the <B>set</B> builtin command. | |
17345e5a JA |
11969 | With no options, or with the |
11970 | <B>-p</B> | |
11971 | ||
11972 | option, a list of all settable options is displayed, with | |
11973 | an indication of whether or not each is set. | |
11974 | The <B>-p</B> option causes output to be displayed in a form that | |
11975 | may be reused as input. | |
11976 | Other options have the following meanings: | |
11977 | <DL COMPACT><DT><DD> | |
11978 | ||
11979 | <DL COMPACT> | |
11980 | <DT><B>-s</B> | |
11981 | ||
11982 | <DD> | |
11983 | Enable (set) each <I>optname</I>. | |
11984 | <DT><B>-u</B> | |
11985 | ||
11986 | <DD> | |
11987 | Disable (unset) each <I>optname</I>. | |
11988 | <DT><B>-q</B> | |
11989 | ||
11990 | <DD> | |
11991 | Suppresses normal output (quiet mode); the return status indicates | |
11992 | whether the <I>optname</I> is set or unset. | |
11993 | If multiple <I>optname</I> arguments are given with | |
11994 | <B>-q</B>, | |
11995 | ||
11996 | the return status is zero if all <I>optnames</I> are enabled; non-zero | |
11997 | otherwise. | |
11998 | <DT><B>-o</B> | |
11999 | ||
12000 | <DD> | |
12001 | Restricts the values of <I>optname</I> to be those defined for the | |
12002 | <B>-o</B> | |
12003 | ||
12004 | option to the | |
12005 | <B>set</B> | |
12006 | ||
12007 | builtin. | |
12008 | ||
12009 | </DL> | |
12010 | <P> | |
12011 | ||
12012 | If either | |
12013 | <B>-s</B> | |
12014 | ||
12015 | or | |
12016 | <B>-u</B> | |
12017 | ||
ac50fbac CR |
12018 | is used with no <I>optname</I> arguments, |
12019 | <B>shopt</B> | |
12020 | ||
12021 | shows only those options which are set or unset, respectively. | |
17345e5a JA |
12022 | Unless otherwise noted, the <B>shopt</B> options are disabled (unset) |
12023 | by default. | |
12024 | <P> | |
12025 | ||
12026 | The return status when listing options is zero if all <I>optnames</I> | |
12027 | are enabled, non-zero otherwise. When setting or unsetting options, | |
12028 | the return status is zero unless an <I>optname</I> is not a valid shell | |
12029 | option. | |
12030 | <P> | |
12031 | ||
12032 | The list of <B>shopt</B> options is: | |
12033 | <P> | |
12034 | ||
12035 | ||
12036 | ||
12037 | <DL COMPACT> | |
12038 | <DT><B>autocd</B> | |
12039 | ||
12040 | <DD> | |
12041 | If set, a command name that is the name of a directory is executed as if | |
12042 | it were the argument to the <B>cd</B> command. | |
12043 | This option is only used by interactive shells. | |
12044 | <DT><B>cdable_vars</B> | |
12045 | ||
12046 | <DD> | |
12047 | If set, an argument to the | |
12048 | <B>cd</B> | |
12049 | ||
12050 | builtin command that | |
12051 | is not a directory is assumed to be the name of a variable whose | |
12052 | value is the directory to change to. | |
12053 | <DT><B>cdspell</B> | |
12054 | ||
12055 | <DD> | |
12056 | If set, minor errors in the spelling of a directory component in a | |
12057 | <B>cd</B> | |
12058 | ||
12059 | command will be corrected. | |
12060 | The errors checked for are transposed characters, | |
12061 | a missing character, and one character too many. | |
ac50fbac | 12062 | If a correction is found, the corrected filename is printed, |
17345e5a JA |
12063 | and the command proceeds. |
12064 | This option is only used by interactive shells. | |
12065 | <DT><B>checkhash</B> | |
12066 | ||
12067 | <DD> | |
12068 | If set, <B>bash</B> checks that a command found in the hash | |
12069 | table exists before trying to execute it. If a hashed command no | |
12070 | longer exists, a normal path search is performed. | |
12071 | <DT><B>checkjobs</B> | |
12072 | ||
12073 | <DD> | |
12074 | If set, <B>bash</B> lists the status of any stopped and running jobs before | |
12075 | exiting an interactive shell. If any jobs are running, this causes | |
12076 | the exit to be deferred until a second exit is attempted without an | |
0001803f CR |
12077 | intervening command (see |
12078 | <FONT SIZE=-1><B>JOB CONTROL</B> | |
12079 | ||
12080 | </FONT> | |
12081 | above). The shell always | |
17345e5a JA |
12082 | postpones exiting if any jobs are stopped. |
12083 | <DT><B>checkwinsize</B> | |
12084 | ||
12085 | <DD> | |
12086 | If set, <B>bash</B> checks the window size after each command | |
12087 | and, if necessary, updates the values of | |
12088 | <FONT SIZE=-1><B>LINES</B> | |
12089 | ||
12090 | </FONT> | |
12091 | and | |
12092 | <FONT SIZE=-1><B>COLUMNS</B>. | |
12093 | ||
12094 | </FONT> | |
12095 | <DT><B>cmdhist</B> | |
12096 | ||
12097 | <DD> | |
12098 | If set, | |
12099 | <B>bash</B> | |
12100 | ||
12101 | attempts to save all lines of a multiple-line | |
12102 | command in the same history entry. This allows | |
12103 | easy re-editing of multi-line commands. | |
12104 | <DT><B>compat31</B> | |
12105 | ||
12106 | <DD> | |
12107 | If set, | |
12108 | <B>bash</B> | |
12109 | ||
12110 | changes its behavior to that of version 3.1 with respect to quoted | |
ac50fbac CR |
12111 | arguments to the <B>[[</B> conditional command's <B>=~</B> operator |
12112 | and locale-specific string comparison when using the <B>[[</B> | |
495aee44 CR |
12113 | conditional command's <B><</B> and <B>></B> operators. |
12114 | Bash versions prior to bash-4.1 use ASCII collation and | |
12115 | <I>strcmp</I>(3); | |
12116 | ||
ac50fbac | 12117 | bash-4.1 and later use the current locale's collation sequence and |
495aee44 CR |
12118 | <I>strcoll</I>(3). |
12119 | ||
ac50fbac CR |
12120 | <DT><B>compat32</B> |
12121 | ||
12122 | <DD> | |
12123 | If set, | |
12124 | <B>bash</B> | |
12125 | ||
12126 | changes its behavior to that of version 3.2 with respect to | |
12127 | locale-specific string comparison when using the <B>[[</B> | |
a0c0a00f CR |
12128 | conditional command's <B><</B> and <B>></B> operators (see previous item) |
12129 | and the effect of interrupting a command list. | |
12130 | Bash versions 3.2 and earlier continue with the next command in the list | |
12131 | after one terminates due to an interrupt. | |
0001803f CR |
12132 | <DT><B>compat40</B> |
12133 | ||
12134 | <DD> | |
12135 | If set, | |
12136 | <B>bash</B> | |
12137 | ||
12138 | changes its behavior to that of version 4.0 with respect to locale-specific | |
495aee44 | 12139 | string comparison when using the <B>[[</B> |
ac50fbac CR |
12140 | conditional command's <B><</B> and <B>></B> operators (see description of |
12141 | <B>compat31</B>) | |
0001803f | 12142 | and the effect of interrupting a command list. |
ac50fbac CR |
12143 | Bash versions 4.0 and later interrupt the list as if the shell received the |
12144 | interrupt; previous versions continue with the next command in the list. | |
495aee44 CR |
12145 | <DT><B>compat41</B> |
12146 | ||
12147 | <DD> | |
495aee44 CR |
12148 | If set, |
12149 | <B>bash</B>, | |
12150 | ||
ac50fbac | 12151 | when in <I>posix</I> mode, treats a single quote in a double-quoted |
495aee44 CR |
12152 | parameter expansion as a special character. The single quotes must match |
12153 | (an even number) and the characters between the single quotes are considered | |
12154 | quoted. This is the behavior of posix mode through version 4.1. | |
12155 | The default bash behavior remains as in previous versions. | |
ac50fbac CR |
12156 | <DT><B>compat42</B> |
12157 | ||
12158 | <DD> | |
12159 | If set, | |
12160 | <B>bash</B> | |
12161 | ||
12162 | does not process the replacement string in the pattern substitution word | |
12163 | expansion using quote removal. | |
a0c0a00f CR |
12164 | <DT><B>compat43</B> |
12165 | ||
12166 | <DD> | |
12167 | If set, | |
12168 | <B>bash</B> | |
12169 | ||
12170 | does not print a warning message if an attempt is made to use a quoted compound | |
12171 | array assignment as an argument to <B>declare</B>, | |
12172 | makes word expansion errors | |
12173 | non-fatal errors that cause the current command to fail (the default behavior is | |
12174 | to make them fatal errors that cause the shell to exit), | |
12175 | and does not reset the | |
12176 | loop state when a shell function is executed (this allows <B>break</B> or | |
12177 | <B>continue</B> in a shell function to affect loops in the caller's context). | |
ac50fbac CR |
12178 | <DT><B>complete_fullquote</B> |
12179 | ||
12180 | <DD> | |
12181 | If set, | |
12182 | <B>bash</B> | |
12183 | ||
12184 | quotes all shell metacharacters in filenames and directory names when | |
12185 | performing completion. | |
12186 | If not set, | |
12187 | <B>bash</B> | |
12188 | ||
12189 | removes metacharacters such as the dollar sign from the set of | |
12190 | characters that will be quoted in completed filenames | |
12191 | when these metacharacters appear in shell variable references in words to be | |
12192 | completed. | |
12193 | This means that dollar signs in variable names that expand to directories | |
12194 | will not be quoted; | |
12195 | however, any dollar signs appearing in filenames will not be quoted, either. | |
12196 | This is active only when bash is using backslashes to quote completed | |
12197 | filenames. | |
12198 | This variable is set by default, which is the default bash behavior in | |
12199 | versions through 4.2. | |
12200 | <DT><B>direxpand</B> | |
12201 | ||
12202 | <DD> | |
12203 | If set, | |
12204 | <B>bash</B> | |
12205 | ||
12206 | replaces directory names with the results of word expansion when performing | |
12207 | filename completion. This changes the contents of the readline editing | |
12208 | buffer. | |
12209 | If not set, | |
12210 | <B>bash</B> | |
12211 | ||
12212 | attempts to preserve what the user typed. | |
17345e5a JA |
12213 | <DT><B>dirspell</B> |
12214 | ||
12215 | <DD> | |
12216 | If set, | |
12217 | <B>bash</B> | |
12218 | ||
12219 | attempts spelling correction on directory names during word completion | |
12220 | if the directory name initially supplied does not exist. | |
12221 | <DT><B>dotglob</B> | |
12222 | ||
12223 | <DD> | |
a0c0a00f | 12224 | If set, |
17345e5a JA |
12225 | <B>bash</B> |
12226 | ||
12227 | includes filenames beginning with a `.' in the results of pathname | |
12228 | expansion. | |
12229 | <DT><B>execfail</B> | |
12230 | ||
12231 | <DD> | |
12232 | If set, a non-interactive shell will not exit if | |
12233 | it cannot execute the file specified as an argument to the | |
12234 | <B>exec</B> | |
12235 | ||
12236 | builtin command. An interactive shell does not exit if | |
12237 | <B>exec</B> | |
12238 | ||
12239 | fails. | |
12240 | <DT><B>expand_aliases</B> | |
12241 | ||
12242 | <DD> | |
12243 | If set, aliases are expanded as described above under | |
12244 | <FONT SIZE=-1><B>ALIASES</B>. | |
12245 | ||
12246 | </FONT> | |
12247 | This option is enabled by default for interactive shells. | |
12248 | <DT><B>extdebug</B> | |
12249 | ||
12250 | <DD> | |
a0c0a00f CR |
12251 | If set at shell invocation, arrange to execute the debugger profile |
12252 | before the shell starts, identical to the <B>--debugger</B> option. | |
12253 | If set after invocation, behavior intended for use by debuggers is enabled: | |
17345e5a JA |
12254 | <DL COMPACT><DT><DD> |
12255 | <DL COMPACT> | |
12256 | <DT><B>1.</B> | |
12257 | ||
12258 | <DD> | |
12259 | The <B>-F</B> option to the <B>declare</B> builtin displays the source | |
12260 | file name and line number corresponding to each function name supplied | |
12261 | as an argument. | |
12262 | <DT><B>2.</B> | |
12263 | ||
12264 | <DD> | |
12265 | If the command run by the <B>DEBUG</B> trap returns a non-zero value, the | |
12266 | next command is skipped and not executed. | |
12267 | <DT><B>3.</B> | |
12268 | ||
12269 | <DD> | |
12270 | If the command run by the <B>DEBUG</B> trap returns a value of 2, and the | |
12271 | shell is executing in a subroutine (a shell function or a shell script | |
a0c0a00f CR |
12272 | executed by the <B>.</B> or <B>source</B> builtins), the shell simulates |
12273 | a call to <B>return</B>. | |
17345e5a JA |
12274 | <DT><B>4.</B> |
12275 | ||
12276 | <DD> | |
0001803f CR |
12277 | <FONT SIZE=-1><B>BASH_ARGC</B> |
12278 | ||
12279 | </FONT> | |
12280 | and | |
12281 | <FONT SIZE=-1><B>BASH_ARGV</B> | |
12282 | ||
12283 | </FONT> | |
12284 | are updated as described in their descriptions above. | |
17345e5a JA |
12285 | <DT><B>5.</B> |
12286 | ||
12287 | <DD> | |
a0c0a00f | 12288 | Function tracing is enabled: command substitution, shell functions, and |
17345e5a JA |
12289 | subshells invoked with <B>(</B> <I>command</I> <B>)</B> inherit the |
12290 | <B>DEBUG</B> and <B>RETURN</B> traps. | |
12291 | <DT><B>6.</B> | |
12292 | ||
12293 | <DD> | |
a0c0a00f | 12294 | Error tracing is enabled: command substitution, shell functions, and |
17345e5a | 12295 | subshells invoked with <B>(</B> <I>command</I> <B>)</B> inherit the |
495aee44 | 12296 | <B>ERR</B> trap. |
17345e5a JA |
12297 | </DL></DL> |
12298 | ||
12299 | <DT><B>extglob</B> | |
12300 | ||
12301 | <DD> | |
12302 | If set, the extended pattern matching features described above under | |
12303 | <B>Pathname Expansion</B> are enabled. | |
12304 | <DT><B>extquote</B> | |
12305 | ||
12306 | <DD> | |
12307 | If set, <B>$</B>aq<I>string</I>aq and <B>$</B>"<I>string</I>" quoting is | |
12308 | performed within <B>${</B><I>parameter</I><B>}</B> expansions | |
12309 | enclosed in double quotes. This option is enabled by default. | |
12310 | <DT><B>failglob</B> | |
12311 | ||
12312 | <DD> | |
12313 | If set, patterns which fail to match filenames during pathname expansion | |
12314 | result in an expansion error. | |
12315 | <DT><B>force_fignore</B> | |
12316 | ||
12317 | <DD> | |
0001803f CR |
12318 | If set, the suffixes specified by the |
12319 | <FONT SIZE=-1><B>FIGNORE</B> | |
12320 | ||
12321 | </FONT> | |
12322 | shell variable | |
17345e5a JA |
12323 | cause words to be ignored when performing word completion even if |
12324 | the ignored words are the only possible completions. | |
12325 | See | |
12326 | <FONT SIZE=-1><B>SHELL VARIABLES</B></FONT> | |
0001803f CR |
12327 | above for a description of |
12328 | <FONT SIZE=-1><B>FIGNORE</B>. | |
12329 | ||
12330 | </FONT> | |
17345e5a | 12331 | This option is enabled by default. |
ac50fbac CR |
12332 | <DT><B>globasciiranges</B> |
12333 | ||
12334 | <DD> | |
12335 | If set, range expressions used in pattern matching bracket expressions (see | |
12336 | <FONT SIZE=-1><B>Pattern Matching</B> | |
12337 | ||
12338 | </FONT> | |
12339 | above) behave as if in the traditional C locale when performing | |
12340 | comparisons. That is, the current locale's collating sequence | |
12341 | is not taken into account, so | |
12342 | <B>b</B> | |
12343 | ||
12344 | will not collate between | |
12345 | <B>A</B> | |
12346 | ||
12347 | and | |
12348 | <B>B</B>, | |
12349 | ||
12350 | and upper-case and lower-case ASCII characters will collate together. | |
17345e5a JA |
12351 | <DT><B>globstar</B> |
12352 | ||
12353 | <DD> | |
0001803f | 12354 | If set, the pattern <B>**</B> used in a pathname expansion context will |
ac50fbac | 12355 | match all files and zero or more directories and subdirectories. |
17345e5a JA |
12356 | If the pattern is followed by a <B>/</B>, only directories and |
12357 | subdirectories match. | |
12358 | <DT><B>gnu_errfmt</B> | |
12359 | ||
12360 | <DD> | |
12361 | If set, shell error messages are written in the standard GNU error | |
12362 | message format. | |
12363 | <DT><B>histappend</B> | |
12364 | ||
12365 | <DD> | |
12366 | If set, the history list is appended to the file named by the value | |
12367 | of the | |
0001803f | 12368 | <FONT SIZE=-1><B>HISTFILE</B> |
17345e5a | 12369 | |
0001803f | 12370 | </FONT> |
17345e5a JA |
12371 | variable when the shell exits, rather than overwriting the file. |
12372 | <DT><B>histreedit</B> | |
12373 | ||
12374 | <DD> | |
12375 | If set, and | |
12376 | <B>readline</B> | |
12377 | ||
12378 | is being used, a user is given the opportunity to re-edit a | |
12379 | failed history substitution. | |
12380 | <DT><B>histverify</B> | |
12381 | ||
12382 | <DD> | |
a0c0a00f | 12383 | If set, and |
17345e5a JA |
12384 | <B>readline</B> |
12385 | ||
12386 | is being used, the results of history substitution are not immediately | |
12387 | passed to the shell parser. Instead, the resulting line is loaded into | |
12388 | the <B>readline</B> editing buffer, allowing further modification. | |
12389 | <DT><B>hostcomplete</B> | |
12390 | ||
12391 | <DD> | |
12392 | If set, and | |
12393 | <B>readline</B> | |
12394 | ||
12395 | is being used, <B>bash</B> will attempt to perform hostname completion when a | |
12396 | word containing a <B>@</B> is being completed (see | |
12397 | <B>Completing</B> | |
12398 | ||
12399 | under | |
12400 | <FONT SIZE=-1><B>READLINE</B> | |
12401 | ||
12402 | </FONT> | |
12403 | above). | |
12404 | This is enabled by default. | |
12405 | <DT><B>huponexit</B> | |
12406 | ||
12407 | <DD> | |
12408 | If set, <B>bash</B> will send | |
12409 | <FONT SIZE=-1><B>SIGHUP</B> | |
12410 | ||
12411 | </FONT> | |
12412 | to all jobs when an interactive login shell exits. | |
a0c0a00f CR |
12413 | <DT><B>inherit_errexit</B> |
12414 | ||
12415 | <DD> | |
12416 | If set, command substitution inherits the value of the <B>errexit</B> option, | |
12417 | instead of unsetting it in the subshell environment. | |
12418 | This option is enabled when <I>posix mode</I> is enabled. | |
17345e5a JA |
12419 | <DT><B>interactive_comments</B> |
12420 | ||
12421 | <DD> | |
12422 | If set, allow a word beginning with | |
12423 | <B>#</B> | |
12424 | ||
12425 | to cause that word and all remaining characters on that | |
12426 | line to be ignored in an interactive shell (see | |
12427 | <FONT SIZE=-1><B>COMMENTS</B> | |
12428 | ||
12429 | </FONT> | |
12430 | above). This option is enabled by default. | |
495aee44 CR |
12431 | <DT><B>lastpipe</B> |
12432 | ||
12433 | <DD> | |
12434 | If set, and job control is not active, the shell runs the last command of | |
12435 | a pipeline not executed in the background in the current shell environment. | |
17345e5a JA |
12436 | <DT><B>lithist</B> |
12437 | ||
12438 | <DD> | |
12439 | If set, and the | |
12440 | <B>cmdhist</B> | |
12441 | ||
12442 | option is enabled, multi-line commands are saved to the history with | |
12443 | embedded newlines rather than using semicolon separators where possible. | |
12444 | <DT><B>login_shell</B> | |
12445 | ||
12446 | <DD> | |
12447 | The shell sets this option if it is started as a login shell (see | |
12448 | <FONT SIZE=-1><B>INVOCATION</B> | |
12449 | ||
12450 | </FONT> | |
12451 | above). | |
12452 | The value may not be changed. | |
12453 | <DT><B>mailwarn</B> | |
12454 | ||
12455 | <DD> | |
a0c0a00f | 12456 | If set, and a file that <B>bash</B> is checking for mail has been |
17345e5a JA |
12457 | accessed since the last time it was checked, the message ``The mail in |
12458 | <I>mailfile</I> has been read'' is displayed. | |
12459 | <DT><B>no_empty_cmd_completion</B> | |
12460 | ||
12461 | <DD> | |
12462 | If set, and | |
12463 | <B>readline</B> | |
12464 | ||
12465 | is being used, | |
12466 | <B>bash</B> | |
12467 | ||
0001803f CR |
12468 | will not attempt to search the |
12469 | <FONT SIZE=-1><B>PATH</B> | |
12470 | ||
12471 | </FONT> | |
12472 | for possible completions when | |
17345e5a JA |
12473 | completion is attempted on an empty line. |
12474 | <DT><B>nocaseglob</B> | |
12475 | ||
12476 | <DD> | |
12477 | If set, | |
12478 | <B>bash</B> | |
12479 | ||
12480 | matches filenames in a case-insensitive fashion when performing pathname | |
12481 | expansion (see | |
12482 | <B>Pathname Expansion</B> | |
12483 | ||
12484 | above). | |
12485 | <DT><B>nocasematch</B> | |
12486 | ||
12487 | <DD> | |
12488 | If set, | |
12489 | <B>bash</B> | |
12490 | ||
12491 | matches patterns in a case-insensitive fashion when performing matching | |
a0c0a00f CR |
12492 | while executing <B>case</B> or <B>[[</B> conditional commands, |
12493 | when performing pattern substitution word expansions, | |
12494 | or when filtering possible completions as part of programmable completion. | |
17345e5a JA |
12495 | <DT><B>nullglob</B> |
12496 | ||
12497 | <DD> | |
12498 | If set, | |
12499 | <B>bash</B> | |
12500 | ||
12501 | allows patterns which match no | |
12502 | files (see | |
12503 | <B>Pathname Expansion</B> | |
12504 | ||
12505 | above) | |
12506 | to expand to a null string, rather than themselves. | |
12507 | <DT><B>progcomp</B> | |
12508 | ||
12509 | <DD> | |
12510 | If set, the programmable completion facilities (see | |
12511 | <B>Programmable Completion</B> above) are enabled. | |
12512 | This option is enabled by default. | |
12513 | <DT><B>promptvars</B> | |
12514 | ||
12515 | <DD> | |
12516 | If set, prompt strings undergo | |
12517 | parameter expansion, command substitution, arithmetic | |
12518 | expansion, and quote removal after being expanded as described in | |
12519 | <FONT SIZE=-1><B>PROMPTING</B> | |
12520 | ||
12521 | </FONT> | |
12522 | above. This option is enabled by default. | |
12523 | <DT><B>restricted_shell</B> | |
12524 | ||
12525 | <DD> | |
12526 | The shell sets this option if it is started in restricted mode (see | |
12527 | <FONT SIZE=-1><B>RESTRICTED SHELL</B> | |
12528 | ||
12529 | </FONT> | |
12530 | below). | |
12531 | The value may not be changed. | |
12532 | This is not reset when the startup files are executed, allowing | |
12533 | the startup files to discover whether or not a shell is restricted. | |
12534 | <DT><B>shift_verbose</B> | |
12535 | ||
12536 | <DD> | |
12537 | If set, the | |
12538 | <B>shift</B> | |
12539 | ||
12540 | builtin prints an error message when the shift count exceeds the | |
12541 | number of positional parameters. | |
12542 | <DT><B>sourcepath</B> | |
12543 | ||
12544 | <DD> | |
12545 | If set, the | |
12546 | <B>source</B> (<B>.</B>) builtin uses the value of | |
12547 | <FONT SIZE=-1><B>PATH</B> | |
12548 | ||
12549 | </FONT> | |
12550 | to find the directory containing the file supplied as an argument. | |
12551 | This option is enabled by default. | |
12552 | <DT><B>xpg_echo</B> | |
12553 | ||
12554 | <DD> | |
12555 | If set, the <B>echo</B> builtin expands backslash-escape sequences | |
12556 | by default. | |
12557 | </DL></DL> | |
12558 | ||
ac50fbac | 12559 | |
17345e5a JA |
12560 | <DT><B>suspend</B> [<B>-f</B>]<DD> |
12561 | Suspend the execution of this shell until it receives a | |
12562 | <FONT SIZE=-1><B>SIGCONT</B> | |
12563 | ||
12564 | </FONT> | |
12565 | signal. A login shell cannot be suspended; the | |
12566 | <B>-f</B> | |
12567 | ||
12568 | option can be used to override this and force the suspension. | |
12569 | The return status is 0 unless the shell is a login shell and | |
12570 | <B>-f</B> | |
12571 | ||
12572 | is not supplied, or if job control is not enabled. | |
12573 | <DT><B>test</B> <I>expr</I><DD> | |
12574 | ||
12575 | <DT><B>[</B> <I>expr</I> <B>]</B><DD> | |
ac50fbac | 12576 | Return a status of 0 (true) or 1 (false) depending on |
17345e5a JA |
12577 | the evaluation of the conditional expression |
12578 | <I>expr</I>. | |
12579 | ||
12580 | Each operator and operand must be a separate argument. | |
12581 | Expressions are composed of the primaries described above under | |
12582 | <FONT SIZE=-1><B>CONDITIONAL EXPRESSIONS</B>. | |
12583 | ||
12584 | </FONT> | |
12585 | <B>test</B> does not accept any options, nor does it accept and ignore | |
12586 | an argument of <B>--</B> as signifying the end of options. | |
12587 | <P> | |
12588 | ||
12589 | ||
12590 | Expressions may be combined using the following operators, listed | |
12591 | in decreasing order of precedence. | |
12592 | The evaluation depends on the number of arguments; see below. | |
495aee44 | 12593 | Operator precedence is used when there are five or more arguments. |
17345e5a JA |
12594 | <DL COMPACT><DT><DD> |
12595 | ||
12596 | <DL COMPACT> | |
12597 | <DT><B>! </B><I>expr</I> | |
12598 | ||
12599 | <DD> | |
12600 | True if | |
12601 | <I>expr</I> | |
12602 | ||
12603 | is false. | |
12604 | <DT><B>( </B><I>expr</I> ) | |
12605 | ||
12606 | <DD> | |
12607 | Returns the value of <I>expr</I>. | |
12608 | This may be used to override the normal precedence of operators. | |
12609 | <DT><I>expr1</I> -<B>a</B> <I>expr2</I><DD> | |
12610 | True if both | |
12611 | <I>expr1</I> | |
12612 | ||
12613 | and | |
12614 | <I>expr2</I> | |
12615 | ||
12616 | are true. | |
12617 | <DT><I>expr1</I> -<B>o</B> <I>expr2</I><DD> | |
12618 | True if either | |
12619 | <I>expr1</I> | |
12620 | ||
12621 | or | |
12622 | <I>expr2</I> | |
12623 | ||
12624 | is true. | |
12625 | ||
12626 | </DL> | |
12627 | <P> | |
12628 | ||
12629 | <B>test</B> and <B>[</B> evaluate conditional | |
12630 | expressions using a set of rules based on the number of arguments. | |
12631 | <P> | |
12632 | ||
12633 | ||
12634 | ||
12635 | <DL COMPACT> | |
12636 | <DT>0 arguments<DD> | |
12637 | The expression is false. | |
12638 | <DT>1 argument<DD> | |
12639 | The expression is true if and only if the argument is not null. | |
12640 | <DT>2 arguments<DD> | |
12641 | If the first argument is <B>!</B>, the expression is true if and | |
12642 | only if the second argument is null. | |
12643 | If the first argument is one of the unary conditional operators listed above | |
12644 | under | |
12645 | <FONT SIZE=-1><B>CONDITIONAL EXPRESSIONS</B>, | |
12646 | ||
12647 | </FONT> | |
12648 | the expression is true if the unary test is true. | |
12649 | If the first argument is not a valid unary conditional operator, the expression | |
12650 | is false. | |
12651 | <DT>3 arguments<DD> | |
495aee44 | 12652 | The following conditions are applied in the order listed. |
17345e5a JA |
12653 | If the second argument is one of the binary conditional operators listed above |
12654 | under | |
12655 | <FONT SIZE=-1><B>CONDITIONAL EXPRESSIONS</B>, | |
12656 | ||
12657 | </FONT> | |
12658 | the result of the expression is the result of the binary test using | |
12659 | the first and third arguments as operands. | |
12660 | The <B>-a</B> and <B>-o</B> operators are considered binary operators | |
a0c0a00f | 12661 | when there are three arguments. |
17345e5a JA |
12662 | If the first argument is <B>!</B>, the value is the negation of |
12663 | the two-argument test using the second and third arguments. | |
12664 | If the first argument is exactly <B>(</B> and the third argument is | |
12665 | exactly <B>)</B>, the result is the one-argument test of the second | |
12666 | argument. | |
12667 | Otherwise, the expression is false. | |
12668 | <DT>4 arguments<DD> | |
12669 | If the first argument is <B>!</B>, the result is the negation of | |
12670 | the three-argument expression composed of the remaining arguments. | |
a0c0a00f | 12671 | Otherwise, the expression is parsed and evaluated according to |
17345e5a JA |
12672 | precedence using the rules listed above. |
12673 | <DT>5 or more arguments<DD> | |
12674 | The expression is parsed and evaluated according to precedence | |
12675 | using the rules listed above. | |
495aee44 CR |
12676 | <P> |
12677 | ||
12678 | ||
12679 | </DL> | |
12680 | <P> | |
12681 | ||
12682 | When used with <B>test</B> or <B>[</B>, the <B><</B> and <B>></B> operators | |
12683 | sort lexicographically using ASCII ordering. | |
12684 | </DL> | |
17345e5a JA |
12685 | |
12686 | ||
12687 | <DT><B>times</B> | |
12688 | ||
12689 | <DD> | |
12690 | Print the accumulated user and system times for the shell and | |
12691 | for processes run from the shell. The return status is 0. | |
12692 | <DT><B>trap</B> [<B>-lp</B>] [[<I>arg</I>] <I>sigspec</I> ...]<DD> | |
12693 | The command | |
12694 | <I>arg</I> | |
12695 | ||
12696 | is to be read and executed when the shell receives | |
12697 | signal(s) | |
12698 | <I>sigspec</I>. | |
12699 | ||
12700 | If | |
12701 | <I>arg</I> | |
12702 | ||
12703 | is absent (and there is a single <I>sigspec</I>) or | |
12704 | <B>-</B>, | |
12705 | ||
12706 | each specified signal is | |
12707 | reset to its original disposition (the value it had | |
12708 | upon entrance to the shell). | |
a0c0a00f | 12709 | If |
17345e5a JA |
12710 | <I>arg</I> |
12711 | ||
12712 | is the null string the signal specified by each | |
12713 | <I>sigspec</I> | |
12714 | ||
12715 | is ignored by the shell and by the commands it invokes. | |
12716 | If | |
12717 | <I>arg</I> | |
12718 | ||
12719 | is not present and | |
12720 | <B>-p</B> | |
12721 | ||
12722 | has been supplied, then the trap commands associated with each | |
12723 | <I>sigspec</I> | |
12724 | ||
12725 | are displayed. | |
12726 | If no arguments are supplied or if only | |
12727 | <B>-p</B> | |
12728 | ||
12729 | is given, | |
12730 | <B>trap</B> | |
12731 | ||
12732 | prints the list of commands associated with each signal. | |
12733 | The | |
12734 | <B>-l</B> | |
12735 | ||
12736 | option causes the shell to print a list of signal names and | |
12737 | their corresponding numbers. | |
12738 | Each | |
12739 | <I>sigspec</I> | |
12740 | ||
12741 | is either | |
12742 | a signal name defined in <<I>signal.h</I>>, or a signal number. | |
495aee44 CR |
12743 | Signal names are case insensitive and the |
12744 | <FONT SIZE=-1><B>SIG</B> | |
12745 | ||
12746 | </FONT> | |
12747 | prefix is optional. | |
0001803f CR |
12748 | <P> |
12749 | ||
12750 | ||
17345e5a JA |
12751 | If a |
12752 | <I>sigspec</I> | |
12753 | ||
12754 | is | |
12755 | <FONT SIZE=-1><B>EXIT</B> | |
12756 | ||
12757 | </FONT> | |
12758 | (0) the command | |
12759 | <I>arg</I> | |
12760 | ||
12761 | is executed on exit from the shell. | |
12762 | If a | |
12763 | <I>sigspec</I> | |
12764 | ||
12765 | is | |
12766 | <FONT SIZE=-1><B>DEBUG</B>, | |
12767 | ||
12768 | </FONT> | |
12769 | the command | |
12770 | <I>arg</I> | |
12771 | ||
12772 | is executed before every <I>simple command</I>, <I>for</I> command, | |
12773 | <I>case</I> command, <I>select</I> command, every arithmetic <I>for</I> | |
12774 | command, and before the first command executes in a shell function (see | |
12775 | <FONT SIZE=-1><B>SHELL GRAMMAR</B> | |
12776 | ||
12777 | </FONT> | |
12778 | above). | |
12779 | Refer to the description of the <B>extdebug</B> option to the | |
12780 | <B>shopt</B> builtin for details of its effect on the <B>DEBUG</B> trap. | |
12781 | If a | |
12782 | <I>sigspec</I> | |
12783 | ||
0001803f CR |
12784 | is |
12785 | <FONT SIZE=-1><B>RETURN</B>, | |
12786 | ||
12787 | </FONT> | |
12788 | the command | |
12789 | <I>arg</I> | |
12790 | ||
495aee44 CR |
12791 | is executed each time a shell function or a script executed with |
12792 | the <B>.</B> or <B>source</B> builtins finishes executing. | |
0001803f CR |
12793 | <P> |
12794 | ||
12795 | ||
12796 | If a | |
12797 | <I>sigspec</I> | |
12798 | ||
17345e5a JA |
12799 | is |
12800 | <FONT SIZE=-1><B>ERR</B>, | |
12801 | ||
12802 | </FONT> | |
12803 | the command | |
12804 | <I>arg</I> | |
12805 | ||
a0c0a00f | 12806 | is executed whenever |
ac50fbac | 12807 | a pipeline (which may consist of a single simple |
a0c0a00f | 12808 | command), a list, or a compound command returns a |
ac50fbac | 12809 | non-zero exit status, |
17345e5a JA |
12810 | subject to the following conditions. |
12811 | The | |
12812 | <FONT SIZE=-1><B>ERR</B> | |
12813 | ||
12814 | </FONT> | |
12815 | trap is not executed if the failed | |
12816 | command is part of the command list immediately following a | |
12817 | <B>while</B> | |
12818 | ||
12819 | or | |
12820 | <B>until</B> | |
12821 | ||
a0c0a00f | 12822 | keyword, |
17345e5a JA |
12823 | part of the test in an |
12824 | <I>if</I> | |
12825 | ||
12826 | statement, part of a command executed in a | |
12827 | <B>&&</B> | |
12828 | ||
12829 | or | |
12830 | <B>||</B> | |
12831 | ||
ac50fbac CR |
12832 | list except the command following the final <B>&&</B> or <B>||</B>, |
12833 | any command in a pipeline but the last, | |
12834 | or if the command's return value is | |
12835 | being inverted using | |
17345e5a JA |
12836 | <B>!</B>. |
12837 | ||
ac50fbac | 12838 | These are the same conditions obeyed by the <B>errexit</B> (<B>-e</B>) option. |
0001803f | 12839 | <P> |
17345e5a | 12840 | |
17345e5a | 12841 | |
17345e5a JA |
12842 | Signals ignored upon entry to the shell cannot be trapped or reset. |
12843 | Trapped signals that are not being ignored are reset to their original | |
0001803f | 12844 | values in a subshell or subshell environment when one is created. |
17345e5a JA |
12845 | The return status is false if any |
12846 | <I>sigspec</I> | |
12847 | ||
12848 | is invalid; otherwise | |
12849 | <B>trap</B> | |
12850 | ||
12851 | returns true. | |
12852 | <DT><B>type</B> [<B>-aftpP</B>] <I>name</I> [<I>name</I> ...]<DD> | |
a0c0a00f | 12853 | With no options, |
17345e5a JA |
12854 | indicate how each |
12855 | <I>name</I> | |
12856 | ||
12857 | would be interpreted if used as a command name. | |
12858 | If the | |
12859 | <B>-t</B> | |
12860 | ||
12861 | option is used, | |
12862 | <B>type</B> | |
12863 | ||
12864 | prints a string which is one of | |
12865 | <I>alias</I>, | |
12866 | ||
12867 | <I>keyword</I>, | |
12868 | ||
12869 | <I>function</I>, | |
12870 | ||
12871 | <I>builtin</I>, | |
12872 | ||
12873 | or | |
a0c0a00f | 12874 | <I>file</I> |
17345e5a JA |
12875 | |
12876 | if | |
12877 | <I>name</I> | |
12878 | ||
12879 | is an alias, shell reserved word, function, builtin, or disk file, | |
12880 | respectively. | |
12881 | If the | |
12882 | <I>name</I> | |
12883 | ||
12884 | is not found, then nothing is printed, and an exit status of false | |
12885 | is returned. | |
12886 | If the | |
12887 | <B>-p</B> | |
12888 | ||
12889 | option is used, | |
12890 | <B>type</B> | |
12891 | ||
12892 | either returns the name of the disk file | |
12893 | that would be executed if | |
12894 | <I>name</I> | |
12895 | ||
12896 | were specified as a command name, | |
12897 | or nothing if | |
12898 | <TT>type -t name</TT> | |
12899 | ||
12900 | would not return | |
12901 | <I>file</I>. | |
12902 | ||
12903 | The | |
12904 | <B>-P</B> | |
12905 | ||
12906 | option forces a | |
12907 | <FONT SIZE=-1><B>PATH</B> | |
12908 | ||
12909 | </FONT> | |
12910 | search for each <I>name</I>, even if | |
12911 | <TT>type -t name</TT> | |
12912 | ||
12913 | would not return | |
12914 | <I>file</I>. | |
12915 | ||
12916 | If a command is hashed, | |
12917 | <B>-p</B> | |
12918 | ||
12919 | and | |
12920 | <B>-P</B> | |
12921 | ||
ac50fbac | 12922 | print the hashed value, which is not necessarily the file that appears |
a0c0a00f | 12923 | first in |
17345e5a JA |
12924 | <FONT SIZE=-1><B>PATH</B>. |
12925 | ||
12926 | </FONT> | |
12927 | If the | |
12928 | <B>-a</B> | |
12929 | ||
a0c0a00f | 12930 | option is used, |
17345e5a JA |
12931 | <B>type</B> |
12932 | ||
12933 | prints all of the places that contain | |
a0c0a00f | 12934 | an executable named |
17345e5a JA |
12935 | <I>name</I>. |
12936 | ||
12937 | This includes aliases and functions, | |
a0c0a00f | 12938 | if and only if the |
17345e5a JA |
12939 | <B>-p</B> |
12940 | ||
12941 | option is not also used. | |
12942 | The table of hashed commands is not consulted | |
12943 | when using | |
12944 | <B>-a</B>. | |
12945 | ||
12946 | The | |
12947 | <B>-f</B> | |
12948 | ||
12949 | option suppresses shell function lookup, as with the <B>command</B> builtin. | |
12950 | <B>type</B> | |
12951 | ||
12952 | returns true if all of the arguments are found, false if | |
12953 | any are not found. | |
a0c0a00f | 12954 | <DT><B>ulimit</B> [<B>-HSabcdefiklmnpqrstuvxPT</B> [<I>limit</I>]]<DD> |
17345e5a JA |
12955 | Provides control over the resources available to the shell and to |
12956 | processes started by it, on systems that allow such control. | |
12957 | The <B>-H</B> and <B>-S</B> options specify that the hard or soft limit is | |
12958 | set for the given resource. | |
12959 | A hard limit cannot be increased by a non-root user once it is set; | |
12960 | a soft limit may be increased up to the value of the hard limit. | |
12961 | If neither <B>-H</B> nor <B>-S</B> is specified, both the soft and hard | |
12962 | limits are set. | |
12963 | The value of | |
12964 | <I>limit</I> | |
12965 | ||
12966 | can be a number in the unit specified for the resource | |
12967 | or one of the special values | |
12968 | <B>hard</B>, | |
12969 | ||
12970 | <B>soft</B>, | |
12971 | ||
12972 | or | |
12973 | <B>unlimited</B>, | |
12974 | ||
12975 | which stand for the current hard limit, the current soft limit, and | |
12976 | no limit, respectively. | |
12977 | If | |
12978 | <I>limit</I> | |
12979 | ||
12980 | is omitted, the current value of the soft limit of the resource is | |
12981 | printed, unless the <B>-H</B> option is given. When more than one | |
12982 | resource is specified, the limit name and unit are printed before the value. | |
12983 | Other options are interpreted as follows: | |
12984 | <DL COMPACT><DT><DD> | |
12985 | ||
12986 | <DL COMPACT> | |
12987 | <DT><B>-a</B> | |
12988 | ||
12989 | <DD> | |
12990 | All current limits are reported | |
12991 | <DT><B>-b</B> | |
12992 | ||
12993 | <DD> | |
12994 | The maximum socket buffer size | |
12995 | <DT><B>-c</B> | |
12996 | ||
12997 | <DD> | |
12998 | The maximum size of core files created | |
12999 | <DT><B>-d</B> | |
13000 | ||
13001 | <DD> | |
13002 | The maximum size of a process's data segment | |
13003 | <DT><B>-e</B> | |
13004 | ||
13005 | <DD> | |
13006 | The maximum scheduling priority ("nice") | |
13007 | <DT><B>-f</B> | |
13008 | ||
13009 | <DD> | |
13010 | The maximum size of files written by the shell and its children | |
13011 | <DT><B>-i</B> | |
13012 | ||
13013 | <DD> | |
13014 | The maximum number of pending signals | |
a0c0a00f CR |
13015 | <DT><B>-k</B> |
13016 | ||
13017 | <DD> | |
13018 | The maximum number of kqueues that may be allocated | |
17345e5a JA |
13019 | <DT><B>-l</B> |
13020 | ||
13021 | <DD> | |
13022 | The maximum size that may be locked into memory | |
13023 | <DT><B>-m</B> | |
13024 | ||
13025 | <DD> | |
0001803f | 13026 | The maximum resident set size (many systems do not honor this limit) |
17345e5a JA |
13027 | <DT><B>-n</B> |
13028 | ||
13029 | <DD> | |
13030 | The maximum number of open file descriptors (most systems do not | |
13031 | allow this value to be set) | |
13032 | <DT><B>-p</B> | |
13033 | ||
13034 | <DD> | |
13035 | The pipe size in 512-byte blocks (this may not be set) | |
13036 | <DT><B>-q</B> | |
13037 | ||
13038 | <DD> | |
13039 | The maximum number of bytes in POSIX message queues | |
13040 | <DT><B>-r</B> | |
13041 | ||
13042 | <DD> | |
13043 | The maximum real-time scheduling priority | |
13044 | <DT><B>-s</B> | |
13045 | ||
13046 | <DD> | |
13047 | The maximum stack size | |
13048 | <DT><B>-t</B> | |
13049 | ||
13050 | <DD> | |
13051 | The maximum amount of cpu time in seconds | |
13052 | <DT><B>-u</B> | |
13053 | ||
13054 | <DD> | |
13055 | The maximum number of processes available to a single user | |
13056 | <DT><B>-v</B> | |
13057 | ||
13058 | <DD> | |
495aee44 CR |
13059 | The maximum amount of virtual memory available to the shell and, on |
13060 | some systems, to its children | |
17345e5a JA |
13061 | <DT><B>-x</B> |
13062 | ||
13063 | <DD> | |
13064 | The maximum number of file locks | |
a0c0a00f CR |
13065 | <DT><B>-P</B> |
13066 | ||
13067 | <DD> | |
13068 | The maximum number of pseudoterminals | |
17345e5a JA |
13069 | <DT><B>-T</B> |
13070 | ||
13071 | <DD> | |
13072 | The maximum number of threads | |
13073 | ||
13074 | </DL> | |
13075 | <P> | |
13076 | ||
13077 | If | |
13078 | <I>limit</I> | |
13079 | ||
ac50fbac | 13080 | is given, and the |
17345e5a JA |
13081 | <B>-a</B> |
13082 | ||
ac50fbac CR |
13083 | option is not used, |
13084 | <I>limit</I> is the new value of the specified resource. | |
17345e5a JA |
13085 | If no option is given, then |
13086 | <B>-f</B> | |
13087 | ||
13088 | is assumed. Values are in 1024-byte increments, except for | |
13089 | <B>-t</B>, | |
13090 | ||
ac50fbac | 13091 | which is in seconds; |
17345e5a JA |
13092 | <B>-p</B>, |
13093 | ||
ac50fbac | 13094 | which is in units of 512-byte blocks; |
a0c0a00f CR |
13095 | <B>-P</B>, |
13096 | ||
17345e5a JA |
13097 | <B>-T</B>, |
13098 | ||
13099 | <B>-b</B>, | |
13100 | ||
a0c0a00f CR |
13101 | <B>-k</B>, |
13102 | ||
17345e5a JA |
13103 | <B>-n</B>, |
13104 | ||
13105 | and | |
13106 | <B>-u</B>, | |
13107 | ||
a0c0a00f CR |
13108 | which are unscaled values; |
13109 | and, when in Posix mode, | |
13110 | <B>-c</B> | |
13111 | ||
13112 | and | |
13113 | <B>-f</B>, | |
13114 | ||
13115 | which are in 512-byte increments. | |
17345e5a JA |
13116 | The return status is 0 unless an invalid option or argument is supplied, |
13117 | or an error occurs while setting a new limit. | |
13118 | </DL> | |
13119 | ||
13120 | <DT><B>umask</B> [<B>-p</B>] [<B>-S</B>] [<I>mode</I>]<DD> | |
a0c0a00f | 13121 | The user file-creation mask is set to |
17345e5a JA |
13122 | <I>mode</I>. |
13123 | ||
13124 | If | |
13125 | <I>mode</I> | |
13126 | ||
13127 | begins with a digit, it | |
13128 | is interpreted as an octal number; otherwise | |
13129 | it is interpreted as a symbolic mode mask similar | |
13130 | to that accepted by | |
13131 | <I>chmod</I>(1). | |
13132 | ||
13133 | If | |
13134 | <I>mode</I> | |
13135 | ||
13136 | is omitted, the current value of the mask is printed. | |
13137 | The | |
13138 | <B>-S</B> | |
13139 | ||
13140 | option causes the mask to be printed in symbolic form; the | |
13141 | default output is an octal number. | |
13142 | If the | |
13143 | <B>-p</B> | |
13144 | ||
13145 | option is supplied, and | |
13146 | <I>mode</I> | |
13147 | ||
13148 | is omitted, the output is in a form that may be reused as input. | |
13149 | The return status is 0 if the mode was successfully changed or if | |
13150 | no <I>mode</I> argument was supplied, and false otherwise. | |
13151 | <DT><B>unalias</B> [-<B>a</B>] [<I>name</I> ...]<DD> | |
13152 | Remove each <I>name</I> from the list of defined aliases. If | |
13153 | <B>-a</B> | |
13154 | ||
13155 | is supplied, all alias definitions are removed. The return | |
13156 | value is true unless a supplied | |
13157 | <I>name</I> | |
13158 | ||
13159 | is not a defined alias. | |
ac50fbac | 13160 | <DT><B>unset</B> [-<B>fv</B>] [-<B>n</B>] [<I>name</I> ...]<DD> |
17345e5a JA |
13161 | For each |
13162 | <I>name</I>, | |
13163 | ||
13164 | remove the corresponding variable or function. | |
ac50fbac | 13165 | If the |
17345e5a JA |
13166 | <B>-v</B> |
13167 | ||
13168 | option is given, each | |
13169 | <I>name</I> | |
13170 | ||
ac50fbac | 13171 | refers to a shell variable, and that variable is removed. |
17345e5a JA |
13172 | Read-only variables may not be unset. |
13173 | If | |
13174 | <B>-f</B> | |
13175 | ||
13176 | is specified, each | |
13177 | <I>name</I> | |
13178 | ||
13179 | refers to a shell function, and the function definition | |
13180 | is removed. | |
ac50fbac CR |
13181 | If the |
13182 | <B>-n</B> | |
13183 | ||
13184 | option is supplied, and <I>name</I> is a variable with the <I>nameref</I> | |
13185 | attribute, <I>name</I> will be unset rather than the variable it | |
13186 | references. | |
13187 | <B>-n</B> has no effect if the <B>-f</B> option is supplied. | |
13188 | If no options are supplied, each <I>name</I> refers to a variable; if | |
13189 | there is no variable by that name, any function with that name is | |
13190 | unset. | |
17345e5a JA |
13191 | Each unset variable or function is removed from the environment |
13192 | passed to subsequent commands. | |
13193 | If any of | |
0001803f CR |
13194 | <FONT SIZE=-1><B>COMP_WORDBREAKS</B>, |
13195 | ||
13196 | </FONT> | |
17345e5a JA |
13197 | <FONT SIZE=-1><B>RANDOM</B>, |
13198 | ||
13199 | </FONT> | |
13200 | <FONT SIZE=-1><B>SECONDS</B>, | |
13201 | ||
13202 | </FONT> | |
13203 | <FONT SIZE=-1><B>LINENO</B>, | |
13204 | ||
13205 | </FONT> | |
13206 | <FONT SIZE=-1><B>HISTCMD</B>, | |
13207 | ||
13208 | </FONT> | |
13209 | <FONT SIZE=-1><B>FUNCNAME</B>, | |
13210 | ||
13211 | </FONT> | |
13212 | <FONT SIZE=-1><B>GROUPS</B>, | |
13213 | ||
13214 | </FONT> | |
13215 | or | |
13216 | <FONT SIZE=-1><B>DIRSTACK</B> | |
13217 | ||
13218 | </FONT> | |
13219 | are unset, they lose their special properties, even if they are | |
13220 | subsequently reset. The exit status is true unless a | |
13221 | <I>name</I> | |
13222 | ||
13223 | is readonly. | |
ac50fbac CR |
13224 | <DT><B>wait</B> [<B>-n</B>] [<I>n ...</I>]<DD> |
13225 | Wait for each specified child process and return its termination status. | |
17345e5a JA |
13226 | Each |
13227 | <I>n</I> | |
13228 | ||
13229 | may be a process | |
13230 | ID or a job specification; if a job spec is given, all processes | |
13231 | in that job's pipeline are waited for. If | |
13232 | <I>n</I> | |
13233 | ||
13234 | is not given, all currently active child processes | |
ac50fbac CR |
13235 | are waited for, and the return status is zero. |
13236 | If the <B>-n</B> option is supplied, <B>wait</B> waits for any job to | |
13237 | terminate and returns its exit status. | |
13238 | If | |
17345e5a JA |
13239 | <I>n</I> |
13240 | ||
13241 | specifies a non-existent process or job, the return status is | |
13242 | 127. Otherwise, the return status is the exit status of the last | |
13243 | process or job waited for. | |
13244 | ||
13245 | ||
13246 | </DL> | |
13247 | <A NAME="lbDC"> </A> | |
13248 | <H3>RESTRICTED SHELL</H3> | |
13249 | ||
13250 | ||
13251 | ||
13252 | <P> | |
13253 | ||
13254 | If | |
13255 | <B>bash</B> | |
13256 | ||
13257 | is started with the name | |
13258 | <B>rbash</B>, | |
13259 | ||
13260 | or the | |
13261 | <B>-r</B> | |
13262 | ||
13263 | option is supplied at invocation, | |
13264 | the shell becomes restricted. | |
13265 | A restricted shell is used to | |
13266 | set up an environment more controlled than the standard shell. | |
13267 | It behaves identically to | |
13268 | <B>bash</B> | |
13269 | ||
13270 | with the exception that the following are disallowed or not performed: | |
13271 | <DL COMPACT> | |
13272 | <DT>*<DD> | |
13273 | changing directories with <B>cd</B> | |
13274 | <DT>*<DD> | |
13275 | setting or unsetting the values of | |
0001803f | 13276 | <FONT SIZE=-1><B>SHELL</B>, |
17345e5a | 13277 | |
0001803f CR |
13278 | </FONT> |
13279 | <FONT SIZE=-1><B>PATH</B>, | |
17345e5a | 13280 | |
0001803f CR |
13281 | </FONT> |
13282 | <FONT SIZE=-1><B>ENV</B>, | |
17345e5a | 13283 | |
0001803f | 13284 | </FONT> |
17345e5a | 13285 | or |
0001803f | 13286 | <FONT SIZE=-1><B>BASH_ENV</B> |
17345e5a | 13287 | |
0001803f | 13288 | </FONT> |
17345e5a JA |
13289 | <DT>*<DD> |
13290 | specifying command names containing | |
13291 | <B>/</B> | |
13292 | ||
13293 | <DT>*<DD> | |
ac50fbac | 13294 | specifying a filename containing a |
17345e5a JA |
13295 | <B>/</B> |
13296 | ||
13297 | as an argument to the | |
13298 | <B>.</B> | |
13299 | ||
13300 | builtin command | |
13301 | <DT>*<DD> | |
495aee44 | 13302 | specifying a filename containing a slash as an argument to the |
17345e5a JA |
13303 | <B>-p</B> |
13304 | ||
13305 | option to the | |
13306 | <B>hash</B> | |
13307 | ||
13308 | builtin command | |
13309 | <DT>*<DD> | |
13310 | importing function definitions from the shell environment at startup | |
13311 | <DT>*<DD> | |
0001803f CR |
13312 | parsing the value of |
13313 | <FONT SIZE=-1><B>SHELLOPTS</B> | |
13314 | ||
13315 | </FONT> | |
13316 | from the shell environment at startup | |
17345e5a JA |
13317 | <DT>*<DD> |
13318 | redirecting output using the >, >|, <>, >&, &>, and >> redirection operators | |
13319 | <DT>*<DD> | |
13320 | using the | |
13321 | <B>exec</B> | |
13322 | ||
13323 | builtin command to replace the shell with another command | |
13324 | <DT>*<DD> | |
13325 | adding or deleting builtin commands with the | |
13326 | <B>-f</B> | |
13327 | ||
13328 | and | |
13329 | <B>-d</B> | |
13330 | ||
13331 | options to the | |
13332 | <B>enable</B> | |
13333 | ||
13334 | builtin command | |
13335 | <DT>*<DD> | |
495aee44 | 13336 | using the <B>enable</B> builtin command to enable disabled shell builtins |
17345e5a JA |
13337 | <DT>*<DD> |
13338 | specifying the | |
13339 | <B>-p</B> | |
13340 | ||
13341 | option to the | |
13342 | <B>command</B> | |
13343 | ||
13344 | builtin command | |
13345 | <DT>*<DD> | |
13346 | turning off restricted mode with | |
13347 | <B>set +r</B> or <B>set +o restricted</B>. | |
13348 | </DL> | |
13349 | <P> | |
13350 | ||
13351 | These restrictions are enforced after any startup files are read. | |
13352 | <P> | |
13353 | ||
13354 | ||
13355 | When a command that is found to be a shell script is executed | |
13356 | (see | |
13357 | <FONT SIZE=-1><B>COMMAND EXECUTION</B> | |
13358 | ||
13359 | </FONT> | |
13360 | ||
13361 | above), | |
13362 | ||
13363 | <B>rbash</B> | |
13364 | ||
13365 | turns off any restrictions in the shell spawned to execute the | |
13366 | script. | |
13367 | ||
13368 | ||
13369 | <A NAME="lbDD"> </A> | |
13370 | <H3>SEE ALSO</H3> | |
13371 | ||
13372 | ||
13373 | <DL COMPACT> | |
13374 | <DT><I>Bash Reference Manual</I>, Brian Fox and Chet Ramey<DD> | |
13375 | <DT><I>The Gnu Readline Library</I>, Brian Fox and Chet Ramey<DD> | |
13376 | <DT><I>The Gnu History Library</I>, Brian Fox and Chet Ramey<DD> | |
ac50fbac CR |
13377 | <DT><I>Portable Operating System Interface (POSIX) Part 2: Shell and Utilities</I>, IEEE --<DD> |
13378 | <A HREF="http://pubs.opengroup.org/onlinepubs/9699919799/">http://pubs.opengroup.org/onlinepubs/9699919799/</A> | |
13379 | <DT><A HREF="http://tiswww.case.edu/~chet/bash/POSIX">http://tiswww.case.edu/~chet/bash/POSIX</A> -- a description of posix mode<DD> | |
17345e5a JA |
13380 | <DT><I>sh</I>(1), <I>ksh</I>(1), <I>csh</I>(1)<DD> |
13381 | <DT><I>emacs</I>(1), <I>vi</I>(1)<DD> | |
13382 | <DT><I>readline</I>(3)<DD> | |
13383 | ||
13384 | </DL> | |
13385 | <A NAME="lbDE"> </A> | |
13386 | <H3>FILES</H3> | |
13387 | ||
13388 | ||
13389 | <DL COMPACT> | |
13390 | <DT> | |
13391 | <A HREF="file:/bin/bash"><I>/bin/bash</I></A> | |
13392 | ||
13393 | <DD> | |
13394 | The <B>bash</B> executable | |
13395 | <DT> | |
13396 | <A HREF="file:/etc/profile"><I>/etc/profile</I></A> | |
13397 | ||
13398 | <DD> | |
13399 | The systemwide initialization file, executed for login shells | |
13400 | <DT> | |
13401 | <A HREF="file:~/.bash_profile"><I>~/.bash_profile</I></A> | |
13402 | ||
13403 | <DD> | |
13404 | The personal initialization file, executed for login shells | |
13405 | <DT> | |
13406 | <A HREF="file:~/.bashrc"><I>~/.bashrc</I></A> | |
13407 | ||
13408 | <DD> | |
13409 | The individual per-interactive-shell startup file | |
13410 | <DT> | |
13411 | <A HREF="file:~/.bash_logout"><I>~/.bash_logout</I></A> | |
13412 | ||
13413 | <DD> | |
13414 | The individual login shell cleanup file, executed when a login shell exits | |
13415 | <DT> | |
13416 | <A HREF="file:~/.inputrc"><I>~/.inputrc</I></A> | |
13417 | ||
13418 | <DD> | |
13419 | Individual <I>readline</I> initialization file | |
13420 | ||
13421 | </DL> | |
13422 | <A NAME="lbDF"> </A> | |
13423 | <H3>AUTHORS</H3> | |
13424 | ||
13425 | Brian Fox, Free Software Foundation | |
13426 | <BR> | |
13427 | ||
13428 | <A HREF="mailto:bfox@gnu.org">bfox@gnu.org</A> | |
13429 | <P> | |
13430 | ||
13431 | Chet Ramey, Case Western Reserve University | |
13432 | <BR> | |
13433 | ||
0001803f | 13434 | <A HREF="mailto:chet.ramey@case.edu">chet.ramey@case.edu</A> |
17345e5a JA |
13435 | <A NAME="lbDG"> </A> |
13436 | <H3>BUG REPORTS</H3> | |
13437 | ||
13438 | If you find a bug in | |
13439 | <B>bash,</B> | |
13440 | ||
13441 | you should report it. But first, you should | |
13442 | make sure that it really is a bug, and that it appears in the latest | |
13443 | version of | |
13444 | <B>bash</B>. | |
13445 | ||
13446 | The latest version is always available from | |
495aee44 | 13447 | <I><A HREF="ftp://ftp.gnu.org/pub/gnu/bash/">ftp://ftp.gnu.org/pub/gnu/bash/</A></I>. |
17345e5a JA |
13448 | <P> |
13449 | ||
13450 | Once you have determined that a bug actually exists, use the | |
13451 | <I>bashbug</I> | |
13452 | ||
13453 | command to submit a bug report. | |
13454 | If you have a fix, you are encouraged to mail that as well! | |
13455 | Suggestions and `philosophical' bug reports may be mailed | |
13456 | to <I><A HREF="mailto:bug-bash@gnu.org">bug-bash@gnu.org</A></I> or posted to the Usenet | |
13457 | newsgroup | |
13458 | <A HREF="news:gnu.bash.bug">gnu.bash.bug</A>. | |
13459 | ||
13460 | <P> | |
13461 | ||
13462 | ALL bug reports should include: | |
13463 | <P> | |
13464 | ||
13465 | ||
13466 | <DL COMPACT> | |
13467 | <DT>The version number of <B>bash</B><DD> | |
13468 | <DT>The hardware and operating system<DD> | |
13469 | <DT>The compiler used to compile<DD> | |
13470 | <DT>A description of the bug behaviour<DD> | |
13471 | <DT>A short script or `recipe' which exercises the bug<DD> | |
13472 | ||
13473 | </DL> | |
13474 | <P> | |
13475 | ||
13476 | <I>bashbug</I> | |
13477 | ||
13478 | inserts the first three items automatically into the template | |
13479 | it provides for filing a bug report. | |
13480 | <P> | |
13481 | ||
13482 | Comments and bug reports concerning | |
13483 | this manual page should be directed to | |
ac50fbac | 13484 | <I><A HREF="mailto:chet.ramey@case.edu">chet.ramey@case.edu</A></I>. |
17345e5a JA |
13485 | |
13486 | <A NAME="lbDH"> </A> | |
13487 | <H3>BUGS</H3> | |
13488 | ||
13489 | <P> | |
13490 | ||
13491 | It's too big and too slow. | |
13492 | <P> | |
13493 | ||
a0c0a00f | 13494 | There are some subtle differences between |
17345e5a JA |
13495 | <B>bash</B> |
13496 | ||
13497 | and traditional versions of | |
13498 | <B>sh</B>, | |
13499 | ||
13500 | mostly because of the | |
13501 | <FONT SIZE=-1><B>POSIX</B> | |
13502 | ||
13503 | </FONT> | |
13504 | specification. | |
13505 | <P> | |
13506 | ||
13507 | Aliases are confusing in some uses. | |
13508 | <P> | |
13509 | ||
13510 | Shell builtin commands and functions are not stoppable/restartable. | |
13511 | <P> | |
13512 | ||
13513 | Compound commands and command sequences of the form `a ; b ; c' | |
13514 | are not handled gracefully when process suspension is attempted. | |
13515 | When a process is stopped, the shell immediately executes the next | |
13516 | command in the sequence. | |
13517 | It suffices to place the sequence of commands between | |
13518 | parentheses to force it into a subshell, which may be stopped as | |
13519 | a unit. | |
13520 | <P> | |
13521 | ||
13522 | Array variables may not (yet) be exported. | |
13523 | <P> | |
13524 | ||
13525 | There may be only one active coprocess at a time. | |
13526 | ||
13527 | ||
13528 | ||
13529 | <HR> | |
13530 | <TABLE WIDTH=100%> | |
13531 | <TR> | |
a0c0a00f | 13532 | <TH ALIGN=LEFT width=33%>GNU Bash 4.4<TH ALIGN=CENTER width=33%>2016 August 26<TH ALIGN=RIGHT width=33%>BASH(1) |
17345e5a JA |
13533 | </TR> |
13534 | </TABLE> | |
13535 | <HR> | |
13536 | <A NAME="index"> </A><H2>Index</H2> | |
13537 | <DL> | |
13538 | <DT><A HREF="#lbAB">NAME</A><DD> | |
13539 | <DT><A HREF="#lbAC">SYNOPSIS</A><DD> | |
13540 | <DT><A HREF="#lbAD">COPYRIGHT</A><DD> | |
13541 | <DT><A HREF="#lbAE">DESCRIPTION</A><DD> | |
13542 | <DT><A HREF="#lbAF">OPTIONS</A><DD> | |
13543 | <DT><A HREF="#lbAG">ARGUMENTS</A><DD> | |
13544 | <DT><A HREF="#lbAH">INVOCATION</A><DD> | |
13545 | <DT><A HREF="#lbAI">DEFINITIONS</A><DD> | |
13546 | <DT><A HREF="#lbAJ">RESERVED WORDS</A><DD> | |
13547 | <DT><A HREF="#lbAK">SHELL GRAMMAR</A><DD> | |
13548 | <DL> | |
13549 | <DT><A HREF="#lbAL">Simple Commands</A><DD> | |
13550 | <DT><A HREF="#lbAM">Pipelines</A><DD> | |
13551 | <DT><A HREF="#lbAN">Lists</A><DD> | |
13552 | <DT><A HREF="#lbAO">Compound Commands</A><DD> | |
13553 | <DT><A HREF="#lbAP">Coprocesses</A><DD> | |
13554 | <DT><A HREF="#lbAQ">Shell Function Definitions</A><DD> | |
13555 | </DL> | |
13556 | <DT><A HREF="#lbAR">COMMENTS</A><DD> | |
13557 | <DT><A HREF="#lbAS">QUOTING</A><DD> | |
13558 | <DT><A HREF="#lbAT">PARAMETERS</A><DD> | |
13559 | <DL> | |
13560 | <DT><A HREF="#lbAU">Positional Parameters</A><DD> | |
13561 | <DT><A HREF="#lbAV">Special Parameters</A><DD> | |
13562 | <DT><A HREF="#lbAW">Shell Variables</A><DD> | |
13563 | <DT><A HREF="#lbAX">Arrays</A><DD> | |
13564 | </DL> | |
13565 | <DT><A HREF="#lbAY">EXPANSION</A><DD> | |
13566 | <DL> | |
13567 | <DT><A HREF="#lbAZ">Brace Expansion</A><DD> | |
13568 | <DT><A HREF="#lbBA">Tilde Expansion</A><DD> | |
13569 | <DT><A HREF="#lbBB">Parameter Expansion</A><DD> | |
13570 | <DT><A HREF="#lbBC">Command Substitution</A><DD> | |
13571 | <DT><A HREF="#lbBD">Arithmetic Expansion</A><DD> | |
13572 | <DT><A HREF="#lbBE">Process Substitution</A><DD> | |
13573 | <DT><A HREF="#lbBF">Word Splitting</A><DD> | |
13574 | <DT><A HREF="#lbBG">Pathname Expansion</A><DD> | |
13575 | <DT><A HREF="#lbBH">Quote Removal</A><DD> | |
13576 | </DL> | |
13577 | <DT><A HREF="#lbBI">REDIRECTION</A><DD> | |
13578 | <DL> | |
13579 | <DT><A HREF="#lbBJ">Redirecting Input</A><DD> | |
13580 | <DT><A HREF="#lbBK">Redirecting Output</A><DD> | |
13581 | <DT><A HREF="#lbBL">Appending Redirected Output</A><DD> | |
13582 | <DT><A HREF="#lbBM">Redirecting Standard Output and Standard Error</A><DD> | |
13583 | <DT><A HREF="#lbBN">Appending Standard Output and Standard Error</A><DD> | |
13584 | <DT><A HREF="#lbBO">Here Documents</A><DD> | |
13585 | <DT><A HREF="#lbBP">Here Strings</A><DD> | |
13586 | <DT><A HREF="#lbBQ">Duplicating File Descriptors</A><DD> | |
13587 | <DT><A HREF="#lbBR">Moving File Descriptors</A><DD> | |
13588 | <DT><A HREF="#lbBS">Opening File Descriptors for Reading and Writing</A><DD> | |
13589 | </DL> | |
13590 | <DT><A HREF="#lbBT">ALIASES</A><DD> | |
13591 | <DT><A HREF="#lbBU">FUNCTIONS</A><DD> | |
13592 | <DT><A HREF="#lbBV">ARITHMETIC EVALUATION</A><DD> | |
13593 | <DT><A HREF="#lbBW">CONDITIONAL EXPRESSIONS</A><DD> | |
13594 | <DT><A HREF="#lbBX">SIMPLE COMMAND EXPANSION</A><DD> | |
13595 | <DT><A HREF="#lbBY">COMMAND EXECUTION</A><DD> | |
13596 | <DT><A HREF="#lbBZ">COMMAND EXECUTION ENVIRONMENT</A><DD> | |
13597 | <DT><A HREF="#lbCA">ENVIRONMENT</A><DD> | |
13598 | <DT><A HREF="#lbCB">EXIT STATUS</A><DD> | |
13599 | <DT><A HREF="#lbCC">SIGNALS</A><DD> | |
13600 | <DT><A HREF="#lbCD">JOB CONTROL</A><DD> | |
13601 | <DT><A HREF="#lbCE">PROMPTING</A><DD> | |
13602 | <DT><A HREF="#lbCF">READLINE</A><DD> | |
13603 | <DL> | |
13604 | <DT><A HREF="#lbCG">Readline Notation</A><DD> | |
13605 | <DT><A HREF="#lbCH">Readline Initialization</A><DD> | |
13606 | <DT><A HREF="#lbCI">Readline Key Bindings</A><DD> | |
13607 | <DT><A HREF="#lbCJ">Readline Variables</A><DD> | |
13608 | <DT><A HREF="#lbCK">Readline Conditional Constructs</A><DD> | |
13609 | <DT><A HREF="#lbCL">Searching</A><DD> | |
13610 | <DT><A HREF="#lbCM">Readline Command Names</A><DD> | |
13611 | <DT><A HREF="#lbCN">Commands for Moving</A><DD> | |
13612 | <DT><A HREF="#lbCO">Commands for Manipulating the History</A><DD> | |
13613 | <DT><A HREF="#lbCP">Commands for Changing Text</A><DD> | |
13614 | <DT><A HREF="#lbCQ">Killing and Yanking</A><DD> | |
13615 | <DT><A HREF="#lbCR">Numeric Arguments</A><DD> | |
13616 | <DT><A HREF="#lbCS">Completing</A><DD> | |
13617 | <DT><A HREF="#lbCT">Keyboard Macros</A><DD> | |
13618 | <DT><A HREF="#lbCU">Miscellaneous</A><DD> | |
13619 | <DT><A HREF="#lbCV">Programmable Completion</A><DD> | |
13620 | </DL> | |
13621 | <DT><A HREF="#lbCW">HISTORY</A><DD> | |
13622 | <DT><A HREF="#lbCX">HISTORY EXPANSION</A><DD> | |
13623 | <DL> | |
13624 | <DT><A HREF="#lbCY">Event Designators</A><DD> | |
13625 | <DT><A HREF="#lbCZ">Word Designators</A><DD> | |
13626 | <DT><A HREF="#lbDA">Modifiers</A><DD> | |
13627 | </DL> | |
13628 | <DT><A HREF="#lbDB">SHELL BUILTIN COMMANDS</A><DD> | |
13629 | <DT><A HREF="#lbDC">RESTRICTED SHELL</A><DD> | |
13630 | <DT><A HREF="#lbDD">SEE ALSO</A><DD> | |
13631 | <DT><A HREF="#lbDE">FILES</A><DD> | |
13632 | <DT><A HREF="#lbDF">AUTHORS</A><DD> | |
13633 | <DT><A HREF="#lbDG">BUG REPORTS</A><DD> | |
13634 | <DT><A HREF="#lbDH">BUGS</A><DD> | |
13635 | </DL> | |
13636 | <HR> | |
13637 | This document was created by man2html from bash.1.<BR> | |
a0c0a00f | 13638 | Time: 31 August 2016 10:24:30 EDT |
17345e5a JA |
13639 | </BODY> |
13640 | </HTML> |