]>
Commit | Line | Data |
---|---|---|
726f6388 JA |
1 | .\" |
2 | .\" MAN PAGE COMMENTS to | |
3 | .\" | |
4 | .\" Chet Ramey | |
5 | .\" Information Network Services | |
6 | .\" Case Western Reserve University | |
7 | .\" chet@ins.CWRU.Edu | |
8 | .\" | |
9 | .\" Last Change: Fri May 5 10:44:39 EDT 1995 | |
10 | .\" | |
11 | .\" bash_builtins, strip all but Built-Ins section | |
12 | .if \n(zZ=1 .ig zZ | |
13 | .TH BASH 1 "1995 May 5" GNU | |
14 | .\" | |
15 | .\" There's some problem with having a `@' | |
16 | .\" in a tagged paragraph with the BSD man macros. | |
17 | .\" It has to do with `@' appearing in the }1 macro. | |
18 | .\" This is a problem on 4.3 BSD and Ultrix, but Sun | |
19 | .\" appears to have fixed it. | |
20 | .\" If you're seeing the characters | |
21 | .\" `@u-3p' appearing before the lines reading | |
22 | .\" `possible-hostname-completions | |
23 | .\" and `complete-hostname' down in READLINE, | |
24 | .\" then uncomment this redefinition. | |
25 | .\" | |
26 | .de }1 | |
27 | .ds ]X \&\\*(]B\\ | |
28 | .nr )E 0 | |
29 | .if !"\\$1"" .nr )I \\$1n | |
30 | .}f | |
31 | .ll \\n(LLu | |
32 | .in \\n()Ru+\\n(INu+\\n()Iu | |
33 | .ti \\n(INu | |
34 | .ie !\\n()Iu+\\n()Ru-\w\a\\*(]X\au-3p \{\\*(]X | |
35 | .br\} | |
36 | .el \\*(]X\h\a|\\n()Iu+\\n()Ru\a\c | |
37 | .}f | |
38 | .. | |
39 | .\" | |
40 | .\" File Name macro. This used to be `.PN', for Path Name, | |
41 | .\" but Sun doesn't seem to like that very much. | |
42 | .\" | |
43 | .de FN | |
44 | \fI\|\\$1\|\fP | |
45 | .. | |
46 | .SH NAME | |
47 | bash \- GNU Bourne\-Again SHell | |
48 | .SH SYNOPSIS | |
49 | .B bash | |
50 | [options] | |
51 | [file] | |
52 | .SH COPYRIGHT | |
53 | .if n Bash is Copyright (C) 1989, 1991 by the Free Software Foundation, Inc. | |
54 | .if t Bash is Copyright \(co 1989, 1991 by the Free Software Foundation, Inc. | |
55 | .SH DESCRIPTION | |
56 | .B Bash | |
57 | is an \fBsh\fR\-compatible command language interpreter that | |
58 | executes commands read from the standard input or from a file. | |
59 | .B Bash | |
60 | also incorporates useful features from the \fIKorn\fP and \fIC\fP | |
61 | shells (\fBksh\fP and \fBcsh\fP). | |
62 | .PP | |
63 | .B Bash | |
64 | is ultimately intended to be a conformant implementation of the IEEE | |
65 | Posix Shell and Tools specification (IEEE Working Group 1003\.2). | |
66 | .SH OPTIONS | |
67 | In addition to the single\-character shell options documented in the | |
68 | description of the \fBset\fR builtin command, \fBbash\fR | |
69 | interprets the following flags when it is invoked: | |
70 | .PP | |
71 | .PD 0 | |
72 | .TP 10 | |
73 | .BI \-c "\| string\^" | |
74 | If the | |
75 | .B \-c | |
76 | flag is present, then commands are read from | |
77 | .IR string . | |
78 | If there are arguments after the | |
79 | .IR string , | |
80 | they are assigned to the positional parameters, starting with | |
81 | .BR $0 . | |
82 | .TP | |
83 | .B \-i | |
84 | If the | |
85 | .B \-i | |
86 | flag is present, the shell is | |
87 | .IR interactive . | |
88 | .TP | |
89 | .B \-s | |
90 | If the | |
91 | .B \-s | |
92 | flag is present, or if no arguments remain after option | |
93 | processing, then commands are read from the standard input. | |
94 | This option allows the positional parameters to be set | |
95 | when invoking an interactive shell. | |
96 | .TP | |
97 | .B \- | |
98 | A single | |
99 | .B \- | |
100 | signals the end of options and disables further option processing. | |
101 | Any arguments after the | |
102 | .B \- | |
103 | are treated as filenames and arguments. An argument of | |
104 | .B \-\- | |
105 | is equivalent to an argument of \fB\-\fP. | |
106 | .PD | |
107 | .PP | |
108 | .B Bash | |
109 | also interprets a number of multi\-character options. These options must | |
110 | appear on the command line before the single\-character options to be | |
111 | recognized. | |
112 | .PP | |
113 | .PD 0 | |
114 | .TP 10 | |
115 | .B \-norc | |
116 | Do not read and execute the personal initialization file | |
117 | .I ~/.bashrc | |
118 | if the shell is interactive. | |
119 | This option is on by default if the shell is invoked as | |
120 | .BR sh . | |
121 | .TP | |
122 | .B \-noprofile | |
123 | Do not read either the system\-wide startup file | |
124 | .FN /etc/profile | |
125 | or any of the personal initialization files | |
126 | .IR ~/.bash_profile , | |
127 | .IR ~/.bash_login , | |
128 | or | |
129 | .IR ~/.profile . | |
130 | By default, | |
131 | .B bash | |
132 | normally reads these files when it is invoked as a login shell (see | |
133 | .SM | |
134 | .B INVOCATION | |
135 | below). | |
136 | .TP | |
137 | \fB\-rcfile\fP \fIfile\fP | |
138 | Execute commands from | |
139 | .I file | |
140 | instead of the standard personal initialization file | |
141 | .IR ~/.bashrc , | |
142 | if the shell is interactive (see | |
143 | .SM | |
144 | .B INVOCATION | |
145 | below). | |
146 | .TP | |
147 | .B \-version | |
148 | Show the version number of this instance of | |
149 | .B bash | |
150 | when starting. | |
151 | .TP | |
152 | .B \-quiet | |
153 | Do not be verbose when starting up (do not show the shell version or any | |
154 | other information). This is the default. | |
155 | .TP | |
156 | .B \-login | |
157 | Make | |
158 | .B bash | |
159 | act as if it had been invoked as a login shell. | |
160 | .TP | |
161 | .B \-nobraceexpansion | |
162 | Do not perform curly brace expansion (see | |
163 | .B Brace Expansion | |
164 | below). | |
165 | .TP | |
166 | .B \-nolineediting | |
167 | Do not use the GNU | |
168 | .I readline | |
169 | library to read command lines if interactive. | |
170 | .TP | |
171 | .B \-posix | |
172 | Change the behavior of bash where the default operation differs | |
173 | from the Posix 1003.2 standard to match the standard | |
174 | .PD | |
175 | .SH ARGUMENTS | |
176 | If arguments remain after option processing, and neither the | |
177 | .B \-c | |
178 | nor the | |
179 | .B \-s | |
180 | option has been supplied, the first argument is assumed to | |
181 | be the name of a file containing shell commands. If | |
182 | .B bash | |
183 | is invoked in this fashion, | |
184 | .B $0 | |
185 | is set to the name of the file, and the positional parameters | |
186 | are set to the remaining arguments. | |
187 | .B Bash | |
188 | reads and executes commands from this file, then exits. | |
189 | .B Bash's | |
190 | exit status is the exit status of the last command executed | |
191 | in the script. | |
192 | .SH DEFINITIONS | |
193 | .PD 0 | |
194 | .TP | |
195 | .B blank | |
196 | A space or tab. | |
197 | .TP | |
198 | .B word | |
199 | A sequence of characters considered as a single unit by the shell. | |
200 | Also known as a | |
201 | .BR token . | |
202 | .TP | |
203 | .B name | |
204 | A | |
205 | .I word | |
206 | consisting only of alphanumeric characters and underscores, and | |
207 | beginning with an alphabetic character or an underscore. Also | |
208 | referred to as an | |
209 | .BR identifier . | |
210 | .TP | |
211 | .B metacharacter | |
212 | A character that, when unquoted, separates words. One of the following: | |
213 | .br | |
214 | .RS | |
215 | .PP | |
216 | .if t \fB| & ; ( ) < > space tab\fP | |
217 | .if n \fB| & ; ( ) < > space tab\fP | |
218 | .RE | |
219 | .PP | |
220 | .TP | |
221 | .B control operator | |
222 | A \fItoken\fP that performs a control function. It is one of the following | |
223 | symbols: | |
224 | .RS | |
225 | .PP | |
226 | .if t \fB\(bv\|\(bv & && ; ;; ( ) | <newline>\fP | |
227 | .if n \fB|| & && ; ;; ( ) | <newline>\fP | |
228 | .RE | |
229 | .PD | |
230 | .SH "RESERVED WORDS" | |
231 | \fIReserved words\fP are words that have a special meaning to the shell. | |
232 | The following words are recognized as reserved when unquoted and either | |
233 | the first word of a simple command (see | |
234 | .SM | |
235 | .B SHELL GRAMMAR | |
236 | below) or the third word of a | |
237 | .B case | |
238 | or | |
239 | .B for | |
240 | command: | |
241 | .if t .RS | |
242 | .PP | |
243 | .B | |
244 | .if n ! case do done elif else esac fi for function if in select then until while { } | |
245 | .if t ! case do done elif else esac fi for function if in select then until while { } | |
246 | .if t .RE | |
247 | .RE | |
248 | .SH "SHELL GRAMMAR" | |
249 | .SS Simple Commands | |
250 | .PP | |
251 | A \fIsimple command\fP is a sequence of optional variable assignments | |
252 | followed by \fIblank\fP\-separated words and redirections, and | |
253 | terminated by a \fIcontrol operator\fP. The first word | |
254 | specifies the command to be executed. The remaining words are | |
255 | passed as arguments to the invoked command. | |
256 | .PP | |
257 | The return value of a \fIsimple command\fP is its exit status, or | |
258 | 128+\fIn\^\fP if the command is terminated by signal | |
259 | .IR n . | |
260 | .SS Pipelines | |
261 | .PP | |
262 | A \fIpipeline\fP is a sequence of one or more commands separated by | |
263 | the character | |
264 | .BR | . | |
265 | The format for a pipeline is: | |
266 | .RS | |
267 | .PP | |
268 | [ ! ] \fIcommand\fP [ \fB|\fP \fIcommand2\fP ... ] | |
269 | .RE | |
270 | .PP | |
271 | The standard output of | |
272 | .I command | |
273 | is connected to the standard input of | |
274 | .IR command2 . | |
275 | This connection is performed before any redirections specified by the | |
276 | command (see | |
277 | .SM | |
278 | .B REDIRECTION | |
279 | below). | |
280 | .PP | |
281 | If the reserved word | |
282 | .B ! | |
283 | precedes a pipeline, the exit status of that | |
284 | pipeline is the logical NOT of the exit status of the last command. | |
285 | Otherwise, the status of the pipeline is the exit status of the last | |
286 | command. The shell waits for all commands in the pipeline to | |
287 | terminate before returning a value. | |
288 | .PP | |
289 | Each command in a pipeline is executed as a separate process (i.e., in a | |
290 | subshell). | |
291 | .SS Lists | |
292 | .PP | |
293 | A \fIlist\fP is a sequence of one or more pipelines separated by one | |
294 | of the operators | |
295 | .BR ; , | |
296 | .BR & , | |
297 | .BR && , | |
298 | or | |
299 | .BR \(bv\|\(bv , | |
300 | and terminated by one of | |
301 | .BR ; , | |
302 | .BR & , | |
303 | or | |
304 | .BR <newline> . | |
305 | .PP | |
306 | Of these list operators, | |
307 | .B && | |
308 | and | |
309 | .B \(bv\|\(bv | |
310 | have equal precedence, followed by | |
311 | .B ; | |
312 | and | |
313 | .BR &, | |
314 | which have equal precedence. | |
315 | .PP | |
316 | If a command is terminated by the control operator | |
317 | .BR & , | |
318 | the shell executes the command in the \fIbackground\fP | |
319 | in a subshell. The shell does not wait for the command to | |
320 | finish, and the return status is 0. Commands separated by a | |
321 | .B ; | |
322 | are executed sequentially; the shell waits for each | |
323 | command to terminate in turn. The return status is the | |
324 | exit status of the last command executed. | |
325 | .PP | |
326 | The control operators | |
327 | .B && | |
328 | and | |
329 | .B \(bv\|\(bv | |
330 | denote AND lists and OR lists, respectively. | |
331 | An AND list has the form | |
332 | .RS | |
333 | .PP | |
334 | \fIcommand\fP \fB&&\fP \fIcommand2\fP | |
335 | .RE | |
336 | .PP | |
337 | .I command2 | |
338 | is executed if, and only if, | |
339 | .I command | |
340 | returns an exit status of zero. | |
341 | .PP | |
342 | An OR list has the form | |
343 | .RS | |
344 | .PP | |
345 | \fIcommand\fP \fB\(bv\|\(bv\fP \fIcommand2\fP | |
346 | .PP | |
347 | .RE | |
348 | .PP | |
349 | .I command2 | |
350 | is executed if and only if | |
351 | .I command | |
352 | returns a non\-zero exit status. The return status of | |
353 | AND and OR lists is the exit status of the last command | |
354 | executed in the list. | |
355 | .SS Compound Commands | |
356 | .PP | |
357 | A \fIcompound command\fP is one of the following: | |
358 | .TP | |
359 | (\fIlist\fP) | |
360 | \fIlist\fP is executed in a subshell. Variable assignments and builtin | |
361 | commands that affect the shell's environment do not remain in effect | |
362 | after the command completes. The return status is the exit status of | |
363 | \fIlist\fP. | |
364 | .TP | |
365 | { \fIlist\fP; } | |
366 | \fIlist\fP is simply executed in the current shell environment. This is | |
367 | known as a \fIgroup command\fP. The return status is the exit status of | |
368 | \fIlist\fP. | |
369 | .TP | |
370 | \fBfor\fP \fIname\fP [ \fBin\fP \fIword\fP; ] \fBdo\fP \fIlist\fP ; \fBdone\fP | |
371 | The list of words following \fBin\fP is expanded, generating a list | |
372 | of items. The variable \fIname\fP is set to each element of this list | |
373 | in turn, and \fIlist\fP is executed each time. If the \fBin\fP | |
374 | \fIword\fP is omitted, the \fBfor\fP command executes \fIlist\fP | |
375 | once for each positional parameter that is set (see | |
376 | .SM | |
377 | .B PARAMETERS | |
378 | below). | |
379 | .TP | |
380 | \fBselect\fP \fIname\fP [ \fBin\fP \fIword\fP; ] \fBdo\fP \fIlist\fP ; \fBdone\fP | |
381 | The list of words following \fBin\fP is expanded, generating a list | |
382 | of items. The set of expanded words is printed on the standard | |
383 | error, each preceded by a number. If the \fBin\fP | |
384 | \fIword\fP is omitted, the positional parameters are printed (see | |
385 | .SM | |
386 | .B PARAMETERS | |
387 | below). The | |
388 | .B PS3 | |
389 | prompt is then displayed and a line read from the standard input. | |
390 | If the line consists of the number corresponding to one of | |
391 | the displayed words, then the value of | |
392 | .I name | |
393 | is set to that word. If the line is empty, the words and prompt | |
394 | are displayed again. If EOF is read, the command completes. Any | |
395 | other value read causes | |
396 | .I name | |
397 | to be set to null. The line read is saved in the variable | |
398 | .BR REPLY . | |
399 | The | |
400 | .I list | |
401 | is executed after each selection until a | |
402 | .B break | |
403 | or | |
404 | .B return | |
405 | command is executed. | |
406 | The exit status of | |
407 | .B select | |
408 | is the exit status of the last command executed in | |
409 | .IR list , | |
410 | or zero if no commands were executed. | |
411 | .TP | |
412 | \fBcase\fP \fIword\fP \fBin\fP [ \fIpattern\fP [ \fB|\fP \fIpattern\fP ] \ | |
413 | ... ) \fIlist\fP ;; ] ... \fBesac\fP | |
414 | A \fBcase\fP command first expands \fIword\fP, and tries to match | |
415 | it against each \fIpattern\fP in turn, using the same matching rules | |
416 | as for pathname expansion (see | |
417 | .B Pathname Expansion | |
418 | below). When a match is found, the | |
419 | corresponding \fIlist\fP is executed. After the first match, no | |
420 | subsequent matches are attempted. The exit status is zero if no | |
421 | patterns are matches. Otherwise, it is the exit status of the | |
422 | last command executed in \fIlist\fP. | |
423 | .TP | |
424 | \fBif\fP \fIlist\fP \fBthen\fP \fIlist\fP \ | |
425 | [ \fBelif\fP \fIlist\fP \fBthen\fP \fIlist\fP ] ... \ | |
426 | [ \fBelse\fP \fIlist\fP ] \fBfi\fP | |
427 | The | |
428 | .B if | |
429 | .I list | |
430 | is executed. If its exit status is zero, the | |
431 | \fBthen\fP \fIlist\fP is executed. Otherwise, each \fBelif\fP | |
432 | \fIlist\fP is executed in turn, and if its exit status is zero, | |
433 | the corresponding \fBthen\fP \fIlist\fP is executed and the | |
434 | command completes. Otherwise, the \fBelse\fP \fIlist\fP is | |
435 | executed, if present. The exit status is the exit status of the | |
436 | last command executed, or zero if no condition tested true. | |
437 | .TP | |
438 | .PD 0 | |
439 | \fBwhile\fP \fIlist\fP \fBdo\fP \fIlist\fP \fBdone\fP | |
440 | .TP | |
441 | \fBuntil\fP \fIlist\fP \fBdo\fP \fIlist\fP \fBdone\fP | |
442 | .PD | |
443 | The \fBwhile\fP command continuously executes the \fBdo\fP | |
444 | \fIlist\fP as long as the last command in \fIlist\fP returns | |
445 | an exit status of zero. The \fBuntil\fP command is identical | |
446 | to the \fBwhile\fP command, except that the test is negated; | |
447 | the | |
448 | .B do | |
449 | .I list | |
450 | is executed as long as the last command in | |
451 | .I list | |
452 | returns a non\-zero exit status. | |
453 | The exit status of the \fBwhile\fP and \fBuntil\fP commands | |
454 | is the exit status | |
455 | of the last \fBdo\fP \fIlist\fP command executed, or zero if | |
456 | none was executed. | |
457 | .TP | |
458 | [ \fBfunction\fP ] \fIname\fP () { \fIlist\fP; } | |
459 | This defines a function named \fIname\fP. The \fIbody\fP of the | |
460 | function is the | |
461 | .I list | |
462 | of commands between { and }. This list | |
463 | is executed whenever \fIname\fP is specified as the | |
464 | name of a simple command. The exit status of a function is | |
465 | the exit status of the last command executed in the body. (See | |
466 | .SM | |
467 | .B FUNCTIONS | |
468 | below.) | |
469 | .SH COMMENTS | |
470 | In a non\-interactive shell, or an interactive shell in which the | |
471 | .B -o interactive\-comments | |
472 | option to the \fBset\fP builtin is enabled, a word beginning with | |
473 | .B # | |
474 | causes that word and all remaining characters on that line to | |
475 | be ignored. An interactive shell without the | |
476 | .B -o interactive\-comments | |
477 | option enabled does not allow comments. | |
478 | .SH QUOTING | |
479 | \fIQuoting\fP is used to remove the special meaning of certain | |
480 | characters or words to the shell. Quoting can be used to | |
481 | disable special treatment for special characters, to prevent | |
482 | reserved words from being recognized as such, and to prevent | |
483 | parameter expansion. | |
484 | .PP | |
485 | Each of the \fImetacharacters\fP listed above under | |
486 | .SM | |
487 | .B DEFINITIONS | |
488 | has special meaning to the shell and must be quoted if they are to | |
489 | represent themselves. There are three quoting mechanisms: the | |
490 | .IR "escape character" , | |
491 | single quotes, and double quotes. | |
492 | .PP | |
493 | A non-quoted backslash (\fB\e\fP) is the | |
494 | .IR "escape character" . | |
495 | It preserves the literal value of the next character that follows, | |
496 | with the exception of <newline>. If a \fB\e\fP<newline> pair | |
497 | appears, and the backslash is not quoted, the \fB\e\fP<newline> | |
498 | is treated as a line continuation (that is, it is effectively ignored). | |
499 | .PP | |
500 | Enclosing characters in single quotes preserves the literal value | |
501 | of each character within the quotes. A single quote may not occur | |
502 | between single quotes, even when preceded by a backslash. | |
503 | .PP | |
504 | Enclosing characters in double quotes preserves the literal value | |
505 | of all characters within the quotes, with the exception of | |
506 | .BR $ , | |
507 | .BR ` , | |
508 | and | |
509 | .BR \e . | |
510 | The characters | |
511 | .B $ | |
512 | and | |
513 | .B ` | |
514 | retain their special meaning within double quotes. The backslash | |
515 | retains its special meaning only when followed by one of the following | |
516 | characters: | |
517 | .BR $ , | |
518 | .BR ` , | |
519 | \^\fB"\fP\^, | |
520 | .BR \e , | |
521 | or | |
522 | .BR <newline> . | |
523 | A double quote may be quoted within double quotes by preceding it with | |
524 | a backslash. | |
525 | .PP | |
526 | The special parameters | |
527 | .B * | |
528 | and | |
529 | .B @ | |
530 | have special meaning when in double | |
531 | quotes (see | |
532 | .SM | |
533 | .B PARAMETERS | |
534 | below). | |
535 | .SH PARAMETERS | |
536 | A | |
537 | .I parameter | |
538 | is an entity that stores values, somewhat like a | |
539 | variable in a conventional programming language. It can be a | |
540 | .IR name , | |
541 | a number, or one of the special characters listed below under | |
542 | .BR "Special Parameters" . | |
543 | For the shell's purposes, a | |
544 | .I variable | |
545 | is a parameter denoted by a | |
546 | .IR name . | |
547 | .PP | |
548 | A parameter is set if it has been assigned a value. The null string is | |
549 | a valid value. Once a variable is set, it may be unset only by using | |
550 | the | |
551 | .B unset | |
552 | builtin command (see | |
553 | .SM | |
554 | .B SHELL BUILTIN COMMANDS | |
555 | below). | |
556 | .PP | |
557 | A | |
558 | .I variable | |
559 | may be assigned to by a statement of the form | |
560 | .RS | |
561 | .PP | |
562 | \fIname\fP=[\fIvalue\fP] | |
563 | .RE | |
564 | .PP | |
565 | If | |
566 | .I value | |
567 | is not given, the variable is assigned the null string. All | |
568 | .I values | |
569 | undergo tilde expansion, parameter and variable expansion, command | |
570 | substitution, arithmetic expansion, and quote removal. If | |
571 | the variable has its | |
572 | .B \-i | |
573 | attribute set (see | |
574 | .B declare | |
575 | below in | |
576 | .SM | |
577 | .BR "SHELL BUILTIN COMMANDS" ) | |
578 | then | |
579 | .I value | |
580 | is subject to arithmetic expansion even if the $[...] syntax does | |
581 | not appear. Word splitting is not performed, with the exception | |
582 | of \fB"$@"\fP as explained below under | |
583 | .BR "Special Parameters" . | |
584 | Pathname expansion is not performed. | |
585 | .SS Positional Parameters | |
586 | .PP | |
587 | A | |
588 | .I positional parameter | |
589 | is a parameter denoted by one or more | |
590 | digits, other than the single digit 0. Positional parameters are | |
591 | assigned from the shell's arguments when it is invoked, | |
592 | and may be reassigned using the | |
593 | .B set | |
594 | builtin command. Positional parameters may not be assigned to | |
595 | with assignment statements. The positional parameters are | |
596 | temporarily replaced when a shell function is executed (see | |
597 | .SM | |
598 | .B FUNCTIONS | |
599 | below). | |
600 | .PP | |
601 | When a positional parameter consisting of more than a single | |
602 | digit is expanded, it must be enclosed in braces (see | |
603 | .SM | |
604 | .B EXPANSION | |
605 | below). | |
606 | .SS Special Parameters | |
607 | .PP | |
608 | The shell treats several parameters specially. These parameters may | |
609 | only be referenced; assignment to them is not allowed. | |
610 | .PD 0 | |
611 | .TP | |
612 | .B * | |
613 | Expands to the positional parameters, starting from one. When the | |
614 | expansion occurs within double quotes, it expands to a single word | |
615 | with the value of each parameter separated by the first character | |
616 | of the | |
617 | .SM | |
618 | .B IFS | |
619 | special variable. That is, ``\fB$*\fP'' is equivalent | |
620 | to ``\fB$1\fP\fIc\fP\fB$2\fP\fIc\fP\fB...\fP'', where | |
621 | .I c | |
622 | is the first character of the value of the | |
623 | .SM | |
624 | .B IFS | |
625 | variable. If | |
626 | .SM | |
627 | .B IFS | |
628 | is null or unset, the parameters are separated by spaces. | |
629 | .TP | |
630 | .B @ | |
631 | Expands to the positional parameters, starting from one. When the | |
632 | expansion occurs within double quotes, each parameter expands as a | |
633 | separate word. That is, `` | |
634 | .BR $@ '' | |
635 | is equivalent to | |
636 | ``\fB$1\fP'' ``\fB$2\fP'' ... | |
637 | When there are no positional parameters, ``\fB$@\fP'' and | |
638 | .B $@ | |
639 | expand to nothing (i.e., they are removed). | |
640 | .TP | |
641 | .B # | |
642 | Expands to the number of positional parameters in decimal. | |
643 | .TP | |
644 | .B ? | |
645 | Expands to the status of the most recently executed foreground | |
646 | pipeline. | |
647 | .TP | |
648 | .B \- | |
649 | Expands to the current option flags as specified upon invocation, | |
650 | by the | |
651 | .B set | |
652 | builtin command, or those set by the shell itself | |
653 | (such as the | |
654 | .B \-i | |
655 | flag). | |
656 | .TP | |
657 | .B $ | |
658 | Expands to the process ID of the shell. In a () subshell, it | |
659 | expands to the process ID of the current shell, not the | |
660 | subshell. | |
661 | .TP | |
662 | .B ! | |
663 | Expands to the process ID of the most recently executed background | |
664 | (asynchronous) command. | |
665 | .TP | |
666 | .B 0 | |
667 | Expands to the name of the shell or shell script. This is set at | |
668 | shell initialization. If | |
669 | .B bash | |
670 | is invoked with a file of commands, | |
671 | .B $0 | |
672 | is set to the name of that file. If | |
673 | .B bash | |
674 | is started with the | |
675 | .B \-c | |
676 | option, then | |
677 | .B $0 | |
678 | is set to the first argument after the string to be | |
679 | executed, if one is present. Otherwise, it is set | |
680 | to the pathname used to invoke | |
681 | .BR bash , | |
682 | as given by argument zero. | |
683 | .TP | |
684 | .B _ | |
685 | Expands to the last argument to the previous command, after expansion. | |
686 | Also set to the full pathname of each command executed and placed in | |
687 | the environment exported to that command. | |
688 | .PD | |
689 | .SS Shell Variables | |
690 | .PP | |
691 | The following variables are set by the shell: | |
692 | .PP | |
693 | .PD 0 | |
694 | .TP | |
695 | .B PPID | |
696 | The process ID of the shell's parent. | |
697 | .TP | |
698 | .B PWD | |
699 | The current working directory as set by the | |
700 | .B cd | |
701 | command. | |
702 | .TP | |
703 | .B OLDPWD | |
704 | The previous working directory as set by the | |
705 | .B cd | |
706 | command. | |
707 | .TP | |
708 | .B REPLY | |
709 | Set to the line of input read by the | |
710 | .B read | |
711 | builtin command when no arguments are supplied. | |
712 | .TP | |
713 | .B UID | |
714 | Expands to the user ID of the current user, initialized at shell startup. | |
715 | .TP | |
716 | .B EUID | |
717 | Expands to the effective user ID of the current user, initialized at | |
718 | shell startup. | |
719 | .TP | |
720 | .B BASH | |
721 | Expands to the full pathname used to invoke this instance of | |
722 | .BR bash . | |
723 | .TP | |
724 | .B BASH_VERSION | |
725 | Expands to the version number of this instance of | |
726 | .BR bash . | |
727 | .TP | |
728 | .B SHLVL | |
729 | Incremented by one each time an instance of | |
730 | .B bash | |
731 | is started. | |
732 | .TP | |
733 | .B RANDOM | |
734 | Each time this parameter is referenced, a random integer is | |
735 | generated. The sequence of random numbers may be initialized by assigning | |
736 | a value to | |
737 | .SM | |
738 | .BR RANDOM . | |
739 | If | |
740 | .SM | |
741 | .B RANDOM | |
742 | is unset, it loses its special properties, even if it is | |
743 | subsequently reset. | |
744 | .TP | |
745 | .B SECONDS | |
746 | Each time this parameter is | |
747 | referenced, the number of seconds since shell invocation is returned. If a | |
748 | value is assigned to | |
749 | .SM | |
750 | .BR SECONDS , | |
751 | the value returned upon subsequent | |
752 | references is | |
753 | the number of seconds since the assignment plus the value assigned. | |
754 | If | |
755 | .SM | |
756 | .B SECONDS | |
757 | is unset, it loses its special properties, even if it is | |
758 | subsequently reset. | |
759 | .TP | |
760 | .B LINENO | |
761 | Each time this parameter is referenced, the shell substitutes | |
762 | a decimal number representing the current sequential line number | |
763 | (starting with 1) within a script or function. When not in a | |
764 | script or function, the value substituted is not guaranteed to | |
765 | be meaningful. When in a function, the value is not | |
766 | the number of the source line that the command appears | |
767 | on (that information has been lost by the time the function is | |
768 | executed), but is an approximation of the number of | |
769 | .I simple commands | |
770 | executed in the current function. | |
771 | If | |
772 | .SM | |
773 | .B LINENO | |
774 | is unset, it loses its special properties, even if it is | |
775 | subsequently reset. | |
776 | .TP | |
777 | .B HISTCMD | |
778 | The history number, or index in the history list, of the current | |
779 | command. If | |
780 | .SM | |
781 | .B HISTCMD | |
782 | is unset, it loses its special properties, even if it is | |
783 | subsequently reset. | |
784 | .TP | |
785 | .B OPTARG | |
786 | The value of the last option argument processed by the | |
787 | .B getopts | |
788 | builtin command (see | |
789 | .SM | |
790 | .B SHELL BUILTIN COMMANDS | |
791 | below). | |
792 | .TP | |
793 | .B OPTIND | |
794 | The index of the next argument to be processed by the | |
795 | .B getopts | |
796 | builtin command (see | |
797 | .SM | |
798 | .B SHELL BUILTIN COMMANDS | |
799 | below). | |
800 | .TP | |
801 | .B HOSTTYPE | |
802 | Automatically set to a string that uniquely | |
803 | describes the type of machine on which | |
804 | .B bash | |
805 | is executing. The default is system-dependent. | |
806 | .TP | |
807 | .B OSTYPE | |
808 | Automatically set to a string that | |
809 | describes the operating system on which | |
810 | .B bash | |
811 | is executing. The default is system-dependent. | |
812 | .PD | |
813 | .PP | |
814 | The following variables are used by the shell. In some cases, | |
815 | .B bash | |
816 | assigns a default value to a variable; these cases are noted | |
817 | below. | |
818 | .PP | |
819 | .PD 0 | |
820 | .TP | |
821 | .B IFS | |
822 | The | |
823 | .I Internal Field Separator | |
824 | that is used | |
825 | for word splitting after expansion and to | |
826 | split lines into words with the | |
827 | .B read | |
828 | builtin command. The default value is | |
829 | ``<space><tab><newline>''. | |
830 | .TP | |
831 | .B PATH | |
832 | The search path for commands. It | |
833 | is a colon-separated list of directories in which | |
834 | the shell looks for commands (see | |
835 | .SM | |
836 | .B COMMAND EXECUTION | |
837 | below). The default path is system\-dependent, | |
838 | and is set by the administrator who installs | |
839 | .BR bash . | |
840 | A common value is ``/usr/gnu/bin:/usr/local/bin:/usr/ucb:/bin:/usr/bin:.''. | |
841 | .TP | |
842 | .B HOME | |
843 | The home directory of the current user; the default argument for the | |
844 | \fBcd\fP builtin command. | |
845 | .TP | |
846 | .B CDPATH | |
847 | The search path for the | |
848 | .B cd | |
849 | command. This is a colon-separated | |
850 | list of directories in which the shell looks for destination directories | |
851 | specified by the | |
852 | .B cd | |
853 | command. A sample value is | |
854 | ``.:~:/usr''. | |
855 | .TP | |
856 | .B ENV | |
857 | If this parameter is set when \fBbash\fP is executing a shell script, | |
858 | its value is interpreted as a filename containing commands to | |
859 | initialize the shell, as in | |
860 | .IR .bashrc . | |
861 | The value of | |
862 | .SM | |
863 | .B ENV | |
864 | is subjected to parameter expansion, command substitution, and arithmetic | |
865 | expansion before being interpreted as a pathname. | |
866 | .SM | |
867 | .B PATH | |
868 | is not used to search for the resultant pathname. | |
869 | .TP | |
870 | .B MAIL | |
871 | If this parameter is set to a filename and the | |
872 | .SM | |
873 | .B MAILPATH | |
874 | variable is not set, | |
875 | .B bash | |
876 | informs the user of the arrival of mail in the specified file. | |
877 | .TP | |
878 | .B MAILCHECK | |
879 | Specifies how | |
880 | often (in seconds) | |
881 | .B bash | |
882 | checks for mail. The default is 60 seconds. When it is time to check | |
883 | for mail, the shell does so before prompting. | |
884 | If this variable is unset, the shell disables mail checking. | |
885 | .TP | |
886 | .B MAILPATH | |
887 | A colon-separated list of pathnames to be checked for mail. | |
888 | The message to be printed may be specified by separating the pathname from | |
889 | the message with a `?'. $_ stands for the name of the current mailfile. | |
890 | Example: | |
891 | .RS | |
892 | .PP | |
893 | \fBMAILPATH\fP='/usr/spool/mail/bfox?"You have mail":~/shell-mail?"$_ has mail!"' | |
894 | .PP | |
895 | .B Bash | |
896 | supplies a default value for this variable, but the location of the user | |
897 | mail files that it uses is system dependent (e.g., /usr/spool/mail/\fB$USER\fP). | |
898 | .RE | |
899 | .TP | |
900 | .B MAIL_WARNING | |
901 | If set, and a file that \fBbash\fP is checking for mail has been | |
902 | accessed since the last time it was checked, the message ``The mail in | |
903 | \fImailfile\fP has been read'' is printed. | |
904 | .TP | |
905 | .B PS1 | |
906 | The value of this parameter is expanded (see | |
907 | .SM | |
908 | .B PROMPTING | |
909 | below) and used as the primary prompt string. The default value is | |
910 | ``\fBbash\e$ \fP''. | |
911 | .TP | |
912 | .B PS2 | |
913 | The value of this parameter is expanded | |
914 | and used as the secondary prompt string. The default is | |
915 | ``\fB> \fP''. | |
916 | .TP | |
917 | .B PS3 | |
918 | The value of this parameter is used as the prompt for the | |
919 | .I select | |
920 | command (see | |
921 | .SM | |
922 | .B SHELL GRAMMAR | |
923 | above). | |
924 | .TP | |
925 | .B PS4 | |
926 | The value of this parameter is expanded | |
927 | and the value is printed before each command | |
928 | .B bash | |
929 | displays during an execution trace. The first character of | |
930 | .SM | |
931 | .B PS4 | |
932 | is replicated multiple times, as necessary, to indicate multiple | |
933 | levels of indirection. The default is ``\fB+ \fP''. | |
934 | .TP | |
935 | .B HISTSIZE | |
936 | The number of commands to remember in the command history (see | |
937 | .SM | |
938 | .B HISTORY | |
939 | below). The default value is 500. | |
940 | .TP | |
941 | .B HISTFILE | |
942 | The name of the file in which command history is saved. (See | |
943 | .SM | |
944 | .B HISTORY | |
945 | below.) The default value is \fI~/.bash_history\fP. If unset, the | |
946 | command history is not saved when an interactive shell exits. | |
947 | .TP | |
948 | .B HISTFILESIZE | |
949 | The maximum number of lines contained in the history file. When this | |
950 | variable is assigned a value, the history file is truncated, if | |
951 | necessary, to contain no more than that number of lines. The default | |
952 | value is 500. | |
953 | .TP | |
954 | .B OPTERR | |
955 | If set to the value 1, | |
956 | .B bash | |
957 | displays error messages generated by the | |
958 | .B getopts | |
959 | builtin command (see | |
960 | .SM | |
961 | .B SHELL BUILTIN COMMANDS | |
962 | below). | |
963 | .SM | |
964 | .B OPTERR | |
965 | is initialized to 1 each time the shell is invoked or a shell | |
966 | script is executed. | |
967 | .TP | |
968 | .B PROMPT_COMMAND | |
969 | If set, the value is executed as a command prior to issuing each primary | |
970 | prompt. | |
971 | .TP | |
972 | .B IGNOREEOF | |
973 | Controls the | |
974 | action of the shell on receipt of an | |
975 | .SM | |
976 | .B EOF | |
977 | character as the sole input. If set, the value is the number of | |
978 | consecutive | |
979 | .SM | |
980 | .B EOF | |
981 | characters typed as the first characters on an input line before | |
982 | .B bash | |
983 | exits. If the variable exists but does not have a numeric value, or | |
984 | has no value, the default value is 10. If it does not exist, | |
985 | .SM | |
986 | .B EOF | |
987 | signifies the end of input to the shell. This is only in effect for | |
988 | interactive shells. | |
989 | .TP | |
990 | .B TMOUT | |
991 | If set to a value greater than zero, the value is interpreted as the | |
992 | number of seconds to wait for input after issuing the primary prompt. | |
993 | .B Bash | |
994 | terminates after waiting for that number of seconds if input does | |
995 | not arrive. | |
996 | .TP | |
997 | .B FCEDIT | |
998 | The default editor for the | |
999 | .B fc | |
1000 | builtin command. | |
1001 | .TP | |
1002 | .B FIGNORE | |
1003 | A colon-separated list of suffixes to ignore when performing | |
1004 | filename completion (see | |
1005 | .SM | |
1006 | .B READLINE | |
1007 | below). A filename whose suffix matches one of the entries in | |
1008 | .SM | |
1009 | .B FIGNORE | |
1010 | is excluded from the list of matched filenames. A sample | |
1011 | value is ``.o:~''. | |
1012 | .TP | |
1013 | .B INPUTRC | |
1014 | The filename for the readline startup file, overriding the default | |
1015 | of | |
1016 | .FN ~/.inputrc | |
1017 | (see | |
1018 | .SM | |
1019 | .B READLINE | |
1020 | below). | |
1021 | .TP | |
1022 | .B notify | |
1023 | If set, | |
1024 | .B bash | |
1025 | reports terminated background jobs immediately, rather than waiting | |
1026 | until before printing the next primary prompt (see also the | |
1027 | .B \-b | |
1028 | option to the | |
1029 | .B set | |
1030 | builtin command). | |
1031 | .PD 0 | |
1032 | .TP | |
1033 | .B history_control | |
1034 | .TP | |
1035 | .B HISTCONTROL | |
1036 | .PD | |
1037 | If set to a value of | |
1038 | .IR ignorespace , | |
1039 | lines which begin with a | |
1040 | .B space | |
1041 | character are not entered on the history list. If set to | |
1042 | a value of | |
1043 | .IR ignoredups , | |
1044 | lines matching the last history line are not entered. | |
1045 | A value of | |
1046 | .I ignoreboth | |
1047 | combines the two options. | |
1048 | If unset, or if set to any other value than those above, | |
1049 | all lines read | |
1050 | by the parser are saved on the history list. | |
1051 | .TP | |
1052 | .B command_oriented_history | |
1053 | If set, | |
1054 | .B bash | |
1055 | attempts to save all lines of a multiple\-line | |
1056 | command in the same history entry. This allows | |
1057 | easy re\-editing of multi\-line commands. | |
1058 | .TP | |
1059 | .B glob_dot_filenames | |
1060 | If set, | |
1061 | .B bash | |
1062 | includes filenames beginning with a `.' in the results of pathname | |
1063 | expansion. | |
1064 | .TP | |
1065 | .B allow_null_glob_expansion | |
1066 | If set, | |
1067 | .B bash | |
1068 | allows pathname patterns which match no | |
1069 | files (see | |
1070 | .B Pathname Expansion | |
1071 | below) | |
1072 | to expand to a null string, rather than themselves. | |
1073 | .TP | |
1074 | .B histchars | |
1075 | The two or three characters which control history expansion | |
1076 | and tokenization (see | |
1077 | .SM | |
1078 | .B HISTORY EXPANSION | |
1079 | below). The first character is the | |
1080 | .IR "history expansion character" , | |
1081 | that is, the character which signals the start of a history | |
1082 | expansion, normally `\fB!\fP'. | |
1083 | The second character is the | |
1084 | .IR "quick substitution" | |
1085 | character, which is used as shorthand for re-running the previous | |
1086 | command entered, substituting one string for another in the command. | |
1087 | The default is `\fB^\fP'. | |
1088 | The optional third character is the character | |
1089 | which signifies that the remainder of the line is a comment, when found | |
1090 | as the first character of a word, normally `\fB#\fP'. The history | |
1091 | comment character causes history substitution to be skipped for the | |
1092 | remaining words on the line. It does not necessarily cause the shell | |
1093 | parser to treat the rest of the line as a comment. | |
1094 | .TP | |
1095 | .B nolinks | |
1096 | If set, the shell does not follow symbolic links when executing | |
1097 | commands that change the current working directory. It uses the | |
1098 | physical directory structure instead. By default, | |
1099 | .B bash | |
1100 | follows the logical chain of directories when performing commands | |
1101 | which change the current directory, such as | |
1102 | .BR cd . | |
1103 | See also the description of the \fB\-P\fP option to the \fBset\fP | |
1104 | builtin ( | |
1105 | .SM | |
1106 | .B SHELL BUILTIN COMMANDS | |
1107 | below). | |
1108 | .PD 0 | |
1109 | .TP | |
1110 | .B hostname_completion_file | |
1111 | .TP | |
1112 | .B HOSTFILE | |
1113 | .PD | |
1114 | Contains the name of a file in the same format as | |
1115 | .FN /etc/hosts | |
1116 | that should be read when the shell needs to complete a | |
1117 | hostname. The file may be changed interactively; the next | |
1118 | time hostname completion is attempted | |
1119 | .B bash | |
1120 | adds the contents of the new file to the already existing database. | |
1121 | .TP | |
1122 | .B noclobber | |
1123 | If set, | |
1124 | .B bash | |
1125 | does not overwrite an existing file with the | |
1126 | .BR > , | |
1127 | .BR >& , | |
1128 | and | |
1129 | .B <> | |
1130 | redirection operators. This variable may be overridden when | |
1131 | creating output files by using the redirection operator | |
1132 | .B >| | |
1133 | instead of | |
1134 | .B > | |
1135 | (see also the \fB\-C\fP option to the | |
1136 | .B set | |
1137 | builtin command). | |
1138 | .TP | |
1139 | .B auto_resume | |
1140 | This variable controls how the shell interacts with the user and | |
1141 | job control. If this variable is set, single word simple | |
1142 | commands without redirections are treated as candidates for resumption | |
1143 | of an existing stopped job. There is no ambiguity allowed; if there is | |
1144 | more than one job beginning with the string typed, the job most recently | |
1145 | accessed is selected. The | |
1146 | .I name | |
1147 | of a stopped job, in this context, is the command line used to | |
1148 | start it. | |
1149 | If set to the value | |
1150 | .IR exact , | |
1151 | the string supplied must match the name of a stopped job exactly; | |
1152 | if set to | |
1153 | .IR substring , | |
1154 | the string supplied needs to match a substring of the name of a | |
1155 | stopped job. The | |
1156 | .I substring | |
1157 | value provides functionality analogous to the | |
1158 | .B %? | |
1159 | job id (see | |
1160 | .SM | |
1161 | .B JOB CONTROL | |
1162 | below). If set to any other value, the supplied string must | |
1163 | be a prefix of a stopped job's name; this provides functionality | |
1164 | analogous to the | |
1165 | .B % | |
1166 | job id. | |
1167 | .TP | |
1168 | .B no_exit_on_failed_exec | |
1169 | If this variable exists, a non-interactive shell will not exit if | |
1170 | it cannot execute the file specified in the | |
1171 | .B exec | |
1172 | builtin command. An interactive shell does not exit if | |
1173 | .B exec | |
1174 | fails. | |
1175 | .TP | |
1176 | .B cdable_vars | |
1177 | If this is set, an argument to the | |
1178 | .B cd | |
1179 | builtin command that | |
1180 | is not a directory is assumed to be the name of a variable whose | |
1181 | value is the directory to change to. | |
1182 | .PD | |
1183 | .SH EXPANSION | |
1184 | Expansion is performed on the command line after it has been split into | |
1185 | words. There are seven kinds of expansion performed: | |
1186 | .IR "brace expansion" , | |
1187 | .IR "tilde expansion" , | |
1188 | .IR "parameter and variable expansion" , | |
1189 | .IR "command substitution" , | |
1190 | .IR "arithmetic expansion" , | |
1191 | .IR "word splitting" , | |
1192 | and | |
1193 | .IR "pathname expansion" . | |
1194 | .PP | |
1195 | The order of expansions is: brace expansion, tilde expansion, | |
1196 | parameter, variable, command, and arithmetic substitution (done | |
1197 | in a left\-to\-right fashion), word splitting, and pathname | |
1198 | expansion. | |
1199 | .PP | |
1200 | On systems that can support it, there is an additional expansion | |
1201 | available: \fIprocess substitution\fP. | |
1202 | .PP | |
1203 | Only brace expansion, word splitting, and pathname expansion | |
1204 | can change the number of words of the expansion; other expansions | |
1205 | expand a single word to a single word. | |
1206 | The single exception to this is the expansion of | |
1207 | ``\fB$@\fP'' as explained above (see | |
1208 | .SM | |
1209 | .BR PARAMETERS ). | |
1210 | .SS Brace Expansion | |
1211 | .PP | |
1212 | .I "Brace expansion" | |
1213 | is a mechanism by which arbitrary strings | |
1214 | may be generated. This mechanism is similar to | |
1215 | \fIpathname expansion\fP, but the filenames generated | |
1216 | need not exist. Patterns to be brace expanded take | |
1217 | the form of an optional | |
1218 | .IR preamble , | |
1219 | followed by a series of comma-separated strings | |
1220 | between a pair of braces, followed by an optional | |
1221 | .IR postamble . | |
1222 | The preamble is prepended to each string contained | |
1223 | within the braces, and the postamble is then appended | |
1224 | to each resulting string, expanding left to right. | |
1225 | .PP | |
1226 | Brace expansions may be nested. The results of each expanded | |
1227 | string are not sorted; left to right order is preserved. | |
1228 | For example, a\fB{\fPd,c,b\fB}\fPe expands into `ade ace abe'. | |
1229 | .PP | |
1230 | Brace expansion is performed before any other expansions, | |
1231 | and any characters special to other expansions are preserved | |
1232 | in the result. It is strictly textual. | |
1233 | .B Bash | |
1234 | does not apply any syntactic interpretation to the context of the | |
1235 | expansion or the text between the braces. | |
1236 | .PP | |
1237 | A correctly-formed brace expansion must contain unquoted opening | |
1238 | and closing braces, and at least one unquoted comma. | |
1239 | Any incorrectly formed brace expansion is left unchanged. | |
1240 | .PP | |
1241 | This construct is typically used as shorthand when the common | |
1242 | prefix of the strings to be generated is longer than in the | |
1243 | above example: | |
1244 | .RS | |
1245 | .PP | |
1246 | mkdir /usr/local/src/bash/{old,new,dist,bugs} | |
1247 | .RE | |
1248 | or | |
1249 | .RS | |
1250 | chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}} | |
1251 | .RE | |
1252 | .PP | |
1253 | Brace expansion introduces a slight incompatibility with | |
1254 | traditional versions of | |
1255 | .BR sh , | |
1256 | the Bourne shell. | |
1257 | .B sh | |
1258 | does not treat opening or closing braces specially when they | |
1259 | appear as part of a word, and preserves them in the output. | |
1260 | .B Bash | |
1261 | removes braces from words as a consequence of brace | |
1262 | expansion. For example, a word entered to | |
1263 | .B sh | |
1264 | as \fIfile{1,2}\fP | |
1265 | appears identically in the output. The same word is | |
1266 | output as | |
1267 | .I file1 file2 | |
1268 | after expansion by | |
1269 | .BR bash . | |
1270 | If strict compatibility with | |
1271 | .B sh | |
1272 | is desired, start | |
1273 | .B bash | |
1274 | with the | |
1275 | .B \-nobraceexpansion | |
1276 | flag (see | |
1277 | .SM | |
1278 | .B OPTIONS | |
1279 | above) | |
1280 | or disable brace expansion with the | |
1281 | .B +o braceexpand | |
1282 | option to the | |
1283 | .B set | |
1284 | command (see | |
1285 | .SM | |
1286 | .B SHELL BUILTIN COMMANDS | |
1287 | below). | |
1288 | .SS Tilde Expansion | |
1289 | .PP | |
1290 | If a word begins with a tilde character (`\fB~\fP'), all of the characters | |
1291 | preceding the first slash (or all characters, if there is no slash) | |
1292 | are treated as a possible \fIlogin name\fP. If this \fIlogin name\fP | |
1293 | is the null string, the tilde is replaced with the value of the | |
1294 | parameter | |
1295 | .SM | |
1296 | .BR HOME . | |
1297 | If | |
1298 | .SM | |
1299 | .B HOME | |
1300 | is unset, the home directory of | |
1301 | the user executing the shell is substituted instead. | |
1302 | .PP | |
1303 | If a `+' follows the tilde, the value of | |
1304 | .SM | |
1305 | .B PWD | |
1306 | replaces the tilde and `+'. If | |
1307 | a `\-' follows, the value of | |
1308 | .SM | |
1309 | .B OLDPWD | |
1310 | is substituted. | |
1311 | If the value following the tilde is a valid \fIlogin name\fP, | |
1312 | the tilde and \fIlogin name\fP are replaced with the home directory | |
1313 | associated with that name. If the name is invalid, or the tilde | |
1314 | expansion fails, the word is unchanged. | |
1315 | .PP | |
1316 | Each variable assignment is checked for unquoted | |
1317 | instances of tildes following a | |
1318 | .B : | |
1319 | or | |
1320 | .BR = . | |
1321 | In these cases, tilde substitution is also performed. Consequently, one | |
1322 | may use pathnames with tildes in assignments to | |
1323 | .SM | |
1324 | .BR PATH , | |
1325 | .SM | |
1326 | .BR MAILPATH , | |
1327 | and | |
1328 | .SM | |
1329 | .BR CDPATH , | |
1330 | and the shell assigns the expanded value. | |
1331 | .SS Parameter Expansion | |
1332 | .PP | |
1333 | The `\fB$\fP' character introduces parameter expansion, | |
1334 | command substitution, or arithmetic expansion. The parameter name | |
1335 | or symbol to be expanded may be enclosed in braces, which | |
1336 | are optional but serve to protect the variable to be expanded from | |
1337 | characters immediately following it which could be | |
1338 | interpreted as part of the name. | |
1339 | .PP | |
1340 | .PD 0 | |
1341 | .TP | |
1342 | ${\fIparameter\fP} | |
1343 | The value of \fIparameter\fP is substituted. The braces are required | |
1344 | when | |
1345 | .I parameter | |
1346 | is a positional parameter with more than one digit, | |
1347 | or when | |
1348 | .I parameter | |
1349 | is followed by a character which is not to be | |
1350 | interpreted as part of its name. | |
1351 | .PD | |
1352 | .PP | |
1353 | In each of the cases below, \fIword\fP is subject to tilde expansion, | |
1354 | parameter expansion, command substitution, and arithmetic expansion. | |
1355 | \fBBash\fP tests for a parameter that is unset or null; omitting the | |
1356 | colon results in a test only for a parameter that is unset. | |
1357 | .PP | |
1358 | .PD 0 | |
1359 | .TP | |
1360 | ${\fIparameter\fP\fB:\-\fP\fIword\fP} | |
1361 | \fBUse Default Values\fP. If | |
1362 | .I parameter | |
1363 | is unset or null, the expansion of | |
1364 | .I word | |
1365 | is substituted. Otherwise, the value of | |
1366 | .I parameter | |
1367 | is substituted. | |
1368 | .TP | |
1369 | ${\fIparameter\fP\fB:=\fP\fIword\fP} | |
1370 | \fBAssign Default Values\fP. | |
1371 | If | |
1372 | .I parameter | |
1373 | is unset or null, the expansion of | |
1374 | .I word | |
1375 | is assigned to | |
1376 | .IR parameter . | |
1377 | The value of | |
1378 | .I parameter | |
1379 | is then substituted. Positional parameters and special parameters may | |
1380 | not be assigned to in this way. | |
1381 | .TP | |
1382 | ${\fIparameter\fP\fB:?\fP\fIword\fP} | |
1383 | \fBDisplay Error if Null or Unset\fP. | |
1384 | If | |
1385 | .I parameter | |
1386 | is null or unset, the expansion of \fIword\fP (or a message to that effect | |
1387 | if | |
1388 | .I word | |
1389 | is not present) is written to the standard error and the shell, if it | |
1390 | is not interactive, exits. Otherwise, the value of \fIparameter\fP is | |
1391 | substituted. | |
1392 | .TP | |
1393 | ${\fIparameter\fP\fB:+\fP\fIword\fP} | |
1394 | \fBUse Alternate Value\fP. | |
1395 | If | |
1396 | .I parameter | |
1397 | is null or unset, nothing is substituted, otherwise the expansion of | |
1398 | .I word | |
1399 | is substituted. | |
1400 | .TP | |
1401 | ${\fB#\fP\fIparameter\fP} | |
1402 | The length in characters of the value of \fIparameter\fP is substituted. | |
1403 | If \fIparameter\fP is | |
1404 | .B * | |
1405 | or | |
1406 | .BR @ , | |
1407 | the length substituted is the length of | |
1408 | .B * | |
1409 | expanded within double quotes. | |
1410 | .TP | |
1411 | .PD 0 | |
1412 | ${\fIparameter\fP\fB#\fP\fIword\fP} | |
1413 | .TP | |
1414 | ${\fIparameter\fP\fB##\fP\fIword\fP} | |
1415 | .PD | |
1416 | The | |
1417 | .I word | |
1418 | is expanded to produce a pattern just as in pathname | |
1419 | expansion. If the pattern matches the beginning of | |
1420 | the value of | |
1421 | .IR parameter , | |
1422 | then the expansion is the value of | |
1423 | .I parameter | |
1424 | with the shortest matching pattern deleted (the ``\fB#\fP'' | |
1425 | case) or the longest | |
1426 | matching pattern deleted (the ``\fB##\fP'' case). | |
1427 | .TP | |
1428 | .PD 0 | |
1429 | ${\fIparameter\fP\fB%\fP\fIword\fP} | |
1430 | .TP | |
1431 | ${\fIparameter\fP\fB%%\fP\fIword\fP} | |
1432 | .PD | |
1433 | The \fIword\fP is expanded to produce a pattern just as in | |
1434 | pathname expansion. If the pattern matches a | |
1435 | trailing portion of the value of | |
1436 | .IR parameter , | |
1437 | then the expansion is the value of | |
1438 | .I parameter | |
1439 | with the shortest matching pattern deleted | |
1440 | (the ``\fB%\fP'' case) or the longest | |
1441 | matching pattern deleted (the ``\fB%%\fP'' case). | |
1442 | .SS Command Substitution | |
1443 | .PP | |
1444 | \fICommand substitution\fP allows the output of a command to replace | |
1445 | the command name. There are two forms: | |
1446 | .PP | |
1447 | .RS | |
1448 | .PP | |
1449 | \fB$(\fP\fIcommand\fP\|\fB)\fP | |
1450 | .RE | |
1451 | or | |
1452 | .RS | |
1453 | \fB`\fP\fIcommand\fP\fB`\fP | |
1454 | .RE | |
1455 | .PP | |
1456 | . B Bash | |
1457 | performs the expansion by executing \fIcommand\fP and | |
1458 | replacing the command substitution with the standard output of the | |
1459 | command, with any trailing newlines deleted. | |
1460 | .PP | |
1461 | When the old\-style backquote form of substitution is used, | |
1462 | backslash retains its literal meaning except when followed by | |
1463 | .BR $ , | |
1464 | .BR ` , | |
1465 | or | |
1466 | .BR \e . | |
1467 | When using the $(\^\fIcommand\fP\|) form, all characters between the | |
1468 | parentheses make up the command; none are treated specially. | |
1469 | .PP | |
1470 | Command substitutions may be nested. To nest when using the old form, | |
1471 | escape the inner backquotes with backslashes. | |
1472 | .PP | |
1473 | If the substitution appears within double quotes, word splitting and | |
1474 | pathname expansion are not performed on the results. | |
1475 | .SS Arithmetic Expansion | |
1476 | .PP | |
1477 | Arithmetic expansion allows the evaluation of an arithmetic expression | |
1478 | and the substitution of the result. There are two formats for | |
1479 | arithmetic expansion: | |
1480 | .RS | |
1481 | .PP | |
1482 | \fB$[\fP\fIexpression\fP\fB]\fP | |
1483 | .PP | |
1484 | \fB$((\fP\fIexpression\fP\fB))\fP | |
1485 | .RE | |
1486 | .PP | |
1487 | The | |
1488 | .I expression | |
1489 | is treated as if it were within double quotes, but a double quote | |
1490 | inside the braces or parentheses | |
1491 | is not treated specially. All tokens in the | |
1492 | expression undergo parameter expansion, command substitution, | |
1493 | and quote removal. Arithmetic substitutions may be nested. | |
1494 | .PP | |
1495 | The evaluation is performed according to the rules listed below under | |
1496 | .SM | |
1497 | .BR "ARITHMETIC EVALUATION" . | |
1498 | If | |
1499 | .I expression | |
1500 | is invalid, | |
1501 | .B bash | |
1502 | prints a message indicating failure and no substitution occurs. | |
1503 | .SS Process Substitution | |
1504 | .PP | |
1505 | \fIProcess substitution\fP is supported on systems that support named | |
1506 | pipes (\fIFIFOs\fP) or the \fB/dev/fd\fP method of naming open files. | |
1507 | It takes the form of | |
1508 | \fB<(\fP\fIlist\^\fP\fB)\fP | |
1509 | or | |
1510 | \fB>(\fP\fIlist\^\fP\fB)\fP. | |
1511 | The process \fIlist\fP is run with its input or output connected to a | |
1512 | \fIFIFO\fP or some file in \fB/dev/fd\fP. The name of this file is | |
1513 | passed as an argument to the current command as the result of the | |
1514 | expansion. If the \fB>(\fP\fIlist\^\fP\fB)\fP form is used, writing to | |
1515 | the file will provide input for \fIlist\fP. If the | |
1516 | \fB<(\fP\fIlist\^\fP\fB)\fP form is used, the file passed as an | |
1517 | argument should be read to obtain the output of \fIlist\fP. | |
1518 | .PP | |
1519 | On systems that support it, \fIprocess substitution\fP is performed | |
1520 | simultaneously with | |
1521 | .IR "parameter and variable expansion" , | |
1522 | .IR "command substitution" , | |
1523 | and | |
1524 | .IR "arithmetic expansion" . | |
1525 | .SS Word Splitting | |
1526 | .PP | |
1527 | The shell scans the results of | |
1528 | parameter expansion, | |
1529 | command substitution, | |
1530 | and | |
1531 | arithmetic expansion | |
1532 | that did not occur within double quotes for | |
1533 | .IR "word splitting" . | |
1534 | .PP | |
1535 | The shell treats each character of | |
1536 | .SM | |
1537 | .B IFS | |
1538 | as a delimiter, and splits the results of the other | |
1539 | expansions into words on these characters. If the | |
1540 | value of | |
1541 | .SM | |
1542 | .B IFS | |
1543 | is exactly | |
1544 | .BR <space><tab><newline> , | |
1545 | the default, then | |
1546 | any sequence of | |
1547 | .SM | |
1548 | .B IFS | |
1549 | characters serves to delimit words. If | |
1550 | .SM | |
1551 | .B IFS | |
1552 | has a value other than the default, then sequences of | |
1553 | the whitespace characters | |
1554 | .B space | |
1555 | and | |
1556 | .B tab | |
1557 | are ignored at the beginning and end of the | |
1558 | word, as long as the whitespace character is in the | |
1559 | value of | |
1560 | .SM | |
1561 | .BR IFS | |
1562 | (an | |
1563 | .SM | |
1564 | .B IFS | |
1565 | whitespace character). | |
1566 | Any character in | |
1567 | .SM | |
1568 | .B IFS | |
1569 | that is not | |
1570 | .SM | |
1571 | .B IFS | |
1572 | whitespace, along with any adjacent | |
1573 | .SM | |
1574 | .B IFS | |
1575 | whitespace characters, delimits a field. | |
1576 | A sequence of | |
1577 | .SM | |
1578 | .B IFS | |
1579 | whitespace characters is also treated as a delimiter. | |
1580 | If the value of | |
1581 | .SM | |
1582 | .B IFS | |
1583 | is null, no word splitting occurs. | |
1584 | .SM | |
1585 | .B IFS | |
1586 | cannot be unset. | |
1587 | .PP | |
1588 | Explicit null arguments (\^\f3"\^"\fP or \^\f3'\^'\fP\^) | |
1589 | are retained. Implicit null arguments, resulting from the expansion | |
1590 | of | |
1591 | .I parameters | |
1592 | that have no values, are removed. | |
1593 | .PP | |
1594 | Note that if no expansion occurs, no splitting | |
1595 | is performed. | |
1596 | .SS Pathname Expansion | |
1597 | .PP | |
1598 | After word splitting, | |
1599 | unless the | |
1600 | .B \-f | |
1601 | option has been set, | |
1602 | .B bash | |
1603 | scans each | |
1604 | .I word | |
1605 | for the characters | |
1606 | .BR * , | |
1607 | .BR ? , | |
1608 | and | |
1609 | .BR [ . | |
1610 | If one of these characters appears, then the word is | |
1611 | regarded as a | |
1612 | .IR pattern , | |
1613 | and replaced with an alphabetically sorted list of | |
1614 | pathnames matching the pattern. | |
1615 | If no matching pathnames are found, | |
1616 | and the shell variable | |
1617 | .B allow_null_glob_expansion | |
1618 | is unset, the word is left unchanged. | |
1619 | If the variable is set, and no matches are found, | |
1620 | the word is removed. | |
1621 | When a pattern is used for pathname generation, | |
1622 | the character | |
1623 | .B ``.'' | |
1624 | at the start of a name or immediately following a slash | |
1625 | must be matched explicitly, unless the shell variable | |
1626 | .B glob_dot_filenames | |
1627 | is set. The slash character must always be matched | |
1628 | explicitly. In other cases, the | |
1629 | .B ``.'' | |
1630 | character is not treated specially. | |
1631 | .PP | |
1632 | The special pattern characters have the following meanings: | |
1633 | .PP | |
1634 | .PD 0 | |
1635 | .TP | |
1636 | .B * | |
1637 | Matches any string, including the null string. | |
1638 | .TP | |
1639 | .B ? | |
1640 | Matches any single character. | |
1641 | .TP | |
1642 | .B [...] | |
1643 | Matches any one of the enclosed characters. A pair of characters | |
1644 | separated by a minus sign denotes a | |
1645 | .IR range ; | |
1646 | any character lexically between those two characters, inclusive, | |
1647 | is matched. If the first character following the | |
1648 | .B [ | |
1649 | is a | |
1650 | .B ! | |
1651 | or a | |
1652 | .B ^ | |
1653 | then any character not enclosed is matched. A | |
1654 | .B \- | |
1655 | or | |
1656 | .B ] | |
1657 | may be matched by including it as the first or last character | |
1658 | in the set. | |
1659 | .PD | |
1660 | .SS Quote Removal | |
1661 | .PP | |
1662 | After the preceding expansions, all unquoted occurrences of the | |
1663 | characters | |
1664 | .BR \e , | |
1665 | .BR ` , | |
1666 | and \^\f3"\fP\^ are removed. | |
1667 | .SH REDIRECTION | |
1668 | Before a command is executed, its input and output | |
1669 | may be | |
1670 | .I redirected | |
1671 | using a special notation interpreted by the shell. | |
1672 | Redirection may also be used to open and close files for the | |
1673 | current shell execution environment. The following redirection | |
1674 | operators may precede or appear anywhere within a | |
1675 | .I simple command | |
1676 | or may follow a | |
1677 | .IR command . | |
1678 | Redirections are processed in the order they appear, from | |
1679 | left to right. | |
1680 | .PP | |
1681 | In the following descriptions, if the file descriptor number is | |
1682 | omitted, and the first character of the redirection operator is | |
1683 | .BR < , | |
1684 | the redirection refers to the standard input (file descriptor | |
1685 | 0). If the first character of the redirection operator is | |
1686 | .BR > , | |
1687 | the redirection refers to the standard output (file descriptor | |
1688 | 1). | |
1689 | .PP | |
1690 | The word that follows the redirection operator in the following | |
1691 | descriptions is subjected to brace expansion, tilde expansion, | |
1692 | parameter expansion, command substitution, arithmetic expansion, | |
1693 | quote removal, and pathname expansion. If it expands to more | |
1694 | than one word, | |
1695 | .B bash | |
1696 | reports an error. | |
1697 | .PP | |
1698 | Note that the order of redirections is significant. For example, | |
1699 | the command | |
1700 | .RS | |
1701 | .PP | |
1702 | ls \fB>\fP dirlist 2\fB>&\fP1 | |
1703 | .RE | |
1704 | .PP | |
1705 | directs both standard output and standard error to the file | |
1706 | .IR dirlist , | |
1707 | while the command | |
1708 | .RS | |
1709 | .PP | |
1710 | ls 2\fB>&\fP1 \fB>\fP dirlist | |
1711 | .RE | |
1712 | .PP | |
1713 | directs only the standard output to file | |
1714 | .IR dirlist , | |
1715 | because the standard error was duplicated as standard output | |
1716 | before the standard output was redirected to | |
1717 | .IR dirlist . | |
1718 | .SS Redirecting Input | |
1719 | .PP | |
1720 | Redirection of input causes the file whose name results from | |
1721 | the expansion of | |
1722 | .I word | |
1723 | to be opened for reading on file descriptor | |
1724 | .IR n , | |
1725 | or the standard input (file descriptor 0) if | |
1726 | .I n | |
1727 | is not specified. | |
1728 | .PP | |
1729 | The general format for redirecting input is: | |
1730 | .RS | |
1731 | .PP | |
1732 | [\fIn\fP]\fB<\fP\fIword\fP | |
1733 | .RE | |
1734 | .SS Redirecting Output | |
1735 | .PP | |
1736 | Redirection of output causes the file whose name results from | |
1737 | the expansion of | |
1738 | .I word | |
1739 | to be opened for writing on file descriptor | |
1740 | .IR n , | |
1741 | or the standard output (file descriptor 1) if | |
1742 | .I n | |
1743 | is not specified. If the file does not exist it is created; | |
1744 | if it does exist it is truncated to zero size. | |
1745 | .PP | |
1746 | The general format for redirecting output is: | |
1747 | .RS | |
1748 | .PP | |
1749 | [\fIn\fP]\fB>\fP\fIword\fP | |
1750 | .RE | |
1751 | .PP | |
1752 | If the redirection operator is | |
1753 | .BR >| , | |
1754 | then the value of the | |
1755 | .B -C | |
1756 | option to the | |
1757 | .B set | |
1758 | builtin command is not tested, and file creation is attempted. | |
1759 | (See also the description of | |
1760 | .B noclobber | |
1761 | under | |
1762 | .B "Shell Variables" | |
1763 | above.) | |
1764 | .SS Appending Redirected Output | |
1765 | .PP | |
1766 | Redirection of output in this fashion | |
1767 | causes the file whose name results from | |
1768 | the expansion of | |
1769 | .I word | |
1770 | to be opened for appending on file descriptor | |
1771 | .IR n , | |
1772 | or the standard output (file descriptor 1) if | |
1773 | .I n | |
1774 | is not specified. If the file does not exist it is created. | |
1775 | .PP | |
1776 | The general format for appending output is: | |
1777 | .RS | |
1778 | .PP | |
1779 | [\fIn\fP]\fB>>\fP\fIword\fP | |
1780 | .RE | |
1781 | .PP | |
1782 | .SS Redirecting Standard Output and Standard Error | |
1783 | .PP | |
1784 | .B Bash | |
1785 | allows both the | |
1786 | standard output (file descriptor 1) and | |
1787 | the standard error output (file descriptor 2) | |
1788 | to be redirected to the file whose name is the | |
1789 | expansion of | |
1790 | .I word | |
1791 | with this construct. | |
1792 | .PP | |
1793 | There are two formats for redirecting standard output and | |
1794 | standard error: | |
1795 | .RS | |
1796 | .PP | |
1797 | \fB&>\fP\fIword\fP | |
1798 | .RE | |
1799 | and | |
1800 | .RS | |
1801 | \fB>&\fP\fIword\fP | |
1802 | .RE | |
1803 | .PP | |
1804 | Of the two forms, the first is preferred. | |
1805 | This is semantically equivalent to | |
1806 | .RS | |
1807 | .PP | |
1808 | \fB>\fP\fIword\fP 2\fB>&\fP1 | |
1809 | .RE | |
1810 | .SS Here Documents | |
1811 | .PP | |
1812 | This type of redirection instructs the shell to read input from the | |
1813 | current source until a line containing only | |
1814 | .I word | |
1815 | (with no trailing blanks) | |
1816 | is seen. All of | |
1817 | the lines read up to that point are then used as the standard | |
1818 | input for a command. | |
1819 | .PP | |
1820 | The format of here-documents is as follows: | |
1821 | .RS | |
1822 | .PP | |
1823 | .nf | |
1824 | \fB<<\fP[\fB\-\fP]\fIword\fP | |
1825 | \fIhere-document\fP | |
1826 | \fIdelimiter\fP | |
1827 | .fi | |
1828 | .RE | |
1829 | .PP | |
1830 | No parameter expansion, command substitution, pathname | |
1831 | expansion, or arithmetic expansion is performed on | |
1832 | .IR word . | |
1833 | If any characters in | |
1834 | .I word | |
1835 | are quoted, the | |
1836 | .I delimiter | |
1837 | is the result of quote removal on | |
1838 | .IR word , | |
1839 | and the lines in the here-document are not expanded. Otherwise, | |
1840 | all lines of the here-document are subjected to parameter expansion, | |
1841 | command substitution, and arithmetic expansion. In the latter | |
1842 | case, the pair | |
1843 | .B \e<newline> | |
1844 | is ignored, and | |
1845 | .B \e | |
1846 | must be used to quote the characters | |
1847 | .BR \e , | |
1848 | .BR $ , | |
1849 | and | |
1850 | .BR ` . | |
1851 | .PP | |
1852 | If the redirection operator is | |
1853 | .BR <<\- , | |
1854 | then all leading tab characters are stripped from input lines and the | |
1855 | line containing | |
1856 | .IR delimiter . | |
1857 | This allows | |
1858 | here-documents within shell scripts to be indented in a | |
1859 | natural fashion. | |
1860 | .SS "Duplicating File Descriptors" | |
1861 | .PP | |
1862 | The redirection operator | |
1863 | .RS | |
1864 | .PP | |
1865 | [\fIn\fP]\fB<&\fP\fIword\fP | |
1866 | .RE | |
1867 | .PP | |
1868 | is used to duplicate input file descriptors. | |
1869 | If | |
1870 | .I word | |
1871 | expands to one or more digits, the file descriptor denoted by | |
1872 | .I n | |
1873 | is made to be a copy of that file descriptor. If | |
1874 | .I word | |
1875 | evaluates to | |
1876 | .BR \- , | |
1877 | file descriptor | |
1878 | .I n | |
1879 | is closed. If | |
1880 | .I n | |
1881 | is not specified, the standard input (file descriptor 0) is used. | |
1882 | .PP | |
1883 | The operator | |
1884 | .RS | |
1885 | .PP | |
1886 | [\fIn\fP]\fB>&\fP\fIword\fP | |
1887 | .RE | |
1888 | .PP | |
1889 | is used similarly to duplicate output file descriptors. If | |
1890 | .I n | |
1891 | is not specified, the standard output (file descriptor 1) is used. | |
1892 | As a special case, if \fIn\fP is omitted, and \fIword\fP does not | |
1893 | expand to one or more digits, the standard output and standard | |
1894 | error are redirected as described previously. | |
1895 | .SS "Opening File Descriptors for Reading and Writing" | |
1896 | .PP | |
1897 | The redirection operator | |
1898 | .RS | |
1899 | .PP | |
1900 | [\fIn\fP]\fB<>\fP\fIword\fP | |
1901 | .RE | |
1902 | .PP | |
1903 | causes the file whose name is the expansion of | |
1904 | .I word | |
1905 | to be opened for both reading and writing on file descriptor | |
1906 | .IR n , | |
1907 | or as the standard input and standard output if | |
1908 | .I n | |
1909 | is not specified. If the file does not exist, it is created. | |
1910 | .SH FUNCTIONS | |
1911 | A shell function, defined as described above under | |
1912 | .SM | |
1913 | .BR "SHELL GRAMMAR" , | |
1914 | stores a series of commands for later execution. | |
1915 | Functions are executed in the context of the | |
1916 | current shell; no new process is created to interpret | |
1917 | them (contrast this with the execution of a shell script). | |
1918 | When a function is executed, the arguments to the | |
1919 | function become the positional parameters | |
1920 | during its execution. The special parameter | |
1921 | .B # | |
1922 | is updated to reflect the change. Positional parameter 0 | |
1923 | is unchanged. | |
1924 | .PP | |
1925 | Variables local to the function may be declared with the | |
1926 | .B local | |
1927 | builtin command. Ordinarily, variables and their values | |
1928 | are shared between the function and its caller. | |
1929 | .PP | |
1930 | If the builtin command | |
1931 | .B return | |
1932 | is executed in a function, the function completes and | |
1933 | execution resumes with the next command after the function | |
1934 | call. When a function completes, the values of the | |
1935 | positional parameters and the special parameter | |
1936 | .B # | |
1937 | are restored to the values they had prior to function | |
1938 | execution. | |
1939 | .PP | |
1940 | Function names and definitions may be listed with the | |
1941 | .B \-f | |
1942 | option to the | |
1943 | .B declare | |
1944 | or | |
1945 | .B typeset | |
1946 | builtin commands. Functions may be exported so that subshells | |
1947 | automatically have them defined with the | |
1948 | .B \-f | |
1949 | option to the | |
1950 | .B export | |
1951 | builtin. | |
1952 | .PP | |
1953 | Functions may be recursive. No limit is imposed on the number | |
1954 | of recursive calls. | |
1955 | .SH ALIASES | |
1956 | The shell maintains a list of | |
1957 | .I aliases | |
1958 | that may be set and unset with the | |
1959 | .B alias | |
1960 | and | |
1961 | .B unalias | |
1962 | builtin commands (see | |
1963 | .SM | |
1964 | .B SHELL BUILTIN COMMANDS | |
1965 | below). | |
1966 | The first word of each command, if unquoted, | |
1967 | is checked to see if it has an | |
1968 | alias. If so, that word is replaced by the text of the alias. | |
1969 | The alias name and the replacement text may contain any valid | |
1970 | shell input, including the | |
1971 | .I metacharacters | |
1972 | listed above, with the exception that the alias name may not | |
1973 | contain \fI=\fP. The first word of the replacement text is tested | |
1974 | for aliases, but a word that is identical to an alias being expanded | |
1975 | is not expanded a second time. This means that one may alias | |
1976 | .B ls | |
1977 | to | |
1978 | .BR "ls \-F" , | |
1979 | for instance, and | |
1980 | .B bash | |
1981 | does not try to recursively expand the replacement text. | |
1982 | If the last character of the alias value is a | |
1983 | .IR blank , | |
1984 | then the next command | |
1985 | word following the alias is also checked for alias expansion. | |
1986 | .PP | |
1987 | Aliases are created and listed with the | |
1988 | .B alias | |
1989 | command, and removed with the | |
1990 | .B unalias | |
1991 | command. | |
1992 | .PP | |
1993 | There is no mechanism for using arguments in the replacement text, | |
1994 | as in | |
1995 | .BR csh . | |
1996 | If arguments are needed, a shell function should be used. | |
1997 | .PP | |
1998 | Aliases are not expanded when the shell is not interactive. | |
1999 | .PP | |
2000 | The rules concerning the definition and use of aliases are | |
2001 | somewhat confusing. | |
2002 | .B Bash | |
2003 | always reads at least one complete line | |
2004 | of input before executing any | |
2005 | of the commands on that line. Aliases are expanded when a | |
2006 | command is read, not when it is executed. Therefore, an | |
2007 | alias definition appearing on the same line as another | |
2008 | command does not take effect until the next line of input is read. | |
2009 | This means that the commands following the alias definition | |
2010 | on that line are not affected by the new alias. | |
2011 | This behavior is also an issue when functions are executed. | |
2012 | Aliases are expanded when the function definition is read, | |
2013 | not when the function is executed, because a function definition | |
2014 | is itself a compound command. As a consequence, aliases | |
2015 | defined in a function are not available until after that | |
2016 | function is executed. To be safe, always put | |
2017 | alias definitions on a separate line, and do not use | |
2018 | .B alias | |
2019 | in compound commands. | |
2020 | .PP | |
2021 | Note that for almost every purpose, aliases are superseded by | |
2022 | shell functions. | |
2023 | .SH "JOB CONTROL" | |
2024 | .I Job control | |
2025 | refers to the ability to selectively stop (\fIsuspend\fP) | |
2026 | the execution of processes and continue (\fIresume\fP) | |
2027 | their execution at a later point. A user typically employs | |
2028 | this facility via an interactive interface supplied jointly | |
2029 | by the system's terminal driver and | |
2030 | .BR bash . | |
2031 | .PP | |
2032 | The shell associates a | |
2033 | .I job | |
2034 | with each pipeline. It keeps a table of currently executing | |
2035 | jobs, which may be listed with the | |
2036 | .B jobs | |
2037 | command. When | |
2038 | .B bash | |
2039 | starts a job asynchronously (in the | |
2040 | .IR background ), | |
2041 | it prints a line that looks like: | |
2042 | .RS | |
2043 | .PP | |
2044 | [1] 25647 | |
2045 | .RE | |
2046 | .PP | |
2047 | indicating that this job is job number 1 and that the process ID | |
2048 | of the last process in the pipeline associated with this job is 25647. | |
2049 | All of the processes in a single pipeline are members of the same job. | |
2050 | .B Bash | |
2051 | uses the | |
2052 | .I job | |
2053 | abstraction as the basis for job control. | |
2054 | .PP | |
2055 | To facilitate the implementation of the user interface to job | |
2056 | control, the system maintains the notion of a \fIcurrent terminal | |
2057 | process group ID\fP. Members of this process group (processes whose | |
2058 | process group ID is equal to the current terminal process group ID) | |
2059 | receive keyboard-generated signals such as | |
2060 | .SM | |
2061 | .BR SIGINT . | |
2062 | These processes are said to be in the | |
2063 | .IR foreground . | |
2064 | .I Background | |
2065 | processes are those whose process group ID differs from the terminal's; | |
2066 | such processes are immune to keyboard-generated signals. | |
2067 | Only foreground processes are allowed to read from or write to the | |
2068 | terminal. Background processes which attempt to read from (write to) the | |
2069 | terminal are sent a | |
2070 | .SM | |
2071 | .B SIGTTIN (SIGTTOU) | |
2072 | signal by the terminal driver, | |
2073 | which, unless caught, suspends the process. | |
2074 | .PP | |
2075 | If the operating system on which | |
2076 | .B bash | |
2077 | is running supports | |
2078 | job control, | |
2079 | .B bash | |
2080 | allows you to use it. | |
2081 | Typing the | |
2082 | .I suspend | |
2083 | character (typically | |
2084 | .BR ^Z , | |
2085 | Control-Z) while a process is running | |
2086 | causes that process to be stopped and returns you to | |
2087 | .BR bash . | |
2088 | Typing the | |
2089 | .I "delayed suspend" | |
2090 | character (typically | |
2091 | .BR ^Y , | |
2092 | Control-Y) causes the process to be stopped when it | |
2093 | attempts to read input from the terminal, and control to | |
2094 | be returned to | |
2095 | .BR bash . | |
2096 | You may then manipulate the state of this job, using the | |
2097 | .B bg | |
2098 | command to continue it in the background, the | |
2099 | .B fg | |
2100 | command to continue it in the foreground, or | |
2101 | the | |
2102 | .B kill | |
2103 | command to kill it. A \fB^Z\fP takes effect immediately, | |
2104 | and has the additional side effect of causing pending output | |
2105 | and typeahead to be discarded. | |
2106 | .PP | |
2107 | There are a number of ways to refer to a job in the shell. | |
2108 | The character | |
2109 | .B % | |
2110 | introduces a job name. Job number | |
2111 | .I n | |
2112 | may be referred to as | |
2113 | .BR %n . | |
2114 | A job may also be referred to using a prefix of the name used to | |
2115 | start it, or using a substring that appears in its command line. | |
2116 | For example, | |
2117 | .B %ce | |
2118 | refers to a stopped | |
2119 | .B ce | |
2120 | job. If a prefix matches more than one job, | |
2121 | .B bash | |
2122 | reports an error. Using | |
2123 | .BR %?ce , | |
2124 | on the other hand, refers to any job containing the string | |
2125 | .B ce | |
2126 | in its command line. If the substring matches more than one job, | |
2127 | .B bash | |
2128 | reports an error. The symbols | |
2129 | .B %% | |
2130 | and | |
2131 | .B %+ | |
2132 | refer to the shell's notion of the | |
2133 | .IR "current job" , | |
2134 | which is the last job stopped while it was in | |
2135 | the foreground. | |
2136 | The | |
2137 | .I "previous job" | |
2138 | may be referenced using | |
2139 | .BR %\- . | |
2140 | In output pertaining to jobs (e.g., the output of the | |
2141 | .B jobs | |
2142 | command), the current job is always flagged with a | |
2143 | .BR + , | |
2144 | and the previous job with a | |
2145 | .BR \- . | |
2146 | .PP | |
2147 | Simply naming a job can be used to bring it into the | |
2148 | foreground: | |
2149 | .B %1 | |
2150 | is a synonym for | |
2151 | \fB``fg %1''\fP, | |
2152 | bringing job 1 from the background into the foreground. | |
2153 | Similarly, | |
2154 | .B ``%1 &'' | |
2155 | resumes job 1 in the background, equivalent to | |
2156 | \fB``bg %1''\fP. | |
2157 | .PP | |
2158 | The shell learns immediately whenever a job changes state. | |
2159 | Normally, | |
2160 | .B bash | |
2161 | waits until it is about to print a prompt before reporting | |
2162 | changes in a job's status so as to not interrupt | |
2163 | any other output. If the | |
2164 | .B -b | |
2165 | option to the | |
2166 | .B set | |
2167 | builtin command | |
2168 | is set, | |
2169 | .B bash | |
2170 | reports such changes immediately. (See also the description of | |
2171 | .B notify | |
2172 | variable under | |
2173 | .B "Shell Variables" | |
2174 | above.) | |
2175 | .PP | |
2176 | If you attempt to exit | |
2177 | .B bash | |
2178 | while jobs are stopped, the shell prints a message warning you. You | |
2179 | may then use the | |
2180 | .B jobs | |
2181 | command to inspect their status. If you do this, or try to exit | |
2182 | again immediately, you are not warned again, and the stopped | |
2183 | jobs are terminated. | |
2184 | .SH SIGNALS | |
2185 | When \fBbash\fP is interactive, it ignores | |
2186 | .SM | |
2187 | .B SIGTERM | |
2188 | (so that \fBkill 0\fP does not kill an interactive shell), | |
2189 | and | |
2190 | .SM | |
2191 | .B SIGINT | |
2192 | is caught and handled (so that the \fBwait\fP builtin is interruptible). | |
2193 | In all cases, \fBbash\fP ignores | |
2194 | .SM | |
2195 | .BR SIGQUIT . | |
2196 | If job control is in effect, | |
2197 | .B bash | |
2198 | ignores | |
2199 | .SM | |
2200 | .BR SIGTTIN , | |
2201 | .SM | |
2202 | .BR SIGTTOU , | |
2203 | and | |
2204 | .SM | |
2205 | .BR SIGTSTP . | |
2206 | .PP | |
2207 | Synchronous jobs started by \fBbash\fP have signals set to the | |
2208 | values inherited by the shell from its parent. When job control | |
2209 | is not in effect, background jobs (jobs started with | |
2210 | .BR & ) | |
2211 | ignore | |
2212 | .SM | |
2213 | .B SIGINT | |
2214 | and | |
2215 | .SM | |
2216 | .BR SIGQUIT . | |
2217 | Commands run as a result of command substitution ignore the | |
2218 | keyboard-generated job control signals | |
2219 | .SM | |
2220 | .BR SIGTTIN , | |
2221 | .SM | |
2222 | .BR SIGTTOU , | |
2223 | and | |
2224 | .SM | |
2225 | .BR SIGTSTP . | |
2226 | .SH "COMMAND EXECUTION" | |
2227 | After a command has been split into words, if it results in a | |
2228 | simple command and an optional list of arguments, the following | |
2229 | actions are taken. | |
2230 | .PP | |
2231 | If the command name contains no slashes, the shell attempts to | |
2232 | locate it. If there exists a shell function by that name, that | |
2233 | function is invoked as described above in | |
2234 | .SM | |
2235 | .BR FUNCTIONS . | |
2236 | If the name does not match a function, the shell searches for | |
2237 | it in the list of shell builtins. If a match is found, that | |
2238 | builtin is invoked. | |
2239 | .PP | |
2240 | If the name is neither a shell function nor a builtin, | |
2241 | and contains no slashes, | |
2242 | .B bash | |
2243 | searches each element of the | |
2244 | .SM | |
2245 | .B PATH | |
2246 | for a directory containing an executable file by that name. | |
2247 | If the search is unsuccessful, the shell prints an error | |
2248 | message and returns a nonzero exit status. | |
2249 | .PP | |
2250 | If the search is successful, or if the command name contains | |
2251 | one or more slashes, the shell executes the named program. | |
2252 | Argument 0 is set to the name given, and the remaining arguments | |
2253 | to the command are set to the arguments given, if any. | |
2254 | .PP | |
2255 | If this execution fails because the file is not in executable | |
2256 | format, and the file is not a directory, it is assumed to be | |
2257 | a \fIshell script\fP, a file | |
2258 | containing shell commands. A subshell is spawned to execute | |
2259 | it. This subshell reinitializes itself, so | |
2260 | that the effect is as if a new shell had been invoked | |
2261 | to handle the script, with the exception that the locations of | |
2262 | commands remembered by the parent (see | |
2263 | .B hash | |
2264 | below under | |
2265 | .SM | |
2266 | \fBSHELL BUILTIN COMMANDS\fP) | |
2267 | are retained by the child. | |
2268 | .PP | |
2269 | If the program is a file beginning with | |
2270 | .BR #! , | |
2271 | the remainder of the first line specifies an interpreter | |
2272 | for the program. The shell executes the | |
2273 | specified interpreter on operating systems that do not | |
2274 | handle this executable format themselves. The arguments to the | |
2275 | interpreter consist of a single optional argument following the | |
2276 | interpreter name on the first line of the program, followed | |
2277 | by the name of the program, followed by the command | |
2278 | arguments, if any. | |
2279 | .SH ENVIRONMENT | |
2280 | When a program is invoked it is given an array of strings | |
2281 | called the | |
2282 | .IR environment . | |
2283 | This is a list of | |
2284 | \fIname\fP\-\fIvalue\fP pairs, of the form | |
2285 | .IR "name\fR=\fPvalue" . | |
2286 | .PP | |
2287 | The shell allows you to manipulate the environment in several | |
2288 | ways. On invocation, the shell scans its own environment and | |
2289 | creates a parameter for each name found, automatically marking | |
2290 | it for | |
2291 | .I export | |
2292 | to child processes. Executed commands inherit the environment. | |
2293 | The | |
2294 | .B export | |
2295 | and | |
2296 | .B declare \-x | |
2297 | commands allow parameters and functions to be added to and | |
2298 | deleted from the environment. If the value of a parameter | |
2299 | in the environment is modified, the new value becomes part | |
2300 | of the environment, replacing the old. The environment | |
2301 | inherited by any executed command consists of the shell's | |
2302 | initial environment, whose values may be modified in the shell, | |
2303 | less any pairs removed by the | |
2304 | .B unset | |
2305 | command, plus any additions via the | |
2306 | .B export | |
2307 | and | |
2308 | .B declare \-x | |
2309 | commands. | |
2310 | .PP | |
2311 | The environment for any | |
2312 | .I simple command | |
2313 | or function may be augmented temporarily by prefixing it with | |
2314 | parameter assignments, as described above in | |
2315 | .SM | |
2316 | .BR PARAMETERS . | |
2317 | These assignment statements affect only the environment seen | |
2318 | by that command. | |
2319 | .PP | |
2320 | If the | |
2321 | .B \-k | |
2322 | flag is set (see the | |
2323 | .B set | |
2324 | builtin command below), then | |
2325 | .I all | |
2326 | parameter assignments are placed in the environment for a command, | |
2327 | not just those that precede the command name. | |
2328 | .PP | |
2329 | When | |
2330 | .B bash | |
2331 | invokes an external command, the variable | |
2332 | .B _ | |
2333 | is set to the full path name of the command and passed to that | |
2334 | command in its environment. | |
2335 | .SH "EXIT STATUS" | |
2336 | For the purposes of the shell, a command which exits with a | |
2337 | zero exit status has succeeded. An exit status of zero | |
2338 | indicates success. A non\-zero exit status indicates failure. | |
2339 | When a command terminates on a fatal signal, \fBbash\fP uses | |
2340 | the value of 128+\fBsignal\fP as the exit status. | |
2341 | .PP | |
2342 | If a command is not found, the child process created to | |
2343 | execute it returns a status of 127. If a command is found | |
2344 | but is not executable, the return status is 126. | |
2345 | .PP | |
2346 | \fBBash\fP itself returns the exit status of the last command | |
2347 | executed, unless a syntax error occurs, in which case it exits | |
2348 | with a non\-zero value. See also the \fBexit\fP builtin | |
2349 | command below. | |
2350 | .SH PROMPTING | |
2351 | When executing interactively, | |
2352 | .B bash | |
2353 | displays the primary prompt | |
2354 | .SM | |
2355 | .B PS1 | |
2356 | when it is ready to read a command, and the secondary prompt | |
2357 | .SM | |
2358 | .B PS2 | |
2359 | when it needs more input to complete a command. | |
2360 | .B Bash | |
2361 | allows these prompt strings to be customized by inserting a number of | |
2362 | backslash-escaped special characters that are decoded as follows: | |
2363 | .RS | |
2364 | .PD 0 | |
2365 | .TP | |
2366 | .B \et | |
2367 | the current time in HH:MM:SS format | |
2368 | .TP | |
2369 | .B \ed | |
2370 | the date in "Weekday Month Date" format (e.g., "Tue May 26") | |
2371 | .TP | |
2372 | .B \en | |
2373 | newline | |
2374 | .TP | |
2375 | .B \es | |
2376 | the name of the shell, the basename of | |
2377 | .B $0 | |
2378 | (the portion following the final slash) | |
2379 | .TP | |
2380 | .B \ew | |
2381 | the current working directory | |
2382 | .TP | |
2383 | .B \eW | |
2384 | the basename of the current working directory | |
2385 | .TP | |
2386 | .B \eu | |
2387 | the username of the current user | |
2388 | .TP | |
2389 | .B \eh | |
2390 | the hostname | |
2391 | .TP | |
2392 | .B \e# | |
2393 | the command number of this command | |
2394 | .TP | |
2395 | .B \e! | |
2396 | the history number of this command | |
2397 | .TP | |
2398 | .B \e$ | |
2399 | if the effective UID is 0, a | |
2400 | .BR # , | |
2401 | otherwise a | |
2402 | .B $ | |
2403 | .TP | |
2404 | .B \ennn | |
2405 | the character corresponding to the octal number \fBnnn\fP | |
2406 | .TP | |
2407 | .B \e\e | |
2408 | a backslash | |
2409 | .TP | |
2410 | .B \e[ | |
2411 | begin a sequence of non-printing characters, which could be used to | |
2412 | embed a terminal control sequence into the prompt | |
2413 | .TP | |
2414 | .B \e] | |
2415 | end a sequence of non-printing characters | |
2416 | .PD | |
2417 | .RE | |
2418 | .PP | |
2419 | The command number and the history number are usually different: | |
2420 | the history number of a command is its position in the history | |
2421 | list, which may include commands restored from the history file | |
2422 | (see | |
2423 | .SM | |
2424 | .B HISTORY | |
2425 | below), while the command number is the position in the sequence | |
2426 | of commands executed during the current shell session. | |
2427 | After the string is decoded, it is expanded via | |
2428 | parameter expansion, | |
2429 | command substitution, arithmetic expansion, and word splitting. | |
2430 | .SH READLINE | |
2431 | This is the library that handles reading input when using an interactive | |
2432 | shell, unless the | |
2433 | .B \-nolineediting | |
2434 | option is given. By default, the line editing commands | |
2435 | are similar to those of emacs. | |
2436 | A vi-style line editing interface is also available. | |
2437 | .PP | |
2438 | In this section, the emacs-style notation is used to denote | |
2439 | keystrokes. Control keys are denoted by C\-\fIkey\fR, e.g., C\-n | |
2440 | means Control\-N. Similarly, | |
2441 | .I meta | |
2442 | keys are denoted by M\-\fIkey\fR, so M\-x means Meta\-X. (On keyboards | |
2443 | without a | |
2444 | .I meta | |
2445 | key, M\-\fIx\fP means ESC \fIx\fP, i.e., press the Escape key | |
2446 | then the | |
2447 | .I x | |
2448 | key. This makes ESC the \fImeta prefix\fP. | |
2449 | The combination M\-C\-\fIx\fP means ESC\-Control\-\fIx\fP, | |
2450 | or press the Escape key | |
2451 | then hold the Control key while pressing the | |
2452 | .I x | |
2453 | key.) | |
2454 | .PP | |
2455 | The default key-bindings may be changed with an | |
2456 | .FN ~/.inputrc | |
2457 | file. The value of the shell variable | |
2458 | .SM | |
2459 | .BR INPUTRC , | |
2460 | if set, is used instead of | |
2461 | .IR ~/.inputrc . | |
2462 | Other programs that use this library may add their own commands | |
2463 | and bindings. | |
2464 | .PP | |
2465 | For example, placing | |
2466 | .RS | |
2467 | .PP | |
2468 | M\-Control\-u: universal\-argument | |
2469 | .RE | |
2470 | or | |
2471 | .RS | |
2472 | C\-Meta\-u: universal\-argument | |
2473 | .RE | |
2474 | into the | |
2475 | .FN ~/.inputrc | |
2476 | would make M\-C\-u execute the readline command | |
2477 | .IR universal\-argument . | |
2478 | .PP | |
2479 | The following symbolic character names are recognized: | |
2480 | .IR RUBOUT , | |
2481 | .IR DEL , | |
2482 | .IR ESC , | |
2483 | .IR LFD , | |
2484 | .IR NEWLINE , | |
2485 | .IR RET , | |
2486 | .IR RETURN , | |
2487 | .IR SPC , | |
2488 | .IR SPACE , | |
2489 | and | |
2490 | .IR TAB . | |
2491 | In addition to command names, readline allows keys to be bound | |
2492 | to a string that is inserted when the key is pressed (a \fImacro\fP). | |
2493 | .PP | |
2494 | Readline is customized by putting commands in an initialization | |
2495 | file. The name of this file is taken from the value of the | |
2496 | .SM | |
2497 | .B INPUTRC | |
2498 | variable. If that variable is unset, the default is | |
2499 | .IR ~/.inputrc . | |
2500 | When a program which uses the readline library starts up, the | |
2501 | init file is read, and the key bindings and variables are set. | |
2502 | There are only a few basic constructs allowed in the | |
2503 | readline init file. Blank lines are ignored. | |
2504 | Lines beginning with a \fB#\fP are comments. | |
2505 | Lines beginning with a \fB$\fP indicate conditional | |
2506 | constructs. Other lines | |
2507 | denote key bindings and variable settings. | |
2508 | .PP | |
2509 | The syntax for controlling key bindings in the | |
2510 | .I ~/.inputrc | |
2511 | file is simple. All that is required is the name of the | |
2512 | command or the text of a macro and a key sequence to which | |
2513 | it should be bound. The name may be specified in one of two ways: | |
2514 | as a symbolic key name, possibly with \fIMeta-\fP or \fIControl-\fP | |
2515 | prefixes, or as a key sequence. | |
2516 | When using the form \fBkeyname\fP:\fIfunction-name\fP or \fImacro\fP, | |
2517 | .I keyname | |
2518 | is the name of a key spelled out in English. For example: | |
2519 | .sp | |
2520 | .RS | |
2521 | Control-u: universal\-argument | |
2522 | .br | |
2523 | Meta-Rubout: backward-kill-word | |
2524 | .br | |
2525 | Control-o: ">&output" | |
2526 | .RE | |
2527 | .LP | |
2528 | In the above example, | |
2529 | .I C-u | |
2530 | is bound to the function | |
2531 | .BR universal\-argument , | |
2532 | .I M-DEL | |
2533 | is bound to the function | |
2534 | .BR backward\-kill\-word , | |
2535 | and | |
2536 | .I C-o | |
2537 | is bound to run the macro | |
2538 | expressed on the right hand side (that is, to insert the text | |
2539 | .I >&output | |
2540 | into the line). | |
2541 | .PP | |
2542 | In the second form, \fB"keyseq"\fP:\fIfunction-name\fP or \fImacro\fP, | |
2543 | .B keyseq | |
2544 | differs from | |
2545 | .B keyname | |
2546 | above in that strings denoting | |
2547 | an entire key sequence may be specified by placing the sequence | |
2548 | within double quotes. Some GNU Emacs style key escapes can be | |
2549 | used, as in the following example. | |
2550 | .sp | |
2551 | .RS | |
2552 | "\eC-u": universal\-argument | |
2553 | .br | |
2554 | "\eC-x\eC-r": re\-read\-init\-file | |
2555 | .br | |
2556 | "\ee[11~": "Function Key 1" | |
2557 | .RE | |
2558 | .PP | |
2559 | In this example, | |
2560 | .I C-u | |
2561 | is again bound to the function | |
2562 | .BR universal\-argument . | |
2563 | .I "C-x C-r" | |
2564 | is bound to the function | |
2565 | .BR re\-read\-init\-file , | |
2566 | and | |
2567 | .I "ESC [ 1 1 ~" | |
2568 | is bound to insert the text | |
2569 | .BR "Function Key 1" . | |
2570 | The full set of escape sequences is | |
2571 | .RS | |
2572 | .TP | |
2573 | .B \eC\- | |
2574 | control prefix | |
2575 | .TP | |
2576 | .B \eM- | |
2577 | meta prefix | |
2578 | .TP | |
2579 | .B \ee | |
2580 | an escape character | |
2581 | .TP | |
2582 | .B \e\e | |
2583 | backslash | |
2584 | .TP | |
2585 | .B \e" | |
2586 | literal " | |
2587 | .TP | |
2588 | .B \e' | |
2589 | literal ' | |
2590 | .RE | |
2591 | .PP | |
2592 | When entering the text of a macro, single or double quotes should | |
2593 | be used to indicate a macro definition. Unquoted text | |
2594 | is assumed to be a function name. Backslash | |
2595 | will quote any character in the macro text, including " and '. | |
2596 | .PP | |
2597 | .B Bash | |
2598 | allows the current readline key bindings to be displayed or modified | |
2599 | with the | |
2600 | .B bind | |
2601 | builtin command. The editing mode may be switched during interactive | |
2602 | use by using the | |
2603 | .B \-o | |
2604 | option to the | |
2605 | .B set | |
2606 | builtin command (see | |
2607 | .SM | |
2608 | .B SHELL BUILTIN COMMANDS | |
2609 | below). | |
2610 | .PP | |
2611 | Readline has variables that can be used to further customize its | |
2612 | behavior. A variable may be set in the | |
2613 | .I inputrc | |
2614 | file with a statement of the form | |
2615 | .RS | |
2616 | .PP | |
2617 | \fBset\fP \fIvariable\-name\fP \fIvalue\fP | |
2618 | .RE | |
2619 | .PP | |
2620 | Except where noted, readline variables can take the values | |
2621 | .B On | |
2622 | or | |
2623 | .BR Off . | |
2624 | The variables and their default values are: | |
2625 | .PP | |
2626 | .PD 0 | |
2627 | .TP | |
2628 | .B horizontal\-scroll\-mode (Off) | |
2629 | When set to \fBOn\fP, makes readline use a single line for display, | |
2630 | scrolling the input horizontally on a single screen line when it | |
2631 | becomes longer than the screen width rather than wrapping to a new line. | |
2632 | .TP | |
2633 | .B editing\-mode (emacs) | |
2634 | Controls whether readline begins with a set of key bindings similar | |
2635 | to \fIemacs\fP or \fIvi\fP. | |
2636 | .B editing\-mode | |
2637 | can be set to either | |
2638 | .B emacs | |
2639 | or | |
2640 | .BR vi . | |
2641 | .TP | |
2642 | .B mark\-modified\-lines (Off) | |
2643 | If set to \fBOn\fP, history lines that have been modified are displayed | |
2644 | with a preceding asterisk (\fB*\fP). | |
2645 | .TP | |
2646 | .B bell\-style (audible) | |
2647 | Controls what happens when readline wants to ring the terminal bell. | |
2648 | If set to \fBnone\fP, readline never rings the bell. If set to | |
2649 | \fBvisible\fP, readline uses a visible bell if one is available. | |
2650 | If set to \fBaudible\fP, readline attempts to ring the terminal's bell. | |
2651 | .TP | |
2652 | .B comment\-begin (``#'') | |
2653 | The string that is inserted in \fBvi\fP mode when the | |
2654 | .B vi\-comment | |
2655 | command is executed. | |
2656 | .TP | |
2657 | .B meta\-flag (Off) | |
2658 | If set to \fBOn\fP, readline will enable eight-bit input (that is, | |
2659 | it will not strip the high bit from the characters it reads), | |
2660 | regardless of what the terminal claims it can support. | |
2661 | .TP | |
2662 | .B convert\-meta (On) | |
2663 | If set to \fBOn\fP, readline will convert characters with the | |
2664 | eighth bit set to an ASCII key sequence | |
2665 | by stripping the eighth bit and prepending an | |
2666 | escape character (in effect, using escape as the \fImeta prefix\fP). | |
2667 | .TP | |
2668 | .B output\-meta (Off) | |
2669 | If set to \fBOn\fP, readline will display characters with the | |
2670 | eighth bit set directly rather than as a meta-prefixed escape | |
2671 | sequence. | |
2672 | .TP | |
2673 | .B completion\-query\-items (100) | |
2674 | This determines when the user is queried about viewing | |
2675 | the number of possible completions | |
2676 | generated by the \fBpossible\-completions\fP command. | |
2677 | It may be set to any integer value greater than or equal to | |
2678 | zero. If the number of possible completions is greater than | |
2679 | or equal to the value of this variable, the user is asked whether | |
2680 | or not he wishes to view them; otherwise they are simply listed | |
2681 | on the terminal. | |
2682 | .TP | |
2683 | .B keymap (emacs) | |
2684 | Set the current readline keymap. The set of legal keymap names is | |
2685 | \fIemacs, emacs-standard, emacs-meta, emacs-ctlx, vi, vi-move, | |
2686 | vi-command\fP, and | |
2687 | .IR vi-insert . | |
2688 | \fIvi\fP is equivalent to \fIvi-command\fP; \fIemacs\fP is | |
2689 | equivalent to \fIemacs-standard\fP. The default value is | |
2690 | .IR emacs ; | |
2691 | the value of | |
2692 | .B editing\-mode | |
2693 | also affects the default keymap. | |
2694 | .TP | |
2695 | .B show\-all\-if\-ambiguous (Off) | |
2696 | This alters the default behavior of the completion functions. If | |
2697 | set to | |
2698 | .BR on , | |
2699 | words which have more than one possible completion cause the | |
2700 | matches to be listed immediately instead of ringing the bell. | |
2701 | .TP | |
2702 | .B expand\-tilde (Off) | |
2703 | If set to \fBon\fP, tilde expansion is performed when readline | |
2704 | attempts word completion. | |
2705 | .PD | |
2706 | .PP | |
2707 | Readline implements a facility similar in spirit to the conditional | |
2708 | compilation features of the C preprocessor which allows key | |
2709 | bindings and variable settings to be performed as the result | |
2710 | of tests. There are three parser directives used. | |
2711 | .IP \fB$if\fP | |
2712 | The | |
2713 | .B $if | |
2714 | construct allows bindings to be made based on the | |
2715 | editing mode, the terminal being used, or the application using | |
2716 | readline. The text of the test extends to the end of the line; | |
2717 | no characters are required to isolate it. | |
2718 | .RS | |
2719 | .IP \fBmode\fP | |
2720 | The \fBmode=\fP form of the \fB$if\fP directive is used to test | |
2721 | whether readline is in emacs or vi mode. | |
2722 | This may be used in conjunction | |
2723 | with the \fBset keymap\fP command, for instance, to set bindings in | |
2724 | the \fIemacs-standard\fP and \fIemacs-ctlx\fP keymaps only if | |
2725 | readline is starting out in emacs mode. | |
2726 | .IP \fBterm\fP | |
2727 | The \fBterm=\fP form may be used to include terminal-specific | |
2728 | key bindings, perhaps to bind the key sequences output by the | |
2729 | terminal's function keys. The word on the right side of the | |
2730 | .B = | |
2731 | is tested against the full name of the terminal and the portion | |
2732 | of the terminal name before the first \fB\-\fP. This allows | |
2733 | .I sun | |
2734 | to match both | |
2735 | .I sun | |
2736 | and | |
2737 | .IR sun\-cmd , | |
2738 | for instance. | |
2739 | .IP \fBapplication\fP | |
2740 | The \fBapplication\fP construct is used to include | |
2741 | application\-specific settings. Each program using the readline | |
2742 | library sets the \fIapplication name\fP, and an initialization | |
2743 | file can test for a particular value. | |
2744 | This could be used to bind key sequences to functions useful for | |
2745 | a specific program. For instance, the following command adds a | |
2746 | key sequence that quotes the current or previous word in Bash: | |
2747 | .RS | |
2748 | .nf | |
2749 | \fB$if\fP Bash | |
2750 | # Quote the current or previous word | |
2751 | "\eC-xq": "\eeb\e"\eef\e"" | |
2752 | \fB$endif\fP | |
2753 | .fi | |
2754 | .RE | |
2755 | .RE | |
2756 | .IP \fB$endif\fP | |
2757 | This command, as you saw in the previous example, terminates an | |
2758 | \fB$if\fP command. | |
2759 | .IP \fB$else\fP | |
2760 | Commands in this branch of the \fB$if\fP directive are executed if | |
2761 | the test fails. | |
2762 | .PP | |
2763 | Readline commands may be given numeric | |
2764 | .IR arguments , | |
2765 | which normally act as a repeat count. Sometimes, however, it is the | |
2766 | sign of the argument that is significant. Passing a negative argument | |
2767 | to a command that acts in the forward direction (e.g., \fBkill\-line\fP) | |
2768 | causes that command to act in a backward direction. Commands whose | |
2769 | behavior with arguments deviates from this are noted. | |
2770 | .PP | |
2771 | When a command is described as \fIkilling\fP text, the text | |
2772 | deleted is saved for possible future retrieval | |
2773 | (\fIyanking\fP). The killed text is saved in a | |
2774 | \fIkill\-ring\fP. Consecutive kills cause the text to be | |
2775 | accumulated into one unit, which can be yanked all at once. | |
2776 | Commands which do not kill text separate the chunks of text | |
2777 | on the kill\-ring. | |
2778 | .PP | |
2779 | The following is a list of the names of the commands and the default | |
2780 | key sequences to which they are bound. | |
2781 | .SS Commands for Moving | |
2782 | .PP | |
2783 | .PD 0 | |
2784 | .TP | |
2785 | .B beginning\-of\-line (C\-a) | |
2786 | Move to the start of the current line. | |
2787 | .TP | |
2788 | .B end\-of\-line (C\-e) | |
2789 | Move to the end of the line. | |
2790 | .TP | |
2791 | .B forward\-char (C\-f) | |
2792 | Move forward a character. | |
2793 | .TP | |
2794 | .B backward\-char (C\-b) | |
2795 | Move back a character. | |
2796 | .TP | |
2797 | .B forward\-word (M\-f) | |
2798 | Move forward to the end of the next word. Words are composed of | |
2799 | alphanumeric characters (letters and digits). | |
2800 | .TP | |
2801 | .B backward\-word (M\-b) | |
2802 | Move back to the start of this, or the previous, word. Words are | |
2803 | composed of alphanumeric characters (letters and digits). | |
2804 | .TP | |
2805 | .B clear\-screen (C\-l) | |
2806 | Clear the screen leaving the current line at the top of the screen. | |
2807 | With an argument, refresh the current line without clearing the | |
2808 | screen. | |
2809 | .TP | |
2810 | .B redraw\-current\-line | |
2811 | Refresh the current line. By default, this is unbound. | |
2812 | .PD | |
2813 | .SS Commands for Manipulating the History | |
2814 | .PP | |
2815 | .PD 0 | |
2816 | .TP | |
2817 | .B accept\-line (Newline, Return) | |
2818 | Accept the line regardless of where the cursor is. If this line is | |
2819 | non\-empty, add it to the history list according to the state of the | |
2820 | .SM | |
2821 | .B HISTCONTROL | |
2822 | variable. If the line is a modified history | |
2823 | line, then restore the history line to its original state. | |
2824 | .TP | |
2825 | .B previous\-history (C\-p) | |
2826 | Fetch the previous command from the history list, moving back in | |
2827 | the list. | |
2828 | .TP | |
2829 | .B next\-history (C\-n) | |
2830 | Fetch the next command from the history list, moving forward in the | |
2831 | list. | |
2832 | .TP | |
2833 | .B beginning\-of\-history (M\-<) | |
2834 | Move to the first line in the history. | |
2835 | .TP | |
2836 | .B end\-of\-history (M\->) | |
2837 | Move to the end of the input history, i.e., the line currently being | |
2838 | entered. | |
2839 | .TP | |
2840 | .B reverse\-search\-history (C\-r) | |
2841 | Search backward starting at the current line and moving `up' through | |
2842 | the history as necessary. This is an incremental search. | |
2843 | .TP | |
2844 | .B forward\-search\-history (C\-s) | |
2845 | Search forward starting at the current line and moving `down' through | |
2846 | the history as necessary. This is an incremental search. | |
2847 | .TP | |
2848 | .B non\-incremental\-reverse\-search\-history (M\-p) | |
2849 | Search backward through the history starting at the current line | |
2850 | using a non\-incremental search for a string supplied by the user. | |
2851 | .TP | |
2852 | .B non\-incremental\-forward\-search\-history (M\-n) | |
2853 | Search forward through the history using a non\-incremental search for | |
2854 | a string supplied by the user. | |
2855 | .TP | |
2856 | .B history\-search\-forward | |
2857 | Search forward through the history for the string of characters | |
2858 | between the start of the current line and the current point. This | |
2859 | is a non-incremental search. By default, this command is unbound. | |
2860 | .TP | |
2861 | .B history\-search\-backward | |
2862 | Search backward through the history for the string of characters | |
2863 | between the start of the current line and the current point. This | |
2864 | is a non-incremental search. By default, this command is unbound. | |
2865 | .TP | |
2866 | .B yank\-nth\-arg (M\-C\-y) | |
2867 | Insert the first argument to the previous command (usually | |
2868 | the second word on the previous line) at point (the current | |
2869 | cursor position). With an argument | |
2870 | .IR n , | |
2871 | insert the \fIn\fPth word from the previous command (the words | |
2872 | in the previous command begin with word 0). A negative argument | |
2873 | inserts the \fIn\fPth word from the end of the previous command. | |
2874 | .TP | |
2875 | .B | |
2876 | yank\-last\-arg (M\-.\^, M\-_\^) | |
2877 | Insert the last argument to the previous command (the last word on | |
2878 | the previous line). With an argument, | |
2879 | behave exactly like \fByank-nth-arg\fP. | |
2880 | .TP | |
2881 | .B shell\-expand\-line (M\-C\-e) | |
2882 | Expand the line the way the shell does when it reads it. This | |
2883 | performs alias and history expansion as well as all of the shell | |
2884 | word expansions. See | |
2885 | .SM | |
2886 | .B HISTORY EXPANSION | |
2887 | below for a description of history expansion. | |
2888 | .TP | |
2889 | .B history\-expand\-line (M\-^) | |
2890 | Perform history expansion on the current line. See | |
2891 | .SM | |
2892 | .B HISTORY EXPANSION | |
2893 | below for a description of history expansion. | |
2894 | .TP | |
2895 | .B insert\-last\-argument (M\-.\^, M\-_\^) | |
2896 | A synonym for \fByank\-last\-arg\fP. | |
2897 | .TP | |
2898 | .B operate-and-get-next (C\-o) | |
2899 | Accept the current line for execution and fetch the next line | |
2900 | relative to the current line from the history for editing. Any | |
2901 | argument is ignored. | |
2902 | .PD | |
2903 | .SS Commands for Changing Text | |
2904 | .PP | |
2905 | .PD 0 | |
2906 | .TP | |
2907 | .B delete\-char (C\-d) | |
2908 | Delete the character under the cursor. If point is at the | |
2909 | beginning of the line, there are no characters in the line, and | |
2910 | the last character typed was not | |
2911 | .BR C\-d , | |
2912 | then return | |
2913 | .SM | |
2914 | .BR EOF . | |
2915 | .TP | |
2916 | .B backward\-delete\-char (Rubout) | |
2917 | Delete the character behind the cursor. When given a numeric argument, | |
2918 | save the deleted text on the kill\-ring. | |
2919 | .TP | |
2920 | .B quoted\-insert (C\-q, C\-v) | |
2921 | Add the next character that you type to the line verbatim. This is | |
2922 | how to insert characters like \fBC\-q\fP, for example. | |
2923 | .TP | |
2924 | .B tab\-insert (C-v TAB) | |
2925 | Insert a tab character. | |
2926 | .TP | |
2927 | .B self\-insert (a,\ b,\ A,\ 1,\ !,\ ...) | |
2928 | Insert the character typed. | |
2929 | .TP | |
2930 | .B transpose\-chars (C\-t) | |
2931 | Drag the character before point forward over the character at point. | |
2932 | Point moves forward as well. If point is at the end of the line, then | |
2933 | transpose the two characters before point. Negative arguments don't work. | |
2934 | .TP | |
2935 | .B transpose\-words (M\-t) | |
2936 | Drag the word behind the cursor past the word in front of the cursor | |
2937 | moving the cursor over that word as well. | |
2938 | .TP | |
2939 | .B upcase\-word (M\-u) | |
2940 | Uppercase the current (or following) word. With a negative argument, | |
2941 | do the previous word, but do not move point. | |
2942 | .TP | |
2943 | .B downcase\-word (M\-l) | |
2944 | Lowercase the current (or following) word. With a negative argument, | |
2945 | do the previous word, but do not move point. | |
2946 | .TP | |
2947 | .B capitalize\-word (M\-c) | |
2948 | Capitalize the current (or following) word. With a negative argument, | |
2949 | do the previous word, but do not move point. | |
2950 | .PD | |
2951 | .SS Killing and Yanking | |
2952 | .PP | |
2953 | .PD 0 | |
2954 | .TP | |
2955 | .B kill\-line (C\-k) | |
2956 | Kill the text from the current cursor position to the end of the line. | |
2957 | .TP | |
2958 | .B backward\-kill\-line (C\-x C\-Rubout) | |
2959 | Kill backward to the beginning of the line. | |
2960 | .TP | |
2961 | .B unix\-line\-discard (C\-u) | |
2962 | Kill backward from point to the beginning of the line. | |
2963 | .\" There is no real difference between this and backward-kill-line | |
2964 | .TP | |
2965 | .B kill\-whole\-line | |
2966 | Kill all characters on the current line, no matter where the | |
2967 | cursor is. By default, this is unbound. | |
2968 | .TP | |
2969 | .B kill\-word (M\-d) | |
2970 | Kill from the cursor to the end of the current word, or if between | |
2971 | words, to the end of the next word. Word boundaries are the same as | |
2972 | those used by \fBforward\-word\fP. | |
2973 | .TP | |
2974 | .B backward\-kill\-word (M\-Rubout) | |
2975 | Kill the word behind the cursor. Word boundaries are the same as | |
2976 | those used by \fBbackward\-word\fP. | |
2977 | .TP | |
2978 | .B unix\-word\-rubout (C\-w) | |
2979 | Kill the word behind the cursor, using white space as a word boundary. | |
2980 | The word boundaries are different from backward\-kill\-word. | |
2981 | .TP | |
2982 | .B delete\-horizontal\-space | |
2983 | Delete all spaces and tabs around point. By default, this is unbound. | |
2984 | .TP | |
2985 | .B yank (C\-y) | |
2986 | Yank the top of the kill ring into the buffer at the cursor. | |
2987 | .TP | |
2988 | .B yank\-pop (M\-y) | |
2989 | Rotate the kill\-ring, and yank the new top. Only works following | |
2990 | .B yank | |
2991 | or | |
2992 | .BR yank\-pop . | |
2993 | .PD | |
2994 | .SS Numeric Arguments | |
2995 | .PP | |
2996 | .PD 0 | |
2997 | .TP | |
2998 | .B digit\-argument (M\-0, M\-1, ..., M\-\-) | |
2999 | Add this digit to the argument already accumulating, or start a new | |
3000 | argument. M\-\- starts a negative argument. | |
3001 | .TP | |
3002 | .B universal\-argument | |
3003 | Each time this is executed, the argument count is multiplied by four. | |
3004 | The argument count is initially one, so executing this function the | |
3005 | first time makes the argument count four. By default, this is not | |
3006 | bound to a key. | |
3007 | .PD | |
3008 | .SS Completing | |
3009 | .PP | |
3010 | .PD 0 | |
3011 | .TP | |
3012 | .B complete (TAB) | |
3013 | Attempt to perform completion on the text before point. | |
3014 | .B Bash | |
3015 | attempts completion treating the text as a variable (if the | |
3016 | text begins with \fB$\fP), username (if the text begins with | |
3017 | \fB~\fP), hostname (if the text begins with \fB@\fP), or | |
3018 | command (including aliases and functions) in turn. If none | |
3019 | of these produces a match, filename completion is attempted. | |
3020 | .TP | |
3021 | .B possible\-completions (M-?) | |
3022 | List the possible completions of the text before point. | |
3023 | .TP | |
3024 | .B insert\-completions | |
3025 | Insert all completions of the text before point | |
3026 | that would have been generated by | |
3027 | \fBpossible\-completions\fP. By default, this | |
3028 | is not bound to a key. | |
3029 | .TP | |
3030 | .B complete\-filename (M\-/) | |
3031 | Attempt filename completion on the text before point. | |
3032 | .TP | |
3033 | .B possible\-filename\-completions (C\-x /) | |
3034 | List the possible completions of the text before point, | |
3035 | treating it as a filename. | |
3036 | .TP | |
3037 | .B complete\-username (M\-~) | |
3038 | Attempt completion on the text before point, treating | |
3039 | it as a username. | |
3040 | .TP | |
3041 | .B possible\-username\-completions (C\-x ~) | |
3042 | List the possible completions of the text before point, | |
3043 | treating it as a username. | |
3044 | .TP | |
3045 | .B complete\-variable (M\-$) | |
3046 | Attempt completion on the text before point, treating | |
3047 | it as a shell variable. | |
3048 | .TP | |
3049 | .B possible\-variable\-completions (C\-x $) | |
3050 | List the possible completions of the text before point, | |
3051 | treating it as a shell variable. | |
3052 | .TP | |
3053 | .B complete\-hostname (M\-@) | |
3054 | Attempt completion on the text before point, treating | |
3055 | it as a hostname. | |
3056 | .TP | |
3057 | .B possible\-hostname\-completions (C\-x @) | |
3058 | List the possible completions of the text before point, | |
3059 | treating it as a hostname. | |
3060 | .TP | |
3061 | .B complete\-command (M\-!) | |
3062 | Attempt completion on the text before point, treating | |
3063 | it as a command name. Command completion attempts to | |
3064 | match the text against aliases, reserved words, shell | |
3065 | functions, builtins, and finally executable filenames, | |
3066 | in that order. | |
3067 | .TP | |
3068 | .B possible\-command\-completions (C\-x !) | |
3069 | List the possible completions of the text before point, | |
3070 | treating it as a command name. | |
3071 | .TP | |
3072 | .B dynamic\-complete\-history (M-TAB) | |
3073 | Attempt completion on the text before point, comparing | |
3074 | the text against lines from the history list for possible | |
3075 | completion matches. | |
3076 | .TP | |
3077 | .B complete\-into\-braces (M\-{) | |
3078 | Perform filename completion and return the list of possible completions | |
3079 | enclosed within braces so the list is available to the shell (see | |
3080 | .B Brace Expansion | |
3081 | above). | |
3082 | .PD | |
3083 | .SS Keyboard Macros | |
3084 | .PP | |
3085 | .PD 0 | |
3086 | .TP | |
3087 | .B start\-kbd\-macro (C-x (\^) | |
3088 | Begin saving the characters typed into the current keyboard macro. | |
3089 | .TP | |
3090 | .B end\-kbd\-macro (C-x )\^) | |
3091 | Stop saving the characters typed into the current keyboard macro | |
3092 | and save the definition. | |
3093 | .TP | |
3094 | .B call\-last\-kbd\-macro (C-x e) | |
3095 | Re-execute the last keyboard macro defined, by making the characters | |
3096 | in the macro appear as if typed at the keyboard. | |
3097 | .PD | |
3098 | .SS Miscellaneous | |
3099 | .PP | |
3100 | .PD 0 | |
3101 | .TP | |
3102 | .B re\-read\-init\-file (C\-x C\-r) | |
3103 | Read in the contents of your init file, and incorporate | |
3104 | any bindings or variable assignments found there. | |
3105 | .TP | |
3106 | .B abort (C\-g) | |
3107 | Abort the current editing command and | |
3108 | ring the terminal's bell (subject to the setting of | |
3109 | .BR bell\-style ). | |
3110 | .TP | |
3111 | .B do\-uppercase\-version (M\-a, M\-b, ...) | |
3112 | Run the command that is bound to the corresponding uppercase | |
3113 | character. | |
3114 | .TP | |
3115 | .B prefix\-meta (ESC) | |
3116 | Metafy the next character typed. | |
3117 | .SM | |
3118 | .B ESC | |
3119 | .B f | |
3120 | is equivalent to | |
3121 | .BR Meta\-f . | |
3122 | .TP | |
3123 | .B undo (C\-_, C\-x C\-u) | |
3124 | Incremental undo, separately remembered for each line. | |
3125 | .TP | |
3126 | .B revert\-line (M\-r) | |
3127 | Undo all changes made to this line. This is like typing the | |
3128 | .B undo | |
3129 | command enough times to return the line to its initial state. | |
3130 | .TP | |
3131 | .B tilde\-expand (M\-~) | |
3132 | Perform tilde expansion on the current word. | |
3133 | .TP | |
3134 | .B dump\-functions | |
3135 | Print all of the functions and their key bindings to the | |
3136 | readline output stream. If a numeric argument is supplied, | |
3137 | the output is formatted in such a way that it can be made part | |
3138 | of an \fIinputrc\fP file. | |
3139 | .TP | |
3140 | .B display\-shell\-version (C\-x C\-v) | |
3141 | Display version information about the current instance of | |
3142 | .BR bash . | |
3143 | .PD | |
3144 | .SH HISTORY | |
3145 | When interactive, the shell provides access to the \fIcommand history\fP, | |
3146 | the list of commands previously typed. The text of the last | |
3147 | .SM | |
3148 | .B HISTSIZE | |
3149 | commands (default 500) is saved in a history list. The shell | |
3150 | stores each command in the history list prior to parameter and | |
3151 | variable expansion (see | |
3152 | .SM | |
3153 | .B EXPANSION | |
3154 | above) but after history expansion is performed, subject to the | |
3155 | values of the shell variables | |
3156 | .B command_oriented_history | |
3157 | and | |
3158 | .SM | |
3159 | .BR HISTCONTROL . | |
3160 | On startup, the history is initialized from the file named by | |
3161 | the variable | |
3162 | .SM | |
3163 | .B HISTFILE | |
3164 | (default \fI~/.bash_history\fP). | |
3165 | .SM | |
3166 | .B HISTFILE | |
3167 | is truncated, if necessary, to contain no more than | |
3168 | .SM | |
3169 | .B HISTFILESIZE | |
3170 | lines. | |
3171 | The builtin command | |
3172 | .B fc | |
3173 | (see | |
3174 | .SM | |
3175 | .B SHELL BUILTIN COMMANDS | |
3176 | below) may be used to list or edit and re-execute a portion of | |
3177 | the history list. | |
3178 | The | |
3179 | .B history | |
3180 | builtin can be used to display the history list and manipulate the | |
3181 | history file. When using the command-line editing, search commands | |
3182 | are available in each editing mode that provide access to the | |
3183 | history list. When an interactive shell exits, the last | |
3184 | .SM | |
3185 | .B HISTSIZE | |
3186 | lines are copied from the history list to | |
3187 | .SM | |
3188 | .BR HISTFILE . | |
3189 | If | |
3190 | .SM | |
3191 | .B HISTFILE | |
3192 | is unset, or if the history file is unwritable, the history is | |
3193 | not saved. | |
3194 | .SH "HISTORY EXPANSION" | |
3195 | .PP | |
3196 | The shell supports a history expansion feature that | |
3197 | is similar to the history expansion in | |
3198 | .BR csh. | |
3199 | This section describes what syntax features are available. This | |
3200 | feature is enabled by default for interactive shells, and can be | |
3201 | disabled using the | |
3202 | .B \+H | |
3203 | option to the | |
3204 | .B set | |
3205 | builtin command (see | |
3206 | .SM | |
3207 | .B SHELL BUILTIN COMMANDS | |
3208 | below). Non-interactive shells do not perform history expansion. | |
3209 | .PP | |
3210 | History expansion is performed immediately after a complete line | |
3211 | is read, before the shell breaks it into words. | |
3212 | It takes place in two parts. The first is to determine | |
3213 | which line from the previous history to use during | |
3214 | substitution. The second is to select portions of that line for | |
3215 | inclusion into the current one. The line selected from the | |
3216 | previous history is the \fIevent\fP, and the portions of that | |
3217 | line that are acted upon are \fIwords\fP. The line is broken | |
3218 | into words in the same fashion as when reading input, so that | |
3219 | several \fImetacharacter\fP\-separated words surrounded by quotes | |
3220 | are considered as one word. Only backslash (\^\fB\e\fP\^) | |
3221 | and single quotes can quote | |
3222 | the history escape character, which is \^\fB!\fP\^ by default. | |
3223 | .PP | |
3224 | The shell allows control of the various characters used by the | |
3225 | history expansion mechanism (see the description of | |
3226 | .B histchars | |
3227 | above under | |
3228 | .BR "Shell Variables" ). | |
3229 | .SS Event Designators | |
3230 | .PP | |
3231 | An event designator is a reference to a command line entry in the | |
3232 | history list. | |
3233 | .PP | |
3234 | .PD 0 | |
3235 | .TP | |
3236 | .B ! | |
3237 | Start a history substitution, except when followed by a | |
3238 | .BR blank , | |
3239 | newline, = or (. | |
3240 | .TP | |
3241 | .B !! | |
3242 | Refer to the previous command. This is a synonym for `!\-1'. | |
3243 | .TP | |
3244 | .B !\fIn\fR | |
3245 | Refer to command line | |
3246 | .IR n . | |
3247 | .TP | |
3248 | .B !\-\fIn\fR | |
3249 | Refer to the current command line minus | |
3250 | .IR n . | |
3251 | .TP | |
3252 | .B !\fIstring\fR | |
3253 | Refer to the most recent command starting with | |
3254 | .IR string . | |
3255 | .TP | |
3256 | .B !?\fIstring\fR\fB[?]\fR | |
3257 | Refer to the most recent command containing | |
3258 | .IR string . | |
3259 | .TP | |
3260 | .B \d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u | |
3261 | Quick substitution. Repeat the last command, replacing | |
3262 | .I string1 | |
3263 | with | |
3264 | .IR string2 . | |
3265 | Equivalent to | |
3266 | ``!!:s/\fIstring1\fP/\fIstring2\fP/'' | |
3267 | (see \fBModifiers\fP below). | |
3268 | .TP | |
3269 | .B !# | |
3270 | The entire command line typed so far. | |
3271 | .PD | |
3272 | .SS Word Designators | |
3273 | .PP | |
3274 | A | |
3275 | .B : | |
3276 | separates the event specification from the word | |
3277 | designator. It can be omitted if the word designator begins with a | |
3278 | .BR ^ , | |
3279 | .BR $ , | |
3280 | .BR * , | |
3281 | or | |
3282 | .BR % . | |
3283 | Words are numbered from the beginning of the line, | |
3284 | with the first word being denoted by a 0 (zero). | |
3285 | .PP | |
3286 | .PD 0 | |
3287 | .TP | |
3288 | .B 0 (zero) | |
3289 | The zeroth word. For the shell, this is the command | |
3290 | word. | |
3291 | .TP | |
3292 | .I n | |
3293 | The \fIn\fRth word. | |
3294 | .TP | |
3295 | .B ^ | |
3296 | The first argument. That is, word 1. | |
3297 | .TP | |
3298 | .B $ | |
3299 | The last argument. | |
3300 | .TP | |
3301 | .B % | |
3302 | The word matched by the most recent `?\fIstring\fR?' search. | |
3303 | .TP | |
3304 | .I x\fB\-\fPy | |
3305 | A range of words; `\-\fIy\fR' abbreviates `0\-\fIy\fR'. | |
3306 | .TP | |
3307 | .B * | |
3308 | All of the words but the zeroth. This is a synonym | |
3309 | for `\fI1\-$\fP'. It is not an error to use | |
3310 | .B * | |
3311 | if there is just one | |
3312 | word in the event; the empty string is returned in that case. | |
3313 | .TP | |
3314 | .B x* | |
3315 | Abbreviates \fIx\-$\fP. | |
3316 | .TP | |
3317 | .B x\- | |
3318 | Abbreviates \fIx\-$\fP like \fBx*\fP, but omits the last word. | |
3319 | .PD | |
3320 | .SS Modifiers | |
3321 | .PP | |
3322 | After the optional word designator, you can add a sequence of one | |
3323 | or more of the following modifiers, each preceded by a `:'. | |
3324 | .PP | |
3325 | .PD 0 | |
3326 | .PP | |
3327 | .TP | |
3328 | .B h | |
3329 | Remove a trailing pathname component, leaving only the head. | |
3330 | .TP | |
3331 | .B r | |
3332 | Remove a trailing suffix of the form \fI.xxx\fP, leaving the | |
3333 | basename. | |
3334 | .TP | |
3335 | .B e | |
3336 | Remove all but the trailing suffix. | |
3337 | .TP | |
3338 | .B t | |
3339 | Remove all leading pathname components, leaving the tail. | |
3340 | .TP | |
3341 | .B p | |
3342 | Print the new command but do not execute it. | |
3343 | .TP | |
3344 | .B q | |
3345 | Quote the substituted words, escaping further substitutions. | |
3346 | .TP | |
3347 | .B x | |
3348 | Quote the substituted words as with | |
3349 | .BR q , | |
3350 | but break into words at | |
3351 | .B blanks | |
3352 | and newlines. | |
3353 | .TP | |
3354 | .B s/\fIold\fP/\fInew\fP/ | |
3355 | Substitute | |
3356 | .I new | |
3357 | for the first occurrence of | |
3358 | .I old | |
3359 | in the event line. Any delimiter can be used in place of /. The | |
3360 | final delimiter is optional if it is the last character of the | |
3361 | event line. The delimiter may be quoted in | |
3362 | .I old | |
3363 | and | |
3364 | .I new | |
3365 | with a single backslash. If & appears in | |
3366 | .IR new , | |
3367 | it is replaced by | |
3368 | .IR old . | |
3369 | A single backslash will quote the &. | |
3370 | .TP | |
3371 | .B & | |
3372 | Repeat the previous substitution. | |
3373 | .TP | |
3374 | .B g | |
3375 | Cause changes to be applied over the entire event line. This is | |
3376 | used in conjunction with `\fB:s\fP' (e.g., `\fB:gs/\fIold\fP/\fInew\fP/\fR') | |
3377 | or `\fB:&\fP'. If used with | |
3378 | `\fB:s\fP', any delimiter can be used | |
3379 | in place of /, and the final delimiter is optional | |
3380 | if it is the last character of the event line. | |
3381 | .PD | |
3382 | .SH "ARITHMETIC EVALUATION" | |
3383 | The shell allows arithmetic expressions to be evaluated, under | |
3384 | certain circumstances (see the \fBlet\fP builtin command and | |
3385 | \fBArithmetic Expansion\fP). | |
3386 | Evaluation | |
3387 | is done in long integers with no check for overflow, though division | |
3388 | by 0 is trapped and flagged as an error. The following list of | |
3389 | operators is grouped into levels of equal-precedence operators. | |
3390 | The levels are listed in order of decreasing precedence. | |
3391 | .PP | |
3392 | .PD 0 | |
3393 | .TP | |
3394 | .B \- + | |
3395 | unary minus and plus | |
3396 | .TP | |
3397 | .B ! ~ | |
3398 | logical and bitwise negation | |
3399 | .TP | |
3400 | .B * / % | |
3401 | multiplication, division, remainder | |
3402 | .TP | |
3403 | .B + \- | |
3404 | addition, subtraction | |
3405 | .TP | |
3406 | .B << >> | |
3407 | left and right bitwise shifts | |
3408 | .TP | |
3409 | .B <= >= < > | |
3410 | comparison | |
3411 | .TP | |
3412 | .B == != | |
3413 | equality and inequality | |
3414 | .TP | |
3415 | .B & | |
3416 | bitwise AND | |
3417 | .TP | |
3418 | .B ^ | |
3419 | bitwise exclusive OR | |
3420 | .TP | |
3421 | .B | | |
3422 | bitwise OR | |
3423 | .TP | |
3424 | .B && | |
3425 | logical AND | |
3426 | .TP | |
3427 | .B || | |
3428 | logical OR | |
3429 | .TP | |
3430 | .B = *= /= %= += \-= <<= >>= &= ^= |= | |
3431 | assignment | |
3432 | .PD | |
3433 | .PP | |
3434 | Shell variables are allowed as operands; parameter expansion is | |
3435 | performed before the expression is evaluated. | |
3436 | The value of a parameter is coerced to a long integer within | |
3437 | an expression. A shell variable need not have its integer attribute | |
3438 | turned on to be used in an expression. | |
3439 | .PP | |
3440 | Constants with a leading 0 are interpreted as octal numbers. | |
3441 | A leading \fI0x\fP or \fI0X\fP denotes hexadecimal. Otherwise, | |
3442 | numbers take the form [\fIbase#\fP]n, where \fIbase\fP is a | |
3443 | decimal number between 2 and 36 representing the arithmetic | |
3444 | base, and \fIn\fP is a number in that base. If \fIbase\fP is | |
3445 | omitted, then base 10 is used. | |
3446 | .PP | |
3447 | Operators are evaluated in order of precedence. Sub-expressions in | |
3448 | parentheses are evaluated first and may override the precedence | |
3449 | rules above. | |
3450 | .SH "SHELL BUILTIN COMMANDS" | |
3451 | .\" start of bash_builtins | |
3452 | .zZ | |
3453 | .PD 0 | |
3454 | .TP | |
3455 | \fB:\fP [\fIarguments\fP] | |
3456 | .PD | |
3457 | No effect; the command does nothing beyond expanding | |
3458 | .I arguments | |
3459 | and performing any specified | |
3460 | redirections. A zero exit code is returned. | |
3461 | .TP | |
3462 | .PD 0 | |
3463 | \fB .\| \fP \fIfilename\fP [\fIarguments\fP] | |
3464 | .TP | |
3465 | \fBsource\fP \fIfilename\fP [\fIarguments\fP] | |
3466 | .PD | |
3467 | Read and execute commands from | |
3468 | .I filename | |
3469 | in the current | |
3470 | shell environment and return the exit status of the last command | |
3471 | executed from | |
3472 | .IR filename . | |
3473 | If | |
3474 | .I filename | |
3475 | does not contain a slash, pathnames in | |
3476 | .SM | |
3477 | .B PATH | |
3478 | are used to find the directory containing | |
3479 | .IR filename . | |
3480 | The file searched for in | |
3481 | .SM | |
3482 | .B PATH | |
3483 | need not be executable. The current directory is | |
3484 | searched if no file is found in | |
3485 | .SM | |
3486 | .BR PATH . | |
3487 | If any \fIarguments\fP are supplied, they become the positional | |
3488 | parameters when \fIfile\fP is executed. Otherwise the positional | |
3489 | parameters are unchanged. | |
3490 | The return status is the status of the last command exited within | |
3491 | the script (0 if no commands are executed), and false if | |
3492 | .I filename | |
3493 | is not found. | |
3494 | .TP | |
3495 | \fBalias\fP [\fIname\fP[=\fIvalue\fP] ...] | |
3496 | \fBAlias\fP with no arguments prints the list of aliases in the form | |
3497 | \fIname\fP=\fIvalue\fP on standard output. When arguments are | |
3498 | supplied, an alias is defined for | |
3499 | each \fIname\fP | |
3500 | whose \fIvalue\fP is given. A trailing space in | |
3501 | \fIvalue\fP causes the next | |
3502 | word to be checked for alias substitution when the alias is | |
3503 | expanded. For each \fIname\fP in the argument list for which | |
3504 | no \fIvalue\fP is supplied, the name and value of the alias is | |
3505 | printed. \fBAlias\fP returns true | |
3506 | unless a \fIname\fP is given for which no alias has been defined. | |
3507 | .TP | |
3508 | \fBbg\fP [\fIjobspec\fP] | |
3509 | Place \fIjobspec\fP in the background, as if it had been started with | |
3510 | .BR & . | |
3511 | If \fIjobspec\fP is not present, the shell's notion of the | |
3512 | \fIcurrent job\fP is used. | |
3513 | .B bg | |
3514 | .I jobspec | |
3515 | returns 0 unless run when job control is disabled or, when run with | |
3516 | job control enabled, if \fIjobspec\fP was not found or started without | |
3517 | job control. | |
3518 | .TP | |
3519 | .PD 0 | |
3520 | \fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-lvd\fP] [\fB-q\fP \fIname\fP] | |
3521 | .TP | |
3522 | \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB-f\fP \fIfilename\fP | |
3523 | .TP | |
3524 | \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fIkeyseq\fP:\fIfunction-name\fP | |
3525 | .PD | |
3526 | Display current | |
3527 | .B readline | |
3528 | key and function bindings, or bind a key sequence to a | |
3529 | .B readline | |
3530 | function or macro. The binding syntax accepted is identical to that of | |
3531 | .IR .inputrc , | |
3532 | but each binding must be passed as a separate argument; | |
3533 | e.g., '"\eC-x\eC-r": re\-read\-init\-file'. Options, if supplied, have the | |
3534 | following meanings: | |
3535 | .RS | |
3536 | .PD 0 | |
3537 | .TP | |
3538 | .B \-m \fIkeymap\fP | |
3539 | Use | |
3540 | .I keymap | |
3541 | as the keymap to be affected by the subsequent bindings. | |
3542 | Acceptable | |
3543 | .I keymap | |
3544 | names are | |
3545 | \fIemacs, emacs-standard, emacs-meta, emacs-ctlx, vi, vi-move, | |
3546 | vi-command\fP, and | |
3547 | .IR vi-insert . | |
3548 | \fIvi\fP is equivalent to \fIvi-command\fP; \fIemacs\fP is | |
3549 | equivalent to \fIemacs-standard\fP. | |
3550 | .TP | |
3551 | .B \-l | |
3552 | List the names of all \fBreadline\fP functions | |
3553 | .TP | |
3554 | .B \-v | |
3555 | List current function names and bindings | |
3556 | .TP | |
3557 | .B \-d | |
3558 | Dump function names and bindings in such a way that they can be re-read | |
3559 | .TP | |
3560 | .B \-f \fIfilename\fP | |
3561 | Read key bindings from \fIfilename\fP | |
3562 | .TP | |
3563 | .B \-q \fIfunction\fP | |
3564 | Query about which keys invoke the named \fIfunction\fP | |
3565 | .PD | |
3566 | .PP | |
3567 | The return value is 0 unless an unrecognized option is given or an | |
3568 | error occurred. | |
3569 | .RE | |
3570 | .TP | |
3571 | \fBbreak\fP [\fIn\fP] | |
3572 | Exit from within a | |
3573 | .BR for , | |
3574 | .BR while , | |
3575 | or | |
3576 | .B until | |
3577 | loop. If \fIn\fP is specified, break \fIn\fP levels. | |
3578 | .I n | |
3579 | must be \(>= 1. If | |
3580 | .I n | |
3581 | is greater than the number of enclosing loops, all enclosing loops | |
3582 | are exited. The return value is 0 unless the shell is not executing | |
3583 | a loop when | |
3584 | .B break | |
3585 | is executed. | |
3586 | .TP | |
3587 | \fBbuiltin\fP \fIshell\-builtin\fP [\fIarguments\fP] | |
3588 | Execute the specified shell builtin, passing it | |
3589 | .IR arguments , | |
3590 | and return its exit status. | |
3591 | This is useful when you wish to define a | |
3592 | function whose name is the same as a shell builtin, | |
3593 | but need the functionality of the | |
3594 | builtin within the function itself. The \fBcd\fP builtin is | |
3595 | commonly redefined this way. The return status is false if | |
3596 | .I shell\-builtin | |
3597 | is not a shell builtin command. | |
3598 | .TP | |
3599 | \fBcd\fP [\fIdir\fP] | |
3600 | Change the current directory to \fIdir\fP. The variable | |
3601 | .SM | |
3602 | .B HOME | |
3603 | is the | |
3604 | default | |
3605 | .IR dir . | |
3606 | The variable | |
3607 | .SM | |
3608 | .B CDPATH | |
3609 | defines the search path for | |
3610 | the directory containing | |
3611 | .IR dir . | |
3612 | Alternative directory names are | |
3613 | separated by a colon (:). A null directory name in | |
3614 | .SM | |
3615 | .B CDPATH | |
3616 | is the same as | |
3617 | the current directory, i.e., ``\fB.\fP''. If | |
3618 | .I dir | |
3619 | begins with a slash (/), | |
3620 | then | |
3621 | .SM | |
3622 | .B CDPATH | |
3623 | is not used. An argument of | |
3624 | .B \- | |
3625 | is equivalent to | |
3626 | .SM | |
3627 | .BR $OLDPWD . | |
3628 | The return value is true if the directory was successfully changed; | |
3629 | false otherwise. | |
3630 | .TP | |
3631 | \fBcommand\fP [\fB-pVv\fP] \fIcommand\fP [\fIarg\fP ...] | |
3632 | Run | |
3633 | .I command | |
3634 | with | |
3635 | .I args | |
3636 | suppressing the normal shell function lookup. Only builtin | |
3637 | commands or commands found in the | |
3638 | .SM | |
3639 | .B PATH | |
3640 | are executed. If the | |
3641 | .B \-p | |
3642 | option is given, the search for | |
3643 | .I command | |
3644 | is performed using a default value for | |
3645 | .B PATH | |
3646 | that is guaranteed to find all of the standard utilities. | |
3647 | If either the | |
3648 | .B \-V | |
3649 | or | |
3650 | .B \-v | |
3651 | option is supplied, a description of | |
3652 | .I command | |
3653 | is printed. The | |
3654 | .B \-v | |
3655 | option causes a single word indicating the command or pathname | |
3656 | used to invoke | |
3657 | .I command | |
3658 | to be printed; the | |
3659 | .B \-V | |
3660 | option produces a more verbose description. | |
3661 | An argument of | |
3662 | .B \-\- | |
3663 | disables option checking for the rest of the arguments. | |
3664 | If the | |
3665 | .B \-V | |
3666 | or | |
3667 | .B \-v | |
3668 | option is supplied, the exit status is 0 if | |
3669 | .I command | |
3670 | was found, and 1 if not. If neither option is supplied and | |
3671 | an error occurred or | |
3672 | .I command | |
3673 | cannot be found, the exit status is 127. Otherwise, the exit status of the | |
3674 | .B command | |
3675 | builtin is the exit status of | |
3676 | .IR command . | |
3677 | .TP | |
3678 | \fBcontinue\fP [\fIn\fP] | |
3679 | Resume the next iteration of the enclosing | |
3680 | .BR for , | |
3681 | .BR while , | |
3682 | or | |
3683 | .B until | |
3684 | loop. | |
3685 | If | |
3686 | .I n | |
3687 | is specified, resume at the \fIn\fPth enclosing loop. | |
3688 | .I n | |
3689 | must be \(>= 1. If | |
3690 | .I n | |
3691 | is greater than the number of enclosing loops, the last enclosing loop | |
3692 | (the `top\-level' loop) is resumed. The return value is 0 unless the | |
3693 | shell is not executing a loop when | |
3694 | .B continue | |
3695 | is executed. | |
3696 | .TP | |
3697 | .PD 0 | |
3698 | \fBdeclare\fP [\fB\-frxi\fP] [\fIname\fP[=\fIvalue\fP]] | |
3699 | .TP | |
3700 | \fBtypeset\fP [\fB\-frxi\fP] [\fIname\fP[=\fIvalue\fP]] | |
3701 | .PD | |
3702 | Declare variables and/or give them attributes. If no \fIname\fPs are | |
3703 | given, then display the values of variables instead. The options can | |
3704 | be used to restrict output to variables with the specified attribute. | |
3705 | .RS | |
3706 | .PD 0 | |
3707 | .TP | |
3708 | .B \-f | |
3709 | Use function names only | |
3710 | .TP | |
3711 | .B \-r | |
3712 | Make \fIname\fPs readonly. These names cannot then be assigned values | |
3713 | by subsequent assignment statements. | |
3714 | .TP | |
3715 | .B \-x | |
3716 | Mark \fIname\fPs for export to subsequent commands via the environment. | |
3717 | .TP | |
3718 | .B \-i | |
3719 | The variable is treated as an integer; arithmetic evaluation (see | |
3720 | .SM | |
3721 | .B "ARITHMETIC EVALUATION" ") " | |
3722 | is performed when the variable is assigned a value. | |
3723 | .PD | |
3724 | .PP | |
3725 | Using `+' instead of `\-' | |
3726 | turns off the attribute instead. When used in a function, makes | |
3727 | \fIname\fPs local, as with the | |
3728 | .B local | |
3729 | command. The return value is 0 unless an illegal option is encountered, | |
3730 | an attempt is made to define a function using "-f foo=bar", | |
3731 | one of the \fInames\fP is not a legal shell variable name, | |
3732 | an attempt is made to turn off readonly status for a readonly variable, | |
3733 | or an attempt is made to display a non-existant function with -f. | |
3734 | .RE | |
3735 | .TP | |
3736 | .B dirs [\fB-l\fP] [\fB+/\-n\fP] | |
3737 | Display the list of currently remembered directories. Directories | |
3738 | are added to the list with the | |
3739 | .B pushd | |
3740 | command; the | |
3741 | .B popd | |
3742 | command moves back up through the list. | |
3743 | .RS | |
3744 | .PD 0 | |
3745 | .TP | |
3746 | .B +n | |
3747 | displays the \fIn\fPth entry counting from the left of the list | |
3748 | shown by | |
3749 | .B dirs | |
3750 | when invoked without options, starting with zero. | |
3751 | .TP | |
3752 | .B \-n | |
3753 | displays the \fIn\fPth entry counting from the right of the list | |
3754 | shown by | |
3755 | .B dirs | |
3756 | when invoked without options, starting with zero. | |
3757 | .TP | |
3758 | .B \-l | |
3759 | produces a longer listing; the default listing format uses a | |
3760 | tilde to denote the home directory. | |
3761 | .PD | |
3762 | .PP | |
3763 | The return value is 0 unless an | |
3764 | illegal option is supplied or \fIn\fP indexes beyond the end | |
3765 | of the directory stack. | |
3766 | .RE | |
3767 | .TP | |
3768 | \fBecho\fP [\fB\-neE\fP] [\fIarg\fP ...] | |
3769 | Output the \fIarg\fPs, separated by spaces. The return status is | |
3770 | always 0. If \fB\-n\fP is specified, the trailing newline is | |
3771 | suppressed. If the \fB\-e\fP option is given, interpretation of | |
3772 | the following backslash-escaped characters is enabled. The | |
3773 | .B \-E | |
3774 | option disables the interpretation of these escape characters, | |
3775 | even on systems where they are interpreted by default. | |
3776 | .RS | |
3777 | .PD 0 | |
3778 | .TP | |
3779 | .B \ea | |
3780 | alert (bell) | |
3781 | .TP | |
3782 | .B \eb | |
3783 | backspace | |
3784 | .TP | |
3785 | .B \ec | |
3786 | suppress trailing newline | |
3787 | .TP | |
3788 | .B \ef | |
3789 | form feed | |
3790 | .TP | |
3791 | .B \en | |
3792 | new line | |
3793 | .TP | |
3794 | .B \er | |
3795 | carriage return | |
3796 | .TP | |
3797 | .B \et | |
3798 | horizontal tab | |
3799 | .TP | |
3800 | .B \ev | |
3801 | vertical tab | |
3802 | .TP | |
3803 | .B \e\e | |
3804 | backslash | |
3805 | .TP | |
3806 | .B \ennn | |
3807 | the character whose ASCII code is \fInnn\fP (octal) | |
3808 | .PD | |
3809 | .RE | |
3810 | .TP | |
3811 | \fBenable\fP [\fB\-n\fP] [\fB\-all\fP] [\fIname\fP ...] | |
3812 | Enable and disable builtin shell commands. This allows | |
3813 | the execution of a disk command which has the same name as a shell | |
3814 | builtin without specifying a full pathname. | |
3815 | If \fB\-n\fP is used, each \fIname\fP | |
3816 | is disabled; otherwise, | |
3817 | \fInames\fP are enabled. For example, to use the | |
3818 | .B test | |
3819 | binary found via the | |
3820 | .SM | |
3821 | .B PATH | |
3822 | instead of the shell builtin version, type | |
3823 | ``enable -n test''. If no arguments are given, | |
3824 | a list of all enabled shell builtins is printed. | |
3825 | If only \fB\-n\fP is supplied, a list of all disabled | |
3826 | builtins is printed. If only \fB\-all\fP is supplied, | |
3827 | the list printed includes all builtins, with an | |
3828 | indication of whether or not each is enabled. | |
3829 | .B enable | |
3830 | accepts | |
3831 | .B \-a | |
3832 | as a synonym for | |
3833 | .BR \-all . | |
3834 | The return value is 0 unless a | |
3835 | .I name | |
3836 | is not a shell builtin. | |
3837 | .TP | |
3838 | \fBeval\fP [\fIarg\fP ...] | |
3839 | The \fIarg\fPs are read and concatenated together into a single | |
3840 | command. This command is then read and executed by the shell, and | |
3841 | its exit status is returned as the value of the | |
3842 | .B eval | |
3843 | command. If there are no | |
3844 | .IR args , | |
3845 | or only null arguments, | |
3846 | .B eval | |
3847 | returns true. | |
3848 | .TP | |
3849 | \fBexec\fP [[\fB\-\fP] \fIcommand\fP [\fIarguments\fP]] | |
3850 | If | |
3851 | .I command | |
3852 | is specified, it replaces the shell. | |
3853 | No new process is created. The | |
3854 | .I arguments | |
3855 | become the arguments to \fIcommand\fP. | |
3856 | If the first argument is | |
3857 | .BR \- , | |
3858 | the shell places a dash in the zeroth arg passed to | |
3859 | .IR command . | |
3860 | This is what login does. If the file | |
3861 | cannot be executed for some reason, a non-interactive shell exits, | |
3862 | unless the shell variable \fBno_exit_on_failed_exec\fP exists, in | |
3863 | which case it returns failure. An interactive shell returns failure | |
3864 | if the file cannot be executed. | |
3865 | If | |
3866 | .I command | |
3867 | is not specified, any redirections take effect in the current shell, | |
3868 | and the return status is 0. | |
3869 | .TP | |
3870 | \fBexit\fP [\fIn\fP] | |
3871 | Cause the shell to exit | |
3872 | with a status of \fIn\fP. If | |
3873 | .I n | |
3874 | is omitted, the exit status | |
3875 | is that of the last command executed. | |
3876 | A trap on | |
3877 | .SM | |
3878 | .B EXIT | |
3879 | is executed before the shell terminates. | |
3880 | .TP | |
3881 | .PD 0 | |
3882 | \fBexport\fP [\fB\-nf\fP\^] [\fIname\fP[=\fIword\fP]] ... | |
3883 | .TP | |
3884 | .B export \-p | |
3885 | .PD | |
3886 | The supplied | |
3887 | .I names | |
3888 | are marked for automatic export to the environment of | |
3889 | subsequently executed commands. If the | |
3890 | .B \-f | |
3891 | option is given, | |
3892 | the | |
3893 | .I names | |
3894 | refer to functions. | |
3895 | If no | |
3896 | .I names | |
3897 | are given, or if the | |
3898 | .B \-p | |
3899 | option is supplied, a list | |
3900 | of all names that are exported in this shell is printed. | |
3901 | The | |
3902 | .B \-n | |
3903 | option causes the export property to be removed from the | |
3904 | named variables. An argument of | |
3905 | .B \-\- | |
3906 | disables option checking for the rest of the arguments. | |
3907 | .B export | |
3908 | returns an exit status of 0 unless an illegal option is | |
3909 | encountered, | |
3910 | one of the \fInames\fP is not a legal shell variable name, or | |
3911 | .B \-f | |
3912 | is supplied with a | |
3913 | .I name | |
3914 | that is not a function. | |
3915 | .TP | |
3916 | .PD 0 | |
3917 | \fBfc\fP [\fB\-e\fP \fIename\fP] [\fB\-nlr\fP] [\fIfirst\fP] [\fIlast\fP] | |
3918 | .TP | |
3919 | \fBfc\fP \fB\-s\fP [\fIpat\fP=\fIrep\fP] [\fIcmd\fP] | |
3920 | .PD | |
3921 | Fix Command. In the first form, a range of commands from | |
3922 | .I first | |
3923 | to | |
3924 | .I last | |
3925 | is selected from the history list. | |
3926 | .I First | |
3927 | and | |
3928 | .I last | |
3929 | may be specified as a string (to locate the last command beginning | |
3930 | with that string) or as a number (an index into the history list, | |
3931 | where a negative number is used as an offset from the current | |
3932 | command number). If | |
3933 | .I last | |
3934 | is not specified it is set to | |
3935 | the current command for listing (so that | |
3936 | .B fc \-l \-10 | |
3937 | prints the last 10 commands) and to | |
3938 | .I first | |
3939 | otherwise. | |
3940 | If | |
3941 | .I first | |
3942 | is not specified it is set to the previous | |
3943 | command for editing and \-16 for listing. | |
3944 | .sp 1 | |
3945 | The | |
3946 | .B \-n | |
3947 | flag suppresses | |
3948 | the command numbers when listing. The | |
3949 | .B \-r | |
3950 | flag reverses the order of | |
3951 | the commands. If the | |
3952 | .B \-l | |
3953 | flag is given, | |
3954 | the commands are listed on | |
3955 | standard output. Otherwise, the editor given by | |
3956 | .I ename | |
3957 | is invoked | |
3958 | on a file containing those commands. If | |
3959 | .I ename | |
3960 | is not given, the | |
3961 | value of the | |
3962 | .SM | |
3963 | .B FCEDIT | |
3964 | variable is used, and | |
3965 | the value of | |
3966 | .SM | |
3967 | .B EDITOR | |
3968 | if | |
3969 | .SM | |
3970 | .B FCEDIT | |
3971 | is not set. If neither variable is set, | |
3972 | .FN vi | |
3973 | is used. When editing is complete, the edited commands are | |
3974 | echoed and executed. | |
3975 | .sp 1 | |
3976 | In the second form, \fIcommand\fP is re-executed after each instance | |
3977 | of \fIpat\fP is replaced by \fIrep\fP. | |
3978 | A useful alias to use with this is ``r=fc \-s'', | |
3979 | so that typing ``r cc'' | |
3980 | runs the last command beginning with ``cc'' and typing ``r'' | |
3981 | re-executes the last command. | |
3982 | .sp 1 | |
3983 | If the first form is used, the return value is 0 unless an illegal | |
3984 | option is encountered or | |
3985 | .I first | |
3986 | or | |
3987 | .I last | |
3988 | specify history lines out of range. | |
3989 | If the | |
3990 | .B \-e | |
3991 | option is supplied, the return value is the value of the last | |
3992 | command executed or failure if an error occurs with the temporary | |
3993 | file of commands. If the second form is used, the return status | |
3994 | is that of the command re-executed, unless | |
3995 | .I cmd | |
3996 | does not specify a valid history line, in which case | |
3997 | .B fc | |
3998 | returns failure. | |
3999 | .TP | |
4000 | \fBfg\fP [\fIjobspec\fP] | |
4001 | Place | |
4002 | .I jobspec | |
4003 | in the foreground, and make it the current job. If | |
4004 | .I jobspec | |
4005 | is not present, the shell's notion of the \fIcurrent job\fP is used. | |
4006 | The return value is that of the command placed into the foreground, | |
4007 | or failure if run when job control is disabled or, when run with | |
4008 | job control enabled, if | |
4009 | .I jobspec | |
4010 | does not specify a valid job or | |
4011 | .I jobspec | |
4012 | specifies a job that was started without job control. | |
4013 | .TP | |
4014 | \fBgetopts\fP \fIoptstring\fP \fIname\fP [\fIargs\fP] | |
4015 | .B getopts | |
4016 | is used by shell procedures to parse positional parameters. | |
4017 | .I optstring | |
4018 | contains the option letters to be recognized; if a letter | |
4019 | is followed by a colon, the option is expected to have an | |
4020 | argument, which should be separated from it by white space. | |
4021 | Each time it is invoked, | |
4022 | .B getopts | |
4023 | places the next option in the shell variable | |
4024 | .IR name , | |
4025 | initializing | |
4026 | .I name | |
4027 | if it does not exist, | |
4028 | and the index of the next argument to be processed into the | |
4029 | variable | |
4030 | .SM | |
4031 | .BR OPTIND . | |
4032 | .SM | |
4033 | .B OPTIND | |
4034 | is initialized to 1 each time the shell or a shell script | |
4035 | is invoked. When an option requires an argument, | |
4036 | .B getopts | |
4037 | places that argument into the variable | |
4038 | .SM | |
4039 | .BR OPTARG . | |
4040 | The shell does not reset | |
4041 | .SM | |
4042 | .B OPTIND | |
4043 | automatically; it must be manually reset between multiple | |
4044 | calls to | |
4045 | .B getopts | |
4046 | within the same shell invocation if a new set of parameters | |
4047 | is to be used. | |
4048 | .sp 1 | |
4049 | .B getopts | |
4050 | can report errors in two ways. If the first character of | |
4051 | .I optstring | |
4052 | is a colon, | |
4053 | .I silent | |
4054 | error reporting is used. In normal operation diagnostic messages | |
4055 | are printed when illegal options or missing option arguments are | |
4056 | encountered. | |
4057 | If the variable | |
4058 | .SM | |
4059 | .B OPTERR | |
4060 | is set to 0, no error message will be displayed, even if the first | |
4061 | character of | |
4062 | .I optstring | |
4063 | is not a colon. | |
4064 | .sp 1 | |
4065 | If an illegal option is seen, | |
4066 | .B getopts | |
4067 | places ? into | |
4068 | .I name | |
4069 | and, if not silent, | |
4070 | prints an error message and unsets | |
4071 | .SM | |
4072 | .BR OPTARG . | |
4073 | If | |
4074 | .B getopts | |
4075 | is silent, | |
4076 | the option character found is placed in | |
4077 | .SM | |
4078 | .B OPTARG | |
4079 | and no diagnostic message is printed. | |
4080 | .sp 1 | |
4081 | If a required argument is not found, and | |
4082 | .B getopts | |
4083 | is not silent, | |
4084 | a question mark (\^\fB?\fP\^) is placed in | |
4085 | .IR name , | |
4086 | .B OPTARG | |
4087 | is unset, and a diagnostic message is printed. | |
4088 | If | |
4089 | .B getopts | |
4090 | is silent, then a colon (\^\fB:\fP\^) is placed in | |
4091 | .I name | |
4092 | and | |
4093 | .SM | |
4094 | .B OPTARG | |
4095 | is set to the option character found. | |
4096 | .sp 1 | |
4097 | .B getopts | |
4098 | normally parses the positional parameters, but if more arguments are | |
4099 | given in | |
4100 | .IR args , | |
4101 | .B getopts | |
4102 | parses those instead. | |
4103 | .B getopts | |
4104 | returns true if an option, specified or unspecified, is found. | |
4105 | It returns false if the end of options is encountered or an | |
4106 | error occurs. | |
4107 | .TP | |
4108 | \fBhash\fP [\fB\-r\fP] [\fIname\fP] | |
4109 | For each | |
4110 | .IR name , | |
4111 | the full pathname of the command is determined | |
4112 | and remembered. The | |
4113 | .B \-r | |
4114 | option causes the shell to forget all | |
4115 | remembered locations. If no arguments are given, information | |
4116 | about remembered commands is printed. | |
4117 | An argument of | |
4118 | .B \-\- | |
4119 | disables option checking for the rest of the arguments. The return | |
4120 | status is true unless a | |
4121 | .I name | |
4122 | is not found or an illegal option is supplied. | |
4123 | .TP | |
4124 | \fBhelp\fP [\fIpattern\fP] | |
4125 | Display helpful information about builtin commands. If | |
4126 | .I pattern | |
4127 | is specified, | |
4128 | .B help | |
4129 | gives detailed help on all commands matching | |
4130 | .IR pattern ; | |
4131 | otherwise a list of the builtins is printed. The return status is 0 | |
4132 | unless no command matches | |
4133 | .IR pattern . | |
4134 | .TP | |
4135 | .PD 0 | |
4136 | \fBhistory\fP [\fIn\fP] | |
4137 | .TP | |
4138 | \fBhistory\fP \fB\-rwan\fP [\fIfilename\fP] | |
4139 | .\".TP | |
4140 | .\"\fBhistory\fP \fB\-s\fP \fIargs\fP | |
4141 | .PD | |
4142 | With no options, display the command | |
4143 | history list with line numbers. Lines listed | |
4144 | with a | |
4145 | .B * | |
4146 | have been modified. An argument of | |
4147 | .I n | |
4148 | lists only the last | |
4149 | .I n | |
4150 | lines. If a non-option argument is supplied, it is used as the | |
4151 | name of the history file; if not, the value of | |
4152 | .SM | |
4153 | .B HISTFILE | |
4154 | is used. Options, if supplied, have the following meanings: | |
4155 | .RS | |
4156 | .PD 0 | |
4157 | .TP | |
4158 | .B \-a | |
4159 | Append the ``new'' history lines (history lines entered since the | |
4160 | beginning of the current \fBbash\fP session) to the history file | |
4161 | .TP | |
4162 | .B \-n | |
4163 | Read the history lines not already read from the history | |
4164 | file into the current history list. These are lines | |
4165 | appended to the history file since the beginning of the | |
4166 | current \fBbash\fP session. | |
4167 | .TP | |
4168 | .B \-r | |
4169 | Read the contents of the history file | |
4170 | and use them as the current history | |
4171 | .TP | |
4172 | .B \-w | |
4173 | Write the current history to the history file, overwriting the | |
4174 | history file's contents. | |
4175 | .\".TP | |
4176 | .\".B \-s | |
4177 | .\"perform history | |
4178 | .\"substitution on the following \fIargs\fP and display | |
4179 | .\"the result on the standard output. | |
4180 | .PD | |
4181 | .PP | |
4182 | The return value is 0 unless an illegal option is encountered or an | |
4183 | error occurs while reading or writing the history file. | |
4184 | .RE | |
4185 | .TP | |
4186 | .PD 0 | |
4187 | \fBjobs\fP [\fB\-lnp\fP] [ \fIjobspec\fP ... ] | |
4188 | .TP | |
4189 | \fBjobs\fP \fB\-x\fP \fIcommand\fP [ \fIargs\fP ... ] | |
4190 | .PD | |
4191 | The first form lists the active jobs. The | |
4192 | .B \-l | |
4193 | option lists process IDs | |
4194 | in addition to the normal information; the | |
4195 | .B \-p | |
4196 | option lists only the process ID of the job's process group | |
4197 | leader. The | |
4198 | .B \-n | |
4199 | option displays only jobs that have changed status since | |
4200 | last notified. If | |
4201 | .I jobspec | |
4202 | is given, output is restricted to information about that job. | |
4203 | The return status is 0 unless an illegal option is encountered | |
4204 | or an illegal | |
4205 | .I jobspec | |
4206 | is supplied. | |
4207 | .sp 1 | |
4208 | If the | |
4209 | .B \-x | |
4210 | option is supplied, | |
4211 | .B jobs | |
4212 | replaces any | |
4213 | .I jobspec | |
4214 | found in | |
4215 | .I command | |
4216 | or | |
4217 | .I args | |
4218 | with the corresponding process group ID, and executes | |
4219 | .I command | |
4220 | passing it | |
4221 | .IR args , | |
4222 | returning its exit status. | |
4223 | .TP | |
4224 | .PD 0 | |
4225 | \fBkill\fP [\fB-s sigspec\fP | \fB\-sigspec\fP] [\fIpid\fP | \fIjobspec\fP] ... | |
4226 | .TP | |
4227 | \fBkill\fP \fB\-l\fP [\fIsignum\fP] | |
4228 | .PD | |
4229 | Send the signal named by | |
4230 | .I sigspec | |
4231 | to the processes named by | |
4232 | .I pid | |
4233 | or | |
4234 | .IR jobspec . | |
4235 | .I sigspec | |
4236 | is either a signal name such as | |
4237 | .SM | |
4238 | .B SIGKILL | |
4239 | or a signal number. If | |
4240 | .I sigspec | |
4241 | is a signal name, the name is case insensitive and may be | |
4242 | given with or without the | |
4243 | .SM | |
4244 | .B SIG | |
4245 | prefix. | |
4246 | If | |
4247 | .I sigspec | |
4248 | is not present, then | |
4249 | .SM | |
4250 | .B SIGTERM | |
4251 | is assumed. An argument of | |
4252 | .B \-l | |
4253 | lists the signal names. If any arguments are supplied when | |
4254 | .B \-l | |
4255 | is given, the names of the specified signals are listed, and | |
4256 | the return status is 0. | |
4257 | An argument of | |
4258 | .B \-\- | |
4259 | disables option checking for the rest of the arguments. | |
4260 | .B kill | |
4261 | returns true if at least one signal was successfully sent, or false | |
4262 | if an error occurs or an illegal option is encountered. | |
4263 | .TP | |
4264 | \fBlet\fP \fIarg\fP [\fIarg\fP ...] | |
4265 | Each | |
4266 | .I arg | |
4267 | is an arithmetic expression to be evaluated (see | |
4268 | .SM | |
4269 | .BR "ARITHMETIC EVALUATION" ). | |
4270 | If the last | |
4271 | .I arg | |
4272 | evaluates to 0, | |
4273 | .B let | |
4274 | returns 1; 0 is returned otherwise. | |
4275 | .TP | |
4276 | \fBlocal\fP [\fIname\fP[=\fIvalue\fP] ...] | |
4277 | For each argument, create a local variable named | |
4278 | .IR name , | |
4279 | and assign it | |
4280 | .IR value . | |
4281 | When | |
4282 | .B local | |
4283 | is used within a function, it causes the variable | |
4284 | .I name | |
4285 | to have a visible scope restricted to that function and its children. | |
4286 | With no operands, | |
4287 | .B local | |
4288 | writes a list of local variables to the standard output. It is | |
4289 | an error to use | |
4290 | .B local | |
4291 | when not within a function. The return status is 0 unless | |
4292 | .B local | |
4293 | is used outside a function, or an illegal | |
4294 | .I name | |
4295 | is supplied. | |
4296 | .TP | |
4297 | .B logout | |
4298 | Exit a login shell. | |
4299 | .TP | |
4300 | \fBpopd\fP [\fB+/\-n\fP] | |
4301 | Removes entries from the directory stack. With no arguments, | |
4302 | removes the top directory from the stack, and performs a | |
4303 | .B cd | |
4304 | to the new top directory. | |
4305 | .RS | |
4306 | .PD 0 | |
4307 | .TP | |
4308 | .B +n | |
4309 | removes the \fIn\fPth entry counting from the left of the list | |
4310 | shown by | |
4311 | .BR dirs , | |
4312 | starting with zero. For example: ``popd +0'' | |
4313 | removes the first directory, ``popd +1'' the second. | |
4314 | .TP | |
4315 | .B \-n | |
4316 | removes the \fIn\fPth entry counting from the right of the list | |
4317 | shown by | |
4318 | .BR dirs , | |
4319 | starting with zero. For example: ``popd -0'' | |
4320 | removes the last directory, ``popd -1'' the next to last. | |
4321 | .PD | |
4322 | .PP | |
4323 | If the | |
4324 | .B popd | |
4325 | command is successful, a | |
4326 | .B dirs | |
4327 | is performed as well, and the return status is 0. | |
4328 | .B popd | |
4329 | returns false if an illegal option is encountered, the directory stack | |
4330 | is empty, a non-existent directory stack entry is specified, or the | |
4331 | directory change fails. | |
4332 | .RE | |
4333 | .TP | |
4334 | .PD 0 | |
4335 | \fBpushd\fP [\fIdir\fP] | |
4336 | .TP | |
4337 | \fBpushd\fP \fB+/\-n\fP | |
4338 | .PD | |
4339 | Adds a directory to the top of the directory stack, or rotates | |
4340 | the stack, making the new top of the stack the current working | |
4341 | directory. With no arguments, exchanges the top two directories | |
4342 | and returns 0, unless the directory stack is empty. | |
4343 | .RS | |
4344 | .PD 0 | |
4345 | .TP | |
4346 | .B +n | |
4347 | Rotates the stack so that the \fIn\fPth directory | |
4348 | (counting from the left of the list shown by | |
4349 | .BR dirs ) | |
4350 | is at the top. | |
4351 | .TP | |
4352 | .B \-n | |
4353 | Rotates the stack so that the \fIn\fPth directory | |
4354 | (counting from the right) is at the top. | |
4355 | .TP | |
4356 | .B dir | |
4357 | adds | |
4358 | .I dir | |
4359 | to the directory stack at the top, making it the | |
4360 | new current working directory. | |
4361 | .PD | |
4362 | .PP | |
4363 | If the | |
4364 | .B pushd | |
4365 | command is successful, a | |
4366 | .B dirs | |
4367 | is performed as well. | |
4368 | If the first form is used, | |
4369 | .B pushd | |
4370 | returns 0 unless the cd to | |
4371 | .I dir | |
4372 | fails. With the second form, | |
4373 | .B pushd | |
4374 | returns 0 unless the directory stack is empty, | |
4375 | a non-existant directory stack element is specified, | |
4376 | or the directory change to the specified new current directory | |
4377 | fails. | |
4378 | .RE | |
4379 | .TP | |
4380 | \fBpwd\fP | |
4381 | Print the absolute pathname of the current working directory. | |
4382 | The path printed contains no symbolic links if the | |
4383 | .B \-P | |
4384 | option to the | |
4385 | .B set | |
4386 | builtin command is set. | |
4387 | See also the description of | |
4388 | .B nolinks | |
4389 | under | |
4390 | .B Shell Variables | |
4391 | above). The return status is 0 unless an error occurs while | |
4392 | reading the pathname of the current directory. | |
4393 | .TP | |
4394 | \fBread\fP [\fB\-r\fP] [\fIname\fP ...] | |
4395 | One line is read from the standard input, and the first word | |
4396 | is assigned to the first | |
4397 | .IR name , | |
4398 | the second word to the second | |
4399 | .IR name , | |
4400 | and so on, with leftover words assigned to the last | |
4401 | .IR name . | |
4402 | Only the | |
4403 | characters in | |
4404 | .SM | |
4405 | .B IFS | |
4406 | are recognized as word delimiters. If no | |
4407 | .I names | |
4408 | are supplied, the line read is assigned to the variable | |
4409 | .SM | |
4410 | .BR REPLY . | |
4411 | The return code is zero, unless end-of-file is encountered. If the | |
4412 | .B \-r | |
4413 | option | |
4414 | is given, a backslash-newline pair is not ignored, and | |
4415 | the backslash is considered to be part of the line. | |
4416 | .TP | |
4417 | .PD 0 | |
4418 | \fBreadonly\fP [\fB\-f\fP] [\fIname\fP ...] | |
4419 | .TP | |
4420 | \fBreadonly -p\fP | |
4421 | .PD | |
4422 | The given | |
4423 | \fInames\fP are marked readonly and the values of these | |
4424 | \fInames\fP | |
4425 | may not be changed by subsequent assignment. | |
4426 | If the | |
4427 | .B \-f | |
4428 | option is supplied, the functions corresponding to the | |
4429 | \fInames\fP are so | |
4430 | marked. If no arguments are given, or if the | |
4431 | .B \-p | |
4432 | option is supplied, a list of all readonly names | |
4433 | is printed. | |
4434 | An argument of | |
4435 | .B \-\- | |
4436 | disables option checking for the rest of the arguments. The | |
4437 | return status is 0 unless an illegal option is encountered, | |
4438 | one of the \fInames\fP is not a legal shell variable name, or | |
4439 | .B \-f | |
4440 | is supplied with a | |
4441 | .I name | |
4442 | that is not a function. | |
4443 | .TP | |
4444 | \fBreturn\fP [\fIn\fP] | |
4445 | Causes a function to exit with the return value specified by | |
4446 | .IR n . | |
4447 | If | |
4448 | .I n | |
4449 | is omitted, the return status is that of the last command | |
4450 | executed in the function body. If used outside a function, | |
4451 | but during execution of a script by the | |
4452 | .B . | |
4453 | (\fBsource\fP) command, it causes the shell to stop executing | |
4454 | that script and return either | |
4455 | .I n | |
4456 | or the exit status of the last command executed within the | |
4457 | script as the exit status of the script. If used outside a | |
4458 | function and not during execution of a script by \fB.\fP\^, | |
4459 | the return status is false. | |
4460 | .TP | |
4461 | \fBset\fP [\fB\-\-abefhkmnptuvxldCHP\fP] [\fB-o\fP \fIoption\fP] [\fIarg\fP ...] | |
4462 | .RS | |
4463 | .PD 0 | |
4464 | .TP 8 | |
4465 | .B \-a | |
4466 | Automatically mark variables which are modified or created for export | |
4467 | to the environment of subsequent commands. | |
4468 | .TP 8 | |
4469 | .B \-b | |
4470 | Cause the status of terminated background jobs to be reported | |
4471 | immediately, rather than before the next primary prompt. | |
4472 | (Also see | |
4473 | .B notify | |
4474 | under | |
4475 | .B Shell Variables | |
4476 | above). | |
4477 | .TP 8 | |
4478 | .B \-e | |
4479 | Exit immediately if a \fIsimple-command\fP (see | |
4480 | .SM | |
4481 | .B SHELL GRAMMAR | |
4482 | above) exits with a non\-zero status. The shell does not exit if the | |
4483 | command that fails is part of an | |
4484 | .I until | |
4485 | or | |
4486 | .I while | |
4487 | loop, | |
4488 | part of an | |
4489 | .I if | |
4490 | statement, part of a | |
4491 | .B && | |
4492 | or | |
4493 | .B \(bv\|\(bv | |
4494 | list, or if the command's return value is | |
4495 | being inverted via | |
4496 | .BR ! . | |
4497 | .TP 8 | |
4498 | .B \-f | |
4499 | Disable pathname expansion. | |
4500 | .TP 8 | |
4501 | .B \-h | |
4502 | Locate and remember function commands as functions are | |
4503 | defined. Function commands are normally looked up when | |
4504 | the function is executed. | |
4505 | .TP 8 | |
4506 | .B \-k | |
4507 | All keyword arguments are placed in the environment for a | |
4508 | command, not just those that precede the command name. | |
4509 | .TP 8 | |
4510 | .B \-m | |
4511 | Monitor mode. Job control is enabled. This flag is on | |
4512 | by default for interactive shells on systems that support | |
4513 | it (see | |
4514 | .SM | |
4515 | .B JOB CONTROL | |
4516 | above). Background processes run in a separate process | |
4517 | group and a line containing their exit status is printed | |
4518 | upon their completion. | |
4519 | .TP 8 | |
4520 | .B \-n | |
4521 | Read commands but do not execute them. This may be used to | |
4522 | check a shell script for syntax errors. This is ignored for | |
4523 | interactive shells. | |
4524 | .TP 8 | |
4525 | .B \-o \fIoption-name\fP | |
4526 | The \fIoption-name\fP can be one of the following: | |
4527 | .RS | |
4528 | .TP 8 | |
4529 | .B allexport | |
4530 | Same as | |
4531 | .BR \-a . | |
4532 | .TP 8 | |
4533 | .B braceexpand | |
4534 | The shell performs brace expansion (see | |
4535 | .B Brace Expansion | |
4536 | above). This is on by default. | |
4537 | .TP 8 | |
4538 | .B emacs | |
4539 | Use an emacs-style command line editing interface. This is enabled | |
4540 | by default when the shell is interactive, unless the shell is started | |
4541 | with the | |
4542 | .B \-nolineediting | |
4543 | option. | |
4544 | .TP 8 | |
4545 | .B errexit | |
4546 | Same as | |
4547 | .BR \-e . | |
4548 | .TP 8 | |
4549 | .B histexpand | |
4550 | Same as | |
4551 | .BR \-H . | |
4552 | .TP 8 | |
4553 | .B ignoreeof | |
4554 | The effect is as if the shell command `IGNOREEOF=10' had been executed | |
4555 | (see | |
4556 | .B Shell Variables | |
4557 | above). | |
4558 | .TP 8 | |
4559 | .B interactive\-comments | |
4560 | Allow a word beginning with | |
4561 | .B # | |
4562 | to cause that word and all remaining characters on that | |
4563 | line to be ignored in an interactive shell (see | |
4564 | .SM | |
4565 | .B COMMENTS | |
4566 | above). | |
4567 | .TP 8 | |
4568 | .B monitor | |
4569 | Same as | |
4570 | .BR \-m . | |
4571 | .TP 8 | |
4572 | .B noclobber | |
4573 | Same as | |
4574 | .BR \-C . | |
4575 | .TP 8 | |
4576 | .B noexec | |
4577 | Same as | |
4578 | .BR \-n . | |
4579 | .TP 8 | |
4580 | .B noglob | |
4581 | Same as | |
4582 | .BR \-f . | |
4583 | .TP 8 | |
4584 | .B nohash | |
4585 | Same as | |
4586 | .BR \-d . | |
4587 | .TP 8 | |
4588 | .B notify | |
4589 | Same as | |
4590 | .BR \-b . | |
4591 | .TP 8 | |
4592 | .B nounset | |
4593 | Same as | |
4594 | .BR \-u . | |
4595 | .TP 8 | |
4596 | .B physical | |
4597 | Same as | |
4598 | .BR \-P . | |
4599 | .TP 8 | |
4600 | .B posix | |
4601 | Change the behavior of bash where the default operation differs | |
4602 | from the Posix 1003.2 standard to match the standard. | |
4603 | .TP 8 | |
4604 | .B privileged | |
4605 | Same as | |
4606 | .BR \-p . | |
4607 | .TP 8 | |
4608 | .B verbose | |
4609 | Same as | |
4610 | .BR \-v . | |
4611 | .TP 8 | |
4612 | .B vi | |
4613 | Use a vi-style command line editing interface. | |
4614 | .TP 8 | |
4615 | .B xtrace | |
4616 | Same as | |
4617 | .BR \-x . | |
4618 | .PP | |
4619 | If no \fIoption-name\fP is supplied, the values of the current options are | |
4620 | printed. | |
4621 | .RE | |
4622 | .TP 8 | |
4623 | .B \-p | |
4624 | Turn on | |
4625 | .I privileged | |
4626 | mode. In this mode, the | |
4627 | .B $ENV | |
4628 | file is not processed, and shell functions | |
4629 | are not inherited from the environment. This is enabled automatically | |
4630 | on startup if the effective user (group) id is not equal to the real | |
4631 | user (group) id. Turning this option off causes the effective user | |
4632 | and group ids to be set to the real user and group ids. | |
4633 | .TP 8 | |
4634 | .B \-t | |
4635 | Exit after reading and executing one command. | |
4636 | .TP 8 | |
4637 | .B \-u | |
4638 | Treat unset variables as an error when performing | |
4639 | parameter expansion. If expansion is attempted on an | |
4640 | unset variable, the shell prints an error message, and, | |
4641 | if not interactive, exits with a non\-zero status. | |
4642 | .TP 8 | |
4643 | .B \-v | |
4644 | Print shell input lines as they are read. | |
4645 | .TP 8 | |
4646 | .B \-x | |
4647 | After expanding each | |
4648 | .IR simple-command , | |
4649 | .B bash | |
4650 | displays the expanded value of | |
4651 | .SM | |
4652 | .BR PS4 , | |
4653 | followed by the command and its expanded arguments. | |
4654 | .TP 8 | |
4655 | .B \-l | |
4656 | Save and restore the binding of \fIname\fP in a | |
4657 | \fBfor\fP \fIname\fP [in \fBword\fP] command (see | |
4658 | .SM | |
4659 | .B SHELL GRAMMAR | |
4660 | above). | |
4661 | .TP 8 | |
4662 | .B \-d | |
4663 | Disable the hashing of commands that are looked up for execution. | |
4664 | Normally, commands are remembered in a hash table, and once | |
4665 | found, do not have to be looked up again. | |
4666 | .TP 8 | |
4667 | .B \-C | |
4668 | The effect is as if the shell command `noclobber=' had been executed | |
4669 | (see | |
4670 | .B Shell Variables | |
4671 | above). | |
4672 | .TP 8 | |
4673 | .B \-H | |
4674 | Enable | |
4675 | .B ! | |
4676 | style history substitution. This flag is on by | |
4677 | default when the shell is interactive. | |
4678 | .TP 8 | |
4679 | .B \-P | |
4680 | If set, do not follow symbolic links when performing commands such as | |
4681 | .B cd | |
4682 | which change the current directory. The physical directory is | |
4683 | used instead. | |
4684 | .TP 8 | |
4685 | .B \-\- | |
4686 | If no arguments follow this flag, then the positional parameters are | |
4687 | unset. Otherwise, the positional parameters are set to the | |
4688 | \fIarg\fPs, even if some of them begin with a | |
4689 | .BR \- . | |
4690 | .TP 8 | |
4691 | .B \- | |
4692 | Signal the end of options, cause all remaining \fIarg\fPs to be | |
4693 | assigned to the positional parameters. The | |
4694 | .B \-x | |
4695 | and | |
4696 | .B \-v | |
4697 | options are turned off. | |
4698 | If there are no \fIarg\fPs, | |
4699 | the positional parameters remain unchanged. | |
4700 | .PD | |
4701 | .PP | |
4702 | The flags are off by default | |
4703 | unless otherwise noted. | |
4704 | Using + rather than \- causes these flags | |
4705 | to be turned off. The | |
4706 | flags can also be specified as options to an | |
4707 | invocation of the shell. The current | |
4708 | set of flags may be found in | |
4709 | .BR $\- . | |
4710 | After the option arguments are processed, | |
4711 | the remaining \fIn\fP \fIarg\fPs are treated | |
4712 | as values for the positional | |
4713 | parameters and are assigned, in order, to | |
4714 | .BR $1 , | |
4715 | .BR $2 , | |
4716 | .B ... | |
4717 | .BR $\fIn\fP . | |
4718 | If no options or \fIarg\fPs are supplied, | |
4719 | all shell variables are printed. The return status is always true | |
4720 | unless an illegal option is encountered. | |
4721 | .RE | |
4722 | .TP | |
4723 | \fBshift\fP [\fIn\fP] | |
4724 | The positional parameters from \fIn\fP+1 ... are renamed to | |
4725 | .B $1 | |
4726 | .B .... | |
4727 | Parameters represented by the numbers \fB$#\fP | |
4728 | down to \fB$#\fP\-\fIn\fP+1 are unset. | |
4729 | If | |
4730 | .I n | |
4731 | is 0, no parameters are changed. | |
4732 | If | |
4733 | .I n | |
4734 | is not given, it is assumed to be 1. | |
4735 | .I n | |
4736 | must be a non-negative number less than or equal to \fB$#\fP. | |
4737 | If | |
4738 | .I n | |
4739 | is greater than \fB$#\fP, the positional parameters are not changed. | |
4740 | The return status is greater than 0 if | |
4741 | .I n | |
4742 | is greater than | |
4743 | .B $# | |
4744 | or less than 0; otherwise 0. | |
4745 | .TP | |
4746 | \fBsuspend\fP [\fB\-f\fP] | |
4747 | Suspend the execution of this shell until it receives a | |
4748 | .SM | |
4749 | .B SIGCONT | |
4750 | signal. The | |
4751 | .B \-f | |
4752 | option says not to complain if this is | |
4753 | a login shell; just suspend anyway. The return status is 0 unless | |
4754 | the shell is a login shell and | |
4755 | .B \-f | |
4756 | is not supplied, or if job control is not enabled. | |
4757 | .TP | |
4758 | .PD 0 | |
4759 | \fBtest\fP \fIexpr\fP | |
4760 | .TP | |
4761 | \fB[\fP \fIexpr\fP \fB]\fP | |
4762 | Return a status of 0 (true) or 1 (false) depending on | |
4763 | the evaluation of the conditional expression | |
4764 | .IR expr . | |
4765 | Expressions may be unary or binary. Unary | |
4766 | expressions are often used to examine the status of a file. There | |
4767 | are string operators and numeric comparison operators as well. Each | |
4768 | operator and operand must be a separate argument. If \fIfile\fP | |
4769 | is of the form /dev/fd/\fIn\fP, then file descriptor \fIn\fP is | |
4770 | checked. | |
4771 | .RS | |
4772 | .PD 0 | |
4773 | .TP | |
4774 | .B \-b \fIfile\fP | |
4775 | True if \fIfile\fP exists and is block special. | |
4776 | .TP | |
4777 | .B \-c \fIfile\fP | |
4778 | True if \fIfile\fP exists and is character special. | |
4779 | .TP | |
4780 | .B \-d \fIfile\fP | |
4781 | True if \fIfile\fP exists and is a directory. | |
4782 | .TP | |
4783 | .B \-e \fIfile\fP | |
4784 | True if \fIfile\fP exists. | |
4785 | .TP | |
4786 | .B \-f \fIfile\fP | |
4787 | True if \fIfile\fP exists and is a regular file. | |
4788 | .TP | |
4789 | .B \-g \fIfile\fP | |
4790 | True if \fIfile\fP exists and is set-group-id. | |
4791 | .TP | |
4792 | .B \-k \fIfile\fP | |
4793 | True if \fIfile\fP has its ``sticky'' bit set. | |
4794 | .TP | |
4795 | .B \-L \fIfile\fP | |
4796 | True if \fIfile\fP exists and is a symbolic link. | |
4797 | .TP | |
4798 | .B \-p \fIfile\fP | |
4799 | True if \fIfile\fP exists and is a named pipe. | |
4800 | .TP | |
4801 | .B \-r \fIfile\fP | |
4802 | True if \fIfile\fP exists and is readable. | |
4803 | .TP | |
4804 | .B \-s \fIfile\fP | |
4805 | True if \fIfile\fP exists and has a size greater than zero. | |
4806 | .TP | |
4807 | .B \-S \fIfile\fP | |
4808 | True if \fIfile\fP exists and is a socket. | |
4809 | .TP | |
4810 | .B \-t \fIfd\fP | |
4811 | True if | |
4812 | .I fd | |
4813 | is opened on a terminal. | |
4814 | .TP | |
4815 | .B \-u \fIfile\fP | |
4816 | True if \fIfile\fP exists and its set-user-id bit is set. | |
4817 | .TP | |
4818 | .B \-w \fIfile\fP | |
4819 | True if \fIfile\fP exists and is writable. | |
4820 | .TP | |
4821 | .B \-x \fIfile\fP | |
4822 | True if \fIfile\fP exists and is executable. | |
4823 | .TP | |
4824 | .B \-O \fIfile\fP | |
4825 | True if \fIfile\fP exists and is owned by the effective user id. | |
4826 | .TP | |
4827 | .B \-G \fIfile\fP | |
4828 | True if \fIfile\fP exists and is owned by the effective group id. | |
4829 | .TP | |
4830 | \fIfile1\fP \-\fBnt\fP \fIfile2\fP | |
4831 | True if \fIfile1\fP is newer (according to | |
4832 | modification date) than \fIfile2\fP. | |
4833 | .TP | |
4834 | \fIfile1\fP \-\fBot\fP \fIfile2\fP | |
4835 | True if \fIfile1\fP is older than file2. | |
4836 | .TP | |
4837 | \fIfile1\fP \fB\-ef\fP \fIfile\fP | |
4838 | True if \fIfile1\fP and \fIfile2\fP have the same device and | |
4839 | inode numbers. | |
4840 | .TP | |
4841 | .B \-z \fIstring\fP | |
4842 | True if the length of \fIstring\fP is zero. | |
4843 | .TP | |
4844 | .B \-n \fIstring\fP | |
4845 | .TP | |
4846 | \fIstring\fP | |
4847 | True if the length of | |
4848 | .I string | |
4849 | is non\-zero. | |
4850 | .TP | |
4851 | \fIstring1\fP \fB=\fP \fIstring2\fP | |
4852 | True if the strings are equal. | |
4853 | .TP | |
4854 | \fIstring1\fP \fB!=\fP \fIstring2\fP | |
4855 | True if the strings are not equal. | |
4856 | .TP | |
4857 | .B ! \fIexpr\fP | |
4858 | True if | |
4859 | .I expr | |
4860 | is false. | |
4861 | .TP | |
4862 | \fIexpr1\fP \-\fBa\fP \fIexpr2\fP | |
4863 | True if both | |
4864 | .I expr1 | |
4865 | AND | |
4866 | .I expr2 | |
4867 | are true. | |
4868 | .TP | |
4869 | \fIexpr1\fP \-\fBo\fP \fIexpr2\fP | |
4870 | True if either | |
4871 | .I expr1 | |
4872 | OR | |
4873 | .I expr2 | |
4874 | is true. | |
4875 | .TP | |
4876 | .I arg1 \fBOP\fP arg2 | |
4877 | .SM | |
4878 | .B OP | |
4879 | is one of | |
4880 | .BR \-eq , | |
4881 | .BR \-ne , | |
4882 | .BR \-lt , | |
4883 | .BR \-le , | |
4884 | .BR \-gt , | |
4885 | or | |
4886 | .BR \-ge . | |
4887 | These arithmetic binary operators return true if \fIarg1\fP | |
4888 | is equal, not-equal, less-than, less-than-or-equal, | |
4889 | greater-than, or greater-than-or-equal than \fIarg2\fP, | |
4890 | respectively. | |
4891 | .I Arg1 | |
4892 | and | |
4893 | .I arg2 | |
4894 | may be positive integers, negative integers, or the special | |
4895 | expression \fB\-l\fP \fIstring\fP, which evaluates to the | |
4896 | length of | |
4897 | .IR string . | |
4898 | .PD | |
4899 | .RE | |
4900 | .TP | |
4901 | .B times | |
4902 | Print the accumulated user and system times for the shell and | |
4903 | for processes run from the shell. The return status is 0. | |
4904 | .TP | |
4905 | \fBtrap\fP [\fB\-l\fP] [\fIarg\fP] [\fIsigspec\fP] | |
4906 | The command | |
4907 | .I arg | |
4908 | is to be read and executed when the shell receives | |
4909 | signal(s) | |
4910 | .IR sigspec . | |
4911 | If | |
4912 | .I arg | |
4913 | is absent or | |
4914 | .BR \- , | |
4915 | all specified signals are | |
4916 | reset to their original values (the values they had | |
4917 | upon entrance to the shell). If | |
4918 | .I arg | |
4919 | is the null string this | |
4920 | signal is ignored by the shell and by the | |
4921 | commands it invokes. | |
4922 | .I sigspec | |
4923 | is either | |
4924 | a signal name defined in <\fIsignal.h\fP>, or a signal number. | |
4925 | If | |
4926 | .I sigspec | |
4927 | is | |
4928 | .SM | |
4929 | .B EXIT | |
4930 | (0) the command | |
4931 | .I arg | |
4932 | is executed on exit from | |
4933 | the shell. With no arguments, | |
4934 | .B trap | |
4935 | prints the list of commands associated with each signal number. | |
4936 | The | |
4937 | .B \-l | |
4938 | option causes the shell to | |
4939 | print a list of signal names and their corresponding | |
4940 | numbers. An argument of | |
4941 | .B \-\- | |
4942 | disables option checking for the rest of the arguments. | |
4943 | Signals ignored upon entry to the shell cannot be trapped or reset. | |
4944 | Trapped signals are reset to their original values in a child | |
4945 | process when it is created. The return status is false if either | |
4946 | the trap name or number is invalid; otherwise | |
4947 | .B trap | |
4948 | returns true. | |
4949 | .TP | |
4950 | \fBtype\fP [\fB\-all\fP] [\fB\-type\fP | \fB\-path\fP] \fIname\fP [\fIname\fP ...] | |
4951 | With no options, | |
4952 | indicate how each | |
4953 | .I name | |
4954 | would be interpreted if used as a command name. | |
4955 | If the | |
4956 | .B \-type | |
4957 | flag is used, | |
4958 | .B type | |
4959 | prints a phrase which is one of | |
4960 | .IR alias , | |
4961 | .IR keyword , | |
4962 | .IR function , | |
4963 | .IR builtin , | |
4964 | or | |
4965 | .I file | |
4966 | if | |
4967 | .I name | |
4968 | is an alias, shell reserved word, function, builtin, or disk file, | |
4969 | respectively. If the name is not found, then nothing is printed, | |
4970 | and an exit status of false is returned. | |
4971 | If the | |
4972 | .B \-path | |
4973 | flag is used, | |
4974 | .B type | |
4975 | either returns the name of the disk file | |
4976 | that would be executed if | |
4977 | .I name | |
4978 | were specified as a command name, | |
4979 | or nothing if | |
4980 | .B \-type | |
4981 | would not return | |
4982 | .IR file . | |
4983 | If a command is hashed, | |
4984 | .B \-path | |
4985 | prints the hashed value, not necessarily the file that appears | |
4986 | first in | |
4987 | .SM | |
4988 | .BR PATH . | |
4989 | If the | |
4990 | .B \-all | |
4991 | flag is used, | |
4992 | .B type | |
4993 | prints all of the places that contain | |
4994 | an executable named | |
4995 | .IR name . | |
4996 | This includes aliases and functions, | |
4997 | if and only if the | |
4998 | .B \-path | |
4999 | flag is not also used. | |
5000 | The table of hashed commands is not consulted | |
5001 | when using | |
5002 | .BR \-all . | |
5003 | .B type | |
5004 | accepts | |
5005 | .BR \-a , | |
5006 | .BR \-t , | |
5007 | and | |
5008 | .B \-p | |
5009 | in place of | |
5010 | .BR \-all , | |
5011 | .BR \-type , | |
5012 | and | |
5013 | .BR \-path , | |
5014 | respectively. | |
5015 | An argument of | |
5016 | .B \-\- | |
5017 | disables option checking for the rest of the arguments. | |
5018 | .B type | |
5019 | returns true if any of the arguments are found, false if | |
5020 | none are found. | |
5021 | .TP | |
5022 | \fBulimit\fP [\fB\-SHacdfmstpnuv\fP [\fIlimit\fP]] | |
5023 | .B Ulimit | |
5024 | provides control over the resources available to the shell and to | |
5025 | processes started by it, on systems that allow such control. The | |
5026 | value of | |
5027 | .I limit | |
5028 | can be a number in the unit specified for the resource, or the | |
5029 | value | |
5030 | .BR unlimited . | |
5031 | The \fBH\fP and \fBS\fP options specify that the hard or soft limit is | |
5032 | set for the given resource. A hard limit cannot be increased once it | |
5033 | is set; a soft limit may be increased up to the value of the hard limit. | |
5034 | If neither \fBH\fP nor \fBS\fP is specified, the command applies to the | |
5035 | soft limit. If | |
5036 | .I limit | |
5037 | is omitted, the current value of the soft limit of the resource is | |
5038 | printed, unless the \fBH\fP option is given. When more than one resource | |
5039 | is specified, the limit name and unit is printed before the value. | |
5040 | Other options are interpreted as follows: | |
5041 | .RS | |
5042 | .PD 0 | |
5043 | .TP | |
5044 | .B \-a | |
5045 | all current limits are reported | |
5046 | .TP | |
5047 | .B \-c | |
5048 | the maximum size of core files created | |
5049 | .TP | |
5050 | .B \-d | |
5051 | the maximum size of a process's data segment | |
5052 | .TP | |
5053 | .B \-f | |
5054 | the maximum size of files created by the shell | |
5055 | .TP | |
5056 | .B \-m | |
5057 | the maximum resident set size | |
5058 | .TP | |
5059 | .B \-s | |
5060 | the maximum stack size | |
5061 | .TP | |
5062 | .B \-t | |
5063 | the maximum amount of cpu time in seconds | |
5064 | .TP | |
5065 | .B \-p | |
5066 | the pipe size in 512-byte blocks (this may not be set) | |
5067 | .TP | |
5068 | .B \-n | |
5069 | the maximum number of open file descriptors (most systems do not | |
5070 | allow this value to be set, only displayed) | |
5071 | .TP | |
5072 | .B \-u | |
5073 | the maximum number of processes available to a single user | |
5074 | .TP | |
5075 | .B \-v | |
5076 | The maximum amount of virtual memory available to the shell | |
5077 | .PD | |
5078 | .PP | |
5079 | An argument of | |
5080 | .B \-\- | |
5081 | disables option checking for the rest of the arguments. If | |
5082 | .I limit | |
5083 | is given, it is the new value of the specified resource (the | |
5084 | .B \-a | |
5085 | option is display only). | |
5086 | If no option is given, then | |
5087 | .B \-f | |
5088 | is assumed. Values are in 1024-byte increments, except for | |
5089 | .BR \-t , | |
5090 | which is in seconds, | |
5091 | .BR \-p , | |
5092 | which is in units of 512-byte blocks, | |
5093 | and | |
5094 | .B \-n | |
5095 | and | |
5096 | .BR \-u , | |
5097 | which are unscaled values. The return status is 0 | |
5098 | unless an illegal option is encountered, a non-numeric argument | |
5099 | other than \fBunlimited\fP is supplied as \fIlimit\fP, or an | |
5100 | error occurs while setting a new limit. | |
5101 | .RE | |
5102 | .TP | |
5103 | \fBumask\fP [\fB\-S\fP] [\fImode\fP] | |
5104 | The user file-creation mask is set to | |
5105 | .IR mode . | |
5106 | If | |
5107 | .I mode | |
5108 | begins with a digit, it | |
5109 | is interpreted as an octal number; otherwise | |
5110 | it is interpreted as a symbolic mode mask similar | |
5111 | to that accepted by | |
5112 | .IR chmod (1). | |
5113 | If | |
5114 | .I mode | |
5115 | is omitted, or if the | |
5116 | .B \-S | |
5117 | option is supplied, the | |
5118 | current value of the mask is printed. The | |
5119 | .B \-S | |
5120 | option causes the mask to be printed in symbolic form; the | |
5121 | default output is an octal number. | |
5122 | An argument of | |
5123 | .B \-\- | |
5124 | disables option checking for the rest of the arguments. The | |
5125 | return status is 0 if the mode was successfully changed or if | |
5126 | no \fImode\fP argument was supplied, and false otherwise. | |
5127 | .TP | |
5128 | \fBunalias\fP [\-\fBa\fP] [\fIname\fP ...] | |
5129 | Remove \fIname\fPs from the list of defined aliases. If | |
5130 | .B \-a | |
5131 | is supplied, all alias definitions are removed. The return | |
5132 | value is true unless a supplied | |
5133 | .I name | |
5134 | is not a defined alias. | |
5135 | .TP | |
5136 | \fBunset\fP [\-\fBfv\fP] [\fIname\fP ...] | |
5137 | For each | |
5138 | .IR name , | |
5139 | remove the corresponding variable or, given the | |
5140 | .B \-f | |
5141 | option, function. | |
5142 | An argument of | |
5143 | .B \-\- | |
5144 | disables option checking for the rest of the arguments. | |
5145 | Note that | |
5146 | .SM | |
5147 | .BR PATH , | |
5148 | .SM | |
5149 | .BR IFS , | |
5150 | .SM | |
5151 | .BR PPID , | |
5152 | .SM | |
5153 | .BR PS1 , | |
5154 | .SM | |
5155 | .BR PS2 , | |
5156 | .SM | |
5157 | .BR UID , | |
5158 | and | |
5159 | .SM | |
5160 | .B EUID | |
5161 | cannot be unset. If any of | |
5162 | .SM | |
5163 | .BR RANDOM , | |
5164 | .SM | |
5165 | .BR SECONDS , | |
5166 | .SM | |
5167 | .BR LINENO , | |
5168 | or | |
5169 | .SM | |
5170 | .B HISTCMD | |
5171 | are unset, they lose their special properties, even if they are | |
5172 | subsequently reset. The exit status is true unless a | |
5173 | .I name | |
5174 | does not exist or is non-unsettable. | |
5175 | .TP | |
5176 | \fBwait\fP [\fIn\fP] | |
5177 | Wait for the specified process and return its termination | |
5178 | status. | |
5179 | .I n | |
5180 | may be a process | |
5181 | ID or a job specification; if a job spec is given, all processes | |
5182 | in that job's pipeline are waited for. If | |
5183 | .I n | |
5184 | is not given, all currently active child processes | |
5185 | are waited for, and the return status is zero. If | |
5186 | .I n | |
5187 | specifies a non-existant process or job, the return status is | |
5188 | 127. Otherwise, the return status is the exit status of the last | |
5189 | process or job waited for. | |
5190 | .\" bash_builtins | |
5191 | .if \n(zZ=1 .ig zZ | |
5192 | .SH INVOCATION | |
5193 | A \fIlogin shell\fP is one whose first character of argument zero is a | |
5194 | .BR \- , | |
5195 | or one started with the | |
5196 | .B \-login | |
5197 | flag. | |
5198 | .PP | |
5199 | An \fIinteractive\fP shell is one whose standard input and output are | |
5200 | both connected to terminals (as determined by | |
5201 | .IR isatty (3)), | |
5202 | or one started with the | |
5203 | .B \-i | |
5204 | option. | |
5205 | .SM | |
5206 | .B PS1 | |
5207 | is set and | |
5208 | .B $\- | |
5209 | includes | |
5210 | .B i | |
5211 | if | |
5212 | .B bash | |
5213 | is interactive, | |
5214 | allowing a shell script or a startup file to test this state. | |
5215 | .PP | |
5216 | .nf | |
5217 | Login shells: | |
5218 | On login (subject to the \fB\-noprofile\fP option): | |
5219 | if \fI/etc/profile\fP exists, source it. | |
5220 | ||
5221 | if \fI~/.bash_profile\fP exists, source it, | |
5222 | else if \fI~/.bash_login\fP exists, source it, | |
5223 | else if \fI~/.profile\fP exists, source it. | |
5224 | ||
5225 | On exit: | |
5226 | if \fI~/.bash_logout\fP exists, source it. | |
5227 | ||
5228 | Non-login interactive shells: | |
5229 | On startup (subject to the \fB\-norc\fP and \fB\-rcfile\fP options): | |
5230 | if \fI~/.bashrc\fP exists, source it. | |
5231 | ||
5232 | Non-interactive shells: | |
5233 | On startup: | |
5234 | if the environment variable \fBENV\fP is non-null, expand | |
5235 | it and source the file it names, as if the command | |
5236 | if [ "$ENV" ]; then . $ENV; fi | |
5237 | had been executed, but do not use \fBPATH\fP to search | |
5238 | for the pathname. When not started in Posix mode, bash | |
5239 | looks for \fBBASH_ENV\fP before \fBENV\fP. | |
5240 | .PP | |
5241 | .fi | |
5242 | .PP | |
5243 | If Bash is invoked as | |
5244 | .BR sh , | |
5245 | it tries to mimic the behavior of | |
5246 | .B sh | |
5247 | as closely as possible. For a login shell, it attempts to | |
5248 | source only | |
5249 | .I /etc/profile | |
5250 | and | |
5251 | .IR ~/.profile , | |
5252 | in that order. The | |
5253 | .B \-noprofile | |
5254 | option may still be used to disable this behavior. | |
5255 | A shell invoked as | |
5256 | .B sh | |
5257 | does not attempt to source any other startup files. | |
5258 | .PP | |
5259 | When | |
5260 | .B bash | |
5261 | is started in | |
5262 | .I posix | |
5263 | mode, as with the | |
5264 | .B \-posix | |
5265 | command line option, it follows the Posix standard for | |
5266 | startup files. In this mode, the | |
5267 | .B ENV | |
5268 | variable is expanded and that file sourced; no other startup | |
5269 | files are read. | |
5270 | .SH "SEE ALSO" | |
5271 | .PD 0 | |
5272 | .TP | |
5273 | \fIBash Features\fP, Brian Fox and Chet Ramey | |
5274 | .TP | |
5275 | \fIThe Gnu Readline Library\fP, Brian Fox and Chet Ramey | |
5276 | .TP | |
5277 | \fIThe Gnu History Library\fP, Brian Fox and Chet Ramey | |
5278 | .TP | |
5279 | \fIA System V Compatible Implementation of 4.2\s-1BSD\s+1 Job Control\fP, David Lennert | |
5280 | .TP | |
5281 | \fIPortable Operating System Interface (POSIX) Part 2: Shell and Utilities\fP, IEEE | |
5282 | .TP | |
5283 | \fIsh\fP(1), \fIksh\fP(1), \fIcsh\fP(1) | |
5284 | .TP | |
5285 | \fIemacs\fP(1), \fIvi\fP(1) | |
5286 | .TP | |
5287 | \fIreadline\fP(3) | |
5288 | .PD | |
5289 | .SH FILES | |
5290 | .PD 0 | |
5291 | .TP | |
5292 | .FN /bin/bash | |
5293 | The \fBbash\fP executable | |
5294 | .TP | |
5295 | .FN /etc/profile | |
5296 | The systemwide initialization file, executed for login shells | |
5297 | .TP | |
5298 | .FN ~/.bash_profile | |
5299 | The personal initialization file, executed for login shells | |
5300 | .TP | |
5301 | .FN ~/.bashrc | |
5302 | The individual per-interactive-shell startup file | |
5303 | .TP | |
5304 | .FN ~/.inputrc | |
5305 | Individual \fIreadline\fP initialization file | |
5306 | .PD | |
5307 | .SH AUTHORS | |
5308 | .RS | |
5309 | Brian Fox, Free Software Foundation (primary author) | |
5310 | .br | |
5311 | bfox@ai.MIT.Edu | |
5312 | .PP | |
5313 | Chet Ramey, Case Western Reserve University | |
5314 | .br | |
5315 | chet@ins.CWRU.Edu | |
5316 | .SH BUG REPORTS | |
5317 | If you find a bug in | |
5318 | .B bash, | |
5319 | you should report it. But first, you should | |
5320 | make sure that it really is a bug, and that it appears in the latest | |
5321 | version of | |
5322 | .B bash | |
5323 | that you have. | |
5324 | .PP | |
5325 | Once you have determined that a bug actually exists, use the | |
5326 | .I bashbug | |
5327 | command to submit a bug report. | |
5328 | If you have a fix, you are welcome to mail that | |
5329 | as well! | |
5330 | Suggestions and `philosophical' bug reports may be mailed | |
5331 | to \fPbug-bash\fP@\fIprep.ai.MIT.Edu\fP or posted to the Usenet | |
5332 | newsgroup | |
5333 | .BR gnu.bash.bug . | |
5334 | .PP | |
5335 | ALL bug reports should include: | |
5336 | .PP | |
5337 | .PD 0 | |
5338 | .TP 20 | |
5339 | The version number of \fBbash\fR | |
5340 | .TP | |
5341 | The hardware and operating system | |
5342 | .TP | |
5343 | The compiler used to compile | |
5344 | .TP | |
5345 | A description of the bug behaviour | |
5346 | .TP | |
5347 | A short script or `recipe' which exercises the bug | |
5348 | .PD | |
5349 | .PP | |
5350 | .I bashbug | |
5351 | inserts the first three items automatically into the template | |
5352 | it provides for filing a bug report. | |
5353 | .PP | |
5354 | Comments and bug reports concerning | |
5355 | this manual page should be directed to | |
5356 | .IR chet@ins.CWRU.Edu . | |
5357 | .SH BUGS | |
5358 | .PP | |
5359 | It's too big and too slow. | |
5360 | .PP | |
5361 | There are some subtle differences between | |
5362 | .B bash | |
5363 | and traditional versions of | |
5364 | .BR sh , | |
5365 | mostly because of the | |
5366 | .SM | |
5367 | .B POSIX | |
5368 | specification. | |
5369 | .PP | |
5370 | Aliases are confusing in some uses. | |
5371 | .zZ |