]>
Commit | Line | Data |
---|---|---|
db31fb26 | 1 | This is bashref.info, produced by makeinfo version 4.13 from |
abe2eb5b | 2 | /usr/homes/chet/src/bash/src/doc/bashref.texi. |
e8ce775d | 3 | |
6a8fd0ed | 4 | This text is a brief description of the features that are present in |
abe2eb5b | 5 | the Bash shell (version 4.2, 29 January 2012). |
d3a24ed2 | 6 | |
abe2eb5b | 7 | This is Edition 4.2, last updated 29 January 2012, of `The GNU Bash |
77638cbf | 8 | Reference Manual', for `Bash', Version 4.2. |
d3a24ed2 | 9 | |
abe2eb5b | 10 | Copyright (C) 1988-2012 Free Software Foundation, Inc. |
d3a24ed2 CR |
11 | |
12 | Permission is granted to make and distribute verbatim copies of this | |
13 | manual provided the copyright notice and this permission notice are | |
14 | preserved on all copies. | |
15 | ||
16 | Permission is granted to copy, distribute and/or modify this | |
17 | document under the terms of the GNU Free Documentation License, | |
c302751c | 18 | Version 1.3 or any later version published by the Free Software |
d3a24ed2 | 19 | Foundation; with no Invariant Sections, with the Front-Cover texts |
c2a47ea9 | 20 | being "A GNU Manual", and with the Back-Cover Texts as in (a) |
d3a24ed2 | 21 | below. A copy of the license is included in the section entitled |
c2a47ea9 | 22 | "GNU Free Documentation License". |
d3a24ed2 | 23 | |
a9fac3b2 CR |
24 | (a) The FSF's Back-Cover Text is: You are free to copy and modify |
25 | this GNU manual. Buying copies from GNU Press supports the FSF in | |
26 | developing GNU and promoting software freedom." | |
29d25b54 | 27 | |
37c41ab1 | 28 | |
d3a24ed2 | 29 | INFO-DIR-SECTION Basics |
e8ce775d | 30 | START-INFO-DIR-ENTRY |
cce855bc | 31 | * Bash: (bash). The GNU Bourne-Again SHell. |
e8ce775d | 32 | END-INFO-DIR-ENTRY |
ccc6cda3 | 33 | |
ccc6cda3 JA |
34 | \1f |
35 | File: bashref.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) | |
36 | ||
37 | Bash Features | |
38 | ************* | |
39 | ||
37c41ab1 | 40 | This text is a brief description of the features that are present in |
abe2eb5b | 41 | the Bash shell (version 4.2, 29 January 2012). |
ccc6cda3 | 42 | |
abe2eb5b | 43 | This is Edition 4.2, last updated 29 January 2012, of `The GNU Bash |
77638cbf | 44 | Reference Manual', for `Bash', Version 4.2. |
ccc6cda3 JA |
45 | |
46 | Bash contains features that appear in other popular shells, and some | |
47 | features that only appear in Bash. Some of the shells that Bash has | |
48 | borrowed concepts from are the Bourne Shell (`sh'), the Korn Shell | |
122f603c | 49 | (`ksh'), and the C-shell (`csh' and its successor, `tcsh'). The |
ccc6cda3 JA |
50 | following menu breaks the features up into categories based upon which |
51 | one of these other shells inspired the feature. | |
52 | ||
53 | This manual is meant as a brief introduction to features found in | |
54 | Bash. The Bash manual page should be used as the definitive reference | |
55 | on shell behavior. | |
56 | ||
57 | * Menu: | |
58 | ||
59 | * Introduction:: An introduction to the shell. | |
ccc6cda3 JA |
60 | * Definitions:: Some definitions used in the rest of this |
61 | manual. | |
ccc6cda3 | 62 | * Basic Shell Features:: The shell "building blocks". |
bb70624e | 63 | * Shell Builtin Commands:: Commands that are a part of the shell. |
bb70624e | 64 | * Shell Variables:: Variables used or set by Bash. |
ccc6cda3 | 65 | * Bash Features:: Features found only in Bash. |
1c72c0cd CR |
66 | * Job Control:: What job control is and how Bash allows you |
67 | to use it. | |
ccc6cda3 JA |
68 | * Command Line Editing:: Chapter describing the command line |
69 | editing features. | |
c2a47ea9 | 70 | * Using History Interactively:: Command History Expansion |
ccc6cda3 | 71 | * Installing Bash:: How to build and install Bash on your system. |
ccc6cda3 | 72 | * Reporting Bugs:: How to report bugs in Bash. |
bb70624e JA |
73 | * Major Differences From The Bourne Shell:: A terse list of the differences |
74 | between Bash and historical | |
75 | versions of /bin/sh. | |
c2a47ea9 | 76 | * GNU Free Documentation License:: Copying and sharing this documentation. |
d3ad40de | 77 | * Indexes:: Various indexes for this manual. |
ccc6cda3 JA |
78 | |
79 | \1f | |
80 | File: bashref.info, Node: Introduction, Next: Definitions, Prev: Top, Up: Top | |
81 | ||
37c41ab1 CR |
82 | 1 Introduction |
83 | ************** | |
ccc6cda3 JA |
84 | |
85 | * Menu: | |
86 | ||
87 | * What is Bash?:: A short description of Bash. | |
ccc6cda3 JA |
88 | * What is a shell?:: A brief introduction to shells. |
89 | ||
90 | \1f | |
91 | File: bashref.info, Node: What is Bash?, Next: What is a shell?, Up: Introduction | |
92 | ||
37c41ab1 CR |
93 | 1.1 What is Bash? |
94 | ================= | |
ccc6cda3 | 95 | |
37c41ab1 | 96 | Bash is the shell, or command language interpreter, for the GNU |
bb70624e JA |
97 | operating system. The name is an acronym for the `Bourne-Again SHell', |
98 | a pun on Stephen Bourne, the author of the direct ancestor of the | |
d3a24ed2 CR |
99 | current Unix shell `sh', which appeared in the Seventh Edition Bell |
100 | Labs Research version of Unix. | |
ccc6cda3 | 101 | |
bb70624e JA |
102 | Bash is largely compatible with `sh' and incorporates useful |
103 | features from the Korn shell `ksh' and the C shell `csh'. It is | |
104 | intended to be a conformant implementation of the IEEE POSIX Shell and | |
ac18b312 CR |
105 | Tools portion of the IEEE POSIX specification (IEEE Standard 1003.1). |
106 | It offers functional improvements over `sh' for both interactive and | |
107 | programming use. | |
ccc6cda3 | 108 | |
bb70624e JA |
109 | While the GNU operating system provides other shells, including a |
110 | version of `csh', Bash is the default shell. Like other GNU software, | |
111 | Bash is quite portable. It currently runs on nearly every version of | |
112 | Unix and a few other operating systems - independently-supported ports | |
d3a24ed2 | 113 | exist for MS-DOS, OS/2, and Windows platforms. |
ccc6cda3 JA |
114 | |
115 | \1f | |
116 | File: bashref.info, Node: What is a shell?, Prev: What is Bash?, Up: Introduction | |
117 | ||
37c41ab1 CR |
118 | 1.2 What is a shell? |
119 | ==================== | |
ccc6cda3 | 120 | |
37c41ab1 | 121 | At its base, a shell is simply a macro processor that executes |
d3a24ed2 CR |
122 | commands. The term macro processor means functionality where text and |
123 | symbols are expanded to create larger expressions. | |
124 | ||
125 | A Unix shell is both a command interpreter and a programming | |
126 | language. As a command interpreter, the shell provides the user | |
127 | interface to the rich set of GNU utilities. The programming language | |
d3ad40de | 128 | features allow these utilities to be combined. Files containing |
cce855bc | 129 | commands can be created, and become commands themselves. These new |
bb70624e | 130 | commands have the same status as system commands in directories such as |
d3a24ed2 CR |
131 | `/bin', allowing users or groups to establish custom environments to |
132 | automate their common tasks. | |
133 | ||
134 | Shells may be used interactively or non-interactively. In | |
135 | interactive mode, they accept input typed from the keyboard. When | |
136 | executing non-interactively, shells execute commands read from a file. | |
ccc6cda3 | 137 | |
bb70624e | 138 | A shell allows execution of GNU commands, both synchronously and |
cce855bc JA |
139 | asynchronously. The shell waits for synchronous commands to complete |
140 | before accepting more input; asynchronous commands continue to execute | |
141 | in parallel with the shell while it reads and executes additional | |
142 | commands. The "redirection" constructs permit fine-grained control of | |
bb70624e | 143 | the input and output of those commands. Moreover, the shell allows |
d3a24ed2 | 144 | control over the contents of commands' environments. |
bb70624e JA |
145 | |
146 | Shells also provide a small set of built-in commands ("builtins") | |
147 | implementing functionality impossible or inconvenient to obtain via | |
74d0116b CR |
148 | separate utilities. For example, `cd', `break', `continue', and `exec' |
149 | cannot be implemented outside of the shell because they directly | |
150 | manipulate the shell itself. The `history', `getopts', `kill', or `pwd' | |
151 | builtins, among others, could be implemented in separate utilities, but | |
152 | they are more convenient to use as builtin commands. All of the shell | |
153 | builtins are described in subsequent sections. | |
ccc6cda3 JA |
154 | |
155 | While executing commands is essential, most of the power (and | |
156 | complexity) of shells is due to their embedded programming languages. | |
157 | Like any high-level language, the shell provides variables, flow | |
158 | control constructs, quoting, and functions. | |
159 | ||
bb70624e JA |
160 | Shells offer features geared specifically for interactive use rather |
161 | than to augment the programming language. These interactive features | |
d3a24ed2 CR |
162 | include job control, command line editing, command history and aliases. |
163 | Each of these features is described in this manual. | |
ccc6cda3 JA |
164 | |
165 | \1f | |
166 | File: bashref.info, Node: Definitions, Next: Basic Shell Features, Prev: Introduction, Up: Top | |
167 | ||
37c41ab1 CR |
168 | 2 Definitions |
169 | ************* | |
ccc6cda3 | 170 | |
37c41ab1 | 171 | These definitions are used throughout the remainder of this manual. |
ccc6cda3 JA |
172 | |
173 | `POSIX' | |
174 | A family of open system standards based on Unix. Bash is | |
ac18b312 CR |
175 | primarily concerned with the Shell and Utilities portion of the |
176 | POSIX 1003.1 standard. | |
ccc6cda3 JA |
177 | |
178 | `blank' | |
179 | A space or tab character. | |
180 | ||
181 | `builtin' | |
182 | A command that is implemented internally by the shell itself, | |
183 | rather than by an executable program somewhere in the file system. | |
184 | ||
185 | `control operator' | |
3d4e09aa | 186 | A `token' that performs a control function. It is a `newline' or |
ed35cb4a CR |
187 | one of the following: `||', `&&', `&', `;', `;;', `|', `|&', `(', |
188 | or `)'. | |
ccc6cda3 JA |
189 | |
190 | `exit status' | |
f73dda09 JA |
191 | The value returned by a command to its caller. The value is |
192 | restricted to eight bits, so the maximum value is 255. | |
ccc6cda3 JA |
193 | |
194 | `field' | |
195 | A unit of text that is the result of one of the shell expansions. | |
196 | After expansion, when executing a command, the resulting fields | |
197 | are used as the command name and arguments. | |
198 | ||
199 | `filename' | |
200 | A string of characters used to identify a file. | |
201 | ||
202 | `job' | |
203 | A set of processes comprising a pipeline, and any processes | |
204 | descended from it, that are all in the same process group. | |
205 | ||
206 | `job control' | |
d166f048 JA |
207 | A mechanism by which users can selectively stop (suspend) and |
208 | restart (resume) execution of processes. | |
ccc6cda3 JA |
209 | |
210 | `metacharacter' | |
211 | A character that, when unquoted, separates words. A metacharacter | |
212 | is a `blank' or one of the following characters: `|', `&', `;', | |
213 | `(', `)', `<', or `>'. | |
214 | ||
215 | `name' | |
216 | A `word' consisting solely of letters, numbers, and underscores, | |
217 | and beginning with a letter or underscore. `Name's are used as | |
218 | shell variable and function names. Also referred to as an | |
219 | `identifier'. | |
220 | ||
221 | `operator' | |
222 | A `control operator' or a `redirection operator'. *Note | |
a9fac3b2 CR |
223 | Redirections::, for a list of redirection operators. Operators |
224 | contain at least one unquoted `metacharacter'. | |
ccc6cda3 JA |
225 | |
226 | `process group' | |
227 | A collection of related processes each having the same process | |
228 | group ID. | |
229 | ||
230 | `process group ID' | |
d3ad40de | 231 | A unique identifier that represents a `process group' during its |
ccc6cda3 JA |
232 | lifetime. |
233 | ||
234 | `reserved word' | |
235 | A `word' that has a special meaning to the shell. Most reserved | |
236 | words introduce shell flow control constructs, such as `for' and | |
237 | `while'. | |
238 | ||
239 | `return status' | |
240 | A synonym for `exit status'. | |
241 | ||
242 | `signal' | |
bb70624e | 243 | A mechanism by which a process may be notified by the kernel of an |
ccc6cda3 JA |
244 | event occurring in the system. |
245 | ||
246 | `special builtin' | |
247 | A shell builtin command that has been classified as special by the | |
ac18b312 | 248 | POSIX standard. |
ccc6cda3 JA |
249 | |
250 | `token' | |
251 | A sequence of characters considered a single unit by the shell. | |
252 | It is either a `word' or an `operator'. | |
253 | ||
254 | `word' | |
a9fac3b2 CR |
255 | A sequence of characters treated as a unit by the shell. Words |
256 | may not include unquoted `metacharacters'. | |
ccc6cda3 JA |
257 | |
258 | \1f | |
bb70624e | 259 | File: bashref.info, Node: Basic Shell Features, Next: Shell Builtin Commands, Prev: Definitions, Up: Top |
ccc6cda3 | 260 | |
37c41ab1 CR |
261 | 3 Basic Shell Features |
262 | ********************** | |
ccc6cda3 | 263 | |
37c41ab1 CR |
264 | Bash is an acronym for `Bourne-Again SHell'. The Bourne shell is the |
265 | traditional Unix shell originally written by Stephen Bourne. All of | |
266 | the Bourne shell builtin commands are available in Bash, The rules for | |
267 | evaluation and quoting are taken from the POSIX specification for the | |
268 | `standard' Unix shell. | |
ccc6cda3 | 269 | |
cce855bc | 270 | This chapter briefly summarizes the shell's `building blocks': |
ccc6cda3 JA |
271 | commands, control structures, shell functions, shell parameters, shell |
272 | expansions, redirections, which are a way to direct input and output | |
273 | from and to named files, and how the shell executes commands. | |
274 | ||
275 | * Menu: | |
276 | ||
277 | * Shell Syntax:: What your input means to the shell. | |
cce855bc | 278 | * Shell Commands:: The types of commands you can use. |
ccc6cda3 | 279 | * Shell Functions:: Grouping commands by name. |
d3a24ed2 CR |
280 | * Shell Parameters:: How the shell stores values. |
281 | * Shell Expansions:: How Bash expands parameters and the various | |
ccc6cda3 JA |
282 | expansions available. |
283 | * Redirections:: A way to control where input and output go. | |
284 | * Executing Commands:: What happens when you run a command. | |
285 | * Shell Scripts:: Executing files of shell commands. | |
286 | ||
287 | \1f | |
cce855bc | 288 | File: bashref.info, Node: Shell Syntax, Next: Shell Commands, Up: Basic Shell Features |
ccc6cda3 | 289 | |
37c41ab1 CR |
290 | 3.1 Shell Syntax |
291 | ================ | |
ccc6cda3 JA |
292 | |
293 | * Menu: | |
294 | ||
295 | * Shell Operation:: The basic operation of the shell. | |
ccc6cda3 | 296 | * Quoting:: How to remove the special meaning from characters. |
ccc6cda3 JA |
297 | * Comments:: How to specify comments. |
298 | ||
bb70624e JA |
299 | When the shell reads input, it proceeds through a sequence of |
300 | operations. If the input indicates the beginning of a comment, the | |
301 | shell ignores the comment symbol (`#'), and the rest of that line. | |
302 | ||
303 | Otherwise, roughly speaking, the shell reads its input and divides | |
304 | the input into words and operators, employing the quoting rules to | |
305 | select which meanings to assign various words and characters. | |
306 | ||
307 | The shell then parses these tokens into commands and other | |
308 | constructs, removes the special meaning of certain words or characters, | |
309 | expands others, redirects input and output as needed, executes the | |
310 | specified command, waits for the command's exit status, and makes that | |
311 | exit status available for further inspection or processing. | |
312 | ||
ccc6cda3 JA |
313 | \1f |
314 | File: bashref.info, Node: Shell Operation, Next: Quoting, Up: Shell Syntax | |
315 | ||
37c41ab1 CR |
316 | 3.1.1 Shell Operation |
317 | --------------------- | |
ccc6cda3 | 318 | |
37c41ab1 | 319 | The following is a brief description of the shell's operation when it |
ccc6cda3 JA |
320 | reads and executes a command. Basically, the shell does the following: |
321 | ||
28ef6c31 | 322 | 1. Reads its input from a file (*note Shell Scripts::), from a string |
ccc6cda3 | 323 | supplied as an argument to the `-c' invocation option (*note |
28ef6c31 | 324 | Invoking Bash::), or from the user's terminal. |
ccc6cda3 JA |
325 | |
326 | 2. Breaks the input into words and operators, obeying the quoting | |
6a8fd0ed | 327 | rules described in *note Quoting::. These tokens are separated by |
ccc6cda3 | 328 | `metacharacters'. Alias expansion is performed by this step |
28ef6c31 | 329 | (*note Aliases::). |
ccc6cda3 | 330 | |
cce855bc | 331 | 3. Parses the tokens into simple and compound commands (*note Shell |
28ef6c31 | 332 | Commands::). |
ccc6cda3 | 333 | |
28ef6c31 | 334 | 4. Performs the various shell expansions (*note Shell Expansions::), |
ccc6cda3 | 335 | breaking the expanded tokens into lists of filenames (*note |
28ef6c31 | 336 | Filename Expansion::) and commands and arguments. |
ccc6cda3 | 337 | |
28ef6c31 | 338 | 5. Performs any necessary redirections (*note Redirections::) and |
ccc6cda3 JA |
339 | removes the redirection operators and their operands from the |
340 | argument list. | |
341 | ||
28ef6c31 | 342 | 6. Executes the command (*note Executing Commands::). |
ccc6cda3 JA |
343 | |
344 | 7. Optionally waits for the command to complete and collects its exit | |
28ef6c31 | 345 | status (*note Exit Status::). |
ccc6cda3 JA |
346 | |
347 | ||
348 | \1f | |
349 | File: bashref.info, Node: Quoting, Next: Comments, Prev: Shell Operation, Up: Shell Syntax | |
350 | ||
37c41ab1 CR |
351 | 3.1.2 Quoting |
352 | ------------- | |
ccc6cda3 JA |
353 | |
354 | * Menu: | |
355 | ||
356 | * Escape Character:: How to remove the special meaning from a single | |
357 | character. | |
358 | * Single Quotes:: How to inhibit all interpretation of a sequence | |
359 | of characters. | |
360 | * Double Quotes:: How to suppress most of the interpretation of a | |
361 | sequence of characters. | |
362 | * ANSI-C Quoting:: How to expand ANSI-C sequences in quoted strings. | |
ccc6cda3 JA |
363 | * Locale Translation:: How to translate strings into different languages. |
364 | ||
365 | Quoting is used to remove the special meaning of certain characters | |
366 | or words to the shell. Quoting can be used to disable special | |
367 | treatment for special characters, to prevent reserved words from being | |
368 | recognized as such, and to prevent parameter expansion. | |
369 | ||
28ef6c31 | 370 | Each of the shell metacharacters (*note Definitions::) has special |
cce855bc | 371 | meaning to the shell and must be quoted if it is to represent itself. |
01ed5ba4 CR |
372 | When the command history expansion facilities are being used (*note |
373 | History Interaction::), the HISTORY EXPANSION character, usually `!', | |
374 | must be quoted to prevent history expansion. *Note Bash History | |
375 | Facilities::, for more details concerning history expansion. | |
d3a24ed2 CR |
376 | |
377 | There are three quoting mechanisms: the ESCAPE CHARACTER, single | |
378 | quotes, and double quotes. | |
ccc6cda3 JA |
379 | |
380 | \1f | |
381 | File: bashref.info, Node: Escape Character, Next: Single Quotes, Up: Quoting | |
382 | ||
37c41ab1 CR |
383 | 3.1.2.1 Escape Character |
384 | ........................ | |
ccc6cda3 | 385 | |
37c41ab1 CR |
386 | A non-quoted backslash `\' is the Bash escape character. It preserves |
387 | the literal value of the next character that follows, with the | |
388 | exception of `newline'. If a `\newline' pair appears, and the | |
cce855bc JA |
389 | backslash itself is not quoted, the `\newline' is treated as a line |
390 | continuation (that is, it is removed from the input stream and | |
391 | effectively ignored). | |
ccc6cda3 JA |
392 | |
393 | \1f | |
394 | File: bashref.info, Node: Single Quotes, Next: Double Quotes, Prev: Escape Character, Up: Quoting | |
395 | ||
37c41ab1 CR |
396 | 3.1.2.2 Single Quotes |
397 | ..................... | |
ccc6cda3 | 398 | |
37c41ab1 CR |
399 | Enclosing characters in single quotes (`'') preserves the literal value |
400 | of each character within the quotes. A single quote may not occur | |
bb70624e | 401 | between single quotes, even when preceded by a backslash. |
ccc6cda3 JA |
402 | |
403 | \1f | |
404 | File: bashref.info, Node: Double Quotes, Next: ANSI-C Quoting, Prev: Single Quotes, Up: Quoting | |
405 | ||
37c41ab1 CR |
406 | 3.1.2.3 Double Quotes |
407 | ..................... | |
ccc6cda3 | 408 | |
37c41ab1 CR |
409 | Enclosing characters in double quotes (`"') preserves the literal value |
410 | of all characters within the quotes, with the exception of `$', ``', | |
01ed5ba4 CR |
411 | `\', and, when history expansion is enabled, `!'. The characters `$' |
412 | and ``' retain their special meaning within double quotes (*note Shell | |
413 | Expansions::). The backslash retains its special meaning only when | |
414 | followed by one of the following characters: `$', ``', `"', `\', or | |
415 | `newline'. Within double quotes, backslashes that are followed by one | |
416 | of these characters are removed. Backslashes preceding characters | |
417 | without a special meaning are left unmodified. A double quote may be | |
418 | quoted within double quotes by preceding it with a backslash. If | |
419 | enabled, history expansion will be performed unless an `!' appearing in | |
420 | double quotes is escaped using a backslash. The backslash preceding | |
421 | the `!' is not removed. | |
ccc6cda3 JA |
422 | |
423 | The special parameters `*' and `@' have special meaning when in | |
28ef6c31 | 424 | double quotes (*note Shell Parameter Expansion::). |
ccc6cda3 JA |
425 | |
426 | \1f | |
427 | File: bashref.info, Node: ANSI-C Quoting, Next: Locale Translation, Prev: Double Quotes, Up: Quoting | |
428 | ||
37c41ab1 CR |
429 | 3.1.2.4 ANSI-C Quoting |
430 | ...................... | |
ccc6cda3 | 431 | |
37c41ab1 CR |
432 | Words of the form `$'STRING'' are treated specially. The word expands |
433 | to STRING, with backslash-escaped characters replaced as specified by | |
434 | the ANSI C standard. Backslash escape sequences, if present, are | |
435 | decoded as follows: | |
ccc6cda3 JA |
436 | |
437 | `\a' | |
438 | alert (bell) | |
439 | ||
440 | `\b' | |
441 | backspace | |
442 | ||
443 | `\e' | |
984a1947 | 444 | `\E' |
ccc6cda3 JA |
445 | an escape character (not ANSI C) |
446 | ||
447 | `\f' | |
448 | form feed | |
449 | ||
450 | `\n' | |
451 | newline | |
452 | ||
453 | `\r' | |
454 | carriage return | |
455 | ||
456 | `\t' | |
457 | horizontal tab | |
458 | ||
459 | `\v' | |
460 | vertical tab | |
461 | ||
462 | `\\' | |
463 | backslash | |
464 | ||
bb70624e JA |
465 | `\'' |
466 | single quote | |
467 | ||
984a1947 CR |
468 | `\"' |
469 | double quote | |
470 | ||
ccc6cda3 | 471 | `\NNN' |
f73dda09 | 472 | the eight-bit character whose value is the octal value NNN (one to |
cce855bc JA |
473 | three digits) |
474 | ||
f73dda09 JA |
475 | `\xHH' |
476 | the eight-bit character whose value is the hexadecimal value HH | |
477 | (one or two hex digits) | |
ccc6cda3 | 478 | |
220537f2 CR |
479 | `\uHHHH' |
480 | the Unicode (ISO/IEC 10646) character whose value is the | |
481 | hexadecimal value HHHH (one to four hex digits) | |
482 | ||
483 | `\UHHHHHHHH' | |
484 | the Unicode (ISO/IEC 10646) character whose value is the | |
485 | hexadecimal value HHHHHHHH (one to eight hex digits) | |
486 | ||
7117c2d2 JA |
487 | `\cX' |
488 | a control-X character | |
489 | ||
bb70624e JA |
490 | The expanded result is single-quoted, as if the dollar sign had not |
491 | been present. | |
ccc6cda3 JA |
492 | |
493 | \1f | |
494 | File: bashref.info, Node: Locale Translation, Prev: ANSI-C Quoting, Up: Quoting | |
495 | ||
37c41ab1 CR |
496 | 3.1.2.5 Locale-Specific Translation |
497 | ................................... | |
ccc6cda3 | 498 | |
37c41ab1 CR |
499 | A double-quoted string preceded by a dollar sign (`$') will cause the |
500 | string to be translated according to the current locale. If the | |
ccc6cda3 JA |
501 | current locale is `C' or `POSIX', the dollar sign is ignored. If the |
502 | string is translated and replaced, the replacement is double-quoted. | |
503 | ||
28ef6c31 JA |
504 | Some systems use the message catalog selected by the `LC_MESSAGES' |
505 | shell variable. Others create the name of the message catalog from the | |
506 | value of the `TEXTDOMAIN' shell variable, possibly adding a suffix of | |
507 | `.mo'. If you use the `TEXTDOMAIN' variable, you may need to set the | |
508 | `TEXTDOMAINDIR' variable to the location of the message catalog files. | |
f73dda09 JA |
509 | Still others use both variables in this fashion: |
510 | `TEXTDOMAINDIR'/`LC_MESSAGES'/LC_MESSAGES/`TEXTDOMAIN'.mo. | |
28ef6c31 | 511 | |
ccc6cda3 JA |
512 | \1f |
513 | File: bashref.info, Node: Comments, Prev: Quoting, Up: Shell Syntax | |
514 | ||
37c41ab1 CR |
515 | 3.1.3 Comments |
516 | -------------- | |
ccc6cda3 | 517 | |
37c41ab1 | 518 | In a non-interactive shell, or an interactive shell in which the |
ccc6cda3 | 519 | `interactive_comments' option to the `shopt' builtin is enabled (*note |
d3ad40de CR |
520 | The Shopt Builtin::), a word beginning with `#' causes that word and |
521 | all remaining characters on that line to be ignored. An interactive | |
522 | shell without the `interactive_comments' option enabled does not allow | |
ccc6cda3 | 523 | comments. The `interactive_comments' option is on by default in |
bb70624e JA |
524 | interactive shells. *Note Interactive Shells::, for a description of |
525 | what makes a shell interactive. | |
cce855bc JA |
526 | |
527 | \1f | |
528 | File: bashref.info, Node: Shell Commands, Next: Shell Functions, Prev: Shell Syntax, Up: Basic Shell Features | |
529 | ||
37c41ab1 CR |
530 | 3.2 Shell Commands |
531 | ================== | |
cce855bc | 532 | |
37c41ab1 | 533 | A simple shell command such as `echo a b c' consists of the command |
bb70624e JA |
534 | itself followed by arguments, separated by spaces. |
535 | ||
536 | More complex shell commands are composed of simple commands arranged | |
537 | together in a variety of ways: in a pipeline in which the output of one | |
538 | command becomes the input of a second, in a loop or conditional | |
539 | construct, or in some other grouping. | |
540 | ||
cce855bc JA |
541 | * Menu: |
542 | ||
543 | * Simple Commands:: The most common type of command. | |
544 | * Pipelines:: Connecting the input and output of several | |
545 | commands. | |
546 | * Lists:: How to execute commands sequentially. | |
d3a24ed2 | 547 | * Compound Commands:: Shell commands for control flow. |
8e1a6eaa | 548 | * Coprocesses:: Two-way communication between commands. |
220537f2 | 549 | * GNU Parallel:: Running commands in parallel. |
ccc6cda3 JA |
550 | |
551 | \1f | |
cce855bc | 552 | File: bashref.info, Node: Simple Commands, Next: Pipelines, Up: Shell Commands |
ccc6cda3 | 553 | |
37c41ab1 CR |
554 | 3.2.1 Simple Commands |
555 | --------------------- | |
ccc6cda3 | 556 | |
37c41ab1 CR |
557 | A simple command is the kind of command encountered most often. It's |
558 | just a sequence of words separated by `blank's, terminated by one of | |
559 | the shell's control operators (*note Definitions::). The first word | |
28ef6c31 | 560 | generally specifies a command to be executed, with the rest of the |
bb70624e | 561 | words being that command's arguments. |
ccc6cda3 | 562 | |
28ef6c31 | 563 | The return status (*note Exit Status::) of a simple command is its |
bb70624e JA |
564 | exit status as provided by the POSIX 1003.1 `waitpid' function, or |
565 | 128+N if the command was terminated by signal N. | |
ccc6cda3 JA |
566 | |
567 | \1f | |
cce855bc | 568 | File: bashref.info, Node: Pipelines, Next: Lists, Prev: Simple Commands, Up: Shell Commands |
ccc6cda3 | 569 | |
37c41ab1 CR |
570 | 3.2.2 Pipelines |
571 | --------------- | |
ccc6cda3 | 572 | |
ed35cb4a CR |
573 | A `pipeline' is a sequence of simple commands separated by one of the |
574 | control operators `|' or `|&'. | |
ccc6cda3 JA |
575 | |
576 | The format for a pipeline is | |
122f603c | 577 | [time [-p]] [!] COMMAND1 [ | or |& COMMAND2 ] ... |
ccc6cda3 | 578 | |
f73dda09 JA |
579 | The output of each command in the pipeline is connected via a pipe to |
580 | the input of the next command. That is, each command reads the | |
ed35cb4a CR |
581 | previous command's output. This connection is performed before any |
582 | redirections specified by the command. | |
583 | ||
122f603c CR |
584 | If `|&' is used, COMMAND1's standard output and standard error are |
585 | connected to COMMAND2's standard input through the pipe; it is | |
586 | shorthand for `2>&1 |'. This implicit redirection of the standard | |
587 | error is performed after any redirections specified by the command. | |
ccc6cda3 JA |
588 | |
589 | The reserved word `time' causes timing statistics to be printed for | |
cce855bc JA |
590 | the pipeline once it finishes. The statistics currently consist of |
591 | elapsed (wall-clock) time and user and system time consumed by the | |
592 | command's execution. The `-p' option changes the output format to that | |
9ec5ed66 CR |
593 | specified by POSIX. When the shell is in POSIX mode (*note Bash POSIX |
594 | Mode::), it does not recognize `time' as a reserved word if the next | |
595 | token begins with a `-'. The `TIMEFORMAT' variable may be set to a | |
596 | format string that specifies how the timing information should be | |
597 | displayed. *Note Bash Variables::, for a description of the available | |
598 | formats. The use of `time' as a reserved word permits the timing of | |
599 | shell builtins, shell functions, and pipelines. An external `time' | |
600 | command cannot time these easily. | |
cce855bc | 601 | |
220537f2 CR |
602 | When the shell is in POSIX mode (*note Bash POSIX Mode::), `time' |
603 | may be followed by a newline. In this case, the shell displays the | |
604 | total user and system time consumed by the shell and its children. The | |
605 | `TIMEFORMAT' variable may be used to specify the format of the time | |
606 | information. | |
607 | ||
28ef6c31 | 608 | If the pipeline is not executed asynchronously (*note Lists::), the |
cce855bc | 609 | shell waits for all commands in the pipeline to complete. |
ccc6cda3 | 610 | |
cce855bc | 611 | Each command in a pipeline is executed in its own subshell (*note |
28ef6c31 | 612 | Command Execution Environment::). The exit status of a pipeline is the |
5e13499c CR |
613 | exit status of the last command in the pipeline, unless the `pipefail' |
614 | option is enabled (*note The Set Builtin::). If `pipefail' is enabled, | |
615 | the pipeline's return status is the value of the last (rightmost) | |
616 | command to exit with a non-zero status, or zero if all commands exit | |
617 | successfully. If the reserved word `!' precedes the pipeline, the exit | |
618 | status is the logical negation of the exit status as described above. | |
619 | The shell waits for all commands in the pipeline to terminate before | |
620 | returning a value. | |
ccc6cda3 JA |
621 | |
622 | \1f | |
d3a24ed2 | 623 | File: bashref.info, Node: Lists, Next: Compound Commands, Prev: Pipelines, Up: Shell Commands |
ccc6cda3 | 624 | |
37c41ab1 CR |
625 | 3.2.3 Lists of Commands |
626 | ----------------------- | |
ccc6cda3 | 627 | |
37c41ab1 CR |
628 | A `list' is a sequence of one or more pipelines separated by one of the |
629 | operators `;', `&', `&&', or `||', and optionally terminated by one of | |
630 | `;', `&', or a `newline'. | |
ccc6cda3 JA |
631 | |
632 | Of these list operators, `&&' and `||' have equal precedence, | |
633 | followed by `;' and `&', which have equal precedence. | |
634 | ||
7117c2d2 JA |
635 | A sequence of one or more newlines may appear in a `list' to delimit |
636 | commands, equivalent to a semicolon. | |
637 | ||
ccc6cda3 | 638 | If a command is terminated by the control operator `&', the shell |
cce855bc JA |
639 | executes the command asynchronously in a subshell. This is known as |
640 | executing the command in the BACKGROUND. The shell does not wait for | |
bb70624e | 641 | the command to finish, and the return status is 0 (true). When job |
28ef6c31 | 642 | control is not active (*note Job Control::), the standard input for |
bb70624e JA |
643 | asynchronous commands, in the absence of any explicit redirections, is |
644 | redirected from `/dev/null'. | |
cce855bc JA |
645 | |
646 | Commands separated by a `;' are executed sequentially; the shell | |
647 | waits for each command to terminate in turn. The return status is the | |
648 | exit status of the last command executed. | |
ccc6cda3 | 649 | |
6a8fd0ed CR |
650 | AND and OR lists are sequences of one or more pipelines separated by |
651 | the control operators `&&' and `||', respectively. AND and OR lists | |
652 | are executed with left associativity. | |
653 | ||
654 | An AND list has the form | |
bb70624e | 655 | COMMAND1 && COMMAND2 |
ccc6cda3 | 656 | |
bb70624e JA |
657 | COMMAND2 is executed if, and only if, COMMAND1 returns an exit status |
658 | of zero. | |
ccc6cda3 JA |
659 | |
660 | An OR list has the form | |
bb70624e | 661 | COMMAND1 || COMMAND2 |
ccc6cda3 | 662 | |
bb70624e | 663 | COMMAND2 is executed if, and only if, COMMAND1 returns a non-zero exit |
ccc6cda3 JA |
664 | status. |
665 | ||
666 | The return status of AND and OR lists is the exit status of the last | |
667 | command executed in the list. | |
668 | ||
669 | \1f | |
8e1a6eaa | 670 | File: bashref.info, Node: Compound Commands, Next: Coprocesses, Prev: Lists, Up: Shell Commands |
d3a24ed2 | 671 | |
37c41ab1 CR |
672 | 3.2.4 Compound Commands |
673 | ----------------------- | |
d3a24ed2 CR |
674 | |
675 | * Menu: | |
676 | ||
677 | * Looping Constructs:: Shell commands for iterative action. | |
678 | * Conditional Constructs:: Shell commands for conditional execution. | |
679 | * Command Grouping:: Ways to group commands. | |
680 | ||
681 | Compound commands are the shell programming constructs. Each | |
682 | construct begins with a reserved word or control operator and is | |
683 | terminated by a corresponding reserved word or operator. Any | |
684 | redirections (*note Redirections::) associated with a compound command | |
685 | apply to all commands within that compound command unless explicitly | |
686 | overridden. | |
687 | ||
74d0116b CR |
688 | In most cases a list of commands in a compound command's description |
689 | may be separated from the rest of the command by one or more newlines, | |
690 | and may be followed by a newline in place of a semicolon. | |
691 | ||
d3a24ed2 CR |
692 | Bash provides looping constructs, conditional commands, and |
693 | mechanisms to group commands and execute them as a unit. | |
694 | ||
695 | \1f | |
696 | File: bashref.info, Node: Looping Constructs, Next: Conditional Constructs, Up: Compound Commands | |
ccc6cda3 | 697 | |
37c41ab1 CR |
698 | 3.2.4.1 Looping Constructs |
699 | .......................... | |
ccc6cda3 | 700 | |
37c41ab1 | 701 | Bash supports the following looping constructs. |
ccc6cda3 | 702 | |
bb70624e | 703 | Note that wherever a `;' appears in the description of a command's |
cce855bc JA |
704 | syntax, it may be replaced with one or more newlines. |
705 | ||
ccc6cda3 JA |
706 | `until' |
707 | The syntax of the `until' command is: | |
122f603c | 708 | |
ccc6cda3 | 709 | until TEST-COMMANDS; do CONSEQUENT-COMMANDS; done |
122f603c | 710 | |
cce855bc JA |
711 | Execute CONSEQUENT-COMMANDS as long as TEST-COMMANDS has an exit |
712 | status which is not zero. The return status is the exit status of | |
713 | the last command executed in CONSEQUENT-COMMANDS, or zero if none | |
714 | was executed. | |
ccc6cda3 JA |
715 | |
716 | `while' | |
717 | The syntax of the `while' command is: | |
122f603c | 718 | |
ccc6cda3 JA |
719 | while TEST-COMMANDS; do CONSEQUENT-COMMANDS; done |
720 | ||
cce855bc JA |
721 | Execute CONSEQUENT-COMMANDS as long as TEST-COMMANDS has an exit |
722 | status of zero. The return status is the exit status of the last | |
723 | command executed in CONSEQUENT-COMMANDS, or zero if none was | |
724 | executed. | |
ccc6cda3 JA |
725 | |
726 | `for' | |
727 | The syntax of the `for' command is: | |
728 | ||
4a8bb13f | 729 | for NAME [ [in [WORDS ...] ] ; ] do COMMANDS; done |
122f603c | 730 | |
cce855bc JA |
731 | Expand WORDS, and execute COMMANDS once for each member in the |
732 | resultant list, with NAME bound to the current member. If `in | |
bb70624e JA |
733 | WORDS' is not present, the `for' command executes the COMMANDS |
734 | once for each positional parameter that is set, as if `in "$@"' | |
28ef6c31 | 735 | had been specified (*note Special Parameters::). The return |
bb70624e JA |
736 | status is the exit status of the last command that executes. If |
737 | there are no items in the expansion of WORDS, no commands are | |
738 | executed, and the return status is zero. | |
739 | ||
740 | An alternate form of the `for' command is also supported: | |
741 | ||
742 | for (( EXPR1 ; EXPR2 ; EXPR3 )) ; do COMMANDS ; done | |
122f603c | 743 | |
bb70624e | 744 | First, the arithmetic expression EXPR1 is evaluated according to |
28ef6c31 | 745 | the rules described below (*note Shell Arithmetic::). The |
bb70624e JA |
746 | arithmetic expression EXPR2 is then evaluated repeatedly until it |
747 | evaluates to zero. Each time EXPR2 evaluates to a non-zero value, | |
748 | COMMANDS are executed and the arithmetic expression EXPR3 is | |
749 | evaluated. If any expression is omitted, it behaves as if it | |
750 | evaluates to 1. The return value is the exit status of the last | |
9ec5ed66 | 751 | command in COMMANDS that is executed, or false if any of the |
bb70624e | 752 | expressions is invalid. |
ccc6cda3 | 753 | |
28ef6c31 | 754 | The `break' and `continue' builtins (*note Bourne Shell Builtins::) |
ccc6cda3 JA |
755 | may be used to control loop execution. |
756 | ||
757 | \1f | |
d3a24ed2 | 758 | File: bashref.info, Node: Conditional Constructs, Next: Command Grouping, Prev: Looping Constructs, Up: Compound Commands |
ccc6cda3 | 759 | |
37c41ab1 CR |
760 | 3.2.4.2 Conditional Constructs |
761 | .............................. | |
ccc6cda3 JA |
762 | |
763 | `if' | |
764 | The syntax of the `if' command is: | |
765 | ||
766 | if TEST-COMMANDS; then | |
767 | CONSEQUENT-COMMANDS; | |
768 | [elif MORE-TEST-COMMANDS; then | |
769 | MORE-CONSEQUENTS;] | |
770 | [else ALTERNATE-CONSEQUENTS;] | |
771 | fi | |
772 | ||
cce855bc JA |
773 | The TEST-COMMANDS list is executed, and if its return status is |
774 | zero, the CONSEQUENT-COMMANDS list is executed. If TEST-COMMANDS | |
775 | returns a non-zero status, each `elif' list is executed in turn, | |
776 | and if its exit status is zero, the corresponding MORE-CONSEQUENTS | |
777 | is executed and the command completes. If `else | |
778 | ALTERNATE-CONSEQUENTS' is present, and the final command in the | |
779 | final `if' or `elif' clause has a non-zero exit status, then | |
780 | ALTERNATE-CONSEQUENTS is executed. The return status is the exit | |
781 | status of the last command executed, or zero if no condition | |
782 | tested true. | |
ccc6cda3 JA |
783 | |
784 | `case' | |
785 | The syntax of the `case' command is: | |
786 | ||
122f603c | 787 | case WORD in [ [(] PATTERN [| PATTERN]...) COMMAND-LIST ;;]... esac |
ccc6cda3 | 788 | |
cce855bc | 789 | `case' will selectively execute the COMMAND-LIST corresponding to |
9d2b70f0 | 790 | the first PATTERN that matches WORD. If the shell option |
6a8fd0ed | 791 | `nocasematch' (see the description of `shopt' in *note The Shopt |
d3ad40de | 792 | Builtin::) is enabled, the match is performed without regard to |
9d2b70f0 | 793 | the case of alphabetic characters. The `|' is used to separate |
cce855bc JA |
794 | multiple patterns, and the `)' operator terminates a pattern list. |
795 | A list of patterns and an associated command-list is known as a | |
ed35cb4a CR |
796 | CLAUSE. |
797 | ||
c302751c | 798 | Each clause must be terminated with `;;', `;&', or `;;&'. The |
ed35cb4a | 799 | WORD undergoes tilde expansion, parameter expansion, command |
cce855bc JA |
800 | substitution, arithmetic expansion, and quote removal before |
801 | matching is attempted. Each PATTERN undergoes tilde expansion, | |
802 | parameter expansion, command substitution, and arithmetic | |
803 | expansion. | |
804 | ||
805 | There may be an arbitrary number of `case' clauses, each terminated | |
ed35cb4a CR |
806 | by a `;;', `;&', or `;;&'. The first pattern that matches |
807 | determines the command-list that is executed. | |
ccc6cda3 JA |
808 | |
809 | Here is an example using `case' in a script that could be used to | |
810 | describe one interesting feature of an animal: | |
811 | ||
812 | echo -n "Enter the name of an animal: " | |
813 | read ANIMAL | |
814 | echo -n "The $ANIMAL has " | |
815 | case $ANIMAL in | |
816 | horse | dog | cat) echo -n "four";; | |
817 | man | kangaroo ) echo -n "two";; | |
818 | *) echo -n "an unknown number of";; | |
819 | esac | |
820 | echo " legs." | |
821 | ||
ed35cb4a CR |
822 | If the `;;' operator is used, no subsequent matches are attempted |
823 | after the first pattern match. Using `;&' in place of `;;' | |
824 | causes execution to continue with the COMMAND-LIST associated with | |
825 | the next clause, if any. Using `;;&' in place of `;;' causes the | |
826 | shell to test the patterns in the next clause, if any, and execute | |
827 | any associated COMMAND-LIST on a successful match. | |
828 | ||
cce855bc JA |
829 | The return status is zero if no PATTERN is matched. Otherwise, the |
830 | return status is the exit status of the COMMAND-LIST executed. | |
831 | ||
832 | `select' | |
833 | The `select' construct allows the easy generation of menus. It | |
834 | has almost the same syntax as the `for' command: | |
835 | ||
836 | select NAME [in WORDS ...]; do COMMANDS; done | |
837 | ||
838 | The list of words following `in' is expanded, generating a list of | |
839 | items. The set of expanded words is printed on the standard error | |
840 | output stream, each preceded by a number. If the `in WORDS' is | |
841 | omitted, the positional parameters are printed, as if `in "$@"' | |
d3ad40de | 842 | had been specified. The `PS3' prompt is then displayed and a line |
cce855bc JA |
843 | is read from the standard input. If the line consists of a number |
844 | corresponding to one of the displayed words, then the value of | |
845 | NAME is set to that word. If the line is empty, the words and | |
846 | prompt are displayed again. If `EOF' is read, the `select' | |
847 | command completes. Any other value read causes NAME to be set to | |
848 | null. The line read is saved in the variable `REPLY'. | |
849 | ||
f73dda09 JA |
850 | The COMMANDS are executed after each selection until a `break' |
851 | command is executed, at which point the `select' command completes. | |
cce855bc JA |
852 | |
853 | Here is an example that allows the user to pick a filename from the | |
854 | current directory, and displays the name and index of the file | |
855 | selected. | |
856 | ||
857 | select fname in *; | |
858 | do | |
859 | echo you picked $fname \($REPLY\) | |
860 | break; | |
861 | done | |
862 | ||
ccc6cda3 JA |
863 | `((...))' |
864 | (( EXPRESSION )) | |
865 | ||
cce855bc | 866 | The arithmetic EXPRESSION is evaluated according to the rules |
28ef6c31 | 867 | described below (*note Shell Arithmetic::). If the value of the |
cce855bc JA |
868 | expression is non-zero, the return status is 0; otherwise the |
869 | return status is 1. This is exactly equivalent to | |
ccc6cda3 | 870 | let "EXPRESSION" |
cce855bc JA |
871 | *Note Bash Builtins::, for a full description of the `let' builtin. |
872 | ||
873 | `[[...]]' | |
874 | [[ EXPRESSION ]] | |
875 | ||
876 | Return a status of 0 or 1 depending on the evaluation of the | |
877 | conditional expression EXPRESSION. Expressions are composed of | |
6a8fd0ed | 878 | the primaries described below in *note Bash Conditional |
cce855bc JA |
879 | Expressions::. Word splitting and filename expansion are not |
880 | performed on the words between the `[[' and `]]'; tilde expansion, | |
881 | parameter and variable expansion, arithmetic expansion, command | |
882 | substitution, process substitution, and quote removal are | |
d3a24ed2 CR |
883 | performed. Conditional operators such as `-f' must be unquoted to |
884 | be recognized as primaries. | |
cce855bc | 885 | |
54a1fa7c | 886 | When used with `[[', the `<' and `>' operators sort |
d5362af8 CR |
887 | lexicographically using the current locale. |
888 | ||
cce855bc JA |
889 | When the `==' and `!=' operators are used, the string to the right |
890 | of the operator is considered a pattern and matched according to | |
6a8fd0ed | 891 | the rules described below in *note Pattern Matching::. If the |
9d2b70f0 | 892 | shell option `nocasematch' (see the description of `shopt' in |
6a8fd0ed | 893 | *note The Shopt Builtin::) is enabled, the match is performed |
d3ad40de CR |
894 | without regard to the case of alphabetic characters. The return |
895 | value is 0 if the string matches (`==') or does not match | |
896 | (`!=')the pattern, and 1 otherwise. Any part of the pattern may | |
d9e1f41e | 897 | be quoted to force the quoted portion to be matched as a string. |
cce855bc | 898 | |
5e13499c CR |
899 | An additional binary operator, `=~', is available, with the same |
900 | precedence as `==' and `!='. When it is used, the string to the | |
901 | right of the operator is considered an extended regular expression | |
902 | and matched accordingly (as in regex3)). The return value is 0 if | |
903 | the string matches the pattern, and 1 otherwise. If the regular | |
904 | expression is syntactically incorrect, the conditional | |
9d2b70f0 | 905 | expression's return value is 2. If the shell option `nocasematch' |
6a8fd0ed | 906 | (see the description of `shopt' in *note The Shopt Builtin::) is |
5e13499c | 907 | enabled, the match is performed without regard to the case of |
3d4e09aa | 908 | alphabetic characters. Any part of the pattern may be quoted to |
45c0f7f8 CR |
909 | force the quoted portion to be matched as a string. Bracket |
910 | expressions in regular expressions must be treated carefully, | |
911 | since normal quoting characters lose their meanings between | |
912 | brackets. If the pattern is stored in a shell variable, quoting | |
913 | the variable expansion forces the entire pattern to be matched as | |
914 | a string. Substrings matched by parenthesized subexpressions | |
915 | within the regular expression are saved in the array variable | |
916 | `BASH_REMATCH'. The element of `BASH_REMATCH' with index 0 is the | |
917 | portion of the string matching the entire regular expression. The | |
918 | element of `BASH_REMATCH' with index N is the portion of the | |
919 | string matching the Nth parenthesized subexpression. | |
920 | ||
921 | For example, the following will match a line (stored in the shell | |
922 | variable LINE) if there is a sequence of characters in the value | |
923 | consisting of any number, including zero, of space characters, | |
924 | zero or one instances of `a', then a `b': | |
925 | [[ $line =~ [[:space:]]*(a)?b ]] | |
926 | ||
927 | That means values like `aab' and ` aaaaaab' will match, as will a | |
928 | line containing a `b' anywhere in its value. | |
929 | ||
930 | Storing the regular expression in a shell variable is often a | |
931 | useful way to avoid problems with quoting characters that are | |
932 | special to the shell. It is sometimes difficult to specify a | |
933 | regular expression literally without using quotes, or to keep | |
934 | track of the quoting used by regular expressions while paying | |
935 | attention to the shell's quote removal. Using a shell variable to | |
936 | store the pattern decreases these problems. For example, the | |
937 | following is equivalent to the above: | |
938 | pattern='[[:space:]]*(a)?b' | |
939 | [[ $line =~ $pattern ]] | |
940 | ||
941 | If you want to match a character that's special to the regular | |
942 | expression grammar, it has to be quoted to remove its special | |
943 | meaning. This means that in the pattern `xxx.txt', the `.' | |
944 | matches any character in the string (its usual regular expression | |
945 | meaning), but in the pattern `"xxx.txt"' it can only match a | |
946 | literal `.'. Shell programmers should take special care with | |
947 | backslashes, since backslashes are used both by the shell and | |
948 | regular expressions to remove the special meaning from the | |
949 | following character. The following two sets of commands are _not_ | |
950 | equivalent: | |
951 | pattern='\.' | |
952 | ||
953 | [[ . =~ $pattern ]] | |
954 | [[ . =~ \. ]] | |
955 | ||
956 | [[ . =~ "$pattern" ]] | |
957 | [[ . =~ '\.' ]] | |
958 | ||
959 | The first two matches will succeed, but the second two will not, | |
960 | because in the second two the backslash will be part of the | |
961 | pattern to be matched. In the first two examples, the backslash | |
962 | removes the special meaning from `.', so the literal `.' matches. | |
963 | If the string in the first examples were anything other than `.', | |
964 | say `a', the pattern would not match, because the quoted `.' in the | |
965 | pattern loses its special meaning of matching any single character. | |
5e13499c | 966 | |
cce855bc JA |
967 | Expressions may be combined using the following operators, listed |
968 | in decreasing order of precedence: | |
969 | ||
970 | `( EXPRESSION )' | |
971 | Returns the value of EXPRESSION. This may be used to | |
972 | override the normal precedence of operators. | |
973 | ||
974 | `! EXPRESSION' | |
975 | True if EXPRESSION is false. | |
976 | ||
977 | `EXPRESSION1 && EXPRESSION2' | |
978 | True if both EXPRESSION1 and EXPRESSION2 are true. | |
979 | ||
980 | `EXPRESSION1 || EXPRESSION2' | |
981 | True if either EXPRESSION1 or EXPRESSION2 is true. | |
122f603c | 982 | |
45c0f7f8 | 983 | The `&&' and `||' operators do not evaluate EXPRESSION2 if the |
7117c2d2 JA |
984 | value of EXPRESSION1 is sufficient to determine the return value |
985 | of the entire conditional expression. | |
ccc6cda3 JA |
986 | |
987 | \1f | |
d3a24ed2 | 988 | File: bashref.info, Node: Command Grouping, Prev: Conditional Constructs, Up: Compound Commands |
ccc6cda3 | 989 | |
37c41ab1 CR |
990 | 3.2.4.3 Grouping Commands |
991 | ......................... | |
ccc6cda3 | 992 | |
37c41ab1 CR |
993 | Bash provides two ways to group a list of commands to be executed as a |
994 | unit. When commands are grouped, redirections may be applied to the | |
ccc6cda3 JA |
995 | entire command list. For example, the output of all the commands in |
996 | the list may be redirected to a single stream. | |
997 | ||
998 | `()' | |
999 | ( LIST ) | |
1000 | ||
1001 | Placing a list of commands between parentheses causes a subshell | |
d3a24ed2 CR |
1002 | environment to be created (*note Command Execution Environment::), |
1003 | and each of the commands in LIST to be executed in that subshell. | |
1004 | Since the LIST is executed in a subshell, variable assignments do | |
1005 | not remain in effect after the subshell completes. | |
ccc6cda3 JA |
1006 | |
1007 | `{}' | |
1008 | { LIST; } | |
1009 | ||
1010 | Placing a list of commands between curly braces causes the list to | |
1011 | be executed in the current shell context. No subshell is created. | |
cce855bc | 1012 | The semicolon (or newline) following LIST is required. |
ccc6cda3 JA |
1013 | |
1014 | In addition to the creation of a subshell, there is a subtle | |
1015 | difference between these two constructs due to historical reasons. The | |
1016 | braces are `reserved words', so they must be separated from the LIST by | |
d7f49990 CR |
1017 | `blank's or other shell metacharacters. The parentheses are |
1018 | `operators', and are recognized as separate tokens by the shell even if | |
1019 | they are not separated from the LIST by whitespace. | |
ccc6cda3 JA |
1020 | |
1021 | The exit status of both of these constructs is the exit status of | |
1022 | LIST. | |
1023 | ||
8e1a6eaa | 1024 | \1f |
220537f2 | 1025 | File: bashref.info, Node: Coprocesses, Next: GNU Parallel, Prev: Compound Commands, Up: Shell Commands |
8e1a6eaa CR |
1026 | |
1027 | 3.2.5 Coprocesses | |
1028 | ----------------- | |
1029 | ||
1030 | A `coprocess' is a shell command preceded by the `coproc' reserved word. | |
1031 | A coprocess is executed asynchronously in a subshell, as if the command | |
1032 | had been terminated with the `&' control operator, with a two-way pipe | |
1033 | established between the executing shell and the coprocess. | |
1034 | ||
1035 | The format for a coprocess is: | |
122f603c | 1036 | coproc [NAME] COMMAND [REDIRECTIONS] |
8e1a6eaa CR |
1037 | |
1038 | This creates a coprocess named NAME. If NAME is not supplied, the | |
db31fb26 CR |
1039 | default name is COPROC. NAME must not be supplied if COMMAND is a |
1040 | simple command (*note Simple Commands::); otherwise, it is interpreted | |
1041 | as the first word of the simple command. | |
8e1a6eaa | 1042 | |
122f603c CR |
1043 | When the coprocess is executed, the shell creates an array variable |
1044 | (*note Arrays::) named `NAME' in the context of the executing shell. | |
1045 | The standard output of COMMAND is connected via a pipe to a file | |
8e1a6eaa | 1046 | descriptor in the executing shell, and that file descriptor is assigned |
122f603c CR |
1047 | to `NAME'[0]. The standard input of COMMAND is connected via a pipe to |
1048 | a file descriptor in the executing shell, and that file descriptor is | |
1049 | assigned to `NAME'[1]. This pipe is established before any | |
1050 | redirections specified by the command (*note Redirections::). The file | |
1051 | descriptors can be utilized as arguments to shell commands and | |
1052 | redirections using standard word expansions. | |
8e1a6eaa | 1053 | |
e05be32d | 1054 | The process ID of the shell spawned to execute the coprocess is |
122f603c | 1055 | available as the value of the variable `NAME'_PID. The `wait' builtin |
8e1a6eaa CR |
1056 | command may be used to wait for the coprocess to terminate. |
1057 | ||
1058 | The return status of a coprocess is the exit status of COMMAND. | |
1059 | ||
220537f2 CR |
1060 | \1f |
1061 | File: bashref.info, Node: GNU Parallel, Prev: Coprocesses, Up: Shell Commands | |
1062 | ||
1063 | 3.2.6 GNU Parallel | |
1064 | ------------------ | |
1065 | ||
1066 | GNU Parallel, as its name suggests, can be used to build and run | |
1067 | commands in parallel. You may run the same command with different | |
1068 | arguments, whether they are filenames, usernames, hostnames, or lines | |
1069 | read from files. | |
1070 | ||
1071 | For a complete description, refer to the GNU Parallel documentation. | |
1072 | A few examples should provide a brief introduction to its use. | |
1073 | ||
1074 | For example, it is easy to prefix each line in a text file with a | |
1075 | specified string: | |
1076 | cat file | parallel -k echo prefix_string | |
1077 | The `-k' option is required to preserve the lines' order. | |
1078 | ||
1079 | Similarly, you can append a specified string to each line in a text | |
1080 | file: | |
1081 | cat file | parallel -k echo {} append_string | |
1082 | ||
1083 | You can use Parallel to move files from the current directory when | |
1084 | the number of files is too large to process with one `mv' invocation: | |
1085 | ls | parallel mv {} destdir | |
1086 | ||
1087 | As you can see, the {} is replaced with each line read from standard | |
1088 | input. This will run as many `mv' commands as there are files in the | |
1089 | current directory. You can emulate a parallel `xargs' by adding the | |
1090 | `-X' option: | |
1091 | ls | parallel -X mv {} destdir | |
1092 | ||
1093 | GNU Parallel can replace certain common idioms that operate on lines | |
1094 | read from a file (in this case, filenames): | |
1095 | for x in $(cat list); do | |
1096 | do-something1 $x config-$x | |
1097 | do-something2 < $x | |
1098 | done | process-output | |
1099 | ||
1100 | with a more compact syntax reminiscent of lambdas: | |
1101 | cat list | parallel "do-something1 {} config-{} ; do-something2 < {}" | process-output | |
1102 | ||
1103 | Parallel provides a built-in mechanism to remove filename | |
1104 | extensions, which lends itself to batch file transformations or | |
1105 | renaming: | |
1106 | ls *.gz | parallel -j+0 "zcat {} | bzip2 >{.}.bz2 && rm {}" | |
1107 | This will recompress all files in the current directory with names | |
1108 | ending in .gz using bzip2, running one job per CPU (-j+0) in parallel. | |
1109 | ||
1110 | If a command generates output, you may want to preserve the input | |
1111 | order in the output. For instance, the following command | |
1112 | { echo foss.org.my ; echo debian.org; echo freenetproject.org; } | parallel traceroute | |
1113 | will display as output the traceroute invocation that finishes | |
1114 | first. Using the `-k' option, as we saw above | |
1115 | { echo foss.org.my ; echo debian.org; echo freenetproject.org; } | parallel -k traceroute | |
1116 | will ensure that the output of `traceroute foss.org.my' is displayed | |
1117 | first. | |
1118 | ||
ccc6cda3 | 1119 | \1f |
cce855bc | 1120 | File: bashref.info, Node: Shell Functions, Next: Shell Parameters, Prev: Shell Commands, Up: Basic Shell Features |
ccc6cda3 | 1121 | |
37c41ab1 CR |
1122 | 3.3 Shell Functions |
1123 | =================== | |
ccc6cda3 | 1124 | |
37c41ab1 CR |
1125 | Shell functions are a way to group commands for later execution using a |
1126 | single name for the group. They are executed just like a "regular" | |
1127 | command. When the name of a shell function is used as a simple command | |
1128 | name, the list of commands associated with that function name is | |
1129 | executed. Shell functions are executed in the current shell context; | |
1130 | no new process is created to interpret them. | |
ccc6cda3 | 1131 | |
37c41ab1 | 1132 | Functions are declared using this syntax: |
9ec5ed66 | 1133 | NAME () COMPOUND-COMMAND [ REDIRECTIONS ] |
9ec5ed66 | 1134 | |
122f603c CR |
1135 | or |
1136 | ||
1137 | function NAME [()] COMPOUND-COMMAND [ REDIRECTIONS ] | |
ccc6cda3 JA |
1138 | |
1139 | This defines a shell function named NAME. The reserved word | |
cce855bc | 1140 | `function' is optional. If the `function' reserved word is supplied, |
d3a24ed2 CR |
1141 | the parentheses are optional. The BODY of the function is the compound |
1142 | command COMPOUND-COMMAND (*note Compound Commands::). That command is | |
1143 | usually a LIST enclosed between { and }, but may be any compound | |
1144 | command listed above. COMPOUND-COMMAND is executed whenever NAME is | |
122f603c CR |
1145 | specified as the name of a command. When the shell is in POSIX mode |
1146 | (*note Bash POSIX Mode::), NAME may not be the same as one of the | |
1147 | special builtins (*note Special Builtins::). Any redirections (*note | |
d3a24ed2 CR |
1148 | Redirections::) associated with the shell function are performed when |
1149 | the function is executed. | |
1150 | ||
ac18b312 CR |
1151 | A function definition may be deleted using the `-f' option to the |
1152 | `unset' builtin (*note Bourne Shell Builtins::). | |
1153 | ||
d3a24ed2 CR |
1154 | The exit status of a function definition is zero unless a syntax |
1155 | error occurs or a readonly function with the same name already exists. | |
1156 | When executed, the exit status of a function is the exit status of the | |
1157 | last command executed in the body. | |
1158 | ||
1159 | Note that for historical reasons, in the most common usage the curly | |
1160 | braces that surround the body of the function must be separated from | |
1161 | the body by `blank's or newlines. This is because the braces are | |
1162 | reserved words and are only recognized as such when they are separated | |
d7f49990 CR |
1163 | from the command list by whitespace or another shell metacharacter. |
1164 | Also, when using the braces, the LIST must be terminated by a semicolon, | |
1165 | a `&', or a newline. | |
bb70624e | 1166 | |
ccc6cda3 JA |
1167 | When a function is executed, the arguments to the function become |
1168 | the positional parameters during its execution (*note Positional | |
28ef6c31 | 1169 | Parameters::). The special parameter `#' that expands to the number of |
de8913bd | 1170 | positional parameters is updated to reflect the change. Special |
d3a24ed2 CR |
1171 | parameter `0' is unchanged. The first element of the `FUNCNAME' |
1172 | variable is set to the name of the function while the function is | |
4a8bb13f CR |
1173 | executing. |
1174 | ||
1175 | All other aspects of the shell execution environment are identical | |
1176 | between a function and its caller with these exceptions: the `DEBUG' | |
1177 | and `RETURN' traps are not inherited unless the function has been given | |
1178 | the `trace' attribute using the `declare' builtin or the `-o functrace' | |
1179 | option has been enabled with the `set' builtin, (in which case all | |
1180 | functions inherit the `DEBUG' and `RETURN' traps), and the `ERR' trap | |
1181 | is not inherited unless the `-o errtrace' shell option has been enabled. | |
1182 | *Note Bourne Shell Builtins::, for the description of the `trap' | |
1183 | builtin. | |
ccc6cda3 | 1184 | |
220537f2 CR |
1185 | The `FUNCNEST' variable, if set to a numeric value greater than 0, |
1186 | defines a maximum function nesting level. Function invocations that | |
1187 | exceed the limit cause the entire command to abort. | |
1188 | ||
ccc6cda3 JA |
1189 | If the builtin command `return' is executed in a function, the |
1190 | function completes and execution resumes with the next command after | |
d3a24ed2 CR |
1191 | the function call. Any command associated with the `RETURN' trap is |
1192 | executed before execution resumes. When a function completes, the | |
1193 | values of the positional parameters and the special parameter `#' are | |
1194 | restored to the values they had prior to the function's execution. If | |
1195 | a numeric argument is given to `return', that is the function's return | |
1196 | status; otherwise the function's return status is the exit status of | |
1197 | the last command executed before the `return'. | |
ccc6cda3 JA |
1198 | |
1199 | Variables local to the function may be declared with the `local' | |
1200 | builtin. These variables are visible only to the function and the | |
1201 | commands it invokes. | |
1202 | ||
d3a24ed2 | 1203 | Function names and definitions may be listed with the `-f' option to |
122f603c CR |
1204 | the `declare' (`typeset') builtin command (*note Bash Builtins::). The |
1205 | `-F' option to `declare' or `typeset' will list the function names only | |
1206 | (and optionally the source file and line number, if the `extdebug' | |
d3a24ed2 CR |
1207 | shell option is enabled). Functions may be exported so that subshells |
1208 | automatically have them defined with the `-f' option to the `export' | |
1209 | builtin (*note Bourne Shell Builtins::). Note that shell functions and | |
1210 | variables with the same name may result in multiple identically-named | |
1211 | entries in the environment passed to the shell's children. Care should | |
1212 | be taken in cases where this may cause a problem. | |
1213 | ||
9ec5ed66 CR |
1214 | Functions may be recursive. The `FUNCNEST' variable may be used to |
1215 | limit the depth of the function call stack and restrict the number of | |
1216 | function invocations. By default, no limit is placed on the number of | |
ccc6cda3 JA |
1217 | recursive calls. |
1218 | ||
1219 | \1f | |
1220 | File: bashref.info, Node: Shell Parameters, Next: Shell Expansions, Prev: Shell Functions, Up: Basic Shell Features | |
1221 | ||
37c41ab1 CR |
1222 | 3.4 Shell Parameters |
1223 | ==================== | |
ccc6cda3 JA |
1224 | |
1225 | * Menu: | |
1226 | ||
1227 | * Positional Parameters:: The shell's command-line arguments. | |
d3a24ed2 | 1228 | * Special Parameters:: Parameters denoted by special characters. |
ccc6cda3 JA |
1229 | |
1230 | A PARAMETER is an entity that stores values. It can be a `name', a | |
d3a24ed2 CR |
1231 | number, or one of the special characters listed below. A VARIABLE is a |
1232 | parameter denoted by a `name'. A variable has a VALUE and zero or more | |
1233 | ATTRIBUTES. Attributes are assigned using the `declare' builtin command | |
6a8fd0ed | 1234 | (see the description of the `declare' builtin in *note Bash Builtins::). |
ccc6cda3 JA |
1235 | |
1236 | A parameter is set if it has been assigned a value. The null string | |
1237 | is a valid value. Once a variable is set, it may be unset only by using | |
1238 | the `unset' builtin command. | |
1239 | ||
1240 | A variable may be assigned to by a statement of the form | |
1241 | NAME=[VALUE] | |
37c41ab1 | 1242 | If VALUE is not given, the variable is assigned the null string. All |
ccc6cda3 JA |
1243 | VALUEs undergo tilde expansion, parameter and variable expansion, |
1244 | command substitution, arithmetic expansion, and quote removal (detailed | |
f73dda09 | 1245 | below). If the variable has its `integer' attribute set, then VALUE is |
d3a24ed2 CR |
1246 | evaluated as an arithmetic expression even if the `$((...))' expansion |
1247 | is not used (*note Arithmetic Expansion::). Word splitting is not | |
1248 | performed, with the exception of `"$@"' as explained below. Filename | |
1249 | expansion is not performed. Assignment statements may also appear as | |
5e13499c | 1250 | arguments to the `alias', `declare', `typeset', `export', `readonly', |
122f603c CR |
1251 | and `local' builtin commands. When in POSIX mode (*note Bash POSIX |
1252 | Mode::), these builtins may appear in a command after one or more | |
1253 | instances of the `command' builtin and retain these assignment | |
1254 | statement properties. | |
ccc6cda3 | 1255 | |
eb2bb562 CR |
1256 | In the context where an assignment statement is assigning a value to |
1257 | a shell variable or array index (*note Arrays::), the `+=' operator can | |
1258 | be used to append to or add to the variable's previous value. When | |
e05be32d | 1259 | `+=' is applied to a variable for which the INTEGER attribute has been |
eb2bb562 CR |
1260 | set, VALUE is evaluated as an arithmetic expression and added to the |
1261 | variable's current value, which is also evaluated. When `+=' is | |
1262 | applied to an array variable using compound assignment (*note | |
1263 | Arrays::), the variable's value is not unset (as it is when using `='), | |
1264 | and new values are appended to the array beginning at one greater than | |
09767ff0 CR |
1265 | the array's maximum index (for indexed arrays), or added as additional |
1266 | key-value pairs in an associative array. When applied to a | |
1267 | string-valued variable, VALUE is expanded and appended to the | |
1268 | variable's value. | |
eb2bb562 | 1269 | |
ccc6cda3 JA |
1270 | \1f |
1271 | File: bashref.info, Node: Positional Parameters, Next: Special Parameters, Up: Shell Parameters | |
1272 | ||
37c41ab1 CR |
1273 | 3.4.1 Positional Parameters |
1274 | --------------------------- | |
ccc6cda3 | 1275 | |
37c41ab1 | 1276 | A POSITIONAL PARAMETER is a parameter denoted by one or more digits, |
ccc6cda3 JA |
1277 | other than the single digit `0'. Positional parameters are assigned |
1278 | from the shell's arguments when it is invoked, and may be reassigned | |
cce855bc | 1279 | using the `set' builtin command. Positional parameter `N' may be |
bb70624e JA |
1280 | referenced as `${N}', or as `$N' when `N' consists of a single digit. |
1281 | Positional parameters may not be assigned to with assignment statements. | |
1282 | The `set' and `shift' builtins are used to set and unset them (*note | |
28ef6c31 JA |
1283 | Shell Builtin Commands::). The positional parameters are temporarily |
1284 | replaced when a shell function is executed (*note Shell Functions::). | |
ccc6cda3 JA |
1285 | |
1286 | When a positional parameter consisting of more than a single digit | |
1287 | is expanded, it must be enclosed in braces. | |
1288 | ||
1289 | \1f | |
1290 | File: bashref.info, Node: Special Parameters, Prev: Positional Parameters, Up: Shell Parameters | |
1291 | ||
37c41ab1 CR |
1292 | 3.4.2 Special Parameters |
1293 | ------------------------ | |
ccc6cda3 | 1294 | |
37c41ab1 | 1295 | The shell treats several parameters specially. These parameters may |
ccc6cda3 JA |
1296 | only be referenced; assignment to them is not allowed. |
1297 | ||
1298 | `*' | |
1299 | Expands to the positional parameters, starting from one. When the | |
1300 | expansion occurs within double quotes, it expands to a single word | |
1301 | with the value of each parameter separated by the first character | |
1302 | of the `IFS' special variable. That is, `"$*"' is equivalent to | |
1303 | `"$1C$2C..."', where C is the first character of the value of the | |
d166f048 JA |
1304 | `IFS' variable. If `IFS' is unset, the parameters are separated |
1305 | by spaces. If `IFS' is null, the parameters are joined without | |
1306 | intervening separators. | |
ccc6cda3 JA |
1307 | |
1308 | `@' | |
1309 | Expands to the positional parameters, starting from one. When the | |
cce855bc | 1310 | expansion occurs within double quotes, each parameter expands to a |
ccc6cda3 | 1311 | separate word. That is, `"$@"' is equivalent to `"$1" "$2" ...'. |
37c41ab1 CR |
1312 | If the double-quoted expansion occurs within a word, the expansion |
1313 | of the first parameter is joined with the beginning part of the | |
1314 | original word, and the expansion of the last parameter is joined | |
1315 | with the last part of the original word. When there are no | |
1316 | positional parameters, `"$@"' and `$@' expand to nothing (i.e., | |
1317 | they are removed). | |
ccc6cda3 JA |
1318 | |
1319 | `#' | |
1320 | Expands to the number of positional parameters in decimal. | |
1321 | ||
1322 | `?' | |
1323 | Expands to the exit status of the most recently executed foreground | |
1324 | pipeline. | |
1325 | ||
1326 | `-' | |
bb70624e JA |
1327 | (A hyphen.) Expands to the current option flags as specified upon |
1328 | invocation, by the `set' builtin command, or those set by the | |
1329 | shell itself (such as the `-i' option). | |
ccc6cda3 JA |
1330 | |
1331 | `$' | |
1332 | Expands to the process ID of the shell. In a `()' subshell, it | |
cce855bc | 1333 | expands to the process ID of the invoking shell, not the subshell. |
ccc6cda3 JA |
1334 | |
1335 | `!' | |
1336 | Expands to the process ID of the most recently executed background | |
1337 | (asynchronous) command. | |
1338 | ||
1339 | `0' | |
1340 | Expands to the name of the shell or shell script. This is set at | |
cce855bc | 1341 | shell initialization. If Bash is invoked with a file of commands |
28ef6c31 JA |
1342 | (*note Shell Scripts::), `$0' is set to the name of that file. If |
1343 | Bash is started with the `-c' option (*note Invoking Bash::), then | |
1344 | `$0' is set to the first argument after the string to be executed, | |
1345 | if one is present. Otherwise, it is set to the filename used to | |
1346 | invoke Bash, as given by argument zero. | |
ccc6cda3 JA |
1347 | |
1348 | `_' | |
2206f89a CR |
1349 | (An underscore.) At shell startup, set to the absolute pathname |
1350 | used to invoke the shell or shell script being executed as passed | |
1351 | in the environment or argument list. Subsequently, expands to the | |
1352 | last argument to the previous command, after expansion. Also set | |
1353 | to the full pathname used to invoke each command executed and | |
1354 | placed in the environment exported to that command. When checking | |
1355 | mail, this parameter holds the name of the mail file. | |
ccc6cda3 JA |
1356 | |
1357 | \1f | |
1358 | File: bashref.info, Node: Shell Expansions, Next: Redirections, Prev: Shell Parameters, Up: Basic Shell Features | |
1359 | ||
37c41ab1 CR |
1360 | 3.5 Shell Expansions |
1361 | ==================== | |
ccc6cda3 | 1362 | |
37c41ab1 CR |
1363 | Expansion is performed on the command line after it has been split into |
1364 | `token's. There are seven kinds of expansion performed: | |
122f603c | 1365 | |
ccc6cda3 JA |
1366 | * brace expansion |
1367 | ||
1368 | * tilde expansion | |
1369 | ||
1370 | * parameter and variable expansion | |
1371 | ||
1372 | * command substitution | |
1373 | ||
1374 | * arithmetic expansion | |
1375 | ||
1376 | * word splitting | |
1377 | ||
1378 | * filename expansion | |
1379 | ||
1380 | * Menu: | |
1381 | ||
cce855bc JA |
1382 | * Brace Expansion:: Expansion of expressions within braces. |
1383 | * Tilde Expansion:: Expansion of the ~ character. | |
ccc6cda3 JA |
1384 | * Shell Parameter Expansion:: How Bash expands variables to their values. |
1385 | * Command Substitution:: Using the output of a command as an argument. | |
cce855bc | 1386 | * Arithmetic Expansion:: How to use arithmetic in shell expansions. |
ccc6cda3 JA |
1387 | * Process Substitution:: A way to write and read to and from a |
1388 | command. | |
1389 | * Word Splitting:: How the results of expansion are split into separate | |
1390 | arguments. | |
1391 | * Filename Expansion:: A shorthand for specifying filenames matching patterns. | |
1392 | * Quote Removal:: How and when quote characters are removed from | |
1393 | words. | |
1394 | ||
ccc6cda3 JA |
1395 | The order of expansions is: brace expansion, tilde expansion, |
1396 | parameter, variable, and arithmetic expansion and command substitution | |
1397 | (done in a left-to-right fashion), word splitting, and filename | |
1398 | expansion. | |
1399 | ||
1400 | On systems that can support it, there is an additional expansion | |
1401 | available: PROCESS SUBSTITUTION. This is performed at the same time as | |
cce855bc | 1402 | parameter, variable, and arithmetic expansion and command substitution. |
ccc6cda3 JA |
1403 | |
1404 | Only brace expansion, word splitting, and filename expansion can | |
1405 | change the number of words of the expansion; other expansions expand a | |
1406 | single word to a single word. The only exceptions to this are the | |
28ef6c31 JA |
1407 | expansions of `"$@"' (*note Special Parameters::) and `"${NAME[@]}"' |
1408 | (*note Arrays::). | |
ccc6cda3 | 1409 | |
28ef6c31 | 1410 | After all expansions, `quote removal' (*note Quote Removal::) is |
ccc6cda3 JA |
1411 | performed. |
1412 | ||
1413 | \1f | |
cce855bc JA |
1414 | File: bashref.info, Node: Brace Expansion, Next: Tilde Expansion, Up: Shell Expansions |
1415 | ||
37c41ab1 CR |
1416 | 3.5.1 Brace Expansion |
1417 | --------------------- | |
cce855bc | 1418 | |
37c41ab1 | 1419 | Brace expansion is a mechanism by which arbitrary strings may be |
cce855bc | 1420 | generated. This mechanism is similar to FILENAME EXPANSION (*note |
122f603c | 1421 | Filename Expansion::), but the filenames generated need not exist. |
cce855bc | 1422 | Patterns to be brace expanded take the form of an optional PREAMBLE, |
f6da9f85 | 1423 | followed by either a series of comma-separated strings or a sequence |
d3a24ed2 CR |
1424 | expression between a pair of braces, followed by an optional POSTSCRIPT. |
1425 | The preamble is prefixed to each string contained within the braces, and | |
1426 | the postscript is then appended to each resulting string, expanding left | |
1427 | to right. | |
cce855bc JA |
1428 | |
1429 | Brace expansions may be nested. The results of each expanded string | |
1430 | are not sorted; left to right order is preserved. For example, | |
1431 | bash$ echo a{d,c,b}e | |
1432 | ade ace abe | |
1433 | ||
4a8bb13f | 1434 | A sequence expression takes the form `{X..Y[..INCR]}', where X and Y |
ed35cb4a CR |
1435 | are either integers or single characters, and INCR, an optional |
1436 | increment, is an integer. When integers are supplied, the expression | |
1437 | expands to each number between X and Y, inclusive. Supplied integers | |
1438 | may be prefixed with `0' to force each term to have the same width. | |
1439 | When either X or Y begins with a zero, the shell attempts to force all | |
1440 | generated terms to contain the same number of digits, zero-padding | |
1441 | where necessary. When characters are supplied, the expression expands | |
1442 | to each character lexicographically between X and Y, inclusive. Note | |
1443 | that both X and Y must be of the same type. When the increment is | |
1444 | supplied, it is used as the difference between each term. The default | |
1445 | increment is 1 or -1 as appropriate. | |
d3a24ed2 | 1446 | |
cce855bc JA |
1447 | Brace expansion is performed before any other expansions, and any |
1448 | characters special to other expansions are preserved in the result. It | |
1449 | is strictly textual. Bash does not apply any syntactic interpretation | |
bb70624e JA |
1450 | to the context of the expansion or the text between the braces. To |
1451 | avoid conflicts with parameter expansion, the string `${' is not | |
1452 | considered eligible for brace expansion. | |
cce855bc JA |
1453 | |
1454 | A correctly-formed brace expansion must contain unquoted opening and | |
d3a24ed2 CR |
1455 | closing braces, and at least one unquoted comma or a valid sequence |
1456 | expression. Any incorrectly formed brace expansion is left unchanged. | |
1457 | ||
1458 | A { or `,' may be quoted with a backslash to prevent its being | |
1459 | considered part of a brace expression. To avoid conflicts with | |
1460 | parameter expansion, the string `${' is not considered eligible for | |
1461 | brace expansion. | |
cce855bc JA |
1462 | |
1463 | This construct is typically used as shorthand when the common prefix | |
1464 | of the strings to be generated is longer than in the above example: | |
1465 | mkdir /usr/local/src/bash/{old,new,dist,bugs} | |
1466 | or | |
1467 | chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}} | |
1468 | ||
1469 | \1f | |
1470 | File: bashref.info, Node: Tilde Expansion, Next: Shell Parameter Expansion, Prev: Brace Expansion, Up: Shell Expansions | |
1471 | ||
37c41ab1 CR |
1472 | 3.5.2 Tilde Expansion |
1473 | --------------------- | |
cce855bc | 1474 | |
37c41ab1 | 1475 | If a word begins with an unquoted tilde character (`~'), all of the |
cce855bc JA |
1476 | characters up to the first unquoted slash (or all characters, if there |
1477 | is no unquoted slash) are considered a TILDE-PREFIX. If none of the | |
1478 | characters in the tilde-prefix are quoted, the characters in the | |
1479 | tilde-prefix following the tilde are treated as a possible LOGIN NAME. | |
1480 | If this login name is the null string, the tilde is replaced with the | |
1481 | value of the `HOME' shell variable. If `HOME' is unset, the home | |
1482 | directory of the user executing the shell is substituted instead. | |
1483 | Otherwise, the tilde-prefix is replaced with the home directory | |
1484 | associated with the specified login name. | |
1485 | ||
1486 | If the tilde-prefix is `~+', the value of the shell variable `PWD' | |
1487 | replaces the tilde-prefix. If the tilde-prefix is `~-', the value of | |
1488 | the shell variable `OLDPWD', if it is set, is substituted. | |
1489 | ||
1490 | If the characters following the tilde in the tilde-prefix consist of | |
1491 | a number N, optionally prefixed by a `+' or a `-', the tilde-prefix is | |
1492 | replaced with the corresponding element from the directory stack, as it | |
1493 | would be displayed by the `dirs' builtin invoked with the characters | |
1494 | following tilde in the tilde-prefix as an argument (*note The Directory | |
28ef6c31 | 1495 | Stack::). If the tilde-prefix, sans the tilde, consists of a number |
cce855bc JA |
1496 | without a leading `+' or `-', `+' is assumed. |
1497 | ||
1498 | If the login name is invalid, or the tilde expansion fails, the word | |
1499 | is left unchanged. | |
1500 | ||
1501 | Each variable assignment is checked for unquoted tilde-prefixes | |
eb2bb562 | 1502 | immediately following a `:' or the first `='. In these cases, tilde |
122f603c | 1503 | expansion is also performed. Consequently, one may use filenames with |
eb2bb562 CR |
1504 | tildes in assignments to `PATH', `MAILPATH', and `CDPATH', and the |
1505 | shell assigns the expanded value. | |
cce855bc JA |
1506 | |
1507 | The following table shows how Bash treats unquoted tilde-prefixes: | |
1508 | ||
1509 | `~' | |
1510 | The value of `$HOME' | |
1511 | ||
1512 | `~/foo' | |
1513 | `$HOME/foo' | |
1514 | ||
1515 | `~fred/foo' | |
1516 | The subdirectory `foo' of the home directory of the user `fred' | |
1517 | ||
1518 | `~+/foo' | |
1519 | `$PWD/foo' | |
1520 | ||
1521 | `~-/foo' | |
1522 | `${OLDPWD-'~-'}/foo' | |
1523 | ||
1524 | `~N' | |
1525 | The string that would be displayed by `dirs +N' | |
1526 | ||
1527 | `~+N' | |
1528 | The string that would be displayed by `dirs +N' | |
1529 | ||
1530 | `~-N' | |
1531 | The string that would be displayed by `dirs -N' | |
1532 | ||
1533 | \1f | |
1534 | File: bashref.info, Node: Shell Parameter Expansion, Next: Command Substitution, Prev: Tilde Expansion, Up: Shell Expansions | |
ccc6cda3 | 1535 | |
37c41ab1 CR |
1536 | 3.5.3 Shell Parameter Expansion |
1537 | ------------------------------- | |
ccc6cda3 | 1538 | |
37c41ab1 CR |
1539 | The `$' character introduces parameter expansion, command substitution, |
1540 | or arithmetic expansion. The parameter name or symbol to be expanded | |
1541 | may be enclosed in braces, which are optional but serve to protect the | |
1542 | variable to be expanded from characters immediately following it which | |
1543 | could be interpreted as part of the name. | |
ccc6cda3 | 1544 | |
cce855bc JA |
1545 | When braces are used, the matching ending brace is the first `}' not |
1546 | escaped by a backslash or within a quoted string, and not within an | |
1547 | embedded arithmetic expansion, command substitution, or parameter | |
1548 | expansion. | |
1549 | ||
ccc6cda3 JA |
1550 | The basic form of parameter expansion is ${PARAMETER}. The value of |
1551 | PARAMETER is substituted. The braces are required when PARAMETER is a | |
1552 | positional parameter with more than one digit, or when PARAMETER is | |
1553 | followed by a character that is not to be interpreted as part of its | |
1554 | name. | |
1555 | ||
d5362af8 CR |
1556 | If the first character of PARAMETER is an exclamation point (!), a |
1557 | level of variable indirection is introduced. Bash uses the value of | |
1558 | the variable formed from the rest of PARAMETER as the name of the | |
1559 | variable; this variable is then expanded and that value is used in the | |
1560 | rest of the substitution, rather than the value of PARAMETER itself. | |
1561 | This is known as `indirect expansion'. The exceptions to this are the | |
e05be32d CR |
1562 | expansions of ${!PREFIX |
1563 | } and ${!NAME[@]} described below. The exclamation point must | |
1564 | immediately follow the left brace in order to introduce indirection. | |
ccc6cda3 JA |
1565 | |
1566 | In each of the cases below, WORD is subject to tilde expansion, | |
1567 | parameter expansion, command substitution, and arithmetic expansion. | |
bb70624e | 1568 | |
db31fb26 CR |
1569 | When not performing substring expansion, using the form described |
1570 | below, Bash tests for a parameter that is unset or null. Omitting the | |
1571 | colon results in a test only for a parameter that is unset. Put | |
1572 | another way, if the colon is included, the operator tests for both | |
1573 | PARAMETER's existence and that its value is not null; if the colon is | |
1574 | omitted, the operator tests only for existence. | |
ccc6cda3 JA |
1575 | |
1576 | `${PARAMETER:-WORD}' | |
1577 | If PARAMETER is unset or null, the expansion of WORD is | |
1578 | substituted. Otherwise, the value of PARAMETER is substituted. | |
1579 | ||
1580 | `${PARAMETER:=WORD}' | |
1581 | If PARAMETER is unset or null, the expansion of WORD is assigned | |
1582 | to PARAMETER. The value of PARAMETER is then substituted. | |
de8913bd CR |
1583 | Positional parameters and special parameters may not be assigned to |
1584 | in this way. | |
ccc6cda3 JA |
1585 | |
1586 | `${PARAMETER:?WORD}' | |
1587 | If PARAMETER is null or unset, the expansion of WORD (or a message | |
1588 | to that effect if WORD is not present) is written to the standard | |
1589 | error and the shell, if it is not interactive, exits. Otherwise, | |
1590 | the value of PARAMETER is substituted. | |
1591 | ||
1592 | `${PARAMETER:+WORD}' | |
1593 | If PARAMETER is null or unset, nothing is substituted, otherwise | |
1594 | the expansion of WORD is substituted. | |
1595 | ||
1596 | `${PARAMETER:OFFSET}' | |
1597 | `${PARAMETER:OFFSET:LENGTH}' | |
bb70624e | 1598 | Expands to up to LENGTH characters of PARAMETER starting at the |
cce855bc | 1599 | character specified by OFFSET. If LENGTH is omitted, expands to |
bb70624e | 1600 | the substring of PARAMETER starting at the character specified by |
cce855bc | 1601 | OFFSET. LENGTH and OFFSET are arithmetic expressions (*note Shell |
28ef6c31 | 1602 | Arithmetic::). This is referred to as Substring Expansion. |
ccc6cda3 | 1603 | |
ccc6cda3 | 1604 | If OFFSET evaluates to a number less than zero, the value is used |
7d92f73f CR |
1605 | as an offset from the end of the value of PARAMETER. If LENGTH |
1606 | evaluates to a number less than zero, and PARAMETER is not `@' and | |
1607 | not an indexed or associative array, it is interpreted as an | |
1608 | offset from the end of the value of PARAMETER rather than a number | |
1609 | of characters, and the expansion is the characters between the two | |
1610 | offsets. If PARAMETER is `@', the result is LENGTH positional | |
1611 | parameters beginning at OFFSET. If PARAMETER is an indexed array | |
1612 | name subscripted by `@' or `*', the result is the LENGTH members | |
1613 | of the array beginning with `${PARAMETER[OFFSET]}'. A negative | |
1614 | OFFSET is taken relative to one greater than the maximum index of | |
1615 | the specified array. Substring expansion applied to an | |
1616 | associative array produces undefined results. | |
09767ff0 CR |
1617 | |
1618 | Note that a negative offset must be separated from the colon by at | |
1619 | least one space to avoid being confused with the `:-' expansion. | |
eb2bb562 | 1620 | Substring indexing is zero-based unless the positional parameters |
d3ad40de CR |
1621 | are used, in which case the indexing starts at 1 by default. If |
1622 | OFFSET is 0, and the positional parameters are used, `$@' is | |
1623 | prefixed to the list. | |
ccc6cda3 | 1624 | |
bb70624e | 1625 | `${!PREFIX*}' |
d3a24ed2 | 1626 | `${!PREFIX@}' |
bb70624e JA |
1627 | Expands to the names of variables whose names begin with PREFIX, |
1628 | separated by the first character of the `IFS' special variable. | |
d3ad40de CR |
1629 | When `@' is used and the expansion appears within double quotes, |
1630 | each variable name expands to a separate word. | |
bb70624e | 1631 | |
d3a24ed2 CR |
1632 | `${!NAME[@]}' |
1633 | `${!NAME[*]}' | |
1634 | If NAME is an array variable, expands to the list of array indices | |
1635 | (keys) assigned in NAME. If NAME is not an array, expands to 0 if | |
1636 | NAME is set and null otherwise. When `@' is used and the | |
1637 | expansion appears within double quotes, each key expands to a | |
1638 | separate word. | |
1639 | ||
ccc6cda3 | 1640 | `${#PARAMETER}' |
cce855bc JA |
1641 | The length in characters of the expanded value of PARAMETER is |
1642 | substituted. If PARAMETER is `*' or `@', the value substituted is | |
1643 | the number of positional parameters. If PARAMETER is an array | |
1644 | name subscripted by `*' or `@', the value substituted is the | |
1645 | number of elements in the array. | |
ccc6cda3 JA |
1646 | |
1647 | `${PARAMETER#WORD}' | |
1648 | `${PARAMETER##WORD}' | |
1649 | The WORD is expanded to produce a pattern just as in filename | |
28ef6c31 | 1650 | expansion (*note Filename Expansion::). If the pattern matches |
cce855bc JA |
1651 | the beginning of the expanded value of PARAMETER, then the result |
1652 | of the expansion is the expanded value of PARAMETER with the | |
1653 | shortest matching pattern (the `#' case) or the longest matching | |
1654 | pattern (the `##' case) deleted. If PARAMETER is `@' or `*', the | |
1655 | pattern removal operation is applied to each positional parameter | |
1656 | in turn, and the expansion is the resultant list. If PARAMETER is | |
1657 | an array variable subscripted with `@' or `*', the pattern removal | |
1658 | operation is applied to each member of the array in turn, and the | |
1659 | expansion is the resultant list. | |
ccc6cda3 JA |
1660 | |
1661 | `${PARAMETER%WORD}' | |
1662 | `${PARAMETER%%WORD}' | |
1663 | The WORD is expanded to produce a pattern just as in filename | |
cce855bc JA |
1664 | expansion. If the pattern matches a trailing portion of the |
1665 | expanded value of PARAMETER, then the result of the expansion is | |
1666 | the value of PARAMETER with the shortest matching pattern (the `%' | |
1667 | case) or the longest matching pattern (the `%%' case) deleted. If | |
1668 | PARAMETER is `@' or `*', the pattern removal operation is applied | |
1669 | to each positional parameter in turn, and the expansion is the | |
1670 | resultant list. If PARAMETER is an array variable subscripted | |
1671 | with `@' or `*', the pattern removal operation is applied to each | |
1672 | member of the array in turn, and the expansion is the resultant | |
1673 | list. | |
ccc6cda3 JA |
1674 | |
1675 | `${PARAMETER/PATTERN/STRING}' | |
ccc6cda3 JA |
1676 | The PATTERN is expanded to produce a pattern just as in filename |
1677 | expansion. PARAMETER is expanded and the longest match of PATTERN | |
ac18b312 CR |
1678 | against its value is replaced with STRING. If PATTERN begins with |
1679 | `/', all matches of PATTERN are replaced with STRING. Normally | |
1680 | only the first match is replaced. If PATTERN begins with `#', it | |
1681 | must match at the beginning of the expanded value of PARAMETER. | |
1682 | If PATTERN begins with `%', it must match at the end of the | |
1683 | expanded value of PARAMETER. If STRING is null, matches of | |
b72432fd JA |
1684 | PATTERN are deleted and the `/' following PATTERN may be omitted. |
1685 | If PARAMETER is `@' or `*', the substitution operation is applied | |
1686 | to each positional parameter in turn, and the expansion is the | |
1687 | resultant list. If PARAMETER is an array variable subscripted | |
1688 | with `@' or `*', the substitution operation is applied to each | |
1689 | member of the array in turn, and the expansion is the resultant | |
1690 | list. | |
ccc6cda3 | 1691 | |
09767ff0 CR |
1692 | `${PARAMETER^PATTERN}' |
1693 | `${PARAMETER^^PATTERN}' | |
1694 | `${PARAMETER,PATTERN}' | |
1695 | `${PARAMETER,,PATTERN}' | |
1696 | This expansion modifies the case of alphabetic characters in | |
1697 | PARAMETER. The PATTERN is expanded to produce a pattern just as in | |
45c0f7f8 CR |
1698 | filename expansion. Each character in the expanded value of |
1699 | PARAMETER is tested against PATTERN, and, if it matches the | |
1700 | pattern, its case is converted. The pattern should not attempt to | |
1701 | match more than one character. The `^' operator converts | |
1702 | lowercase letters matching PATTERN to uppercase; the `,' operator | |
1703 | converts matching uppercase letters to lowercase. The `^^' and | |
1704 | `,,' expansions convert each matched character in the expanded | |
1705 | value; the `^' and `,' expansions match and convert only the first | |
1706 | character in the expanded value. If PATTERN is omitted, it is | |
1707 | treated like a `?', which matches every character. If PARAMETER | |
1708 | is `@' or `*', the case modification operation is applied to each | |
1709 | positional parameter in turn, and the expansion is the resultant | |
1710 | list. If PARAMETER is an array variable subscripted with `@' or | |
1711 | `*', the case modification operation is applied to each member of | |
1712 | the array in turn, and the expansion is the resultant list. | |
09767ff0 | 1713 | |
ccc6cda3 | 1714 | \1f |
cce855bc | 1715 | File: bashref.info, Node: Command Substitution, Next: Arithmetic Expansion, Prev: Shell Parameter Expansion, Up: Shell Expansions |
ccc6cda3 | 1716 | |
37c41ab1 CR |
1717 | 3.5.4 Command Substitution |
1718 | -------------------------- | |
ccc6cda3 | 1719 | |
37c41ab1 | 1720 | Command substitution allows the output of a command to replace the |
bb70624e JA |
1721 | command itself. Command substitution occurs when a command is enclosed |
1722 | as follows: | |
ccc6cda3 | 1723 | $(COMMAND) |
37c41ab1 | 1724 | or |
ccc6cda3 JA |
1725 | `COMMAND` |
1726 | ||
1727 | Bash performs the expansion by executing COMMAND and replacing the | |
1728 | command substitution with the standard output of the command, with any | |
cce855bc JA |
1729 | trailing newlines deleted. Embedded newlines are not deleted, but they |
1730 | may be removed during word splitting. The command substitution `$(cat | |
1731 | FILE)' can be replaced by the equivalent but faster `$(< FILE)'. | |
ccc6cda3 JA |
1732 | |
1733 | When the old-style backquote form of substitution is used, backslash | |
1734 | retains its literal meaning except when followed by `$', ``', or `\'. | |
cce855bc JA |
1735 | The first backquote not preceded by a backslash terminates the command |
1736 | substitution. When using the `$(COMMAND)' form, all characters between | |
1737 | the parentheses make up the command; none are treated specially. | |
ccc6cda3 | 1738 | |
cce855bc JA |
1739 | Command substitutions may be nested. To nest when using the |
1740 | backquoted form, escape the inner backquotes with backslashes. | |
ccc6cda3 JA |
1741 | |
1742 | If the substitution appears within double quotes, word splitting and | |
1743 | filename expansion are not performed on the results. | |
1744 | ||
1745 | \1f | |
cce855bc JA |
1746 | File: bashref.info, Node: Arithmetic Expansion, Next: Process Substitution, Prev: Command Substitution, Up: Shell Expansions |
1747 | ||
37c41ab1 CR |
1748 | 3.5.5 Arithmetic Expansion |
1749 | -------------------------- | |
cce855bc | 1750 | |
37c41ab1 CR |
1751 | Arithmetic expansion allows the evaluation of an arithmetic expression |
1752 | and the substitution of the result. The format for arithmetic | |
1753 | expansion is: | |
cce855bc JA |
1754 | |
1755 | $(( EXPRESSION )) | |
1756 | ||
1757 | The expression is treated as if it were within double quotes, but a | |
1758 | double quote inside the parentheses is not treated specially. All | |
1759 | tokens in the expression undergo parameter expansion, command | |
d3a24ed2 | 1760 | substitution, and quote removal. Arithmetic expansions may be nested. |
cce855bc JA |
1761 | |
1762 | The evaluation is performed according to the rules listed below | |
28ef6c31 | 1763 | (*note Shell Arithmetic::). If the expression is invalid, Bash prints |
cce855bc JA |
1764 | a message indicating failure to the standard error and no substitution |
1765 | occurs. | |
1766 | ||
1767 | \1f | |
1768 | File: bashref.info, Node: Process Substitution, Next: Word Splitting, Prev: Arithmetic Expansion, Up: Shell Expansions | |
ccc6cda3 | 1769 | |
37c41ab1 CR |
1770 | 3.5.6 Process Substitution |
1771 | -------------------------- | |
ccc6cda3 | 1772 | |
37c41ab1 CR |
1773 | Process substitution is supported on systems that support named pipes |
1774 | (FIFOs) or the `/dev/fd' method of naming open files. It takes the | |
1775 | form of | |
ccc6cda3 | 1776 | <(LIST) |
37c41ab1 | 1777 | or |
ccc6cda3 | 1778 | >(LIST) |
37c41ab1 CR |
1779 | The process LIST is run with its input or output connected to a FIFO |
1780 | or some file in `/dev/fd'. The name of this file is passed as an | |
1781 | argument to the current command as the result of the expansion. If the | |
ccc6cda3 JA |
1782 | `>(LIST)' form is used, writing to the file will provide input for |
1783 | LIST. If the `<(LIST)' form is used, the file passed as an argument | |
bb70624e JA |
1784 | should be read to obtain the output of LIST. Note that no space may |
1785 | appear between the `<' or `>' and the left parenthesis, otherwise the | |
1786 | construct would be interpreted as a redirection. | |
ccc6cda3 | 1787 | |
cce855bc JA |
1788 | When available, process substitution is performed simultaneously with |
1789 | parameter and variable expansion, command substitution, and arithmetic | |
1790 | expansion. | |
ccc6cda3 JA |
1791 | |
1792 | \1f | |
1793 | File: bashref.info, Node: Word Splitting, Next: Filename Expansion, Prev: Process Substitution, Up: Shell Expansions | |
1794 | ||
37c41ab1 CR |
1795 | 3.5.7 Word Splitting |
1796 | -------------------- | |
ccc6cda3 | 1797 | |
37c41ab1 | 1798 | The shell scans the results of parameter expansion, command |
ccc6cda3 JA |
1799 | substitution, and arithmetic expansion that did not occur within double |
1800 | quotes for word splitting. | |
1801 | ||
1802 | The shell treats each character of `$IFS' as a delimiter, and splits | |
1803 | the results of the other expansions into words on these characters. If | |
1804 | `IFS' is unset, or its value is exactly `<space><tab><newline>', the | |
d3ad40de CR |
1805 | default, then sequences of ` <space>', `<tab>', and `<newline>' at the |
1806 | beginning and end of the results of the previous expansions are | |
1807 | ignored, and any sequence of `IFS' characters not at the beginning or | |
1808 | end serves to delimit words. If `IFS' has a value other than the | |
1809 | default, then sequences of the whitespace characters `space' and `tab' | |
1810 | are ignored at the beginning and end of the word, as long as the | |
1811 | whitespace character is in the value of `IFS' (an `IFS' whitespace | |
1812 | character). Any character in `IFS' that is not `IFS' whitespace, along | |
1813 | with any adjacent `IFS' whitespace characters, delimits a field. A | |
1814 | sequence of `IFS' whitespace characters is also treated as a delimiter. | |
1815 | If the value of `IFS' is null, no word splitting occurs. | |
ccc6cda3 JA |
1816 | |
1817 | Explicit null arguments (`""' or `''') are retained. Unquoted | |
bb70624e | 1818 | implicit null arguments, resulting from the expansion of parameters |
ccc6cda3 JA |
1819 | that have no values, are removed. If a parameter with no value is |
1820 | expanded within double quotes, a null argument results and is retained. | |
1821 | ||
1822 | Note that if no expansion occurs, no splitting is performed. | |
1823 | ||
1824 | \1f | |
1825 | File: bashref.info, Node: Filename Expansion, Next: Quote Removal, Prev: Word Splitting, Up: Shell Expansions | |
1826 | ||
37c41ab1 CR |
1827 | 3.5.8 Filename Expansion |
1828 | ------------------------ | |
ccc6cda3 | 1829 | |
cce855bc JA |
1830 | * Menu: |
1831 | ||
1832 | * Pattern Matching:: How the shell matches patterns. | |
1833 | ||
ccc6cda3 | 1834 | After word splitting, unless the `-f' option has been set (*note The |
28ef6c31 | 1835 | Set Builtin::), Bash scans each word for the characters `*', `?', and |
bb70624e | 1836 | `['. If one of these characters appears, then the word is regarded as |
122f603c CR |
1837 | a PATTERN, and replaced with an alphabetically sorted list of filenames |
1838 | matching the pattern (*note Pattern Matching::). If no matching | |
1839 | filenames are found, and the shell option `nullglob' is disabled, the | |
74d0116b CR |
1840 | word is left unchanged. If the `nullglob' option is set, and no |
1841 | matches are found, the word is removed. If the `failglob' shell option | |
1842 | is set, and no matches are found, an error message is printed and the | |
1843 | command is not executed. If the shell option `nocaseglob' is enabled, | |
1844 | the match is performed without regard to the case of alphabetic | |
1845 | characters. | |
cce855bc | 1846 | |
4a8bb13f | 1847 | When a pattern is used for filename expansion, the character `.' at |
28ef6c31 | 1848 | the start of a filename or immediately following a slash must be |
cce855bc | 1849 | matched explicitly, unless the shell option `dotglob' is set. When |
122f603c | 1850 | matching a filename, the slash character must always be matched |
cce855bc JA |
1851 | explicitly. In other cases, the `.' character is not treated specially. |
1852 | ||
6a8fd0ed | 1853 | See the description of `shopt' in *note The Shopt Builtin::, for a |
5e13499c CR |
1854 | description of the `nocaseglob', `nullglob', `failglob', and `dotglob' |
1855 | options. | |
ccc6cda3 JA |
1856 | |
1857 | The `GLOBIGNORE' shell variable may be used to restrict the set of | |
cce855bc | 1858 | filenames matching a pattern. If `GLOBIGNORE' is set, each matching |
ccc6cda3 | 1859 | filename that also matches one of the patterns in `GLOBIGNORE' is |
28ef6c31 | 1860 | removed from the list of matches. The filenames `.' and `..' are |
d3a24ed2 CR |
1861 | always ignored when `GLOBIGNORE' is set and not null. However, setting |
1862 | `GLOBIGNORE' to a non-null value has the effect of enabling the | |
1863 | `dotglob' shell option, so all other filenames beginning with a `.' | |
1864 | will match. To get the old behavior of ignoring filenames beginning | |
1865 | with a `.', make `.*' one of the patterns in `GLOBIGNORE'. The | |
1866 | `dotglob' option is disabled when `GLOBIGNORE' is unset. | |
ccc6cda3 | 1867 | |
cce855bc JA |
1868 | \1f |
1869 | File: bashref.info, Node: Pattern Matching, Up: Filename Expansion | |
1870 | ||
37c41ab1 CR |
1871 | 3.5.8.1 Pattern Matching |
1872 | ........................ | |
cce855bc | 1873 | |
37c41ab1 CR |
1874 | Any character that appears in a pattern, other than the special pattern |
1875 | characters described below, matches itself. The NUL character may not | |
1876 | occur in a pattern. A backslash escapes the following character; the | |
1877 | escaping backslash is discarded when matching. The special pattern | |
1878 | characters must be quoted if they are to be matched literally. | |
cce855bc | 1879 | |
ccc6cda3 JA |
1880 | The special pattern characters have the following meanings: |
1881 | `*' | |
ed35cb4a CR |
1882 | Matches any string, including the null string. When the |
1883 | `globstar' shell option is enabled, and `*' is used in a filename | |
1884 | expansion context, two adjacent `*'s used as a single pattern will | |
1885 | match all files and zero or more directories and subdirectories. | |
1886 | If followed by a `/', two adjacent `*'s will match only | |
1887 | directories and subdirectories. | |
ccc6cda3 JA |
1888 | |
1889 | `?' | |
1890 | Matches any single character. | |
1891 | ||
1892 | `[...]' | |
1893 | Matches any one of the enclosed characters. A pair of characters | |
28ef6c31 JA |
1894 | separated by a hyphen denotes a RANGE EXPRESSION; any character |
1895 | that sorts between those two characters, inclusive, using the | |
1896 | current locale's collating sequence and character set, is matched. | |
1897 | If the first character following the `[' is a `!' or a `^' then | |
1898 | any character not enclosed is matched. A `-' may be matched by | |
1899 | including it as the first or last character in the set. A `]' may | |
1900 | be matched by including it as the first character in the set. The | |
1901 | sorting order of characters in range expressions is determined by | |
74d0116b CR |
1902 | the current locale and the values of the `LC_COLLATE' and `LC_ALL' |
1903 | shell variables, if set. | |
28ef6c31 JA |
1904 | |
1905 | For example, in the default C locale, `[a-dx-z]' is equivalent to | |
1906 | `[abcdxyz]'. Many locales sort characters in dictionary order, | |
1907 | and in these locales `[a-dx-z]' is typically not equivalent to | |
1908 | `[abcdxyz]'; it might be equivalent to `[aBbCcDdxXyYz]', for | |
1909 | example. To obtain the traditional interpretation of ranges in | |
1910 | bracket expressions, you can force the use of the C locale by | |
1911 | setting the `LC_COLLATE' or `LC_ALL' environment variable to the | |
74d0116b | 1912 | value `C', or enable the `globasciiranges' shell option. |
ccc6cda3 | 1913 | |
cce855bc JA |
1914 | Within `[' and `]', CHARACTER CLASSES can be specified using the |
1915 | syntax `[:'CLASS`:]', where CLASS is one of the following classes | |
ac18b312 | 1916 | defined in the POSIX standard: |
cce855bc | 1917 | alnum alpha ascii blank cntrl digit graph lower |
7117c2d2 | 1918 | print punct space upper word xdigit |
cce855bc | 1919 | A character class matches any character belonging to that class. |
7117c2d2 JA |
1920 | The `word' character class matches letters, digits, and the |
1921 | character `_'. | |
cce855bc JA |
1922 | |
1923 | Within `[' and `]', an EQUIVALENCE CLASS can be specified using | |
1924 | the syntax `[='C`=]', which matches all characters with the same | |
1925 | collation weight (as defined by the current locale) as the | |
1926 | character C. | |
1927 | ||
28ef6c31 | 1928 | Within `[' and `]', the syntax `[.'SYMBOL`.]' matches the |
cce855bc JA |
1929 | collating symbol SYMBOL. |
1930 | ||
1931 | If the `extglob' shell option is enabled using the `shopt' builtin, | |
1932 | several extended pattern matching operators are recognized. In the | |
1933 | following description, a PATTERN-LIST is a list of one or more patterns | |
1934 | separated by a `|'. Composite patterns may be formed using one or more | |
1935 | of the following sub-patterns: | |
1936 | ||
1937 | `?(PATTERN-LIST)' | |
1938 | Matches zero or one occurrence of the given patterns. | |
1939 | ||
1940 | `*(PATTERN-LIST)' | |
1941 | Matches zero or more occurrences of the given patterns. | |
1942 | ||
1943 | `+(PATTERN-LIST)' | |
1944 | Matches one or more occurrences of the given patterns. | |
1945 | ||
1946 | `@(PATTERN-LIST)' | |
eb2bb562 | 1947 | Matches one of the given patterns. |
cce855bc JA |
1948 | |
1949 | `!(PATTERN-LIST)' | |
1950 | Matches anything except one of the given patterns. | |
1951 | ||
ccc6cda3 JA |
1952 | \1f |
1953 | File: bashref.info, Node: Quote Removal, Prev: Filename Expansion, Up: Shell Expansions | |
1954 | ||
37c41ab1 CR |
1955 | 3.5.9 Quote Removal |
1956 | ------------------- | |
ccc6cda3 | 1957 | |
37c41ab1 | 1958 | After the preceding expansions, all unquoted occurrences of the |
ccc6cda3 JA |
1959 | characters `\', `'', and `"' that did not result from one of the above |
1960 | expansions are removed. | |
1961 | ||
1962 | \1f | |
1963 | File: bashref.info, Node: Redirections, Next: Executing Commands, Prev: Shell Expansions, Up: Basic Shell Features | |
1964 | ||
37c41ab1 CR |
1965 | 3.6 Redirections |
1966 | ================ | |
ccc6cda3 | 1967 | |
37c41ab1 | 1968 | Before a command is executed, its input and output may be REDIRECTED |
abe2eb5b CR |
1969 | using a special notation interpreted by the shell. Redirection allows |
1970 | commands' file handles to be duplicated, opened, closed, made to refer | |
1971 | to different files, and can change the files the command reads from and | |
1972 | writes to. Redirection may also be used to modify file handles in the | |
1973 | current shell execution environment. The following redirection | |
1974 | operators may precede or appear anywhere within a simple command or may | |
1975 | follow a command. Redirections are processed in the order they appear, | |
1976 | from left to right. | |
ccc6cda3 | 1977 | |
a8fd3f3e CR |
1978 | Each redirection that may be preceded by a file descriptor number |
1979 | may instead be preceded by a word of the form {VARNAME}. In this case, | |
1980 | for each redirection operator except >&- and <&-, the shell will | |
1981 | allocate a file descriptor greater than 10 and assign it to {VARNAME}. | |
d5362af8 | 1982 | If >&- or <&- is preceded by {VARNAME}, the value of VARNAME defines |
a8fd3f3e CR |
1983 | the file descriptor to close. |
1984 | ||
ccc6cda3 JA |
1985 | In the following descriptions, if the file descriptor number is |
1986 | omitted, and the first character of the redirection operator is `<', | |
1987 | the redirection refers to the standard input (file descriptor 0). If | |
1988 | the first character of the redirection operator is `>', the redirection | |
1989 | refers to the standard output (file descriptor 1). | |
1990 | ||
cce855bc JA |
1991 | The word following the redirection operator in the following |
1992 | descriptions, unless otherwise noted, is subjected to brace expansion, | |
1993 | tilde expansion, parameter expansion, command substitution, arithmetic | |
bb70624e JA |
1994 | expansion, quote removal, filename expansion, and word splitting. If |
1995 | it expands to more than one word, Bash reports an error. | |
ccc6cda3 JA |
1996 | |
1997 | Note that the order of redirections is significant. For example, | |
1998 | the command | |
1999 | ls > DIRLIST 2>&1 | |
37c41ab1 | 2000 | directs both standard output (file descriptor 1) and standard error |
bb70624e | 2001 | (file descriptor 2) to the file DIRLIST, while the command |
ccc6cda3 | 2002 | ls 2>&1 > DIRLIST |
37c41ab1 | 2003 | directs only the standard output to file DIRLIST, because the |
6932f7f5 CR |
2004 | standard error was made a copy of the standard output before the |
2005 | standard output was redirected to DIRLIST. | |
ccc6cda3 | 2006 | |
bb70624e JA |
2007 | Bash handles several filenames specially when they are used in |
2008 | redirections, as described in the following table: | |
2009 | ||
2010 | `/dev/fd/FD' | |
2011 | If FD is a valid integer, file descriptor FD is duplicated. | |
2012 | ||
2013 | `/dev/stdin' | |
2014 | File descriptor 0 is duplicated. | |
2015 | ||
2016 | `/dev/stdout' | |
2017 | File descriptor 1 is duplicated. | |
2018 | ||
2019 | `/dev/stderr' | |
2020 | File descriptor 2 is duplicated. | |
2021 | ||
2022 | `/dev/tcp/HOST/PORT' | |
2023 | If HOST is a valid hostname or Internet address, and PORT is an | |
f73dda09 JA |
2024 | integer port number or service name, Bash attempts to open a TCP |
2025 | connection to the corresponding socket. | |
bb70624e JA |
2026 | |
2027 | `/dev/udp/HOST/PORT' | |
2028 | If HOST is a valid hostname or Internet address, and PORT is an | |
f73dda09 JA |
2029 | integer port number or service name, Bash attempts to open a UDP |
2030 | connection to the corresponding socket. | |
bb70624e | 2031 | |
cce855bc JA |
2032 | A failure to open or create a file causes the redirection to fail. |
2033 | ||
eb2bb562 CR |
2034 | Redirections using file descriptors greater than 9 should be used |
2035 | with care, as they may conflict with file descriptors the shell uses | |
2036 | internally. | |
2037 | ||
37c41ab1 CR |
2038 | 3.6.1 Redirecting Input |
2039 | ----------------------- | |
ccc6cda3 | 2040 | |
37c41ab1 | 2041 | Redirection of input causes the file whose name results from the |
ccc6cda3 JA |
2042 | expansion of WORD to be opened for reading on file descriptor `n', or |
2043 | the standard input (file descriptor 0) if `n' is not specified. | |
2044 | ||
2045 | The general format for redirecting input is: | |
7117c2d2 | 2046 | [N]<WORD |
ccc6cda3 | 2047 | |
37c41ab1 CR |
2048 | 3.6.2 Redirecting Output |
2049 | ------------------------ | |
ccc6cda3 | 2050 | |
37c41ab1 | 2051 | Redirection of output causes the file whose name results from the |
7117c2d2 JA |
2052 | expansion of WORD to be opened for writing on file descriptor N, or the |
2053 | standard output (file descriptor 1) if N is not specified. If the file | |
2054 | does not exist it is created; if it does exist it is truncated to zero | |
2055 | size. | |
ccc6cda3 JA |
2056 | |
2057 | The general format for redirecting output is: | |
7117c2d2 | 2058 | [N]>[|]WORD |
ccc6cda3 | 2059 | |
cce855bc JA |
2060 | If the redirection operator is `>', and the `noclobber' option to |
2061 | the `set' builtin has been enabled, the redirection will fail if the | |
bb70624e | 2062 | file whose name results from the expansion of WORD exists and is a |
cce855bc JA |
2063 | regular file. If the redirection operator is `>|', or the redirection |
2064 | operator is `>' and the `noclobber' option is not enabled, the | |
2065 | redirection is attempted even if the file named by WORD exists. | |
ccc6cda3 | 2066 | |
37c41ab1 CR |
2067 | 3.6.3 Appending Redirected Output |
2068 | --------------------------------- | |
ccc6cda3 | 2069 | |
37c41ab1 | 2070 | Redirection of output in this fashion causes the file whose name |
ccc6cda3 | 2071 | results from the expansion of WORD to be opened for appending on file |
7117c2d2 JA |
2072 | descriptor N, or the standard output (file descriptor 1) if N is not |
2073 | specified. If the file does not exist it is created. | |
ccc6cda3 JA |
2074 | |
2075 | The general format for appending output is: | |
7117c2d2 | 2076 | [N]>>WORD |
ccc6cda3 | 2077 | |
37c41ab1 CR |
2078 | 3.6.4 Redirecting Standard Output and Standard Error |
2079 | ---------------------------------------------------- | |
ccc6cda3 | 2080 | |
ed35cb4a CR |
2081 | This construct allows both the standard output (file descriptor 1) and |
2082 | the standard error output (file descriptor 2) to be redirected to the | |
2083 | file whose name is the expansion of WORD. | |
ccc6cda3 JA |
2084 | |
2085 | There are two formats for redirecting standard output and standard | |
2086 | error: | |
2087 | &>WORD | |
37c41ab1 | 2088 | and |
ccc6cda3 | 2089 | >&WORD |
37c41ab1 | 2090 | Of the two forms, the first is preferred. This is semantically |
ccc6cda3 JA |
2091 | equivalent to |
2092 | >WORD 2>&1 | |
77638cbf CR |
2093 | When using the second form, WORD may not expand to a number or `-'. |
2094 | If it does, other redirection operators apply (see Duplicating File | |
2095 | Descriptors below) for compatibility reasons. | |
ccc6cda3 | 2096 | |
ed35cb4a CR |
2097 | 3.6.5 Appending Standard Output and Standard Error |
2098 | -------------------------------------------------- | |
2099 | ||
2100 | This construct allows both the standard output (file descriptor 1) and | |
2101 | the standard error output (file descriptor 2) to be appended to the | |
2102 | file whose name is the expansion of WORD. | |
2103 | ||
2104 | The format for appending standard output and standard error is: | |
2105 | &>>WORD | |
2106 | This is semantically equivalent to | |
2107 | >>WORD 2>&1 | |
f6da9f85 | 2108 | (see Duplicating File Descriptors below). |
ed35cb4a CR |
2109 | |
2110 | 3.6.6 Here Documents | |
37c41ab1 | 2111 | -------------------- |
ccc6cda3 | 2112 | |
37c41ab1 | 2113 | This type of redirection instructs the shell to read input from the |
ccc6cda3 JA |
2114 | current source until a line containing only WORD (with no trailing |
2115 | blanks) is seen. All of the lines read up to that point are then used | |
2116 | as the standard input for a command. | |
2117 | ||
7117c2d2 | 2118 | The format of here-documents is: |
ccc6cda3 JA |
2119 | <<[-]WORD |
2120 | HERE-DOCUMENT | |
2121 | DELIMITER | |
2122 | ||
122f603c CR |
2123 | No parameter and variable expansion, command substitution, |
2124 | arithmetic expansion, or filename expansion is performed on WORD. If | |
2125 | any characters in WORD are quoted, the DELIMITER is the result of quote | |
2126 | removal on WORD, and the lines in the here-document are not expanded. | |
2127 | If WORD is unquoted, all lines of the here-document are subjected to | |
2128 | parameter expansion, command substitution, and arithmetic expansion. | |
2129 | In the latter case, the character sequence `\newline' is ignored, and | |
2130 | `\' must be used to quote the characters `\', `$', and ``'. | |
ccc6cda3 JA |
2131 | |
2132 | If the redirection operator is `<<-', then all leading tab | |
2133 | characters are stripped from input lines and the line containing | |
2134 | DELIMITER. This allows here-documents within shell scripts to be | |
2135 | indented in a natural fashion. | |
2136 | ||
ed35cb4a | 2137 | 3.6.7 Here Strings |
37c41ab1 | 2138 | ------------------ |
7117c2d2 | 2139 | |
37c41ab1 | 2140 | A variant of here documents, the format is: |
7117c2d2 JA |
2141 | <<< WORD |
2142 | ||
122f603c CR |
2143 | The WORD undergoes brace expansion, tilde expansion, parameter and |
2144 | variable expansion, command substitution, arithmetic expansion, and | |
2145 | quote removal. Pathname expansion word splitting are not performed. | |
2146 | The result is supplied as a single string to the command on its | |
2147 | standard input. | |
7117c2d2 | 2148 | |
ed35cb4a | 2149 | 3.6.8 Duplicating File Descriptors |
37c41ab1 | 2150 | ---------------------------------- |
ccc6cda3 | 2151 | |
37c41ab1 | 2152 | The redirection operator |
7117c2d2 | 2153 | [N]<&WORD |
37c41ab1 CR |
2154 | is used to duplicate input file descriptors. If WORD expands to one |
2155 | or more digits, the file descriptor denoted by N is made to be a copy | |
2156 | of that file descriptor. If the digits in WORD do not specify a file | |
cce855bc | 2157 | descriptor open for input, a redirection error occurs. If WORD |
7117c2d2 JA |
2158 | evaluates to `-', file descriptor N is closed. If N is not specified, |
2159 | the standard input (file descriptor 0) is used. | |
ccc6cda3 JA |
2160 | |
2161 | The operator | |
7117c2d2 | 2162 | [N]>&WORD |
37c41ab1 | 2163 | is used similarly to duplicate output file descriptors. If N is not |
cce855bc JA |
2164 | specified, the standard output (file descriptor 1) is used. If the |
2165 | digits in WORD do not specify a file descriptor open for output, a | |
77638cbf CR |
2166 | redirection error occurs. If WORD evaluates to `-', file descriptor N |
2167 | is closed. As a special case, if N is omitted, and WORD does not | |
2168 | expand to one or more digits or `-', the standard output and standard | |
7117c2d2 JA |
2169 | error are redirected as described previously. |
2170 | ||
ed35cb4a | 2171 | 3.6.9 Moving File Descriptors |
37c41ab1 | 2172 | ----------------------------- |
7117c2d2 | 2173 | |
37c41ab1 | 2174 | The redirection operator |
7117c2d2 | 2175 | [N]<&DIGIT- |
37c41ab1 CR |
2176 | moves the file descriptor DIGIT to file descriptor N, or the |
2177 | standard input (file descriptor 0) if N is not specified. DIGIT is | |
2178 | closed after being duplicated to N. | |
7117c2d2 JA |
2179 | |
2180 | Similarly, the redirection operator | |
2181 | [N]>&DIGIT- | |
37c41ab1 CR |
2182 | moves the file descriptor DIGIT to file descriptor N, or the |
2183 | standard output (file descriptor 1) if N is not specified. | |
7117c2d2 | 2184 | |
ed35cb4a CR |
2185 | 3.6.10 Opening File Descriptors for Reading and Writing |
2186 | ------------------------------------------------------- | |
ccc6cda3 | 2187 | |
37c41ab1 | 2188 | The redirection operator |
7117c2d2 | 2189 | [N]<>WORD |
37c41ab1 | 2190 | causes the file whose name is the expansion of WORD to be opened for |
7117c2d2 JA |
2191 | both reading and writing on file descriptor N, or on file descriptor 0 |
2192 | if N is not specified. If the file does not exist, it is created. | |
ccc6cda3 JA |
2193 | |
2194 | \1f | |
2195 | File: bashref.info, Node: Executing Commands, Next: Shell Scripts, Prev: Redirections, Up: Basic Shell Features | |
2196 | ||
37c41ab1 CR |
2197 | 3.7 Executing Commands |
2198 | ====================== | |
ccc6cda3 JA |
2199 | |
2200 | * Menu: | |
2201 | ||
cce855bc JA |
2202 | * Simple Command Expansion:: How Bash expands simple commands before |
2203 | executing them. | |
ccc6cda3 | 2204 | * Command Search and Execution:: How Bash finds commands and runs them. |
cce855bc JA |
2205 | * Command Execution Environment:: The environment in which Bash |
2206 | executes commands that are not | |
2207 | shell builtins. | |
ccc6cda3 | 2208 | * Environment:: The environment given to a command. |
ccc6cda3 JA |
2209 | * Exit Status:: The status returned by commands and how Bash |
2210 | interprets it. | |
ccc6cda3 JA |
2211 | * Signals:: What happens when Bash or a command it runs |
2212 | receives a signal. | |
2213 | ||
2214 | \1f | |
cce855bc JA |
2215 | File: bashref.info, Node: Simple Command Expansion, Next: Command Search and Execution, Up: Executing Commands |
2216 | ||
37c41ab1 CR |
2217 | 3.7.1 Simple Command Expansion |
2218 | ------------------------------ | |
cce855bc | 2219 | |
37c41ab1 | 2220 | When a simple command is executed, the shell performs the following |
cce855bc JA |
2221 | expansions, assignments, and redirections, from left to right. |
2222 | ||
2223 | 1. The words that the parser has marked as variable assignments (those | |
2224 | preceding the command name) and redirections are saved for later | |
2225 | processing. | |
2226 | ||
2227 | 2. The words that are not variable assignments or redirections are | |
28ef6c31 | 2228 | expanded (*note Shell Expansions::). If any words remain after |
cce855bc JA |
2229 | expansion, the first word is taken to be the name of the command |
2230 | and the remaining words are the arguments. | |
2231 | ||
2232 | 3. Redirections are performed as described above (*note | |
28ef6c31 | 2233 | Redirections::). |
cce855bc JA |
2234 | |
2235 | 4. The text after the `=' in each variable assignment undergoes tilde | |
2236 | expansion, parameter expansion, command substitution, arithmetic | |
2237 | expansion, and quote removal before being assigned to the variable. | |
2238 | ||
2239 | If no command name results, the variable assignments affect the | |
2240 | current shell environment. Otherwise, the variables are added to the | |
2241 | environment of the executed command and do not affect the current shell | |
2242 | environment. If any of the assignments attempts to assign a value to a | |
2243 | readonly variable, an error occurs, and the command exits with a | |
2244 | non-zero status. | |
2245 | ||
2246 | If no command name results, redirections are performed, but do not | |
2247 | affect the current shell environment. A redirection error causes the | |
2248 | command to exit with a non-zero status. | |
2249 | ||
2250 | If there is a command name left after expansion, execution proceeds | |
2251 | as described below. Otherwise, the command exits. If one of the | |
2252 | expansions contained a command substitution, the exit status of the | |
2253 | command is the exit status of the last command substitution performed. | |
2254 | If there were no command substitutions, the command exits with a status | |
2255 | of zero. | |
2256 | ||
2257 | \1f | |
2258 | File: bashref.info, Node: Command Search and Execution, Next: Command Execution Environment, Prev: Simple Command Expansion, Up: Executing Commands | |
ccc6cda3 | 2259 | |
37c41ab1 CR |
2260 | 3.7.2 Command Search and Execution |
2261 | ---------------------------------- | |
ccc6cda3 | 2262 | |
37c41ab1 | 2263 | After a command has been split into words, if it results in a simple |
ccc6cda3 JA |
2264 | command and an optional list of arguments, the following actions are |
2265 | taken. | |
2266 | ||
2267 | 1. If the command name contains no slashes, the shell attempts to | |
2268 | locate it. If there exists a shell function by that name, that | |
6a8fd0ed | 2269 | function is invoked as described in *note Shell Functions::. |
ccc6cda3 JA |
2270 | |
2271 | 2. If the name does not match a function, the shell searches for it | |
2272 | in the list of shell builtins. If a match is found, that builtin | |
2273 | is invoked. | |
2274 | ||
2275 | 3. If the name is neither a shell function nor a builtin, and | |
2276 | contains no slashes, Bash searches each element of `$PATH' for a | |
2277 | directory containing an executable file by that name. Bash uses a | |
cce855bc JA |
2278 | hash table to remember the full pathnames of executable files to |
2279 | avoid multiple `PATH' searches (see the description of `hash' in | |
6a8fd0ed | 2280 | *note Bourne Shell Builtins::). A full search of the directories |
ccc6cda3 | 2281 | in `$PATH' is performed only if the command is not found in the |
ed35cb4a CR |
2282 | hash table. If the search is unsuccessful, the shell searches for |
2283 | a defined shell function named `command_not_found_handle'. If | |
2284 | that function exists, it is invoked with the original command and | |
2285 | the original command's arguments as its arguments, and the | |
2286 | function's exit status becomes the exit status of the shell. If | |
2287 | that function is not defined, the shell prints an error message | |
2288 | and returns an exit status of 127. | |
ccc6cda3 JA |
2289 | |
2290 | 4. If the search is successful, or if the command name contains one | |
cce855bc JA |
2291 | or more slashes, the shell executes the named program in a |
2292 | separate execution environment. Argument 0 is set to the name | |
2293 | given, and the remaining arguments to the command are set to the | |
2294 | arguments supplied, if any. | |
ccc6cda3 JA |
2295 | |
2296 | 5. If this execution fails because the file is not in executable | |
cce855bc | 2297 | format, and the file is not a directory, it is assumed to be a |
6a8fd0ed | 2298 | SHELL SCRIPT and the shell executes it as described in *note Shell |
cce855bc JA |
2299 | Scripts::. |
2300 | ||
2301 | 6. If the command was not begun asynchronously, the shell waits for | |
2302 | the command to complete and collects its exit status. | |
2303 | ||
2304 | ||
2305 | \1f | |
2306 | File: bashref.info, Node: Command Execution Environment, Next: Environment, Prev: Command Search and Execution, Up: Executing Commands | |
2307 | ||
37c41ab1 CR |
2308 | 3.7.3 Command Execution Environment |
2309 | ----------------------------------- | |
cce855bc | 2310 | |
37c41ab1 | 2311 | The shell has an EXECUTION ENVIRONMENT, which consists of the following: |
cce855bc JA |
2312 | |
2313 | * open files inherited by the shell at invocation, as modified by | |
2314 | redirections supplied to the `exec' builtin | |
2315 | ||
2316 | * the current working directory as set by `cd', `pushd', or `popd', | |
2317 | or inherited by the shell at invocation | |
2318 | ||
2319 | * the file creation mode mask as set by `umask' or inherited from | |
2320 | the shell's parent | |
2321 | ||
2322 | * current traps set by `trap' | |
2323 | ||
2324 | * shell parameters that are set by variable assignment or with `set' | |
2325 | or inherited from the shell's parent in the environment | |
2326 | ||
2327 | * shell functions defined during execution or inherited from the | |
2328 | shell's parent in the environment | |
2329 | ||
2330 | * options enabled at invocation (either by default or with | |
2331 | command-line arguments) or by `set' | |
2332 | ||
d3ad40de | 2333 | * options enabled by `shopt' (*note The Shopt Builtin::) |
cce855bc | 2334 | |
28ef6c31 | 2335 | * shell aliases defined with `alias' (*note Aliases::) |
cce855bc JA |
2336 | |
2337 | * various process IDs, including those of background jobs (*note | |
28ef6c31 JA |
2338 | Lists::), the value of `$$', and the value of `$PPID' |
2339 | ||
cce855bc JA |
2340 | |
2341 | When a simple command other than a builtin or shell function is to | |
2342 | be executed, it is invoked in a separate execution environment that | |
2343 | consists of the following. Unless otherwise noted, the values are | |
2344 | inherited from the shell. | |
2345 | ||
2346 | * the shell's open files, plus any modifications and additions | |
2347 | specified by redirections to the command | |
2348 | ||
2349 | * the current working directory | |
2350 | ||
2351 | * the file creation mode mask | |
2352 | ||
d3a24ed2 CR |
2353 | * shell variables and functions marked for export, along with |
2354 | variables exported for the command, passed in the environment | |
2355 | (*note Environment::) | |
cce855bc JA |
2356 | |
2357 | * traps caught by the shell are reset to the values inherited from | |
2358 | the shell's parent, and traps ignored by the shell are ignored | |
2359 | ||
28ef6c31 | 2360 | |
cce855bc JA |
2361 | A command invoked in this separate environment cannot affect the |
2362 | shell's execution environment. | |
2363 | ||
d3a24ed2 CR |
2364 | Command substitution, commands grouped with parentheses, and |
2365 | asynchronous commands are invoked in a subshell environment that is a | |
2366 | duplicate of the shell environment, except that traps caught by the | |
2367 | shell are reset to the values that the shell inherited from its parent | |
2368 | at invocation. Builtin commands that are invoked as part of a pipeline | |
2369 | are also executed in a subshell environment. Changes made to the | |
2370 | subshell environment cannot affect the shell's execution environment. | |
ccc6cda3 | 2371 | |
db31fb26 CR |
2372 | Subshells spawned to execute command substitutions inherit the value |
2373 | of the `-e' option from the parent shell. When not in POSIX mode, Bash | |
2374 | clears the `-e' option in such subshells. | |
2375 | ||
f73dda09 JA |
2376 | If a command is followed by a `&' and job control is not active, the |
2377 | default standard input for the command is the empty file `/dev/null'. | |
2378 | Otherwise, the invoked command inherits the file descriptors of the | |
2379 | calling shell as modified by redirections. | |
2380 | ||
ccc6cda3 | 2381 | \1f |
cce855bc | 2382 | File: bashref.info, Node: Environment, Next: Exit Status, Prev: Command Execution Environment, Up: Executing Commands |
ccc6cda3 | 2383 | |
37c41ab1 CR |
2384 | 3.7.4 Environment |
2385 | ----------------- | |
ccc6cda3 | 2386 | |
37c41ab1 | 2387 | When a program is invoked it is given an array of strings called the |
ccc6cda3 JA |
2388 | ENVIRONMENT. This is a list of name-value pairs, of the form |
2389 | `name=value'. | |
2390 | ||
bb70624e | 2391 | Bash provides several ways to manipulate the environment. On |
ccc6cda3 JA |
2392 | invocation, the shell scans its own environment and creates a parameter |
2393 | for each name found, automatically marking it for EXPORT to child | |
2394 | processes. Executed commands inherit the environment. The `export' | |
2395 | and `declare -x' commands allow parameters and functions to be added to | |
2396 | and deleted from the environment. If the value of a parameter in the | |
2397 | environment is modified, the new value becomes part of the environment, | |
2398 | replacing the old. The environment inherited by any executed command | |
2399 | consists of the shell's initial environment, whose values may be | |
cce855bc JA |
2400 | modified in the shell, less any pairs removed by the `unset' and |
2401 | `export -n' commands, plus any additions via the `export' and `declare | |
2402 | -x' commands. | |
ccc6cda3 JA |
2403 | |
2404 | The environment for any simple command or function may be augmented | |
2405 | temporarily by prefixing it with parameter assignments, as described in | |
6a8fd0ed | 2406 | *note Shell Parameters::. These assignment statements affect only the |
ccc6cda3 JA |
2407 | environment seen by that command. |
2408 | ||
28ef6c31 | 2409 | If the `-k' option is set (*note The Set Builtin::), then all |
ccc6cda3 JA |
2410 | parameter assignments are placed in the environment for a command, not |
2411 | just those that precede the command name. | |
2412 | ||
2413 | When Bash invokes an external command, the variable `$_' is set to | |
122f603c | 2414 | the full pathname of the command and passed to that command in its |
ccc6cda3 JA |
2415 | environment. |
2416 | ||
2417 | \1f | |
2418 | File: bashref.info, Node: Exit Status, Next: Signals, Prev: Environment, Up: Executing Commands | |
2419 | ||
37c41ab1 CR |
2420 | 3.7.5 Exit Status |
2421 | ----------------- | |
ccc6cda3 | 2422 | |
29d25b54 CR |
2423 | The exit status of an executed command is the value returned by the |
2424 | WAITPID system call or equivalent function. Exit statuses fall between | |
2425 | 0 and 255, though, as explained below, the shell may use values above | |
2426 | 125 specially. Exit statuses from shell builtins and compound commands | |
122f603c | 2427 | are also limited to this range. Under certain circumstances, the shell |
29d25b54 CR |
2428 | will use special values to indicate specific failure modes. |
2429 | ||
2430 | For the shell's purposes, a command which exits with a zero exit | |
2431 | status has succeeded. A non-zero exit status indicates failure. This | |
cce855bc JA |
2432 | seemingly counter-intuitive scheme is used so there is one well-defined |
2433 | way to indicate success and a variety of ways to indicate various | |
2434 | failure modes. When a command terminates on a fatal signal whose | |
2435 | number is N, Bash uses the value 128+N as the exit status. | |
ccc6cda3 JA |
2436 | |
2437 | If a command is not found, the child process created to execute it | |
2438 | returns a status of 127. If a command is found but is not executable, | |
2439 | the return status is 126. | |
2440 | ||
cce855bc JA |
2441 | If a command fails because of an error during expansion or |
2442 | redirection, the exit status is greater than zero. | |
2443 | ||
ccc6cda3 | 2444 | The exit status is used by the Bash conditional commands (*note |
28ef6c31 JA |
2445 | Conditional Constructs::) and some of the list constructs (*note |
2446 | Lists::). | |
ccc6cda3 JA |
2447 | |
2448 | All of the Bash builtins return an exit status of zero if they | |
2449 | succeed and a non-zero status on failure, so they may be used by the | |
cce855bc JA |
2450 | conditional and list constructs. All builtins return an exit status of |
2451 | 2 to indicate incorrect usage. | |
ccc6cda3 JA |
2452 | |
2453 | \1f | |
2454 | File: bashref.info, Node: Signals, Prev: Exit Status, Up: Executing Commands | |
2455 | ||
37c41ab1 CR |
2456 | 3.7.6 Signals |
2457 | ------------- | |
ccc6cda3 | 2458 | |
37c41ab1 | 2459 | When Bash is interactive, in the absence of any traps, it ignores |
cce855bc JA |
2460 | `SIGTERM' (so that `kill 0' does not kill an interactive shell), and |
2461 | `SIGINT' is caught and handled (so that the `wait' builtin is | |
2462 | interruptible). When Bash receives a `SIGINT', it breaks out of any | |
2463 | executing loops. In all cases, Bash ignores `SIGQUIT'. If job control | |
28ef6c31 | 2464 | is in effect (*note Job Control::), Bash ignores `SIGTTIN', `SIGTTOU', |
cce855bc | 2465 | and `SIGTSTP'. |
ccc6cda3 | 2466 | |
5e13499c CR |
2467 | Non-builtin commands started by Bash have signal handlers set to the |
2468 | values inherited by the shell from its parent. When job control is not | |
2469 | in effect, asynchronous commands ignore `SIGINT' and `SIGQUIT' in | |
2470 | addition to these inherited handlers. Commands run as a result of | |
2471 | command substitution ignore the keyboard-generated job control signals | |
2472 | `SIGTTIN', `SIGTTOU', and `SIGTSTP'. | |
ccc6cda3 JA |
2473 | |
2474 | The shell exits by default upon receipt of a `SIGHUP'. Before | |
f73dda09 JA |
2475 | exiting, an interactive shell resends the `SIGHUP' to all jobs, running |
2476 | or stopped. Stopped jobs are sent `SIGCONT' to ensure that they receive | |
2477 | the `SIGHUP'. To prevent the shell from sending the `SIGHUP' signal to | |
2478 | a particular job, it should be removed from the jobs table with the | |
28ef6c31 | 2479 | `disown' builtin (*note Job Control Builtins::) or marked to not |
cce855bc JA |
2480 | receive `SIGHUP' using `disown -h'. |
2481 | ||
2482 | If the `huponexit' shell option has been set with `shopt' (*note | |
d3ad40de CR |
2483 | The Shopt Builtin::), Bash sends a `SIGHUP' to all jobs when an |
2484 | interactive login shell exits. | |
cce855bc | 2485 | |
5e13499c CR |
2486 | If Bash is waiting for a command to complete and receives a signal |
2487 | for which a trap has been set, the trap will not be executed until the | |
2488 | command completes. When Bash is waiting for an asynchronous command | |
2489 | via the `wait' builtin, the reception of a signal for which a trap has | |
2490 | been set will cause the `wait' builtin to return immediately with an | |
2491 | exit status greater than 128, immediately after which the trap is | |
2492 | executed. | |
ccc6cda3 JA |
2493 | |
2494 | \1f | |
2495 | File: bashref.info, Node: Shell Scripts, Prev: Executing Commands, Up: Basic Shell Features | |
2496 | ||
37c41ab1 CR |
2497 | 3.8 Shell Scripts |
2498 | ================= | |
ccc6cda3 | 2499 | |
37c41ab1 CR |
2500 | A shell script is a text file containing shell commands. When such a |
2501 | file is used as the first non-option argument when invoking Bash, and | |
28ef6c31 | 2502 | neither the `-c' nor `-s' option is supplied (*note Invoking Bash::), |
ccc6cda3 | 2503 | Bash reads and executes commands from the file, then exits. This mode |
f73dda09 JA |
2504 | of operation creates a non-interactive shell. The shell first searches |
2505 | for the file in the current directory, and looks in the directories in | |
2506 | `$PATH' if not found there. | |
2507 | ||
2508 | When Bash runs a shell script, it sets the special parameter `0' to | |
2509 | the name of the file, rather than the name of the shell, and the | |
2510 | positional parameters are set to the remaining arguments, if any are | |
2511 | given. If no additional arguments are supplied, the positional | |
2512 | parameters are unset. | |
ccc6cda3 JA |
2513 | |
2514 | A shell script may be made executable by using the `chmod' command | |
2515 | to turn on the execute bit. When Bash finds such a file while | |
2516 | searching the `$PATH' for a command, it spawns a subshell to execute | |
2517 | it. In other words, executing | |
2518 | filename ARGUMENTS | |
37c41ab1 | 2519 | is equivalent to executing |
ccc6cda3 JA |
2520 | bash filename ARGUMENTS |
2521 | ||
2522 | if `filename' is an executable shell script. This subshell | |
2523 | reinitializes itself, so that the effect is as if a new shell had been | |
cce855bc JA |
2524 | invoked to interpret the script, with the exception that the locations |
2525 | of commands remembered by the parent (see the description of `hash' in | |
6a8fd0ed | 2526 | *note Bourne Shell Builtins::) are retained by the child. |
ccc6cda3 | 2527 | |
bb70624e JA |
2528 | Most versions of Unix make this a part of the operating system's |
2529 | command execution mechanism. If the first line of a script begins with | |
2530 | the two characters `#!', the remainder of the line specifies an | |
2531 | interpreter for the program. Thus, you can specify Bash, `awk', Perl, | |
2532 | or some other interpreter and write the rest of the script file in that | |
2533 | language. | |
2534 | ||
2535 | The arguments to the interpreter consist of a single optional | |
2536 | argument following the interpreter name on the first line of the script | |
2537 | file, followed by the name of the script file, followed by the rest of | |
2538 | the arguments. Bash will perform this action on operating systems that | |
2539 | do not handle it themselves. Note that some older versions of Unix | |
2540 | limit the interpreter name and argument to a maximum of 32 characters. | |
2541 | ||
2542 | Bash scripts often begin with `#! /bin/bash' (assuming that Bash has | |
2543 | been installed in `/bin'), since this ensures that Bash will be used to | |
2544 | interpret the script, even if it is executed under another shell. | |
ccc6cda3 JA |
2545 | |
2546 | \1f | |
bb70624e | 2547 | File: bashref.info, Node: Shell Builtin Commands, Next: Shell Variables, Prev: Basic Shell Features, Up: Top |
ccc6cda3 | 2548 | |
37c41ab1 CR |
2549 | 4 Shell Builtin Commands |
2550 | ************************ | |
ccc6cda3 JA |
2551 | |
2552 | * Menu: | |
2553 | ||
2554 | * Bourne Shell Builtins:: Builtin commands inherited from the Bourne | |
2555 | Shell. | |
bb70624e | 2556 | * Bash Builtins:: Table of builtins specific to Bash. |
d3ad40de CR |
2557 | * Modifying Shell Behavior:: Builtins to modify shell attributes and |
2558 | optional behavior. | |
bb70624e | 2559 | * Special Builtins:: Builtin commands classified specially by |
ac18b312 | 2560 | POSIX. |
bb70624e JA |
2561 | |
2562 | Builtin commands are contained within the shell itself. When the | |
2563 | name of a builtin command is used as the first word of a simple command | |
28ef6c31 | 2564 | (*note Simple Commands::), the shell executes the command directly, |
bb70624e JA |
2565 | without invoking another program. Builtin commands are necessary to |
2566 | implement functionality impossible or inconvenient to obtain with | |
2567 | separate utilities. | |
ccc6cda3 | 2568 | |
ac18b312 CR |
2569 | This section briefly describes the builtins which Bash inherits from |
2570 | the Bourne Shell, as well as the builtin commands which are unique to | |
2571 | or have been extended in Bash. | |
bb70624e JA |
2572 | |
2573 | Several builtin commands are described in other chapters: builtin | |
2574 | commands which provide the Bash interface to the job control facilities | |
28ef6c31 JA |
2575 | (*note Job Control Builtins::), the directory stack (*note Directory |
2576 | Stack Builtins::), the command history (*note Bash History Builtins::), | |
2577 | and the programmable completion facilities (*note Programmable | |
2578 | Completion Builtins::). | |
bb70624e JA |
2579 | |
2580 | Many of the builtins have been extended by POSIX or Bash. | |
ccc6cda3 | 2581 | |
c2258e1c CR |
2582 | Unless otherwise noted, each builtin command documented as accepting |
2583 | options preceded by `-' accepts `--' to signify the end of the options. | |
6932f7f5 CR |
2584 | The `:', `true', `false', and `test' builtins do not accept options and |
2585 | do not treat `--' specially. The `exit', `logout', `break', | |
2586 | `continue', `let', and `shift' builtins accept and process arguments | |
2587 | beginning with `-' without requiring `--'. Other builtins that accept | |
2588 | arguments but are not specified as accepting options interpret | |
2589 | arguments beginning with `-' as invalid options and require `--' to | |
2590 | prevent this interpretation. | |
c2258e1c | 2591 | |
ccc6cda3 | 2592 | \1f |
bb70624e | 2593 | File: bashref.info, Node: Bourne Shell Builtins, Next: Bash Builtins, Up: Shell Builtin Commands |
ccc6cda3 | 2594 | |
37c41ab1 CR |
2595 | 4.1 Bourne Shell Builtins |
2596 | ========================= | |
ccc6cda3 | 2597 | |
37c41ab1 | 2598 | The following shell builtin commands are inherited from the Bourne |
ac18b312 | 2599 | Shell. These commands are implemented as specified by the POSIX |
ccc6cda3 JA |
2600 | standard. |
2601 | ||
bb70624e | 2602 | `: (a colon)' |
ccc6cda3 | 2603 | : [ARGUMENTS] |
122f603c | 2604 | |
ccc6cda3 | 2605 | Do nothing beyond expanding ARGUMENTS and performing redirections. |
cce855bc | 2606 | The return status is zero. |
ccc6cda3 | 2607 | |
bb70624e | 2608 | `. (a period)' |
b72432fd | 2609 | . FILENAME [ARGUMENTS] |
122f603c | 2610 | |
ccc6cda3 | 2611 | Read and execute commands from the FILENAME argument in the |
cce855bc | 2612 | current shell context. If FILENAME does not contain a slash, the |
28ef6c31 JA |
2613 | `PATH' variable is used to find FILENAME. When Bash is not in |
2614 | POSIX mode, the current directory is searched if FILENAME is not | |
2615 | found in `$PATH'. If any ARGUMENTS are supplied, they become the | |
2616 | positional parameters when FILENAME is executed. Otherwise the | |
2617 | positional parameters are unchanged. The return status is the | |
2618 | exit status of the last command executed, or zero if no commands | |
2619 | are executed. If FILENAME is not found, or cannot be read, the | |
2620 | return status is non-zero. This builtin is equivalent to `source'. | |
ccc6cda3 JA |
2621 | |
2622 | `break' | |
2623 | break [N] | |
122f603c | 2624 | |
ccc6cda3 | 2625 | Exit from a `for', `while', `until', or `select' loop. If N is |
cce855bc JA |
2626 | supplied, the Nth enclosing loop is exited. N must be greater |
2627 | than or equal to 1. The return status is zero unless N is not | |
2628 | greater than or equal to 1. | |
ccc6cda3 JA |
2629 | |
2630 | `cd' | |
67362c60 | 2631 | cd [-L|[-P [-e]]] [DIRECTORY] |
122f603c | 2632 | |
ccc6cda3 | 2633 | Change the current working directory to DIRECTORY. If DIRECTORY |
45c0f7f8 CR |
2634 | is not supplied, the value of the `HOME' shell variable is used. |
2635 | Any additional arguments following DIRECTORY are ignored. If the | |
2636 | shell variable `CDPATH' exists, it is used as a search path: each | |
2637 | directory name in `CDPATH' is searched for DIRECTORY, with | |
2638 | alternative directory names in `CDPATH' separated by a colon (`:'). | |
d3a24ed2 CR |
2639 | If DIRECTORY begins with a slash, `CDPATH' is not used. |
2640 | ||
45c0f7f8 CR |
2641 | The `-P' option means to not follow symbolic links: symbolic links |
2642 | are resolved while `cd' is traversing DIRECTORY and before | |
2643 | processing an instance of `..' in DIRECTORY. | |
2644 | ||
2645 | By default, or when the `-L' option is supplied, symbolic links in | |
2646 | DIRECTORY are resolved after `cd' processes an instance of `..' in | |
2647 | DIRECTORY. | |
2648 | ||
2649 | If `..' appears in DIRECTORY, it is processed by removing the | |
2650 | immediately preceding pathname component, back to a slash or the | |
2651 | beginning of DIRECTORY. | |
2652 | ||
2653 | If the `-e' option is supplied with `-P' and the current working | |
2654 | directory cannot be successfully determined after a successful | |
2655 | directory change, `cd' will return an unsuccessful status. If | |
2656 | DIRECTORY is `-', it is converted to `$OLDPWD' before the | |
2657 | directory change is attempted. | |
d3a24ed2 CR |
2658 | |
2659 | If a non-empty directory name from `CDPATH' is used, or if `-' is | |
2660 | the first argument, and the directory change is successful, the | |
2661 | absolute pathname of the new working directory is written to the | |
2662 | standard output. | |
2663 | ||
2664 | The return status is zero if the directory is successfully changed, | |
2665 | non-zero otherwise. | |
ccc6cda3 JA |
2666 | |
2667 | `continue' | |
2668 | continue [N] | |
122f603c | 2669 | |
ccc6cda3 JA |
2670 | Resume the next iteration of an enclosing `for', `while', `until', |
2671 | or `select' loop. If N is supplied, the execution of the Nth | |
cce855bc JA |
2672 | enclosing loop is resumed. N must be greater than or equal to 1. |
2673 | The return status is zero unless N is not greater than or equal to | |
2674 | 1. | |
ccc6cda3 JA |
2675 | |
2676 | `eval' | |
2677 | eval [ARGUMENTS] | |
122f603c | 2678 | |
ccc6cda3 | 2679 | The arguments are concatenated together into a single command, |
cce855bc JA |
2680 | which is then read and executed, and its exit status returned as |
2681 | the exit status of `eval'. If there are no arguments or only | |
2682 | empty arguments, the return status is zero. | |
ccc6cda3 JA |
2683 | |
2684 | `exec' | |
cce855bc | 2685 | exec [-cl] [-a NAME] [COMMAND [ARGUMENTS]] |
122f603c | 2686 | |
cce855bc JA |
2687 | If COMMAND is supplied, it replaces the shell without creating a |
2688 | new process. If the `-l' option is supplied, the shell places a | |
d3ad40de CR |
2689 | dash at the beginning of the zeroth argument passed to COMMAND. |
2690 | This is what the `login' program does. The `-c' option causes | |
2691 | COMMAND to be executed with an empty environment. If `-a' is | |
2692 | supplied, the shell passes NAME as the zeroth argument to COMMAND. | |
122f603c CR |
2693 | If COMMAND cannot be executed for some reason, a non-interactive |
2694 | shell exits, unless the `execfail' shell option is enabled. In | |
2695 | that case, it returns failure. An interactive shell returns | |
2696 | failure if the file cannot be executed. If no COMMAND is | |
2697 | specified, redirections may be used to affect the current shell | |
2698 | environment. If there are no redirection errors, the return | |
2699 | status is zero; otherwise the return status is non-zero. | |
ccc6cda3 JA |
2700 | |
2701 | `exit' | |
2702 | exit [N] | |
122f603c | 2703 | |
bb70624e JA |
2704 | Exit the shell, returning a status of N to the shell's parent. If |
2705 | N is omitted, the exit status is that of the last command executed. | |
cce855bc | 2706 | Any trap on `EXIT' is executed before the shell terminates. |
ccc6cda3 JA |
2707 | |
2708 | `export' | |
2709 | export [-fn] [-p] [NAME[=VALUE]] | |
122f603c | 2710 | |
ccc6cda3 JA |
2711 | Mark each NAME to be passed to child processes in the environment. |
2712 | If the `-f' option is supplied, the NAMEs refer to shell | |
cce855bc JA |
2713 | functions; otherwise the names refer to shell variables. The `-n' |
2714 | option means to no longer mark each NAME for export. If no NAMES | |
122f603c CR |
2715 | are supplied, or if the `-p' option is given, a list of names of |
2716 | all exported variables is displayed. The `-p' option displays | |
2717 | output in a form that may be reused as input. If a variable name | |
2718 | is followed by =VALUE, the value of the variable is set to VALUE. | |
d3a24ed2 CR |
2719 | |
2720 | The return status is zero unless an invalid option is supplied, | |
2721 | one of the names is not a valid shell variable name, or `-f' is | |
2722 | supplied with a name that is not a shell function. | |
ccc6cda3 JA |
2723 | |
2724 | `getopts' | |
2725 | getopts OPTSTRING NAME [ARGS] | |
122f603c | 2726 | |
ccc6cda3 | 2727 | `getopts' is used by shell scripts to parse positional parameters. |
bb70624e JA |
2728 | OPTSTRING contains the option characters to be recognized; if a |
2729 | character is followed by a colon, the option is expected to have an | |
122f603c | 2730 | argument, which should be separated from it by whitespace. The |
bb70624e JA |
2731 | colon (`:') and question mark (`?') may not be used as option |
2732 | characters. Each time it is invoked, `getopts' places the next | |
2733 | option in the shell variable NAME, initializing NAME if it does | |
2734 | not exist, and the index of the next argument to be processed into | |
2735 | the variable `OPTIND'. `OPTIND' is initialized to 1 each time the | |
2736 | shell or a shell script is invoked. When an option requires an | |
2737 | argument, `getopts' places that argument into the variable | |
2738 | `OPTARG'. The shell does not reset `OPTIND' automatically; it | |
2739 | must be manually reset between multiple calls to `getopts' within | |
2740 | the same shell invocation if a new set of parameters is to be used. | |
ccc6cda3 | 2741 | |
cce855bc JA |
2742 | When the end of options is encountered, `getopts' exits with a |
2743 | return value greater than zero. `OPTIND' is set to the index of | |
e05be32d | 2744 | the first non-option argument, and NAME is set to `?'. |
cce855bc JA |
2745 | |
2746 | `getopts' normally parses the positional parameters, but if more | |
2747 | arguments are given in ARGS, `getopts' parses those instead. | |
2748 | ||
ccc6cda3 JA |
2749 | `getopts' can report errors in two ways. If the first character of |
2750 | OPTSTRING is a colon, SILENT error reporting is used. In normal | |
122f603c | 2751 | operation, diagnostic messages are printed when invalid options or |
ccc6cda3 | 2752 | missing option arguments are encountered. If the variable `OPTERR' |
cce855bc | 2753 | is set to 0, no error messages will be displayed, even if the first |
ccc6cda3 JA |
2754 | character of `optstring' is not a colon. |
2755 | ||
cce855bc | 2756 | If an invalid option is seen, `getopts' places `?' into NAME and, |
ccc6cda3 JA |
2757 | if not silent, prints an error message and unsets `OPTARG'. If |
2758 | `getopts' is silent, the option character found is placed in | |
2759 | `OPTARG' and no diagnostic message is printed. | |
2760 | ||
2761 | If a required argument is not found, and `getopts' is not silent, | |
2762 | a question mark (`?') is placed in NAME, `OPTARG' is unset, and a | |
2763 | diagnostic message is printed. If `getopts' is silent, then a | |
2764 | colon (`:') is placed in NAME and `OPTARG' is set to the option | |
2765 | character found. | |
2766 | ||
ccc6cda3 | 2767 | `hash' |
ac18b312 | 2768 | hash [-r] [-p FILENAME] [-dt] [NAME] |
122f603c | 2769 | |
eb0b2ad8 CR |
2770 | Each time `hash' is invoked, it remembers the full pathnames of the |
2771 | commands specified as NAME arguments, so they need not be searched | |
2772 | for on subsequent invocations. The commands are found by | |
2773 | searching through the directories listed in `$PATH'. Any | |
2774 | previously-remembered pathname is discarded. The `-p' option | |
2775 | inhibits the path search, and FILENAME is used as the location of | |
2776 | NAME. The `-r' option causes the shell to forget all remembered | |
2777 | locations. The `-d' option causes the shell to forget the | |
2778 | remembered location of each NAME. If the `-t' option is supplied, | |
2779 | the full pathname to which each NAME corresponds is printed. If | |
2780 | multiple NAME arguments are supplied with `-t' the NAME is printed | |
2781 | before the hashed full pathname. The `-l' option causes output to | |
2782 | be displayed in a format that may be reused as input. If no | |
7117c2d2 JA |
2783 | arguments are given, or if only `-l' is supplied, information |
2784 | about remembered commands is printed. The return status is zero | |
2785 | unless a NAME is not found or an invalid option is supplied. | |
ccc6cda3 JA |
2786 | |
2787 | `pwd' | |
2788 | pwd [-LP] | |
122f603c | 2789 | |
bb70624e JA |
2790 | Print the absolute pathname of the current working directory. If |
2791 | the `-P' option is supplied, the pathname printed will not contain | |
2792 | symbolic links. If the `-L' option is supplied, the pathname | |
2793 | printed may contain symbolic links. The return status is zero | |
2794 | unless an error is encountered while determining the name of the | |
2795 | current directory or an invalid option is supplied. | |
ccc6cda3 JA |
2796 | |
2797 | `readonly' | |
d9e1f41e | 2798 | readonly [-aAf] [-p] [NAME[=VALUE]] ... |
122f603c | 2799 | |
cce855bc JA |
2800 | Mark each NAME as readonly. The values of these names may not be |
2801 | changed by subsequent assignment. If the `-f' option is supplied, | |
2802 | each NAME refers to a shell function. The `-a' option means each | |
09767ff0 | 2803 | NAME refers to an indexed array variable; the `-A' option means |
d9e1f41e CR |
2804 | each NAME refers to an associative array variable. If both |
2805 | options are supplied, `-A' takes precedence. If no NAME arguments | |
2806 | are given, or if the `-p' option is supplied, a list of all | |
2807 | readonly names is printed. The other options may be used to | |
2808 | restrict the output to a subset of the set of readonly names. The | |
2809 | `-p' option causes output to be displayed in a format that may be | |
2810 | reused as input. If a variable name is followed by =VALUE, the | |
2811 | value of the variable is set to VALUE. The return status is zero | |
2812 | unless an invalid option is supplied, one of the NAME arguments is | |
2813 | not a valid shell variable or function name, or the `-f' option is | |
2814 | supplied with a name that is not a shell function. | |
ccc6cda3 JA |
2815 | |
2816 | `return' | |
2817 | return [N] | |
122f603c CR |
2818 | |
2819 | Cause a shell function to stop executing and return the value N to | |
2820 | its caller. If N is not supplied, the return value is the exit | |
2821 | status of the last command executed in the function. `return' may | |
2822 | also be used to terminate execution of a script being executed | |
2823 | with the `.' (`source') builtin, returning either N or the exit | |
2824 | status of the last command executed within the script as the exit | |
77638cbf CR |
2825 | status of the script. If N is supplied, the return value is its |
2826 | least significant 8 bits. Any command associated with the | |
2827 | `RETURN' trap is executed before execution resumes after the | |
2828 | function or script. The return status is non-zero if `return' is | |
2829 | supplied a non-numeric argument or is used outside a function and | |
2830 | not during the execution of a script by `.' or `source'. | |
ccc6cda3 JA |
2831 | |
2832 | `shift' | |
2833 | shift [N] | |
122f603c | 2834 | |
cce855bc | 2835 | Shift the positional parameters to the left by N. The positional |
d3ad40de CR |
2836 | parameters from N+1 ... `$#' are renamed to `$1' ... `$#'-N. |
2837 | Parameters represented by the numbers `$#' to `$#'-N+1 are unset. | |
2838 | N must be a non-negative number less than or equal to `$#'. If N | |
2839 | is zero or greater than `$#', the positional parameters are not | |
bb70624e JA |
2840 | changed. If N is not supplied, it is assumed to be 1. The return |
2841 | status is zero unless N is greater than `$#' or less than zero, | |
2842 | non-zero otherwise. | |
ccc6cda3 | 2843 | |
122f603c | 2844 | `test[B' |
ccc6cda3 | 2845 | `[' |
122f603c CR |
2846 | test EXPR |
2847 | ||
2848 | Evaluate a conditional expression EXPR and return a status of 0 | |
2849 | (true) or 1 (false). Each operator and operand must be a separate | |
2850 | argument. Expressions are composed of the primaries described | |
2851 | below in *note Bash Conditional Expressions::. `test' does not | |
2852 | accept any options, nor does it accept and ignore an argument of | |
2853 | `--' as signifying the end of options. | |
cce855bc | 2854 | |
bb70624e JA |
2855 | When the `[' form is used, the last argument to the command must |
2856 | be a `]'. | |
2857 | ||
cce855bc | 2858 | Expressions may be combined using the following operators, listed |
d7f49990 | 2859 | in decreasing order of precedence. The evaluation depends on the |
510e20a2 CR |
2860 | number of arguments; see below. Operator precedence is used when |
2861 | there are five or more arguments. | |
cce855bc JA |
2862 | |
2863 | `! EXPR' | |
2864 | True if EXPR is false. | |
2865 | ||
2866 | `( EXPR )' | |
2867 | Returns the value of EXPR. This may be used to override the | |
2868 | normal precedence of operators. | |
2869 | ||
2870 | `EXPR1 -a EXPR2' | |
2871 | True if both EXPR1 and EXPR2 are true. | |
2872 | ||
2873 | `EXPR1 -o EXPR2' | |
2874 | True if either EXPR1 or EXPR2 is true. | |
2875 | ||
2876 | The `test' and `[' builtins evaluate conditional expressions using | |
2877 | a set of rules based on the number of arguments. | |
2878 | ||
2879 | 0 arguments | |
2880 | The expression is false. | |
2881 | ||
2882 | 1 argument | |
2883 | The expression is true if and only if the argument is not | |
2884 | null. | |
2885 | ||
2886 | 2 arguments | |
2887 | If the first argument is `!', the expression is true if and | |
2888 | only if the second argument is null. If the first argument | |
2889 | is one of the unary conditional operators (*note Bash | |
28ef6c31 | 2890 | Conditional Expressions::), the expression is true if the |
cce855bc JA |
2891 | unary test is true. If the first argument is not a valid |
2892 | unary operator, the expression is false. | |
2893 | ||
2894 | 3 arguments | |
510e20a2 CR |
2895 | The following conditions are applied in the order listed. If |
2896 | the second argument is one of the binary conditional | |
28ef6c31 | 2897 | operators (*note Bash Conditional Expressions::), the result |
cce855bc | 2898 | of the expression is the result of the binary test using the |
d7f49990 CR |
2899 | first and third arguments as operands. The `-a' and `-o' |
2900 | operators are considered binary operators when there are | |
2901 | three arguments. If the first argument is `!', the value is | |
2902 | the negation of the two-argument test using the second and | |
2903 | third arguments. If the first argument is exactly `(' and | |
2904 | the third argument is exactly `)', the result is the | |
2905 | one-argument test of the second argument. Otherwise, the | |
2906 | expression is false. | |
cce855bc JA |
2907 | |
2908 | 4 arguments | |
2909 | If the first argument is `!', the result is the negation of | |
2910 | the three-argument expression composed of the remaining | |
2911 | arguments. Otherwise, the expression is parsed and evaluated | |
2912 | according to precedence using the rules listed above. | |
2913 | ||
2914 | 5 or more arguments | |
2915 | The expression is parsed and evaluated according to precedence | |
2916 | using the rules listed above. | |
ccc6cda3 | 2917 | |
54a1fa7c CR |
2918 | When used with `test' or `[', the `<' and `>' operators sort |
2919 | lexicographically using ASCII ordering. | |
2920 | ||
ccc6cda3 JA |
2921 | `times' |
2922 | times | |
122f603c | 2923 | |
ccc6cda3 | 2924 | Print out the user and system times used by the shell and its |
cce855bc | 2925 | children. The return status is zero. |
ccc6cda3 JA |
2926 | |
2927 | `trap' | |
d166f048 | 2928 | trap [-lp] [ARG] [SIGSPEC ...] |
122f603c | 2929 | |
ccc6cda3 | 2930 | The commands in ARG are to be read and executed when the shell |
9f422431 CR |
2931 | receives signal SIGSPEC. If ARG is absent (and there is a single |
2932 | SIGSPEC) or equal to `-', each specified signal's disposition is | |
2933 | reset to the value it had when the shell was started. If ARG is | |
2934 | the null string, then the signal specified by each SIGSPEC is | |
2935 | ignored by the shell and commands it invokes. If ARG is not | |
2936 | present and `-p' has been supplied, the shell displays the trap | |
2937 | commands associated with each SIGSPEC. If no arguments are | |
2938 | supplied, or only `-p' is given, `trap' prints the list of commands | |
2939 | associated with each signal number in a form that may be reused as | |
2940 | shell input. The `-l' option causes the shell to print a list of | |
2941 | signal names and their corresponding numbers. Each SIGSPEC is | |
2942 | either a signal name or a signal number. Signal names are case | |
4a8bb13f CR |
2943 | insensitive and the `SIG' prefix is optional. |
2944 | ||
2945 | If a SIGSPEC is `0' or `EXIT', ARG is executed when the shell | |
2946 | exits. If a SIGSPEC is `DEBUG', the command ARG is executed | |
2947 | before every simple command, `for' command, `case' command, | |
2948 | `select' command, every arithmetic `for' command, and before the | |
2949 | first command executes in a shell function. Refer to the | |
2950 | description of the `extdebug' option to the `shopt' builtin (*note | |
2951 | The Shopt Builtin::) for details of its effect on the `DEBUG' trap. | |
2952 | If a SIGSPEC is `RETURN', the command ARG is executed each time a | |
2953 | shell function or a script executed with the `.' or `source' | |
2954 | builtins finishes executing. | |
2955 | ||
2956 | If a SIGSPEC is `ERR', the command ARG is executed whenever a | |
2957 | simple command has a non-zero exit status, subject to the | |
2958 | following conditions. The `ERR' trap is not executed if the | |
2959 | failed command is part of the command list immediately following | |
2960 | an `until' or `while' keyword, part of the test following the `if' | |
2961 | or `elif' reserved words, part of a command executed in a `&&' or | |
2962 | `||' list, or if the command's return status is being inverted | |
2963 | using `!'. These are the same conditions obeyed by the `errexit' | |
2964 | option. | |
d3a24ed2 | 2965 | |
ccc6cda3 | 2966 | Signals ignored upon entry to the shell cannot be trapped or reset. |
d3ad40de | 2967 | Trapped signals that are not being ignored are reset to their |
4a8bb13f CR |
2968 | original values in a subshell or subshell environment when one is |
2969 | created. | |
ccc6cda3 | 2970 | |
cce855bc JA |
2971 | The return status is zero unless a SIGSPEC does not specify a |
2972 | valid signal. | |
2973 | ||
ccc6cda3 | 2974 | `umask' |
cce855bc | 2975 | umask [-p] [-S] [MODE] |
122f603c | 2976 | |
ccc6cda3 JA |
2977 | Set the shell process's file creation mask to MODE. If MODE |
2978 | begins with a digit, it is interpreted as an octal number; if not, | |
2979 | it is interpreted as a symbolic mode mask similar to that accepted | |
2980 | by the `chmod' command. If MODE is omitted, the current value of | |
2981 | the mask is printed. If the `-S' option is supplied without a | |
cce855bc JA |
2982 | MODE argument, the mask is printed in a symbolic format. If the |
2983 | `-p' option is supplied, and MODE is omitted, the output is in a | |
2984 | form that may be reused as input. The return status is zero if | |
2985 | the mode is successfully changed or if no MODE argument is | |
2986 | supplied, and non-zero otherwise. | |
ccc6cda3 | 2987 | |
bb70624e JA |
2988 | Note that when the mode is interpreted as an octal number, each |
2989 | number of the umask is subtracted from `7'. Thus, a umask of `022' | |
2990 | results in permissions of `755'. | |
2991 | ||
ccc6cda3 JA |
2992 | `unset' |
2993 | unset [-fv] [NAME] | |
122f603c CR |
2994 | |
2995 | Remove each variable or function NAME. If the `-v' option is | |
74d0116b CR |
2996 | given, each NAME refers to a shell variable and that variable is |
2997 | remvoved. If the `-f' option is given, the NAMEs refer to shell | |
2998 | functions, and the function definition is removed. If no options | |
2999 | are supplied, each NAME refers to a variable; if there is no | |
3000 | variable by that name, any function with that name is unset. | |
3001 | Readonly variables and functions may not be unset. The return | |
3002 | status is zero unless a NAME is readonly. | |
ccc6cda3 JA |
3003 | |
3004 | \1f | |
d3ad40de | 3005 | File: bashref.info, Node: Bash Builtins, Next: Modifying Shell Behavior, Prev: Bourne Shell Builtins, Up: Shell Builtin Commands |
ccc6cda3 | 3006 | |
37c41ab1 CR |
3007 | 4.2 Bash Builtin Commands |
3008 | ========================= | |
ccc6cda3 | 3009 | |
37c41ab1 | 3010 | This section describes builtin commands which are unique to or have |
bb70624e | 3011 | been extended in Bash. Some of these commands are specified in the |
ac18b312 | 3012 | POSIX standard. |
ccc6cda3 | 3013 | |
bb70624e | 3014 | `alias' |
122f603c | 3015 | alias [-p] [NAME[=VALUE] ...] |
ccc6cda3 | 3016 | |
bb70624e JA |
3017 | Without arguments or with the `-p' option, `alias' prints the list |
3018 | of aliases on the standard output in a form that allows them to be | |
3019 | reused as input. If arguments are supplied, an alias is defined | |
3020 | for each NAME whose VALUE is given. If no VALUE is given, the name | |
6a8fd0ed | 3021 | and value of the alias is printed. Aliases are described in *note |
bb70624e | 3022 | Aliases::. |
ccc6cda3 | 3023 | |
bb70624e | 3024 | `bind' |
45c0f7f8 | 3025 | bind [-m KEYMAP] [-lpsvPSVX] |
bb70624e JA |
3026 | bind [-m KEYMAP] [-q FUNCTION] [-u FUNCTION] [-r KEYSEQ] |
3027 | bind [-m KEYMAP] -f FILENAME | |
3028 | bind [-m KEYMAP] -x KEYSEQ:SHELL-COMMAND | |
3029 | bind [-m KEYMAP] KEYSEQ:FUNCTION-NAME | |
7117c2d2 | 3030 | bind READLINE-COMMAND |
ccc6cda3 | 3031 | |
28ef6c31 | 3032 | Display current Readline (*note Command Line Editing::) key and |
7117c2d2 JA |
3033 | function bindings, bind a key sequence to a Readline function or |
3034 | macro, or set a Readline variable. Each non-option argument is a | |
d3ad40de | 3035 | command as it would appear in a Readline initialization file |
7117c2d2 JA |
3036 | (*note Readline Init File::), but each binding or command must be |
3037 | passed as a separate argument; e.g., | |
ed35cb4a CR |
3038 | `"\C-x\C-r":re-read-init-file'. |
3039 | ||
3040 | Options, if supplied, have the following meanings: | |
ccc6cda3 | 3041 | |
bb70624e JA |
3042 | `-m KEYMAP' |
3043 | Use KEYMAP as the keymap to be affected by the subsequent | |
3044 | bindings. Acceptable KEYMAP names are `emacs', | |
28ef6c31 | 3045 | `emacs-standard', `emacs-meta', `emacs-ctlx', `vi', `vi-move', |
bb70624e JA |
3046 | `vi-command', and `vi-insert'. `vi' is equivalent to |
3047 | `vi-command'; `emacs' is equivalent to `emacs-standard'. | |
cce855bc | 3048 | |
bb70624e JA |
3049 | `-l' |
3050 | List the names of all Readline functions. | |
cce855bc | 3051 | |
bb70624e JA |
3052 | `-p' |
3053 | Display Readline function names and bindings in such a way | |
3054 | that they can be used as input or in a Readline | |
3055 | initialization file. | |
cce855bc | 3056 | |
bb70624e JA |
3057 | `-P' |
3058 | List current Readline function names and bindings. | |
cce855bc | 3059 | |
bb70624e JA |
3060 | `-v' |
3061 | Display Readline variable names and values in such a way that | |
3062 | they can be used as input or in a Readline initialization | |
3063 | file. | |
ccc6cda3 | 3064 | |
bb70624e JA |
3065 | `-V' |
3066 | List current Readline variable names and values. | |
ccc6cda3 | 3067 | |
bb70624e JA |
3068 | `-s' |
3069 | Display Readline key sequences bound to macros and the | |
3070 | strings they output in such a way that they can be used as | |
3071 | input or in a Readline initialization file. | |
ccc6cda3 | 3072 | |
bb70624e JA |
3073 | `-S' |
3074 | Display Readline key sequences bound to macros and the | |
3075 | strings they output. | |
ccc6cda3 | 3076 | |
bb70624e JA |
3077 | `-f FILENAME' |
3078 | Read key bindings from FILENAME. | |
ccc6cda3 | 3079 | |
bb70624e JA |
3080 | `-q FUNCTION' |
3081 | Query about which keys invoke the named FUNCTION. | |
ccc6cda3 | 3082 | |
bb70624e JA |
3083 | `-u FUNCTION' |
3084 | Unbind all keys bound to the named FUNCTION. | |
ccc6cda3 | 3085 | |
bb70624e JA |
3086 | `-r KEYSEQ' |
3087 | Remove any current binding for KEYSEQ. | |
ccc6cda3 | 3088 | |
bb70624e JA |
3089 | `-x KEYSEQ:SHELL-COMMAND' |
3090 | Cause SHELL-COMMAND to be executed whenever KEYSEQ is entered. | |
ed35cb4a CR |
3091 | When SHELL-COMMAND is executed, the shell sets the |
3092 | `READLINE_LINE' variable to the contents of the Readline line | |
3093 | buffer and the `READLINE_POINT' variable to the current | |
3094 | location of the insertion point. If the executed command | |
3095 | changes the value of `READLINE_LINE' or `READLINE_POINT', | |
3096 | those new values will be reflected in the editing state. | |
761783bf | 3097 | |
45c0f7f8 CR |
3098 | `-X' |
3099 | List all key sequences bound to shell commands and the | |
3100 | associated commands in a format that can be reused as input. | |
3101 | ||
bb70624e JA |
3102 | The return status is zero unless an invalid option is supplied or |
3103 | an error occurs. | |
ccc6cda3 | 3104 | |
bb70624e JA |
3105 | `builtin' |
3106 | builtin [SHELL-BUILTIN [ARGS]] | |
122f603c | 3107 | |
bb70624e JA |
3108 | Run a shell builtin, passing it ARGS, and return its exit status. |
3109 | This is useful when defining a shell function with the same name | |
3110 | as a shell builtin, retaining the functionality of the builtin | |
3111 | within the function. The return status is non-zero if | |
3112 | SHELL-BUILTIN is not a shell builtin command. | |
ccc6cda3 | 3113 | |
d3a24ed2 CR |
3114 | `caller' |
3115 | caller [EXPR] | |
122f603c | 3116 | |
d3a24ed2 | 3117 | Returns the context of any active subroutine call (a shell |
5e13499c | 3118 | function or a script executed with the `.' or `source' builtins). |
d3a24ed2 CR |
3119 | |
3120 | Without EXPR, `caller' displays the line number and source | |
3121 | filename of the current subroutine call. If a non-negative | |
3122 | integer is supplied as EXPR, `caller' displays the line number, | |
3123 | subroutine name, and source file corresponding to that position in | |
3124 | the current execution call stack. This extra information may be | |
3125 | used, for example, to print a stack trace. The current frame is | |
3126 | frame 0. | |
3127 | ||
3128 | The return value is 0 unless the shell is not executing a | |
3129 | subroutine call or EXPR does not correspond to a valid position in | |
3130 | the call stack. | |
3131 | ||
bb70624e JA |
3132 | `command' |
3133 | command [-pVv] COMMAND [ARGUMENTS ...] | |
122f603c | 3134 | |
bb70624e JA |
3135 | Runs COMMAND with ARGUMENTS ignoring any shell function named |
3136 | COMMAND. Only shell builtin commands or commands found by | |
3137 | searching the `PATH' are executed. If there is a shell function | |
3138 | named `ls', running `command ls' within the function will execute | |
3139 | the external command `ls' instead of calling the function | |
3140 | recursively. The `-p' option means to use a default value for | |
28ef6c31 | 3141 | `PATH' that is guaranteed to find all of the standard utilities. |
bb70624e JA |
3142 | The return status in this case is 127 if COMMAND cannot be found |
3143 | or an error occurred, and the exit status of COMMAND otherwise. | |
ccc6cda3 | 3144 | |
bb70624e JA |
3145 | If either the `-V' or `-v' option is supplied, a description of |
3146 | COMMAND is printed. The `-v' option causes a single word | |
3147 | indicating the command or file name used to invoke COMMAND to be | |
3148 | displayed; the `-V' option produces a more verbose description. | |
3149 | In this case, the return status is zero if COMMAND is found, and | |
3150 | non-zero if not. | |
ccc6cda3 | 3151 | |
bb70624e | 3152 | `declare' |
122f603c | 3153 | declare [-aAfFgilrtux] [-p] [NAME[=VALUE] ...] |
ccc6cda3 | 3154 | |
bb70624e JA |
3155 | Declare variables and give them attributes. If no NAMEs are |
3156 | given, then display the values of variables instead. | |
ccc6cda3 | 3157 | |
bb70624e | 3158 | The `-p' option will display the attributes and values of each |
6a8fd0ed CR |
3159 | NAME. When `-p' is used with NAME arguments, additional options |
3160 | are ignored. | |
3161 | ||
3162 | When `-p' is supplied without NAME arguments, `declare' will | |
3163 | display the attributes and values of all variables having the | |
3164 | attributes specified by the additional options. If no other | |
3165 | options are supplied with `-p', `declare' will display the | |
3166 | attributes and values of all shell variables. The `-f' option | |
3167 | will restrict the display to shell functions. | |
3168 | ||
3169 | The `-F' option inhibits the display of function definitions; only | |
3170 | the function name and attributes are printed. If the `extdebug' | |
3171 | shell option is enabled using `shopt' (*note The Shopt Builtin::), | |
3172 | the source file name and line number where the function is defined | |
220537f2 CR |
3173 | are displayed as well. `-F' implies `-f'. |
3174 | ||
3175 | The `-g' option forces variables to be created or modified at the | |
d9e1f41e CR |
3176 | global scope, even when `declare' is executed in a shell function. |
3177 | It is ignored in all other cases. | |
220537f2 CR |
3178 | |
3179 | The following options can be used to restrict output to variables | |
3180 | with the specified attributes or to give variables attributes: | |
ccc6cda3 | 3181 | |
bb70624e | 3182 | `-a' |
09767ff0 CR |
3183 | Each NAME is an indexed array variable (*note Arrays::). |
3184 | ||
3185 | `-A' | |
3186 | Each NAME is an associative array variable (*note Arrays::). | |
ccc6cda3 | 3187 | |
bb70624e JA |
3188 | `-f' |
3189 | Use function names only. | |
ccc6cda3 | 3190 | |
bb70624e JA |
3191 | `-i' |
3192 | The variable is to be treated as an integer; arithmetic | |
28ef6c31 | 3193 | evaluation (*note Shell Arithmetic::) is performed when the |
bb70624e | 3194 | variable is assigned a value. |
ccc6cda3 | 3195 | |
8e1a6eaa CR |
3196 | `-l' |
3197 | When the variable is assigned a value, all upper-case | |
3198 | characters are converted to lower-case. The upper-case | |
3199 | attribute is disabled. | |
3200 | ||
bb70624e JA |
3201 | `-r' |
3202 | Make NAMEs readonly. These names cannot then be assigned | |
3203 | values by subsequent assignment statements or unset. | |
ccc6cda3 | 3204 | |
7117c2d2 JA |
3205 | `-t' |
3206 | Give each NAME the `trace' attribute. Traced functions | |
8fed3589 CR |
3207 | inherit the `DEBUG' and `RETURN' traps from the calling shell. |
3208 | The trace attribute has no special meaning for variables. | |
7117c2d2 | 3209 | |
8e1a6eaa CR |
3210 | `-u' |
3211 | When the variable is assigned a value, all lower-case | |
3212 | characters are converted to upper-case. The lower-case | |
3213 | attribute is disabled. | |
3214 | ||
bb70624e JA |
3215 | `-x' |
3216 | Mark each NAME for export to subsequent commands via the | |
3217 | environment. | |
ccc6cda3 | 3218 | |
d3ad40de CR |
3219 | Using `+' instead of `-' turns off the attribute instead, with the |
3220 | exceptions that `+a' may not be used to destroy an array variable | |
3221 | and `+r' will not remove the readonly attribute. When used in a | |
3222 | function, `declare' makes each NAME local, as with the `local' | |
220537f2 CR |
3223 | command, unless the `-g' option is used. If a variable name is |
3224 | followed by =VALUE, the value of the variable is set to VALUE. | |
ccc6cda3 | 3225 | |
bb70624e JA |
3226 | The return status is zero unless an invalid option is encountered, |
3227 | an attempt is made to define a function using `-f foo=bar', an | |
3228 | attempt is made to assign a value to a readonly variable, an | |
3229 | attempt is made to assign a value to an array variable without | |
28ef6c31 | 3230 | using the compound assignment syntax (*note Arrays::), one of the |
bb70624e JA |
3231 | NAMES is not a valid shell variable name, an attempt is made to |
3232 | turn off readonly status for a readonly variable, an attempt is | |
3233 | made to turn off array status for an array variable, or an attempt | |
3234 | is made to display a non-existent function with `-f'. | |
ccc6cda3 | 3235 | |
bb70624e JA |
3236 | `echo' |
3237 | echo [-neE] [ARG ...] | |
122f603c | 3238 | |
bb70624e | 3239 | Output the ARGs, separated by spaces, terminated with a newline. |
74d0116b CR |
3240 | The return status is 0 unless a write error occurs. If `-n' is |
3241 | specified, the trailing newline is suppressed. If the `-e' option | |
3242 | is given, interpretation of the following backslash-escaped | |
3243 | characters is enabled. The `-E' option disables the | |
3244 | interpretation of these escape characters, even on systems where | |
3245 | they are interpreted by default. The `xpg_echo' shell option may | |
3246 | be used to dynamically determine whether or not `echo' expands | |
3247 | these escape characters by default. `echo' does not interpret | |
3248 | `--' to mean the end of options. | |
1c72c0cd CR |
3249 | |
3250 | `echo' interprets the following escape sequences: | |
bb70624e JA |
3251 | `\a' |
3252 | alert (bell) | |
ccc6cda3 | 3253 | |
bb70624e JA |
3254 | `\b' |
3255 | backspace | |
ccc6cda3 | 3256 | |
bb70624e | 3257 | `\c' |
a9fac3b2 | 3258 | suppress further output |
ccc6cda3 | 3259 | |
bb70624e | 3260 | `\e' |
9ec5ed66 | 3261 | `\E' |
bb70624e | 3262 | escape |
ccc6cda3 | 3263 | |
bb70624e JA |
3264 | `\f' |
3265 | form feed | |
ccc6cda3 | 3266 | |
bb70624e JA |
3267 | `\n' |
3268 | new line | |
ccc6cda3 | 3269 | |
bb70624e JA |
3270 | `\r' |
3271 | carriage return | |
ccc6cda3 | 3272 | |
bb70624e JA |
3273 | `\t' |
3274 | horizontal tab | |
ccc6cda3 | 3275 | |
bb70624e JA |
3276 | `\v' |
3277 | vertical tab | |
ccc6cda3 | 3278 | |
bb70624e JA |
3279 | `\\' |
3280 | backslash | |
ccc6cda3 | 3281 | |
7117c2d2 JA |
3282 | `\0NNN' |
3283 | the eight-bit character whose value is the octal value NNN | |
3284 | (zero to three octal digits) | |
3285 | ||
f73dda09 JA |
3286 | `\xHH' |
3287 | the eight-bit character whose value is the hexadecimal value | |
3288 | HH (one or two hex digits) | |
3289 | ||
220537f2 CR |
3290 | `\uHHHH' |
3291 | the Unicode (ISO/IEC 10646) character whose value is the | |
3292 | hexadecimal value HHHH (one to four hex digits) | |
3293 | ||
3294 | `\UHHHHHHHH' | |
3295 | the Unicode (ISO/IEC 10646) character whose value is the | |
3296 | hexadecimal value HHHHHHHH (one to eight hex digits) | |
3297 | ||
bb70624e | 3298 | `enable' |
d3ad40de | 3299 | enable [-a] [-dnps] [-f FILENAME] [NAME ...] |
122f603c | 3300 | |
bb70624e JA |
3301 | Enable and disable builtin shell commands. Disabling a builtin |
3302 | allows a disk command which has the same name as a shell builtin | |
3303 | to be executed without specifying a full pathname, even though the | |
3304 | shell normally searches for builtins before disk commands. If | |
3305 | `-n' is used, the NAMEs become disabled. Otherwise NAMEs are | |
3306 | enabled. For example, to use the `test' binary found via `$PATH' | |
3307 | instead of the shell builtin version, type `enable -n test'. | |
ccc6cda3 | 3308 | |
bb70624e JA |
3309 | If the `-p' option is supplied, or no NAME arguments appear, a |
3310 | list of shell builtins is printed. With no other arguments, the | |
3311 | list consists of all enabled shell builtins. The `-a' option | |
3312 | means to list each builtin with an indication of whether or not it | |
3313 | is enabled. | |
ccc6cda3 | 3314 | |
bb70624e JA |
3315 | The `-f' option means to load the new builtin command NAME from |
3316 | shared object FILENAME, on systems that support dynamic loading. | |
3317 | The `-d' option will delete a builtin loaded with `-f'. | |
ccc6cda3 | 3318 | |
bb70624e JA |
3319 | If there are no options, a list of the shell builtins is displayed. |
3320 | The `-s' option restricts `enable' to the POSIX special builtins. | |
3321 | If `-s' is used with `-f', the new builtin becomes a special | |
28ef6c31 | 3322 | builtin (*note Special Builtins::). |
ccc6cda3 | 3323 | |
bb70624e JA |
3324 | The return status is zero unless a NAME is not a shell builtin or |
3325 | there is an error loading a new builtin from a shared object. | |
ccc6cda3 | 3326 | |
bb70624e | 3327 | `help' |
ed35cb4a | 3328 | help [-dms] [PATTERN] |
122f603c | 3329 | |
bb70624e JA |
3330 | Display helpful information about builtin commands. If PATTERN is |
3331 | specified, `help' gives detailed help on all commands matching | |
ed35cb4a CR |
3332 | PATTERN, otherwise a list of the builtins is printed. |
3333 | ||
3334 | Options, if supplied, have the following meanings: | |
3335 | ||
3336 | `-d' | |
3337 | Display a short description of each PATTERN | |
3338 | ||
3339 | `-m' | |
3340 | Display the description of each PATTERN in a manpage-like | |
3341 | format | |
3342 | ||
3343 | `-s' | |
3344 | Display only a short usage synopsis for each PATTERN | |
3345 | ||
3346 | The return status is zero unless no command matches PATTERN. | |
ccc6cda3 | 3347 | |
bb70624e | 3348 | `let' |
122f603c CR |
3349 | let EXPRESSION [EXPRESSION ...] |
3350 | ||
bb70624e JA |
3351 | The `let' builtin allows arithmetic to be performed on shell |
3352 | variables. Each EXPRESSION is evaluated according to the rules | |
6a8fd0ed | 3353 | given below in *note Shell Arithmetic::. If the last EXPRESSION |
bb70624e | 3354 | evaluates to 0, `let' returns 1; otherwise 0 is returned. |
ccc6cda3 | 3355 | |
bb70624e | 3356 | `local' |
d3a24ed2 | 3357 | local [OPTION] NAME[=VALUE] ... |
122f603c | 3358 | |
bb70624e JA |
3359 | For each argument, a local variable named NAME is created, and |
3360 | assigned VALUE. The OPTION can be any of the options accepted by | |
3361 | `declare'. `local' can only be used within a function; it makes | |
3362 | the variable NAME have a visible scope restricted to that function | |
3363 | and its children. The return status is zero unless `local' is | |
3364 | used outside a function, an invalid NAME is supplied, or NAME is a | |
3365 | readonly variable. | |
ccc6cda3 | 3366 | |
bb70624e JA |
3367 | `logout' |
3368 | logout [N] | |
122f603c | 3369 | |
bb70624e | 3370 | Exit a login shell, returning a status of N to the shell's parent. |
ccc6cda3 | 3371 | |
ed35cb4a | 3372 | `mapfile' |
122f603c CR |
3373 | mapfile [-n COUNT] [-O ORIGIN] [-s COUNT] [-t] [-u FD] |
3374 | [-C CALLBACK] [-c QUANTUM] [ARRAY] | |
3375 | ||
d6593885 CR |
3376 | Read lines from the standard input into the indexed array variable |
3377 | ARRAY, or from file descriptor FD if the `-u' option is supplied. | |
3378 | The variable `MAPFILE' is the default ARRAY. Options, if | |
3379 | supplied, have the following meanings: | |
122f603c | 3380 | |
ed35cb4a CR |
3381 | `-n' |
3382 | Copy at most COUNT lines. If COUNT is 0, all lines are | |
3383 | copied. | |
3384 | ||
3385 | `-O' | |
3386 | Begin assigning to ARRAY at index ORIGIN. The default index | |
3387 | is 0. | |
3388 | ||
3389 | `-s' | |
3390 | Discard the first COUNT lines read. | |
3391 | ||
3392 | `-t' | |
984a1947 | 3393 | Remove a trailing newline from each line read. |
ed35cb4a CR |
3394 | |
3395 | `-u' | |
3396 | Read lines from file descriptor FD instead of the standard | |
3397 | input. | |
3398 | ||
3399 | `-C' | |
3400 | Evaluate CALLBACK each time QUANTUMP lines are read. The | |
3401 | `-c' option specifies QUANTUM. | |
3402 | ||
3403 | `-c' | |
3404 | Specify the number of lines read between each call to | |
3405 | CALLBACK. | |
3406 | ||
3407 | If `-C' is specified without `-c', the default quantum is 5000. | |
db31fb26 | 3408 | When CALLBACK is evaluated, it is supplied the index of the next |
220537f2 CR |
3409 | array element to be assigned and the line to be assigned to that |
3410 | element as additional arguments. CALLBACK is evaluated after the | |
3411 | line is read but before the array element is assigned. | |
ed35cb4a CR |
3412 | |
3413 | If not supplied with an explicit origin, `mapfile' will clear ARRAY | |
3414 | before assigning to it. | |
3415 | ||
3416 | `mapfile' returns successfully unless an invalid option or option | |
d6593885 CR |
3417 | argument is supplied, ARRAY is invalid or unassignable, or ARRAY |
3418 | is not an indexed array. | |
ed35cb4a | 3419 | |
bb70624e | 3420 | `printf' |
29d25b54 | 3421 | printf [-v VAR] FORMAT [ARGUMENTS] |
122f603c | 3422 | |
bb70624e | 3423 | Write the formatted ARGUMENTS to the standard output under the |
220537f2 CR |
3424 | control of the FORMAT. The `-v' option causes the output to be |
3425 | assigned to the variable VAR rather than being printed to the | |
3426 | standard output. | |
3427 | ||
3428 | The FORMAT is a character string which contains three types of | |
3429 | objects: plain characters, which are simply copied to standard | |
3430 | output, character escape sequences, which are converted and copied | |
3431 | to the standard output, and format specifications, each of which | |
3432 | causes printing of the next successive ARGUMENT. In addition to | |
3433 | the standard `printf(1)' formats, `printf' interprets the | |
3434 | following extensions: | |
3435 | ||
3436 | `%b' | |
122f603c CR |
3437 | Causes `printf' to expand backslash escape sequences in the |
3438 | corresponding ARGUMENT, except that `\c' terminates output, | |
220537f2 CR |
3439 | backslashes in `\'', `\"', and `\?' are not removed, and |
3440 | octal escapes beginning with `\0' may contain up to four | |
122f603c | 3441 | digits. |
220537f2 CR |
3442 | |
3443 | `%q' | |
122f603c | 3444 | Causes `printf' to output the corresponding ARGUMENT in a |
220537f2 CR |
3445 | format that can be reused as shell input. |
3446 | ||
3447 | `%(DATEFMT)T' | |
122f603c | 3448 | Causes `printf' to output the date-time string resulting from |
220537f2 CR |
3449 | using DATEFMT as a format string for `strftime'(3). The |
3450 | corresponding ARGUMENT is an integer representing the number | |
3451 | of seconds since the epoch. Two special argument values may | |
3452 | be used: -1 represents the current time, and -2 represents | |
3453 | the time the shell was invoked. | |
ccc6cda3 | 3454 | |
eb0b2ad8 CR |
3455 | Arguments to non-string format specifiers are treated as C |
3456 | language constants, except that a leading plus or minus sign is | |
3457 | allowed, and if the leading character is a single or double quote, | |
3458 | the value is the ASCII value of the following character. | |
3459 | ||
bb70624e JA |
3460 | The FORMAT is reused as necessary to consume all of the ARGUMENTS. |
3461 | If the FORMAT requires more ARGUMENTS than are supplied, the extra | |
3462 | format specifications behave as if a zero value or null string, as | |
3463 | appropriate, had been supplied. The return value is zero on | |
3464 | success, non-zero on failure. | |
ccc6cda3 | 3465 | |
bb70624e | 3466 | `read' |
122f603c CR |
3467 | read [-ers] [-a ANAME] [-d DELIM] [-i TEXT] [-n NCHARS] |
3468 | [-N NCHARS] [-p PROMPT] [-t TIMEOUT] [-u FD] [NAME ...] | |
3469 | ||
7117c2d2 JA |
3470 | One line is read from the standard input, or from the file |
3471 | descriptor FD supplied as an argument to the `-u' option, and the | |
3472 | first word is assigned to the first NAME, the second word to the | |
3473 | second NAME, and so on, with leftover words and their intervening | |
3474 | separators assigned to the last NAME. If there are fewer words | |
3475 | read from the input stream than names, the remaining names are | |
3476 | assigned empty values. The characters in the value of the `IFS' | |
3477 | variable are used to split the line into words. The backslash | |
3478 | character `\' may be used to remove any special meaning for the | |
3479 | next character read and for line continuation. If no names are | |
3480 | supplied, the line read is assigned to the variable `REPLY'. The | |
3481 | return code is zero, unless end-of-file is encountered, `read' | |
45c0f7f8 CR |
3482 | times out (in which case the return code is greater than 128), a |
3483 | variable assignment error (such as assigning to a readonly | |
3484 | variable) occurs, or an invalid file descriptor is supplied as the | |
3485 | argument to `-u'. | |
8e1a6eaa CR |
3486 | |
3487 | Options, if supplied, have the following meanings: | |
ccc6cda3 | 3488 | |
bb70624e JA |
3489 | `-a ANAME' |
3490 | The words are assigned to sequential indices of the array | |
3491 | variable ANAME, starting at 0. All elements are removed from | |
3492 | ANAME before the assignment. Other NAME arguments are | |
3493 | ignored. | |
ccc6cda3 | 3494 | |
bb70624e JA |
3495 | `-d DELIM' |
3496 | The first character of DELIM is used to terminate the input | |
3497 | line, rather than newline. | |
ccc6cda3 | 3498 | |
bb70624e | 3499 | `-e' |
28ef6c31 | 3500 | Readline (*note Command Line Editing::) is used to obtain the |
a9fac3b2 CR |
3501 | line. Readline uses the current (or default, if line editing |
3502 | was not previously active) editing settings. | |
ccc6cda3 | 3503 | |
6a8fd0ed CR |
3504 | `-i TEXT' |
3505 | If Readline is being used to read the line, TEXT is placed | |
3506 | into the editing buffer before editing begins. | |
3507 | ||
bb70624e JA |
3508 | `-n NCHARS' |
3509 | `read' returns after reading NCHARS characters rather than | |
d5362af8 CR |
3510 | waiting for a complete line of input, but honor a delimiter |
3511 | if fewer than NCHARS characters are read before the delimiter. | |
3512 | ||
3513 | `-N NCHARS' | |
3514 | `read' returns after reading exactly NCHARS characters rather | |
3515 | than waiting for a complete line of input, unless EOF is | |
a3143574 CR |
3516 | encountered or `read' times out. Delimiter characters |
3517 | encountered in the input are not treated specially and do not | |
3518 | cause `read' to return until NCHARS characters are read. | |
cce855bc | 3519 | |
bb70624e JA |
3520 | `-p PROMPT' |
3521 | Display PROMPT, without a trailing newline, before attempting | |
3522 | to read any input. The prompt is displayed only if input is | |
3523 | coming from a terminal. | |
ccc6cda3 | 3524 | |
bb70624e JA |
3525 | `-r' |
3526 | If this option is given, backslash does not act as an escape | |
3527 | character. The backslash is considered to be part of the | |
3528 | line. In particular, a backslash-newline pair may not be | |
3529 | used as a line continuation. | |
ccc6cda3 | 3530 | |
bb70624e JA |
3531 | `-s' |
3532 | Silent mode. If input is coming from a terminal, characters | |
3533 | are not echoed. | |
cce855bc | 3534 | |
bb70624e JA |
3535 | `-t TIMEOUT' |
3536 | Cause `read' to time out and return failure if a complete | |
ed35cb4a CR |
3537 | line of input is not read within TIMEOUT seconds. TIMEOUT |
3538 | may be a decimal number with a fractional portion following | |
09767ff0 CR |
3539 | the decimal point. This option is only effective if `read' |
3540 | is reading input from a terminal, pipe, or other special | |
a9fac3b2 | 3541 | file; it has no effect when reading from regular files. If |
122f603c CR |
3542 | TIMEOUT is 0, `read' returns immediately, without trying to |
3543 | read and data. The exit status is 0 if input is available on | |
3544 | the specified file descriptor, non-zero otherwise. The exit | |
a9fac3b2 | 3545 | status is greater than 128 if the timeout is exceeded. |
cce855bc | 3546 | |
7117c2d2 JA |
3547 | `-u FD' |
3548 | Read input from file descriptor FD. | |
3549 | ||
db31fb26 | 3550 | `readarray' |
122f603c CR |
3551 | readarray [-n COUNT] [-O ORIGIN] [-s COUNT] [-t] [-u FD] |
3552 | [-C CALLBACK] [-c QUANTUM] [ARRAY] | |
3553 | ||
d6593885 CR |
3554 | Read lines from the standard input into the indexed array variable |
3555 | ARRAY, or from file descriptor FD if the `-u' option is supplied. | |
db31fb26 CR |
3556 | |
3557 | A synonym for `mapfile'. | |
3558 | ||
bb70624e JA |
3559 | `source' |
3560 | source FILENAME | |
122f603c | 3561 | |
28ef6c31 | 3562 | A synonym for `.' (*note Bourne Shell Builtins::). |
ccc6cda3 | 3563 | |
bb70624e | 3564 | `type' |
7117c2d2 | 3565 | type [-afptP] [NAME ...] |
122f603c | 3566 | |
bb70624e JA |
3567 | For each NAME, indicate how it would be interpreted if used as a |
3568 | command name. | |
cce855bc | 3569 | |
bb70624e JA |
3570 | If the `-t' option is used, `type' prints a single word which is |
3571 | one of `alias', `function', `builtin', `file' or `keyword', if | |
3572 | NAME is an alias, shell function, shell builtin, disk file, or | |
3573 | shell reserved word, respectively. If the NAME is not found, then | |
3574 | nothing is printed, and `type' returns a failure status. | |
ccc6cda3 | 3575 | |
bb70624e JA |
3576 | If the `-p' option is used, `type' either returns the name of the |
3577 | disk file that would be executed, or nothing if `-t' would not | |
3578 | return `file'. | |
ccc6cda3 | 3579 | |
7117c2d2 JA |
3580 | The `-P' option forces a path search for each NAME, even if `-t' |
3581 | would not return `file'. | |
3582 | ||
122f603c CR |
3583 | If a command is hashed, `-p' and `-P' print the hashed value, |
3584 | which is not necessarily the file that appears first in `$PATH'. | |
7117c2d2 | 3585 | |
bb70624e JA |
3586 | If the `-a' option is used, `type' returns all of the places that |
3587 | contain an executable named FILE. This includes aliases and | |
3588 | functions, if and only if the `-p' option is not also used. | |
ccc6cda3 | 3589 | |
7117c2d2 JA |
3590 | If the `-f' option is used, `type' does not attempt to find shell |
3591 | functions, as with the `command' builtin. | |
3592 | ||
ed35cb4a CR |
3593 | The return status is zero if all of the NAMES are found, non-zero |
3594 | if any are not found. | |
ccc6cda3 | 3595 | |
bb70624e | 3596 | `typeset' |
122f603c CR |
3597 | typeset [-afFgrxilrtux] [-p] [NAME[=VALUE] ...] |
3598 | ||
bb70624e | 3599 | The `typeset' command is supplied for compatibility with the Korn |
122f603c | 3600 | shell. It is a synonym for the `declare' builtin command. |
ccc6cda3 | 3601 | |
bb70624e | 3602 | `ulimit' |
6a8fd0ed | 3603 | ulimit [-abcdefilmnpqrstuvxHST] [LIMIT] |
122f603c | 3604 | |
bb70624e JA |
3605 | `ulimit' provides control over the resources available to processes |
3606 | started by the shell, on systems that allow such control. If an | |
3607 | option is given, it is interpreted as follows: | |
122f603c | 3608 | |
bb70624e JA |
3609 | `-S' |
3610 | Change and report the soft limit associated with a resource. | |
ccc6cda3 | 3611 | |
bb70624e JA |
3612 | `-H' |
3613 | Change and report the hard limit associated with a resource. | |
ccc6cda3 | 3614 | |
bb70624e JA |
3615 | `-a' |
3616 | All current limits are reported. | |
ccc6cda3 | 3617 | |
6a8fd0ed CR |
3618 | `-b' |
3619 | The maximum socket buffer size. | |
3620 | ||
bb70624e JA |
3621 | `-c' |
3622 | The maximum size of core files created. | |
ccc6cda3 | 3623 | |
bb70624e JA |
3624 | `-d' |
3625 | The maximum size of a process's data segment. | |
ccc6cda3 | 3626 | |
ac18b312 CR |
3627 | `-e' |
3628 | The maximum scheduling priority ("nice"). | |
3629 | ||
bb70624e | 3630 | `-f' |
d3ad40de CR |
3631 | The maximum size of files written by the shell and its |
3632 | children. | |
ccc6cda3 | 3633 | |
ac18b312 CR |
3634 | `-i' |
3635 | The maximum number of pending signals. | |
3636 | ||
bb70624e JA |
3637 | `-l' |
3638 | The maximum size that may be locked into memory. | |
ccc6cda3 | 3639 | |
bb70624e | 3640 | `-m' |
6932f7f5 CR |
3641 | The maximum resident set size (many systems do not honor this |
3642 | limit). | |
ccc6cda3 | 3643 | |
bb70624e | 3644 | `-n' |
6932f7f5 CR |
3645 | The maximum number of open file descriptors (most systems do |
3646 | not allow this value to be set). | |
ccc6cda3 | 3647 | |
bb70624e JA |
3648 | `-p' |
3649 | The pipe buffer size. | |
ccc6cda3 | 3650 | |
ac18b312 CR |
3651 | `-q' |
3652 | The maximum number of bytes in POSIX message queues. | |
3653 | ||
3654 | `-r' | |
3655 | The maximum real-time scheduling priority. | |
3656 | ||
bb70624e JA |
3657 | `-s' |
3658 | The maximum stack size. | |
ccc6cda3 | 3659 | |
bb70624e JA |
3660 | `-t' |
3661 | The maximum amount of cpu time in seconds. | |
ccc6cda3 | 3662 | |
bb70624e JA |
3663 | `-u' |
3664 | The maximum number of processes available to a single user. | |
cce855bc | 3665 | |
bb70624e | 3666 | `-v' |
eb0b2ad8 CR |
3667 | The maximum amount of virtual memory available to the shell, |
3668 | and, on some systems, to its children. | |
ccc6cda3 | 3669 | |
ac18b312 CR |
3670 | `-x' |
3671 | The maximum number of file locks. | |
3672 | ||
6a8fd0ed CR |
3673 | `-T' |
3674 | The maximum number of threads. | |
3675 | ||
122f603c CR |
3676 | If LIMIT is given, and the `-a' option is not used, LIMIT is the |
3677 | new value of the specified resource. The special LIMIT values | |
3678 | `hard', `soft', and `unlimited' stand for the current hard limit, | |
3679 | the current soft limit, and no limit, respectively. A hard limit | |
3680 | cannot be increased by a non-root user once it is set; a soft | |
3681 | limit may be increased up to the value of the hard limit. | |
3682 | Otherwise, the current value of the soft limit for the specified | |
3683 | resource is printed, unless the `-H' option is supplied. When | |
3684 | setting new limits, if neither `-H' nor `-S' is supplied, both the | |
3685 | hard and soft limits are set. If no option is given, then `-f' is | |
3686 | assumed. Values are in 1024-byte increments, except for `-t', | |
3687 | which is in seconds; `-p', which is in units of 512-byte blocks; | |
3688 | and `-T', `-b', `-n' and `-u', which are unscaled values. | |
ccc6cda3 | 3689 | |
f73dda09 JA |
3690 | The return status is zero unless an invalid option or argument is |
3691 | supplied, or an error occurs while setting a new limit. | |
ccc6cda3 | 3692 | |
bb70624e JA |
3693 | `unalias' |
3694 | unalias [-a] [NAME ... ] | |
ccc6cda3 | 3695 | |
bb70624e | 3696 | Remove each NAME from the list of aliases. If `-a' is supplied, |
6a8fd0ed | 3697 | all aliases are removed. Aliases are described in *note Aliases::. |
ccc6cda3 | 3698 | |
bb70624e | 3699 | \1f |
d3ad40de | 3700 | File: bashref.info, Node: Modifying Shell Behavior, Next: Special Builtins, Prev: Bash Builtins, Up: Shell Builtin Commands |
ccc6cda3 | 3701 | |
d3ad40de CR |
3702 | 4.3 Modifying Shell Behavior |
3703 | ============================ | |
3704 | ||
3705 | * Menu: | |
3706 | ||
3707 | * The Set Builtin:: Change the values of shell attributes and | |
3708 | positional parameters. | |
3709 | * The Shopt Builtin:: Modify shell optional behavior. | |
3710 | ||
3711 | \1f | |
3712 | File: bashref.info, Node: The Set Builtin, Next: The Shopt Builtin, Up: Modifying Shell Behavior | |
3713 | ||
3714 | 4.3.1 The Set Builtin | |
3715 | --------------------- | |
9d6e5e30 | 3716 | |
d3ad40de CR |
3717 | This builtin is so complicated that it deserves its own section. `set' |
3718 | allows you to change the values of shell options and set the positional | |
3719 | parameters, or to display the names and values of shell variables. | |
ccc6cda3 | 3720 | |
bb70624e | 3721 | `set' |
e05be32d CR |
3722 | set [--abefhkmnptuvxBCEHPT] [-o OPTION-NAME] [ARGUMENT ...] |
3723 | set [+abefhkmnptuvxBCEHPT] [+o OPTION-NAME] [ARGUMENT ...] | |
ccc6cda3 | 3724 | |
bb70624e JA |
3725 | If no options or arguments are supplied, `set' displays the names |
3726 | and values of all shell variables and functions, sorted according | |
54cdd75a CR |
3727 | to the current locale, in a format that may be reused as input for |
3728 | setting or resetting the currently-set variables. Read-only | |
3729 | variables cannot be reset. In POSIX mode, only shell variables | |
3730 | are listed. | |
ccc6cda3 | 3731 | |
bb70624e JA |
3732 | When options are supplied, they set or unset shell attributes. |
3733 | Options, if specified, have the following meanings: | |
ccc6cda3 | 3734 | |
bb70624e | 3735 | `-a' |
28ef6c31 JA |
3736 | Mark variables and function which are modified or created for |
3737 | export to the environment of subsequent commands. | |
ccc6cda3 | 3738 | |
bb70624e JA |
3739 | `-b' |
3740 | Cause the status of terminated background jobs to be reported | |
3741 | immediately, rather than before printing the next primary | |
3742 | prompt. | |
ccc6cda3 | 3743 | |
bb70624e | 3744 | `-e' |
6932f7f5 CR |
3745 | Exit immediately if a pipeline (*note Pipelines::), which may |
3746 | consist of a single simple command (*note Simple Commands::), | |
122f603c CR |
3747 | a list (*note Lists::), or a compound command (*note Compound |
3748 | Commands::) returns a non-zero status. The shell does not | |
3749 | exit if the command that fails is part of the command list | |
3750 | immediately following a `while' or `until' keyword, part of | |
3751 | the test in an `if' statement, part of any command executed | |
3752 | in a `&&' or `||' list except the command following the final | |
3753 | `&&' or `||', any command in a pipeline but the last, or if | |
3754 | the command's return status is being inverted with `!'. If a | |
3755 | compound command other than a subshell returns a non-zero | |
3756 | status because a command failed while `-e' was being ignored, | |
3757 | the shell does not exit. A trap on `ERR', if set, is | |
3758 | executed before the shell exits. | |
ccc6cda3 | 3759 | |
6932f7f5 CR |
3760 | This option applies to the shell environment and each |
3761 | subshell environment separately (*note Command Execution | |
3762 | Environment::), and may cause subshells to exit before | |
3763 | executing all the commands in the subshell. | |
3764 | ||
bb70624e | 3765 | `-f' |
4a8bb13f | 3766 | Disable filename expansion (globbing). |
ccc6cda3 | 3767 | |
bb70624e JA |
3768 | `-h' |
3769 | Locate and remember (hash) commands as they are looked up for | |
3770 | execution. This option is enabled by default. | |
ccc6cda3 | 3771 | |
bb70624e JA |
3772 | `-k' |
3773 | All arguments in the form of assignment statements are placed | |
3774 | in the environment for a command, not just those that precede | |
3775 | the command name. | |
ccc6cda3 | 3776 | |
bb70624e | 3777 | `-m' |
74d0116b CR |
3778 | Job control is enabled (*note Job Control::). All processes |
3779 | run in a separate process group. When a background job | |
3780 | completes, the shell prints a line containing its exit status. | |
b72432fd | 3781 | |
bb70624e JA |
3782 | `-n' |
3783 | Read commands but do not execute them; this may be used to | |
3784 | check a script for syntax errors. This option is ignored by | |
3785 | interactive shells. | |
ccc6cda3 | 3786 | |
bb70624e JA |
3787 | `-o OPTION-NAME' |
3788 | Set the option corresponding to OPTION-NAME: | |
ccc6cda3 | 3789 | |
bb70624e JA |
3790 | `allexport' |
3791 | Same as `-a'. | |
ccc6cda3 | 3792 | |
bb70624e JA |
3793 | `braceexpand' |
3794 | Same as `-B'. | |
ccc6cda3 | 3795 | |
bb70624e JA |
3796 | `emacs' |
3797 | Use an `emacs'-style line editing interface (*note | |
a9fac3b2 CR |
3798 | Command Line Editing::). This also affects the editing |
3799 | interface used for `read -e'. | |
ccc6cda3 | 3800 | |
bb70624e JA |
3801 | `errexit' |
3802 | Same as `-e'. | |
d166f048 | 3803 | |
d3a24ed2 CR |
3804 | `errtrace' |
3805 | Same as `-E'. | |
3806 | ||
3807 | `functrace' | |
3808 | Same as `-T'. | |
3809 | ||
bb70624e JA |
3810 | `hashall' |
3811 | Same as `-h'. | |
d166f048 | 3812 | |
bb70624e JA |
3813 | `histexpand' |
3814 | Same as `-H'. | |
ccc6cda3 | 3815 | |
bb70624e | 3816 | `history' |
6a8fd0ed | 3817 | Enable command history, as described in *note Bash |
bb70624e JA |
3818 | History Facilities::. This option is on by default in |
3819 | interactive shells. | |
ccc6cda3 | 3820 | |
bb70624e JA |
3821 | `ignoreeof' |
3822 | An interactive shell will not exit upon reading EOF. | |
ccc6cda3 | 3823 | |
bb70624e JA |
3824 | `keyword' |
3825 | Same as `-k'. | |
ccc6cda3 | 3826 | |
bb70624e JA |
3827 | `monitor' |
3828 | Same as `-m'. | |
ccc6cda3 | 3829 | |
bb70624e JA |
3830 | `noclobber' |
3831 | Same as `-C'. | |
ccc6cda3 | 3832 | |
bb70624e JA |
3833 | `noexec' |
3834 | Same as `-n'. | |
ccc6cda3 | 3835 | |
28157acd CR |
3836 | `noglob' |
3837 | Same as `-f'. | |
9d6e5e30 | 3838 | |
d3ad40de CR |
3839 | `nolog' |
3840 | Currently ignored. | |
3841 | ||
3842 | `notify' | |
3843 | Same as `-b'. | |
3844 | ||
3845 | `nounset' | |
3846 | Same as `-u'. | |
3847 | ||
3848 | `onecmd' | |
3849 | Same as `-t'. | |
3850 | ||
3851 | `physical' | |
3852 | Same as `-P'. | |
3853 | ||
3854 | `pipefail' | |
3855 | If set, the return value of a pipeline is the value of | |
3856 | the last (rightmost) command to exit with a non-zero | |
3857 | status, or zero if all commands in the pipeline exit | |
3858 | successfully. This option is disabled by default. | |
3859 | ||
3860 | `posix' | |
3861 | Change the behavior of Bash where the default operation | |
3862 | differs from the POSIX standard to match the standard | |
3863 | (*note Bash POSIX Mode::). This is intended to make | |
3864 | Bash behave as a strict superset of that standard. | |
3865 | ||
3866 | `privileged' | |
3867 | Same as `-p'. | |
3868 | ||
3869 | `verbose' | |
3870 | Same as `-v'. | |
3871 | ||
3872 | `vi' | |
a9fac3b2 CR |
3873 | Use a `vi'-style line editing interface. This also |
3874 | affects the editing interface used for `read -e'. | |
d3ad40de CR |
3875 | |
3876 | `xtrace' | |
3877 | Same as `-x'. | |
3878 | ||
3879 | `-p' | |
3880 | Turn on privileged mode. In this mode, the `$BASH_ENV' and | |
3881 | `$ENV' files are not processed, shell functions are not | |
8f714a7c CR |
3882 | inherited from the environment, and the `SHELLOPTS', |
3883 | `BASHOPTS', `CDPATH' and `GLOBIGNORE' variables, if they | |
3884 | appear in the environment, are ignored. If the shell is | |
3885 | started with the effective user (group) id not equal to the | |
3886 | real user (group) id, and the `-p' option is not supplied, | |
3887 | these actions are taken and the effective user id is set to | |
3888 | the real user id. If the `-p' option is supplied at startup, | |
3889 | the effective user id is not reset. Turning this option off | |
3890 | causes the effective user and group ids to be set to the real | |
3891 | user and group ids. | |
d3ad40de CR |
3892 | |
3893 | `-t' | |
3894 | Exit after reading and executing one command. | |
3895 | ||
3896 | `-u' | |
2c471a92 CR |
3897 | Treat unset variables and parameters other than the special |
3898 | parameters `@' or `*' as an error when performing parameter | |
d3ad40de CR |
3899 | expansion. An error message will be written to the standard |
3900 | error, and a non-interactive shell will exit. | |
3901 | ||
3902 | `-v' | |
3903 | Print shell input lines as they are read. | |
3904 | ||
3905 | `-x' | |
3906 | Print a trace of simple commands, `for' commands, `case' | |
3907 | commands, `select' commands, and arithmetic `for' commands | |
3908 | and their arguments or associated word lists after they are | |
3909 | expanded and before they are executed. The value of the `PS4' | |
3910 | variable is expanded and the resultant value is printed before | |
3911 | the command and its expanded arguments. | |
3912 | ||
3913 | `-B' | |
3914 | The shell will perform brace expansion (*note Brace | |
3915 | Expansion::). This option is on by default. | |
3916 | ||
3917 | `-C' | |
3918 | Prevent output redirection using `>', `>&', and `<>' from | |
3919 | overwriting existing files. | |
3920 | ||
3921 | `-E' | |
3922 | If set, any trap on `ERR' is inherited by shell functions, | |
3923 | command substitutions, and commands executed in a subshell | |
3924 | environment. The `ERR' trap is normally not inherited in | |
3925 | such cases. | |
3926 | ||
3927 | `-H' | |
3928 | Enable `!' style history substitution (*note History | |
3929 | Interaction::). This option is on by default for interactive | |
3930 | shells. | |
3931 | ||
3932 | `-P' | |
45c0f7f8 CR |
3933 | If set, do not resolve symbolic links when performing |
3934 | commands such as `cd' which change the current directory. | |
3935 | The physical directory is used instead. By default, Bash | |
3936 | follows the logical chain of directories when performing | |
3937 | commands which change the current directory. | |
d3ad40de CR |
3938 | |
3939 | For example, if `/usr/sys' is a symbolic link to | |
3940 | `/usr/local/sys' then: | |
3941 | $ cd /usr/sys; echo $PWD | |
3942 | /usr/sys | |
3943 | $ cd ..; pwd | |
3944 | /usr | |
3945 | ||
3946 | If `set -P' is on, then: | |
3947 | $ cd /usr/sys; echo $PWD | |
3948 | /usr/local/sys | |
3949 | $ cd ..; pwd | |
3950 | /usr/local | |
3951 | ||
3952 | `-T' | |
3953 | If set, any trap on `DEBUG' and `RETURN' are inherited by | |
3954 | shell functions, command substitutions, and commands executed | |
3955 | in a subshell environment. The `DEBUG' and `RETURN' traps | |
3956 | are normally not inherited in such cases. | |
3957 | ||
3958 | `--' | |
3959 | If no arguments follow this option, then the positional | |
3960 | parameters are unset. Otherwise, the positional parameters | |
3961 | are set to the ARGUMENTS, even if some of them begin with a | |
3962 | `-'. | |
3963 | ||
3964 | `-' | |
3965 | Signal the end of options, cause all remaining ARGUMENTS to | |
3966 | be assigned to the positional parameters. The `-x' and `-v' | |
3967 | options are turned off. If there are no arguments, the | |
3968 | positional parameters remain unchanged. | |
3969 | ||
3970 | Using `+' rather than `-' causes these options to be turned off. | |
3971 | The options can also be used upon invocation of the shell. The | |
3972 | current set of options may be found in `$-'. | |
3973 | ||
3974 | The remaining N ARGUMENTS are positional parameters and are | |
3975 | assigned, in order, to `$1', `$2', ... `$N'. The special | |
3976 | parameter `#' is set to N. | |
3977 | ||
3978 | The return status is always zero unless an invalid option is | |
3979 | supplied. | |
3980 | ||
3981 | \1f | |
3982 | File: bashref.info, Node: The Shopt Builtin, Prev: The Set Builtin, Up: Modifying Shell Behavior | |
3983 | ||
3984 | 4.3.2 The Shopt Builtin | |
3985 | ----------------------- | |
3986 | ||
3987 | This builtin allows you to change additional shell optional behavior. | |
3988 | ||
3989 | `shopt' | |
3990 | shopt [-pqsu] [-o] [OPTNAME ...] | |
122f603c | 3991 | |
d3ad40de CR |
3992 | Toggle the values of variables controlling optional shell behavior. |
3993 | With no options, or with the `-p' option, a list of all settable | |
3994 | options is displayed, with an indication of whether or not each is | |
3995 | set. The `-p' option causes output to be displayed in a form that | |
3996 | may be reused as input. Other options have the following meanings: | |
3997 | ||
3998 | `-s' | |
3999 | Enable (set) each OPTNAME. | |
4000 | ||
4001 | `-u' | |
4002 | Disable (unset) each OPTNAME. | |
4003 | ||
4004 | `-q' | |
4005 | Suppresses normal output; the return status indicates whether | |
4006 | the OPTNAME is set or unset. If multiple OPTNAME arguments | |
4007 | are given with `-q', the return status is zero if all | |
4008 | OPTNAMES are enabled; non-zero otherwise. | |
4009 | ||
4010 | `-o' | |
4011 | Restricts the values of OPTNAME to be those defined for the | |
4012 | `-o' option to the `set' builtin (*note The Set Builtin::). | |
4013 | ||
122f603c CR |
4014 | If either `-s' or `-u' is used with no OPTNAME arguments, `shopt' |
4015 | shows only those options which are set or unset, respectively. | |
d3ad40de CR |
4016 | |
4017 | Unless otherwise noted, the `shopt' options are disabled (off) by | |
4018 | default. | |
4019 | ||
4020 | The return status when listing options is zero if all OPTNAMES are | |
4021 | enabled, non-zero otherwise. When setting or unsetting options, | |
4022 | the return status is zero unless an OPTNAME is not a valid shell | |
4023 | option. | |
4024 | ||
4025 | The list of `shopt' options is: | |
4026 | `autocd' | |
4027 | If set, a command name that is the name of a directory is | |
4028 | executed as if it were the argument to the `cd' command. | |
4029 | This option is only used by interactive shells. | |
4030 | ||
4031 | `cdable_vars' | |
4032 | If this is set, an argument to the `cd' builtin command that | |
4033 | is not a directory is assumed to be the name of a variable | |
4034 | whose value is the directory to change to. | |
4035 | ||
4036 | `cdspell' | |
4037 | If set, minor errors in the spelling of a directory component | |
4038 | in a `cd' command will be corrected. The errors checked for | |
4039 | are transposed characters, a missing character, and a | |
4040 | character too many. If a correction is found, the corrected | |
4041 | path is printed, and the command proceeds. This option is | |
4042 | only used by interactive shells. | |
4043 | ||
4044 | `checkhash' | |
4045 | If this is set, Bash checks that a command found in the hash | |
4046 | table exists before trying to execute it. If a hashed | |
4047 | command no longer exists, a normal path search is performed. | |
4048 | ||
4049 | `checkjobs' | |
4050 | If set, Bash lists the status of any stopped and running jobs | |
4051 | before exiting an interactive shell. If any jobs are | |
4052 | running, this causes the exit to be deferred until a second | |
4053 | exit is attempted without an intervening command (*note Job | |
4054 | Control::). The shell always postpones exiting if any jobs | |
4055 | are stopped. | |
4056 | ||
4057 | `checkwinsize' | |
74d0116b | 4058 | If set, Bash checks the window size after each command and, |
d3ad40de CR |
4059 | if necessary, updates the values of `LINES' and `COLUMNS'. |
4060 | ||
4061 | `cmdhist' | |
4062 | If set, Bash attempts to save all lines of a multiple-line | |
4063 | command in the same history entry. This allows easy | |
4064 | re-editing of multi-line commands. | |
4065 | ||
29d25b54 CR |
4066 | `compat31' |
4067 | If set, Bash changes its behavior to that of version 3.1 with | |
e05be32d | 4068 | respect to quoted arguments to the conditional command's `=~' |
abe2eb5b CR |
4069 | operator and with respect to locale-specific string |
4070 | comparison when using the `[[' conditional command's `<' and | |
4071 | `>' operators. Bash versions prior to bash-4.1 use ASCII | |
4072 | collation and strcmp(3); bash-4.1 and later use the current | |
4073 | locale's collation sequence and strcoll(3). | |
29d25b54 | 4074 | |
5cdaaf76 CR |
4075 | `compat32' |
4076 | If set, Bash changes its behavior to that of version 3.2 with | |
4077 | respect to locale-specific string comparison when using the | |
abe2eb5b CR |
4078 | `[[' conditional command's `<' and `>' operators (see |
4079 | previous item). | |
5cdaaf76 CR |
4080 | |
4081 | `compat40' | |
4082 | If set, Bash changes its behavior to that of version 4.0 with | |
4083 | respect to locale-specific string comparison when using the | |
54a1fa7c | 4084 | `[[' conditional command's `<' and `>' operators (see |
abe2eb5b CR |
4085 | description of `compat31') and the effect of interrupting a |
4086 | command list. Bash versions 4.0 and later interrupt the list | |
4087 | as if the shell received the interrupt; previous versions | |
4088 | continue with the next command in the list. | |
5cdaaf76 | 4089 | |
7d92f73f CR |
4090 | `compat41' |
4091 | If set, Bash, when in posix mode, treats a single quote in a | |
4092 | double-quoted parameter expansion as a special character. | |
4093 | The single quotes must match (an even number) and the | |
4094 | characters between the single quotes are considered quoted. | |
4095 | This is the behavior of POSIX mode through version 4.1. The | |
4096 | default Bash behavior remains as in previous versions. | |
4097 | ||
122f603c CR |
4098 | `complete_fullquote' |
4099 | If set, Bash quotes all shell metacharacters in filenames and | |
4100 | directory names when performing completion. If not set, Bash | |
4101 | removes metacharacters such as the dollar sign from the set of | |
4102 | characters that will be quoted in completed filenames when | |
4103 | these metacharacters appear in shell variable references in | |
4104 | words to be completed. This means that dollar signs in | |
4105 | variable names that expand to directories will not be quoted; | |
4106 | however, any dollar signs appearing in filenames will not be | |
4107 | quoted, either. This is active only when bash is using | |
4108 | backslashes to quote completed filenames. This variable is | |
4109 | set by default, which is the default Bash behavior in | |
4110 | versions through 4.2. | |
4111 | ||
74d0116b CR |
4112 | `direxpand' |
4113 | If set, Bash replaces directory names with the results of | |
4114 | word expansion when performing filename completion. This | |
4115 | changes the contents of the readline editing buffer. If not | |
4116 | set, Bash attempts to preserve what the user typed. | |
4117 | ||
ed35cb4a CR |
4118 | `dirspell' |
4119 | If set, Bash attempts spelling correction on directory names | |
4120 | during word completion if the directory name initially | |
4121 | supplied does not exist. | |
4122 | ||
d3ad40de CR |
4123 | `dotglob' |
4124 | If set, Bash includes filenames beginning with a `.' in the | |
4125 | results of filename expansion. | |
4126 | ||
4127 | `execfail' | |
4128 | If this is set, a non-interactive shell will not exit if it | |
4129 | cannot execute the file specified as an argument to the `exec' | |
4130 | builtin command. An interactive shell does not exit if `exec' | |
4131 | fails. | |
4132 | ||
4133 | `expand_aliases' | |
4134 | If set, aliases are expanded as described below under Aliases, | |
6a8fd0ed | 4135 | *note Aliases::. This option is enabled by default for |
d3ad40de CR |
4136 | interactive shells. |
4137 | ||
4138 | `extdebug' | |
4139 | If set, behavior intended for use by debuggers is enabled: | |
4140 | ||
4141 | 1. The `-F' option to the `declare' builtin (*note Bash | |
4142 | Builtins::) displays the source file name and line | |
4143 | number corresponding to each function name supplied as | |
4144 | an argument. | |
4145 | ||
4146 | 2. If the command run by the `DEBUG' trap returns a | |
4147 | non-zero value, the next command is skipped and not | |
4148 | executed. | |
4149 | ||
4150 | 3. If the command run by the `DEBUG' trap returns a value | |
4151 | of 2, and the shell is executing in a subroutine (a | |
4152 | shell function or a shell script executed by the `.' or | |
4153 | `source' builtins), a call to `return' is simulated. | |
4154 | ||
4155 | 4. `BASH_ARGC' and `BASH_ARGV' are updated as described in | |
4156 | their descriptions (*note Bash Variables::). | |
4157 | ||
4158 | 5. Function tracing is enabled: command substitution, | |
4159 | shell functions, and subshells invoked with `( COMMAND | |
4160 | )' inherit the `DEBUG' and `RETURN' traps. | |
9d6e5e30 | 4161 | |
d3ad40de CR |
4162 | 6. Error tracing is enabled: command substitution, shell |
4163 | functions, and subshells invoked with `( COMMAND )' | |
5cdaaf76 | 4164 | inherit the `ERR' trap. |
9d6e5e30 | 4165 | |
d3ad40de CR |
4166 | `extglob' |
4167 | If set, the extended pattern matching features described above | |
4168 | (*note Pattern Matching::) are enabled. | |
9d6e5e30 | 4169 | |
d3ad40de CR |
4170 | `extquote' |
4171 | If set, `$'STRING'' and `$"STRING"' quoting is performed | |
4172 | within `${PARAMETER}' expansions enclosed in double quotes. | |
4173 | This option is enabled by default. | |
9d6e5e30 | 4174 | |
d3ad40de CR |
4175 | `failglob' |
4176 | If set, patterns which fail to match filenames during | |
4a8bb13f | 4177 | filename expansion result in an expansion error. |
9d6e5e30 | 4178 | |
d3ad40de CR |
4179 | `force_fignore' |
4180 | If set, the suffixes specified by the `FIGNORE' shell variable | |
4181 | cause words to be ignored when performing word completion | |
4182 | even if the ignored words are the only possible completions. | |
4183 | *Note Bash Variables::, for a description of `FIGNORE'. This | |
4184 | option is enabled by default. | |
9d6e5e30 | 4185 | |
74d0116b CR |
4186 | `globasciiranges' |
4187 | If set, range expressions used in pattern matching (*note | |
4188 | Pattern Matching::) behave as if in the traditional C locale | |
4189 | when performing comparisons. That is, the current locale's | |
4190 | collating sequence is not taken into account, so `b' will not | |
4191 | collate between `A' and `B', and upper-case and lower-case | |
4192 | ASCII characters will collate together. | |
4193 | ||
ed35cb4a CR |
4194 | `globstar' |
4195 | If set, the pattern `**' used in a filename expansion context | |
d9e1f41e | 4196 | will match all files and zero or more directories and |
ed35cb4a CR |
4197 | subdirectories. If the pattern is followed by a `/', only |
4198 | directories and subdirectories match. | |
4199 | ||
d3ad40de CR |
4200 | `gnu_errfmt' |
4201 | If set, shell error messages are written in the standard GNU | |
4202 | error message format. | |
9d6e5e30 | 4203 | |
d3ad40de CR |
4204 | `histappend' |
4205 | If set, the history list is appended to the file named by the | |
4206 | value of the `HISTFILE' variable when the shell exits, rather | |
4207 | than overwriting the file. | |
9d6e5e30 | 4208 | |
d3ad40de CR |
4209 | `histreedit' |
4210 | If set, and Readline is being used, a user is given the | |
4211 | opportunity to re-edit a failed history substitution. | |
9d6e5e30 | 4212 | |
d3ad40de CR |
4213 | `histverify' |
4214 | If set, and Readline is being used, the results of history | |
4215 | substitution are not immediately passed to the shell parser. | |
4216 | Instead, the resulting line is loaded into the Readline | |
4217 | editing buffer, allowing further modification. | |
9d6e5e30 | 4218 | |
d3ad40de CR |
4219 | `hostcomplete' |
4220 | If set, and Readline is being used, Bash will attempt to | |
4221 | perform hostname completion when a word containing a `@' is | |
4222 | being completed (*note Commands For Completion::). This | |
4223 | option is enabled by default. | |
9d6e5e30 | 4224 | |
d3ad40de CR |
4225 | `huponexit' |
4226 | If set, Bash will send `SIGHUP' to all jobs when an | |
4227 | interactive login shell exits (*note Signals::). | |
9d6e5e30 | 4228 | |
d3ad40de CR |
4229 | `interactive_comments' |
4230 | Allow a word beginning with `#' to cause that word and all | |
4231 | remaining characters on that line to be ignored in an | |
4232 | interactive shell. This option is enabled by default. | |
9d6e5e30 | 4233 | |
9ec5ed66 CR |
4234 | `lastpipe' |
4235 | If set, and job control is not active, the shell runs the | |
4236 | last command of a pipeline not executed in the background in | |
4237 | the current shell environment. | |
4238 | ||
d3ad40de CR |
4239 | `lithist' |
4240 | If enabled, and the `cmdhist' option is enabled, multi-line | |
4241 | commands are saved to the history with embedded newlines | |
4242 | rather than using semicolon separators where possible. | |
9d6e5e30 | 4243 | |
d3ad40de CR |
4244 | `login_shell' |
4245 | The shell sets this option if it is started as a login shell | |
4246 | (*note Invoking Bash::). The value may not be changed. | |
9d6e5e30 | 4247 | |
d3ad40de CR |
4248 | `mailwarn' |
4249 | If set, and a file that Bash is checking for mail has been | |
4250 | accessed since the last time it was checked, the message | |
4251 | `"The mail in MAILFILE has been read"' is displayed. | |
9d6e5e30 | 4252 | |
d3ad40de CR |
4253 | `no_empty_cmd_completion' |
4254 | If set, and Readline is being used, Bash will not attempt to | |
4255 | search the `PATH' for possible completions when completion is | |
4256 | attempted on an empty line. | |
9d6e5e30 | 4257 | |
d3ad40de CR |
4258 | `nocaseglob' |
4259 | If set, Bash matches filenames in a case-insensitive fashion | |
4260 | when performing filename expansion. | |
9d6e5e30 | 4261 | |
d3ad40de CR |
4262 | `nocasematch' |
4263 | If set, Bash matches patterns in a case-insensitive fashion | |
4264 | when performing matching while executing `case' or `[[' | |
4265 | conditional commands. | |
9d6e5e30 | 4266 | |
d3ad40de CR |
4267 | `nullglob' |
4268 | If set, Bash allows filename patterns which match no files to | |
4269 | expand to a null string, rather than themselves. | |
9d6e5e30 | 4270 | |
d3ad40de CR |
4271 | `progcomp' |
4272 | If set, the programmable completion facilities (*note | |
4273 | Programmable Completion::) are enabled. This option is | |
4274 | enabled by default. | |
9d6e5e30 | 4275 | |
d3ad40de CR |
4276 | `promptvars' |
4277 | If set, prompt strings undergo parameter expansion, command | |
4278 | substitution, arithmetic expansion, and quote removal after | |
122f603c CR |
4279 | being expanded as described below (*note Controlling the |
4280 | Prompt::). This option is enabled by default. | |
9d6e5e30 | 4281 | |
d3ad40de CR |
4282 | `restricted_shell' |
4283 | The shell sets this option if it is started in restricted mode | |
4284 | (*note The Restricted Shell::). The value may not be changed. | |
4285 | This is not reset when the startup files are executed, | |
4286 | allowing the startup files to discover whether or not a shell | |
4287 | is restricted. | |
9d6e5e30 | 4288 | |
d3ad40de CR |
4289 | `shift_verbose' |
4290 | If this is set, the `shift' builtin prints an error message | |
4291 | when the shift count exceeds the number of positional | |
4292 | parameters. | |
9d6e5e30 | 4293 | |
d3ad40de CR |
4294 | `sourcepath' |
4295 | If set, the `source' builtin uses the value of `PATH' to find | |
4296 | the directory containing the file supplied as an argument. | |
4297 | This option is enabled by default. | |
9d6e5e30 | 4298 | |
d3ad40de CR |
4299 | `xpg_echo' |
4300 | If set, the `echo' builtin expands backslash-escape sequences | |
4301 | by default. | |
9d6e5e30 CR |
4302 | |
4303 | ||
d3ad40de CR |
4304 | The return status when listing options is zero if all OPTNAMES are |
4305 | enabled, non-zero otherwise. When setting or unsetting options, | |
4306 | the return status is zero unless an OPTNAME is not a valid shell | |
4307 | option. | |
9d6e5e30 | 4308 | |
9d6e5e30 | 4309 | \1f |
d3ad40de | 4310 | File: bashref.info, Node: Special Builtins, Prev: Modifying Shell Behavior, Up: Shell Builtin Commands |
ccc6cda3 | 4311 | |
37c41ab1 CR |
4312 | 4.4 Special Builtins |
4313 | ==================== | |
ccc6cda3 | 4314 | |
ac18b312 CR |
4315 | For historical reasons, the POSIX standard has classified several |
4316 | builtin commands as _special_. When Bash is executing in POSIX mode, | |
4317 | the special builtins differ from other builtin commands in three | |
bb70624e | 4318 | respects: |
ccc6cda3 | 4319 | |
bb70624e JA |
4320 | 1. Special builtins are found before shell functions during command |
4321 | lookup. | |
ccc6cda3 | 4322 | |
bb70624e JA |
4323 | 2. If a special builtin returns an error status, a non-interactive |
4324 | shell exits. | |
ccc6cda3 | 4325 | |
bb70624e JA |
4326 | 3. Assignment statements preceding the command stay in effect in the |
4327 | shell environment after the command completes. | |
ccc6cda3 | 4328 | |
bb70624e JA |
4329 | When Bash is not executing in POSIX mode, these builtins behave no |
4330 | differently than the rest of the Bash builtin commands. The Bash POSIX | |
6a8fd0ed | 4331 | mode is described in *note Bash POSIX Mode::. |
ccc6cda3 | 4332 | |
bb70624e JA |
4333 | These are the POSIX special builtins: |
4334 | break : . continue eval exec exit export readonly return set | |
4335 | shift trap unset | |
ccc6cda3 | 4336 | |
bb70624e JA |
4337 | \1f |
4338 | File: bashref.info, Node: Shell Variables, Next: Bash Features, Prev: Shell Builtin Commands, Up: Top | |
cce855bc | 4339 | |
37c41ab1 CR |
4340 | 5 Shell Variables |
4341 | ***************** | |
ccc6cda3 | 4342 | |
bb70624e | 4343 | * Menu: |
ccc6cda3 | 4344 | |
bb70624e JA |
4345 | * Bourne Shell Variables:: Variables which Bash uses in the same way |
4346 | as the Bourne Shell. | |
4347 | * Bash Variables:: List of variables that exist in Bash. | |
ccc6cda3 | 4348 | |
bb70624e JA |
4349 | This chapter describes the shell variables that Bash uses. Bash |
4350 | automatically assigns default values to a number of variables. | |
cce855bc | 4351 | |
bb70624e JA |
4352 | \1f |
4353 | File: bashref.info, Node: Bourne Shell Variables, Next: Bash Variables, Up: Shell Variables | |
ccc6cda3 | 4354 | |
37c41ab1 CR |
4355 | 5.1 Bourne Shell Variables |
4356 | ========================== | |
cce855bc | 4357 | |
37c41ab1 CR |
4358 | Bash uses certain shell variables in the same way as the Bourne shell. |
4359 | In some cases, Bash assigns a default value to the variable. | |
cce855bc | 4360 | |
bb70624e JA |
4361 | `CDPATH' |
4362 | A colon-separated list of directories used as a search path for | |
4363 | the `cd' builtin command. | |
ccc6cda3 | 4364 | |
bb70624e JA |
4365 | `HOME' |
4366 | The current user's home directory; the default for the `cd' builtin | |
4367 | command. The value of this variable is also used by tilde | |
28ef6c31 | 4368 | expansion (*note Tilde Expansion::). |
ccc6cda3 | 4369 | |
bb70624e JA |
4370 | `IFS' |
4371 | A list of characters that separate fields; used when the shell | |
4372 | splits words as part of expansion. | |
ccc6cda3 | 4373 | |
bb70624e | 4374 | `MAIL' |
e05be32d CR |
4375 | If this parameter is set to a filename or directory name and the |
4376 | `MAILPATH' variable is not set, Bash informs the user of the | |
4377 | arrival of mail in the specified file or Maildir-format directory. | |
cce855bc | 4378 | |
bb70624e JA |
4379 | `MAILPATH' |
4380 | A colon-separated list of filenames which the shell periodically | |
4381 | checks for new mail. Each list entry can specify the message that | |
4382 | is printed when new mail arrives in the mail file by separating | |
122f603c | 4383 | the filename from the message with a `?'. When used in the text |
bb70624e | 4384 | of the message, `$_' expands to the name of the current mail file. |
cce855bc | 4385 | |
bb70624e JA |
4386 | `OPTARG' |
4387 | The value of the last option argument processed by the `getopts' | |
4388 | builtin. | |
ccc6cda3 | 4389 | |
bb70624e JA |
4390 | `OPTIND' |
4391 | The index of the last option argument processed by the `getopts' | |
4392 | builtin. | |
ccc6cda3 | 4393 | |
bb70624e JA |
4394 | `PATH' |
4395 | A colon-separated list of directories in which the shell looks for | |
d3a24ed2 CR |
4396 | commands. A zero-length (null) directory name in the value of |
4397 | `PATH' indicates the current directory. A null directory name may | |
4398 | appear as two adjacent colons, or as an initial or trailing colon. | |
ccc6cda3 | 4399 | |
bb70624e JA |
4400 | `PS1' |
4401 | The primary prompt string. The default value is `\s-\v\$ '. | |
122f603c | 4402 | *Note Controlling the Prompt::, for the complete list of escape |
bb70624e | 4403 | sequences that are expanded before `PS1' is displayed. |
ccc6cda3 | 4404 | |
bb70624e JA |
4405 | `PS2' |
4406 | The secondary prompt string. The default value is `> '. | |
ccc6cda3 | 4407 | |
761783bf | 4408 | |
bb70624e JA |
4409 | \1f |
4410 | File: bashref.info, Node: Bash Variables, Prev: Bourne Shell Variables, Up: Shell Variables | |
ccc6cda3 | 4411 | |
37c41ab1 CR |
4412 | 5.2 Bash Variables |
4413 | ================== | |
ccc6cda3 | 4414 | |
37c41ab1 | 4415 | These variables are set or used by Bash, but other shells do not |
bb70624e | 4416 | normally treat them specially. |
ccc6cda3 | 4417 | |
bb70624e JA |
4418 | A few variables used by Bash are described in different chapters: |
4419 | variables for controlling the job control facilities (*note Job Control | |
28ef6c31 | 4420 | Variables::). |
ccc6cda3 | 4421 | |
bb70624e JA |
4422 | `BASH' |
4423 | The full pathname used to execute the current instance of Bash. | |
ccc6cda3 | 4424 | |
8f714a7c CR |
4425 | `BASHOPTS' |
4426 | A colon-separated list of enabled shell options. Each word in the | |
4427 | list is a valid argument for the `-s' option to the `shopt' | |
4428 | builtin command (*note The Shopt Builtin::). The options | |
4429 | appearing in `BASHOPTS' are those reported as `on' by `shopt'. If | |
4430 | this variable is in the environment when Bash starts up, each | |
4431 | shell option in the list will be enabled before reading any | |
4432 | startup files. This variable is readonly. | |
4433 | ||
d3ad40de | 4434 | `BASHPID' |
e05be32d | 4435 | Expands to the process ID of the current Bash process. This |
d3ad40de CR |
4436 | differs from `$$' under certain circumstances, such as subshells |
4437 | that do not require Bash to be re-initialized. | |
4438 | ||
09767ff0 CR |
4439 | `BASH_ALIASES' |
4440 | An associative array variable whose members correspond to the | |
e05be32d | 4441 | internal list of aliases as maintained by the `alias' builtin. |
09767ff0 CR |
4442 | (*note Bourne Shell Builtins::). Elements added to this array |
4443 | appear in the alias list; unsetting array elements cause aliases | |
4444 | to be removed from the alias list. | |
4445 | ||
d3a24ed2 CR |
4446 | `BASH_ARGC' |
4447 | An array variable whose values are the number of parameters in each | |
4448 | frame of the current bash execution call stack. The number of | |
4449 | parameters to the current subroutine (shell function or script | |
4450 | executed with `.' or `source') is at the top of the stack. When a | |
4451 | subroutine is executed, the number of parameters passed is pushed | |
9d2b70f0 | 4452 | onto `BASH_ARGC'. The shell sets `BASH_ARGC' only when in |
6a8fd0ed | 4453 | extended debugging mode (see *note The Shopt Builtin:: for a |
9d2b70f0 | 4454 | description of the `extdebug' option to the `shopt' builtin). |
d3a24ed2 CR |
4455 | |
4456 | `BASH_ARGV' | |
4457 | An array variable containing all of the parameters in the current | |
4458 | bash execution call stack. The final parameter of the last | |
4459 | subroutine call is at the top of the stack; the first parameter of | |
4460 | the initial call is at the bottom. When a subroutine is executed, | |
9d2b70f0 | 4461 | the parameters supplied are pushed onto `BASH_ARGV'. The shell |
6a8fd0ed | 4462 | sets `BASH_ARGV' only when in extended debugging mode (see *note |
d3ad40de CR |
4463 | The Shopt Builtin:: for a description of the `extdebug' option to |
4464 | the `shopt' builtin). | |
d3a24ed2 | 4465 | |
09767ff0 CR |
4466 | `BASH_CMDS' |
4467 | An associative array variable whose members correspond to the | |
4468 | internal hash table of commands as maintained by the `hash' builtin | |
4469 | (*note Bourne Shell Builtins::). Elements added to this array | |
4470 | appear in the hash table; unsetting array elements cause commands | |
4471 | to be removed from the hash table. | |
4472 | ||
d3a24ed2 CR |
4473 | `BASH_COMMAND' |
4474 | The command currently being executed or about to be executed, | |
4475 | unless the shell is executing a command as the result of a trap, | |
4476 | in which case it is the command executing at the time of the trap. | |
4477 | ||
bb70624e JA |
4478 | `BASH_ENV' |
4479 | If this variable is set when Bash is invoked to execute a shell | |
4480 | script, its value is expanded and used as the name of a startup | |
4481 | file to read before executing the script. *Note Bash Startup | |
4482 | Files::. | |
ccc6cda3 | 4483 | |
d3a24ed2 CR |
4484 | `BASH_EXECUTION_STRING' |
4485 | The command argument to the `-c' invocation option. | |
4486 | ||
4487 | `BASH_LINENO' | |
4488 | An array variable whose members are the line numbers in source | |
9ec5ed66 CR |
4489 | files where each corresponding member of FUNCNAME was invoked. |
4490 | `${BASH_LINENO[$i]}' is the line number in the source file | |
4491 | (`${BASH_SOURCE[$i+1]}') where `${FUNCNAME[$i]}' was called (or | |
4492 | `${BASH_LINENO[$i-1]}' if referenced within another shell | |
4493 | function). Use `LINENO' to obtain the current line number. | |
d3a24ed2 | 4494 | |
5e13499c CR |
4495 | `BASH_REMATCH' |
4496 | An array variable whose members are assigned by the `=~' binary | |
4497 | operator to the `[[' conditional command (*note Conditional | |
4498 | Constructs::). The element with index 0 is the portion of the | |
4499 | string matching the entire regular expression. The element with | |
4500 | index N is the portion of the string matching the Nth | |
4501 | parenthesized subexpression. This variable is read-only. | |
4502 | ||
d3a24ed2 | 4503 | `BASH_SOURCE' |
9ec5ed66 CR |
4504 | An array variable whose members are the source filenames where the |
4505 | corresponding shell function names in the `FUNCNAME' array | |
4506 | variable are defined. The shell function `${FUNCNAME[$i]}' is | |
4507 | defined in the file `${BASH_SOURCE[$i]}' and called from | |
4508 | `${BASH_SOURCE[$i+1]}' | |
d3a24ed2 CR |
4509 | |
4510 | `BASH_SUBSHELL' | |
f6da9f85 CR |
4511 | Incremented by one within each subshell or subshell environment |
4512 | when the shell begins executing in that environment. The initial | |
4513 | value is 0. | |
ccc6cda3 | 4514 | |
bb70624e | 4515 | `BASH_VERSINFO' |
28ef6c31 | 4516 | A readonly array variable (*note Arrays::) whose members hold |
bb70624e JA |
4517 | version information for this instance of Bash. The values |
4518 | assigned to the array members are as follows: | |
ccc6cda3 | 4519 | |
bb70624e JA |
4520 | `BASH_VERSINFO[0]' |
4521 | The major version number (the RELEASE). | |
ccc6cda3 | 4522 | |
bb70624e JA |
4523 | `BASH_VERSINFO[1]' |
4524 | The minor version number (the VERSION). | |
ccc6cda3 | 4525 | |
bb70624e JA |
4526 | `BASH_VERSINFO[2]' |
4527 | The patch level. | |
ccc6cda3 | 4528 | |
bb70624e JA |
4529 | `BASH_VERSINFO[3]' |
4530 | The build version. | |
ccc6cda3 | 4531 | |
bb70624e JA |
4532 | `BASH_VERSINFO[4]' |
4533 | The release status (e.g., BETA1). | |
ccc6cda3 | 4534 | |
bb70624e JA |
4535 | `BASH_VERSINFO[5]' |
4536 | The value of `MACHTYPE'. | |
ccc6cda3 | 4537 | |
d3a24ed2 CR |
4538 | `BASH_VERSION' |
4539 | The version number of the current instance of Bash. | |
4540 | ||
8f714a7c CR |
4541 | `BASH_XTRACEFD' |
4542 | If set to an integer corresponding to a valid file descriptor, Bash | |
4543 | will write the trace output generated when `set -x' is enabled to | |
4544 | that file descriptor. This allows tracing output to be separated | |
4545 | from diagnostic and error messages. The file descriptor is closed | |
4546 | when `BASH_XTRACEFD' is unset or assigned a new value. Unsetting | |
4547 | `BASH_XTRACEFD' or assigning it the empty string causes the trace | |
4548 | output to be sent to the standard error. Note that setting | |
4549 | `BASH_XTRACEFD' to 2 (the standard error file descriptor) and then | |
4550 | unsetting it will result in the standard error being closed. | |
4551 | ||
f73dda09 | 4552 | `COLUMNS' |
54a1fa7c | 4553 | Used by the `select' command to determine the terminal width when |
74d0116b CR |
4554 | printing selection lists. Automatically set by an interactive |
4555 | shell upon receipt of a `SIGWINCH'. | |
bb70624e JA |
4556 | |
4557 | `COMP_CWORD' | |
4558 | An index into `${COMP_WORDS}' of the word containing the current | |
4559 | cursor position. This variable is available only in shell | |
4560 | functions invoked by the programmable completion facilities (*note | |
28ef6c31 | 4561 | Programmable Completion::). |
bb70624e JA |
4562 | |
4563 | `COMP_LINE' | |
4564 | The current command line. This variable is available only in | |
4565 | shell functions and external commands invoked by the programmable | |
28ef6c31 | 4566 | completion facilities (*note Programmable Completion::). |
bb70624e JA |
4567 | |
4568 | `COMP_POINT' | |
4569 | The index of the current cursor position relative to the beginning | |
4570 | of the current command. If the current cursor position is at the | |
4571 | end of the current command, the value of this variable is equal to | |
4572 | `${#COMP_LINE}'. This variable is available only in shell | |
4573 | functions and external commands invoked by the programmable | |
28ef6c31 | 4574 | completion facilities (*note Programmable Completion::). |
bb70624e | 4575 | |
d3ad40de CR |
4576 | `COMP_TYPE' |
4577 | Set to an integer value corresponding to the type of completion | |
4578 | attempted that caused a completion function to be called: TAB, for | |
4579 | normal completion, `?', for listing completions after successive | |
4580 | tabs, `!', for listing alternatives on partial word completion, | |
4581 | `@', to list completions if the word is not unmodified, or `%', | |
4582 | for menu completion. This variable is available only in shell | |
4583 | functions and external commands invoked by the programmable | |
4584 | completion facilities (*note Programmable Completion::). | |
4585 | ||
4586 | `COMP_KEY' | |
4587 | The key (or final key of a key sequence) used to invoke the current | |
4588 | completion function. | |
4589 | ||
d3a24ed2 CR |
4590 | `COMP_WORDBREAKS' |
4591 | The set of characters that the Readline library treats as word | |
4592 | separators when performing word completion. If `COMP_WORDBREAKS' | |
4593 | is unset, it loses its special properties, even if it is | |
4594 | subsequently reset. | |
4595 | ||
f73dda09 JA |
4596 | `COMP_WORDS' |
4597 | An array variable consisting of the individual words in the | |
6932f7f5 CR |
4598 | current command line. The line is split into words as Readline |
4599 | would split it, using `COMP_WORDBREAKS' as described above. This | |
4600 | variable is available only in shell functions invoked by the | |
4601 | programmable completion facilities (*note Programmable | |
4602 | Completion::). | |
f73dda09 | 4603 | |
bb70624e JA |
4604 | `COMPREPLY' |
4605 | An array variable from which Bash reads the possible completions | |
4606 | generated by a shell function invoked by the programmable | |
45c0f7f8 CR |
4607 | completion facility (*note Programmable Completion::). Each array |
4608 | element contains one possible completion. | |
ccc6cda3 | 4609 | |
5cdaaf76 CR |
4610 | `COPROC' |
4611 | An array variable created to hold the file descriptors for output | |
4612 | from and input to an unnamed coprocess (*note Coprocesses::). | |
4613 | ||
bb70624e JA |
4614 | `DIRSTACK' |
4615 | An array variable containing the current contents of the directory | |
4616 | stack. Directories appear in the stack in the order they are | |
4617 | displayed by the `dirs' builtin. Assigning to members of this | |
4618 | array variable may be used to modify directories already in the | |
4619 | stack, but the `pushd' and `popd' builtins must be used to add and | |
4620 | remove directories. Assignment to this variable will not change | |
4621 | the current directory. If `DIRSTACK' is unset, it loses its | |
4622 | special properties, even if it is subsequently reset. | |
cce855bc | 4623 | |
d3a24ed2 CR |
4624 | `EMACS' |
4625 | If Bash finds this variable in the environment when the shell | |
4626 | starts with value `t', it assumes that the shell is running in an | |
e05be32d | 4627 | Emacs shell buffer and disables line editing. |
d3a24ed2 | 4628 | |
5cdaaf76 CR |
4629 | `ENV' |
4630 | Similar to `BASH_ENV'; used when the shell is invoked in POSIX | |
4631 | Mode (*note Bash POSIX Mode::). | |
4632 | ||
bb70624e JA |
4633 | `EUID' |
4634 | The numeric effective user id of the current user. This variable | |
4635 | is readonly. | |
cce855bc | 4636 | |
bb70624e JA |
4637 | `FCEDIT' |
4638 | The editor used as a default by the `-e' option to the `fc' | |
4639 | builtin command. | |
ccc6cda3 | 4640 | |
bb70624e JA |
4641 | `FIGNORE' |
4642 | A colon-separated list of suffixes to ignore when performing | |
122f603c CR |
4643 | filename completion. A filename whose suffix matches one of the |
4644 | entries in `FIGNORE' is excluded from the list of matched | |
4645 | filenames. A sample value is `.o:~' | |
ccc6cda3 | 4646 | |
f73dda09 | 4647 | `FUNCNAME' |
d3a24ed2 CR |
4648 | An array variable containing the names of all shell functions |
4649 | currently in the execution call stack. The element with index 0 | |
4650 | is the name of any currently-executing shell function. The | |
9ec5ed66 CR |
4651 | bottom-most element (the one with the highest index) is `"main"'. |
4652 | This variable exists only when a shell function is executing. | |
4653 | Assignments to `FUNCNAME' have no effect and return an error | |
4654 | status. If `FUNCNAME' is unset, it loses its special properties, | |
4655 | even if it is subsequently reset. | |
4656 | ||
4657 | This variable can be used with `BASH_LINENO' and `BASH_SOURCE'. | |
4658 | Each element of `FUNCNAME' has corresponding elements in | |
4659 | `BASH_LINENO' and `BASH_SOURCE' to describe the call stack. For | |
4660 | instance, `${FUNCNAME[$i]}' was called from the file | |
4661 | `${BASH_SOURCE[$i+1]}' at line number `${BASH_LINENO[$i]}'. The | |
4662 | `caller' builtin displays the current call stack using this | |
4663 | information. | |
f73dda09 | 4664 | |
220537f2 CR |
4665 | `FUNCNEST' |
4666 | If set to a numeric value greater than 0, defines a maximum | |
4667 | function nesting level. Function invocations that exceed this | |
4668 | nesting level will cause the current command to abort. | |
4669 | ||
bb70624e JA |
4670 | `GLOBIGNORE' |
4671 | A colon-separated list of patterns defining the set of filenames to | |
4672 | be ignored by filename expansion. If a filename matched by a | |
4673 | filename expansion pattern also matches one of the patterns in | |
4674 | `GLOBIGNORE', it is removed from the list of matches. | |
ccc6cda3 | 4675 | |
bb70624e JA |
4676 | `GROUPS' |
4677 | An array variable containing the list of groups of which the | |
4678 | current user is a member. Assignments to `GROUPS' have no effect | |
28ef6c31 | 4679 | and return an error status. If `GROUPS' is unset, it loses its |
bb70624e | 4680 | special properties, even if it is subsequently reset. |
ccc6cda3 | 4681 | |
bb70624e JA |
4682 | `histchars' |
4683 | Up to three characters which control history expansion, quick | |
28ef6c31 JA |
4684 | substitution, and tokenization (*note History Interaction::). The |
4685 | first character is the HISTORY EXPANSION character, that is, the | |
4686 | character which signifies the start of a history expansion, | |
bb70624e JA |
4687 | normally `!'. The second character is the character which |
4688 | signifies `quick substitution' when seen as the first character on | |
4689 | a line, normally `^'. The optional third character is the | |
4690 | character which indicates that the remainder of the line is a | |
4691 | comment when found as the first character of a word, usually `#'. | |
4692 | The history comment character causes history substitution to be | |
4693 | skipped for the remaining words on the line. It does not | |
4694 | necessarily cause the shell parser to treat the rest of the line | |
4695 | as a comment. | |
cce855bc | 4696 | |
bb70624e JA |
4697 | `HISTCMD' |
4698 | The history number, or index in the history list, of the current | |
4699 | command. If `HISTCMD' is unset, it loses its special properties, | |
4700 | even if it is subsequently reset. | |
ccc6cda3 | 4701 | |
bb70624e | 4702 | `HISTCONTROL' |
d3a24ed2 CR |
4703 | A colon-separated list of values controlling how commands are |
4704 | saved on the history list. If the list of values includes | |
4705 | `ignorespace', lines which begin with a space character are not | |
4706 | saved in the history list. A value of `ignoredups' causes lines | |
4707 | which match the previous history entry to not be saved. A value | |
4708 | of `ignoreboth' is shorthand for `ignorespace' and `ignoredups'. | |
4709 | A value of `erasedups' causes all previous lines matching the | |
4710 | current line to be removed from the history list before that line | |
4711 | is saved. Any value not in the above list is ignored. If | |
4712 | `HISTCONTROL' is unset, or does not include a valid value, all | |
4713 | lines read by the shell parser are saved on the history list, | |
4714 | subject to the value of `HISTIGNORE'. The second and subsequent | |
4715 | lines of a multi-line compound command are not tested, and are | |
4716 | added to the history regardless of the value of `HISTCONTROL'. | |
ccc6cda3 | 4717 | |
f73dda09 JA |
4718 | `HISTFILE' |
4719 | The name of the file to which the command history is saved. The | |
4720 | default value is `~/.bash_history'. | |
4721 | ||
4722 | `HISTFILESIZE' | |
4723 | The maximum number of lines contained in the history file. When | |
4724 | this variable is assigned a value, the history file is truncated, | |
45c0f7f8 CR |
4725 | if necessary, to contain no more than that number of lines by |
4726 | removing the oldest entries. The history file is also truncated | |
4727 | to this size after writing it when an interactive shell exits. If | |
4728 | the value is 0, the history file is truncated to zero size. | |
4729 | Non-numeric values and numeric values less than zero inhibit | |
4730 | truncation. The shell sets the default value to the value of | |
4731 | `HISTSIZE' after reading any startup files. | |
f73dda09 | 4732 | |
bb70624e JA |
4733 | `HISTIGNORE' |
4734 | A colon-separated list of patterns used to decide which command | |
4735 | lines should be saved on the history list. Each pattern is | |
4736 | anchored at the beginning of the line and must match the complete | |
4737 | line (no implicit `*' is appended). Each pattern is tested | |
4738 | against the line after the checks specified by `HISTCONTROL' are | |
4739 | applied. In addition to the normal shell pattern matching | |
4740 | characters, `&' matches the previous history line. `&' may be | |
4741 | escaped using a backslash; the backslash is removed before | |
4742 | attempting a match. The second and subsequent lines of a | |
4743 | multi-line compound command are not tested, and are added to the | |
4744 | history regardless of the value of `HISTIGNORE'. | |
cce855bc | 4745 | |
bb70624e JA |
4746 | `HISTIGNORE' subsumes the function of `HISTCONTROL'. A pattern of |
4747 | `&' is identical to `ignoredups', and a pattern of `[ ]*' is | |
4748 | identical to `ignorespace'. Combining these two patterns, | |
4749 | separating them with a colon, provides the functionality of | |
4750 | `ignoreboth'. | |
ccc6cda3 | 4751 | |
bb70624e JA |
4752 | `HISTSIZE' |
4753 | The maximum number of commands to remember on the history list. | |
45c0f7f8 CR |
4754 | If the value is 0, commands are not saved in the history list. |
4755 | Numeric values less than zero result in every command being saved | |
4756 | on the history list (there is no limit). The shell sets the | |
4757 | default value to 500 after reading any startup files. | |
b72432fd | 4758 | |
d3a24ed2 CR |
4759 | `HISTTIMEFORMAT' |
4760 | If this variable is set and not null, its value is used as a | |
4761 | format string for STRFTIME to print the time stamp associated with | |
4762 | each history entry displayed by the `history' builtin. If this | |
4763 | variable is set, time stamps are written to the history file so | |
d3ad40de CR |
4764 | they may be preserved across shell sessions. This uses the |
4765 | history comment character to distinguish timestamps from other | |
4766 | history lines. | |
d3a24ed2 | 4767 | |
bb70624e JA |
4768 | `HOSTFILE' |
4769 | Contains the name of a file in the same format as `/etc/hosts' that | |
4770 | should be read when the shell needs to complete a hostname. The | |
4771 | list of possible hostname completions may be changed while the | |
4772 | shell is running; the next time hostname completion is attempted | |
4773 | after the value is changed, Bash adds the contents of the new file | |
3eb2d94a CR |
4774 | to the existing list. If `HOSTFILE' is set, but has no value, or |
4775 | does not name a readable file, Bash attempts to read `/etc/hosts' | |
4776 | to obtain the list of possible hostname completions. When | |
4777 | `HOSTFILE' is unset, the hostname list is cleared. | |
cce855bc | 4778 | |
bb70624e JA |
4779 | `HOSTNAME' |
4780 | The name of the current host. | |
cce855bc | 4781 | |
bb70624e JA |
4782 | `HOSTTYPE' |
4783 | A string describing the machine Bash is running on. | |
ccc6cda3 | 4784 | |
bb70624e JA |
4785 | `IGNOREEOF' |
4786 | Controls the action of the shell on receipt of an `EOF' character | |
4787 | as the sole input. If set, the value denotes the number of | |
4788 | consecutive `EOF' characters that can be read as the first | |
4789 | character on an input line before the shell will exit. If the | |
4790 | variable exists but does not have a numeric value (or has no | |
4791 | value) then the default is 10. If the variable does not exist, | |
4792 | then `EOF' signifies the end of input to the shell. This is only | |
4793 | in effect for interactive shells. | |
ccc6cda3 | 4794 | |
bb70624e JA |
4795 | `INPUTRC' |
4796 | The name of the Readline initialization file, overriding the | |
4797 | default of `~/.inputrc'. | |
ccc6cda3 | 4798 | |
bb70624e JA |
4799 | `LANG' |
4800 | Used to determine the locale category for any category not | |
4801 | specifically selected with a variable starting with `LC_'. | |
ccc6cda3 | 4802 | |
bb70624e JA |
4803 | `LC_ALL' |
4804 | This variable overrides the value of `LANG' and any other `LC_' | |
4805 | variable specifying a locale category. | |
cce855bc | 4806 | |
bb70624e JA |
4807 | `LC_COLLATE' |
4808 | This variable determines the collation order used when sorting the | |
4809 | results of filename expansion, and determines the behavior of | |
4810 | range expressions, equivalence classes, and collating sequences | |
4811 | within filename expansion and pattern matching (*note Filename | |
28ef6c31 | 4812 | Expansion::). |
ccc6cda3 | 4813 | |
bb70624e JA |
4814 | `LC_CTYPE' |
4815 | This variable determines the interpretation of characters and the | |
4816 | behavior of character classes within filename expansion and pattern | |
28ef6c31 | 4817 | matching (*note Filename Expansion::). |
ccc6cda3 | 4818 | |
bb70624e JA |
4819 | `LC_MESSAGES' |
4820 | This variable determines the locale used to translate double-quoted | |
28ef6c31 | 4821 | strings preceded by a `$' (*note Locale Translation::). |
ccc6cda3 | 4822 | |
bb70624e JA |
4823 | `LC_NUMERIC' |
4824 | This variable determines the locale category used for number | |
4825 | formatting. | |
ccc6cda3 | 4826 | |
f73dda09 JA |
4827 | `LINENO' |
4828 | The line number in the script or shell function currently | |
4829 | executing. | |
4830 | ||
28ef6c31 | 4831 | `LINES' |
54a1fa7c | 4832 | Used by the `select' command to determine the column length for |
74d0116b CR |
4833 | printing selection lists. Automatically set by an interactive |
4834 | shell upon receipt of a `SIGWINCH'. | |
28ef6c31 | 4835 | |
bb70624e JA |
4836 | `MACHTYPE' |
4837 | A string that fully describes the system type on which Bash is | |
4838 | executing, in the standard GNU CPU-COMPANY-SYSTEM format. | |
ccc6cda3 | 4839 | |
bb70624e JA |
4840 | `MAILCHECK' |
4841 | How often (in seconds) that the shell should check for mail in the | |
28ef6c31 JA |
4842 | files specified in the `MAILPATH' or `MAIL' variables. The |
4843 | default is 60 seconds. When it is time to check for mail, the | |
4844 | shell does so before displaying the primary prompt. If this | |
4845 | variable is unset, or set to a value that is not a number greater | |
4846 | than or equal to zero, the shell disables mail checking. | |
ccc6cda3 | 4847 | |
5cdaaf76 CR |
4848 | `MAPFILE' |
4849 | An array variable created to hold the text read by the `mapfile' | |
4850 | builtin when no variable name is supplied. | |
4851 | ||
bb70624e JA |
4852 | `OLDPWD' |
4853 | The previous working directory as set by the `cd' builtin. | |
ccc6cda3 | 4854 | |
bb70624e JA |
4855 | `OPTERR' |
4856 | If set to the value 1, Bash displays error messages generated by | |
4857 | the `getopts' builtin command. | |
ccc6cda3 | 4858 | |
bb70624e JA |
4859 | `OSTYPE' |
4860 | A string describing the operating system Bash is running on. | |
ccc6cda3 | 4861 | |
bb70624e | 4862 | `PIPESTATUS' |
28ef6c31 | 4863 | An array variable (*note Arrays::) containing a list of exit |
bb70624e JA |
4864 | status values from the processes in the most-recently-executed |
4865 | foreground pipeline (which may contain only a single command). | |
ccc6cda3 | 4866 | |
f73dda09 | 4867 | `POSIXLY_CORRECT' |
122f603c CR |
4868 | If this variable is in the environment when Bash starts, the shell |
4869 | enters POSIX mode (*note Bash POSIX Mode::) before reading the | |
4870 | startup files, as if the `--posix' invocation option had been | |
4871 | supplied. If it is set while the shell is running, Bash enables | |
f73dda09 JA |
4872 | POSIX mode, as if the command |
4873 | `set -o posix' | |
f73dda09 JA |
4874 | had been executed. |
4875 | ||
bb70624e JA |
4876 | `PPID' |
4877 | The process ID of the shell's parent process. This variable is | |
4878 | readonly. | |
ccc6cda3 | 4879 | |
bb70624e JA |
4880 | `PROMPT_COMMAND' |
4881 | If set, the value is interpreted as a command to execute before | |
4882 | the printing of each primary prompt (`$PS1'). | |
ccc6cda3 | 4883 | |
09767ff0 CR |
4884 | `PROMPT_DIRTRIM' |
4885 | If set to a number greater than zero, the value is used as the | |
4886 | number of trailing directory components to retain when expanding | |
122f603c | 4887 | the `\w' and `\W' prompt string escapes (*note Controlling the |
09767ff0 CR |
4888 | Prompt::). Characters removed are replaced with an ellipsis. |
4889 | ||
bb70624e JA |
4890 | `PS3' |
4891 | The value of this variable is used as the prompt for the `select' | |
4892 | command. If this variable is not set, the `select' command | |
4893 | prompts with `#? ' | |
ccc6cda3 | 4894 | |
bb70624e JA |
4895 | `PS4' |
4896 | The value is the prompt printed before the command line is echoed | |
28ef6c31 | 4897 | when the `-x' option is set (*note The Set Builtin::). The first |
bb70624e JA |
4898 | character of `PS4' is replicated multiple times, as necessary, to |
4899 | indicate multiple levels of indirection. The default is `+ '. | |
ccc6cda3 | 4900 | |
bb70624e JA |
4901 | `PWD' |
4902 | The current working directory as set by the `cd' builtin. | |
ccc6cda3 | 4903 | |
bb70624e JA |
4904 | `RANDOM' |
4905 | Each time this parameter is referenced, a random integer between 0 | |
4906 | and 32767 is generated. Assigning a value to this variable seeds | |
4907 | the random number generator. | |
cce855bc | 4908 | |
5cdaaf76 CR |
4909 | `READLINE_LINE' |
4910 | The contents of the Readline line buffer, for use with `bind -x' | |
4911 | (*note Bash Builtins::). | |
4912 | ||
4913 | `READLINE_POINT' | |
4914 | The position of the insertion point in the Readline line buffer, | |
4915 | for use with `bind -x' (*note Bash Builtins::). | |
4916 | ||
bb70624e JA |
4917 | `REPLY' |
4918 | The default variable for the `read' builtin. | |
ccc6cda3 | 4919 | |
bb70624e JA |
4920 | `SECONDS' |
4921 | This variable expands to the number of seconds since the shell was | |
4922 | started. Assignment to this variable resets the count to the | |
4923 | value assigned, and the expanded value becomes the value assigned | |
4924 | plus the number of seconds since the assignment. | |
ccc6cda3 | 4925 | |
9f422431 CR |
4926 | `SHELL' |
4927 | The full pathname to the shell is kept in this environment | |
4928 | variable. If it is not set when the shell starts, Bash assigns to | |
4929 | it the full pathname of the current user's login shell. | |
4930 | ||
bb70624e JA |
4931 | `SHELLOPTS' |
4932 | A colon-separated list of enabled shell options. Each word in the | |
4933 | list is a valid argument for the `-o' option to the `set' builtin | |
28ef6c31 | 4934 | command (*note The Set Builtin::). The options appearing in |
bb70624e JA |
4935 | `SHELLOPTS' are those reported as `on' by `set -o'. If this |
4936 | variable is in the environment when Bash starts up, each shell | |
4937 | option in the list will be enabled before reading any startup | |
4938 | files. This variable is readonly. | |
ccc6cda3 | 4939 | |
bb70624e JA |
4940 | `SHLVL' |
4941 | Incremented by one each time a new instance of Bash is started. | |
4942 | This is intended to be a count of how deeply your Bash shells are | |
4943 | nested. | |
cce855bc | 4944 | |
bb70624e JA |
4945 | `TIMEFORMAT' |
4946 | The value of this parameter is used as a format string specifying | |
4947 | how the timing information for pipelines prefixed with the `time' | |
4948 | reserved word should be displayed. The `%' character introduces an | |
4949 | escape sequence that is expanded to a time value or other | |
4950 | information. The escape sequences and their meanings are as | |
4951 | follows; the braces denote optional portions. | |
cce855bc | 4952 | |
bb70624e JA |
4953 | `%%' |
4954 | A literal `%'. | |
ccc6cda3 | 4955 | |
bb70624e JA |
4956 | `%[P][l]R' |
4957 | The elapsed time in seconds. | |
ccc6cda3 | 4958 | |
bb70624e JA |
4959 | `%[P][l]U' |
4960 | The number of CPU seconds spent in user mode. | |
ccc6cda3 | 4961 | |
bb70624e JA |
4962 | `%[P][l]S' |
4963 | The number of CPU seconds spent in system mode. | |
ccc6cda3 | 4964 | |
bb70624e JA |
4965 | `%P' |
4966 | The CPU percentage, computed as (%U + %S) / %R. | |
ccc6cda3 | 4967 | |
bb70624e JA |
4968 | The optional P is a digit specifying the precision, the number of |
4969 | fractional digits after a decimal point. A value of 0 causes no | |
4970 | decimal point or fraction to be output. At most three places | |
4971 | after the decimal point may be specified; values of P greater than | |
4972 | 3 are changed to 3. If P is not specified, the value 3 is used. | |
ccc6cda3 | 4973 | |
bb70624e JA |
4974 | The optional `l' specifies a longer format, including minutes, of |
4975 | the form MMmSS.FFs. The value of P determines whether or not the | |
4976 | fraction is included. | |
ccc6cda3 | 4977 | |
bb70624e JA |
4978 | If this variable is not set, Bash acts as if it had the value |
4979 | `$'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS'' | |
4980 | If the value is null, no timing information is displayed. A | |
4981 | trailing newline is added when the format string is displayed. | |
ccc6cda3 | 4982 | |
bb70624e | 4983 | `TMOUT' |
7117c2d2 JA |
4984 | If set to a value greater than zero, `TMOUT' is treated as the |
4985 | default timeout for the `read' builtin (*note Bash Builtins::). | |
4986 | The `select' command (*note Conditional Constructs::) terminates | |
4987 | if input does not arrive after `TMOUT' seconds when input is coming | |
4988 | from a terminal. | |
4989 | ||
d3ad40de | 4990 | In an interactive shell, the value is interpreted as the number of |
7117c2d2 JA |
4991 | seconds to wait for input after issuing the primary prompt when |
4992 | the shell is interactive. Bash terminates after that number of | |
4993 | seconds if input does not arrive. | |
ccc6cda3 | 4994 | |
1c72c0cd CR |
4995 | `TMPDIR' |
4996 | If set, Bash uses its value as the name of a directory in which | |
4997 | Bash creates temporary files for the shell's use. | |
4998 | ||
bb70624e JA |
4999 | `UID' |
5000 | The numeric real user id of the current user. This variable is | |
5001 | readonly. | |
ccc6cda3 | 5002 | |
761783bf | 5003 | |
bb70624e JA |
5004 | \1f |
5005 | File: bashref.info, Node: Bash Features, Next: Job Control, Prev: Shell Variables, Up: Top | |
ccc6cda3 | 5006 | |
37c41ab1 CR |
5007 | 6 Bash Features |
5008 | *************** | |
ccc6cda3 | 5009 | |
122f603c | 5010 | This chapter describes features unique to Bash. |
ccc6cda3 | 5011 | |
bb70624e | 5012 | * Menu: |
ccc6cda3 | 5013 | |
bb70624e JA |
5014 | * Invoking Bash:: Command line options that you can give |
5015 | to Bash. | |
5016 | * Bash Startup Files:: When and how Bash executes scripts. | |
5017 | * Interactive Shells:: What an interactive shell is. | |
5018 | * Bash Conditional Expressions:: Primitives used in composing expressions for | |
5019 | the `test' builtin. | |
5020 | * Shell Arithmetic:: Arithmetic on shell variables. | |
5021 | * Aliases:: Substituting one command for another. | |
5022 | * Arrays:: Array Variables. | |
5023 | * The Directory Stack:: History of visited directories. | |
122f603c | 5024 | * Controlling the Prompt:: Customizing the various prompt strings. |
bb70624e JA |
5025 | * The Restricted Shell:: A more controlled mode of shell execution. |
5026 | * Bash POSIX Mode:: Making Bash behave more closely to what | |
5027 | the POSIX standard specifies. | |
ccc6cda3 | 5028 | |
bb70624e JA |
5029 | \1f |
5030 | File: bashref.info, Node: Invoking Bash, Next: Bash Startup Files, Up: Bash Features | |
ccc6cda3 | 5031 | |
37c41ab1 CR |
5032 | 6.1 Invoking Bash |
5033 | ================= | |
ccc6cda3 | 5034 | |
f73dda09 JA |
5035 | bash [long-opt] [-ir] [-abefhkmnptuvxdBCDHP] [-o OPTION] [-O SHOPT_OPTION] [ARGUMENT ...] |
5036 | bash [long-opt] [-abefhkmnptuvxdBCDHP] [-o OPTION] [-O SHOPT_OPTION] -c STRING [ARGUMENT ...] | |
5037 | bash [long-opt] -s [-abefhkmnptuvxdBCDHP] [-o OPTION] [-O SHOPT_OPTION] [ARGUMENT ...] | |
ccc6cda3 | 5038 | |
eb0b2ad8 CR |
5039 | All of the single-character options used with the `set' builtin |
5040 | (*note The Set Builtin::) can be used as options when the shell is | |
5041 | invoked. In addition, there are several multi-character options that | |
5042 | you can use. These options must appear on the command line before the | |
5043 | single-character options to be recognized. | |
ccc6cda3 | 5044 | |
d3a24ed2 CR |
5045 | `--debugger' |
5046 | Arrange for the debugger profile to be executed before the shell | |
6a8fd0ed | 5047 | starts. Turns on extended debugging mode (see *note The Shopt |
d3ad40de | 5048 | Builtin:: for a description of the `extdebug' option to the `shopt' |
eb0b2ad8 | 5049 | builtin). |
d3a24ed2 | 5050 | |
bb70624e JA |
5051 | `--dump-po-strings' |
5052 | A list of all double-quoted strings preceded by `$' is printed on | |
eb2bb562 | 5053 | the standard output in the GNU `gettext' PO (portable object) file |
bb70624e | 5054 | format. Equivalent to `-D' except for the output format. |
ccc6cda3 | 5055 | |
bb70624e JA |
5056 | `--dump-strings' |
5057 | Equivalent to `-D'. | |
ccc6cda3 | 5058 | |
bb70624e | 5059 | `--help' |
d3ad40de | 5060 | Display a usage message on standard output and exit successfully. |
ccc6cda3 | 5061 | |
28ef6c31 JA |
5062 | `--init-file FILENAME' |
5063 | `--rcfile FILENAME' | |
5064 | Execute commands from FILENAME (instead of `~/.bashrc') in an | |
5065 | interactive shell. | |
5066 | ||
bb70624e | 5067 | `--login' |
7117c2d2 | 5068 | Equivalent to `-l'. |
ccc6cda3 | 5069 | |
bb70624e | 5070 | `--noediting' |
28ef6c31 | 5071 | Do not use the GNU Readline library (*note Command Line Editing::) |
bb70624e | 5072 | to read command lines when the shell is interactive. |
ccc6cda3 | 5073 | |
bb70624e JA |
5074 | `--noprofile' |
5075 | Don't load the system-wide startup file `/etc/profile' or any of | |
5076 | the personal initialization files `~/.bash_profile', | |
5077 | `~/.bash_login', or `~/.profile' when Bash is invoked as a login | |
5078 | shell. | |
ccc6cda3 | 5079 | |
bb70624e JA |
5080 | `--norc' |
5081 | Don't read the `~/.bashrc' initialization file in an interactive | |
5082 | shell. This is on by default if the shell is invoked as `sh'. | |
ccc6cda3 | 5083 | |
bb70624e JA |
5084 | `--posix' |
5085 | Change the behavior of Bash where the default operation differs | |
ac18b312 CR |
5086 | from the POSIX standard to match the standard. This is intended |
5087 | to make Bash behave as a strict superset of that standard. *Note | |
5088 | Bash POSIX Mode::, for a description of the Bash POSIX mode. | |
ccc6cda3 | 5089 | |
bb70624e | 5090 | `--restricted' |
28ef6c31 | 5091 | Make the shell a restricted shell (*note The Restricted Shell::). |
ccc6cda3 | 5092 | |
bb70624e JA |
5093 | `--verbose' |
5094 | Equivalent to `-v'. Print shell input lines as they're read. | |
ccc6cda3 | 5095 | |
bb70624e JA |
5096 | `--version' |
5097 | Show version information for this instance of Bash on the standard | |
5098 | output and exit successfully. | |
ccc6cda3 | 5099 | |
bb70624e JA |
5100 | There are several single-character options that may be supplied at |
5101 | invocation which are not available with the `set' builtin. | |
ccc6cda3 | 5102 | |
45c0f7f8 CR |
5103 | `-c' |
5104 | Read and execute commands from the first non-option ARGUMENT after | |
5105 | processing the options, then exit. Any remaining arguments are | |
5106 | assigned to the positional parameters, starting with `$0'. | |
ccc6cda3 | 5107 | |
bb70624e JA |
5108 | `-i' |
5109 | Force the shell to run interactively. Interactive shells are | |
6a8fd0ed | 5110 | described in *note Interactive Shells::. |
ccc6cda3 | 5111 | |
7117c2d2 JA |
5112 | `-l' |
5113 | Make this shell act as if it had been directly invoked by login. | |
5114 | When the shell is interactive, this is equivalent to starting a | |
5115 | login shell with `exec -l bash'. When the shell is not | |
5116 | interactive, the login shell startup files will be executed. | |
5117 | `exec bash -l' or `exec bash --login' will replace the current | |
5118 | shell with a Bash login shell. *Note Bash Startup Files::, for a | |
5119 | description of the special behavior of a login shell. | |
5120 | ||
bb70624e | 5121 | `-r' |
28ef6c31 | 5122 | Make the shell a restricted shell (*note The Restricted Shell::). |
ccc6cda3 | 5123 | |
bb70624e JA |
5124 | `-s' |
5125 | If this option is present, or if no arguments remain after option | |
5126 | processing, then commands are read from the standard input. This | |
5127 | option allows the positional parameters to be set when invoking an | |
5128 | interactive shell. | |
ccc6cda3 | 5129 | |
bb70624e JA |
5130 | `-D' |
5131 | A list of all double-quoted strings preceded by `$' is printed on | |
eb2bb562 | 5132 | the standard output. These are the strings that are subject to |
bb70624e | 5133 | language translation when the current locale is not `C' or `POSIX' |
28ef6c31 | 5134 | (*note Locale Translation::). This implies the `-n' option; no |
bb70624e | 5135 | commands will be executed. |
ccc6cda3 | 5136 | |
f73dda09 JA |
5137 | `[-+]O [SHOPT_OPTION]' |
5138 | SHOPT_OPTION is one of the shell options accepted by the `shopt' | |
d3ad40de CR |
5139 | builtin (*note The Shopt Builtin::). If SHOPT_OPTION is present, |
5140 | `-O' sets the value of that option; `+O' unsets it. If | |
f73dda09 JA |
5141 | SHOPT_OPTION is not supplied, the names and values of the shell |
5142 | options accepted by `shopt' are printed on the standard output. | |
5143 | If the invocation option is `+O', the output is displayed in a | |
5144 | format that may be reused as input. | |
5145 | ||
bb70624e JA |
5146 | `--' |
5147 | A `--' signals the end of options and disables further option | |
5148 | processing. Any arguments after the `--' are treated as filenames | |
5149 | and arguments. | |
ccc6cda3 | 5150 | |
f73dda09 JA |
5151 | A _login_ shell is one whose first character of argument zero is |
5152 | `-', or one invoked with the `--login' option. | |
5153 | ||
28ef6c31 | 5154 | An _interactive_ shell is one started without non-option arguments, |
bb70624e JA |
5155 | unless `-s' is specified, without specifying the `-c' option, and whose |
5156 | input and output are both connected to terminals (as determined by | |
5157 | `isatty(3)'), or one started with the `-i' option. *Note Interactive | |
28ef6c31 | 5158 | Shells::, for more information. |
ccc6cda3 | 5159 | |
bb70624e JA |
5160 | If arguments remain after option processing, and neither the `-c' |
5161 | nor the `-s' option has been supplied, the first argument is assumed to | |
28ef6c31 JA |
5162 | be the name of a file containing shell commands (*note Shell Scripts::). |
5163 | When Bash is invoked in this fashion, `$0' is set to the name of the | |
5164 | file, and the positional parameters are set to the remaining arguments. | |
5165 | Bash reads and executes commands from this file, then exits. Bash's | |
5166 | exit status is the exit status of the last command executed in the | |
5167 | script. If no commands are executed, the exit status is 0. | |
ccc6cda3 | 5168 | |
bb70624e JA |
5169 | \1f |
5170 | File: bashref.info, Node: Bash Startup Files, Next: Interactive Shells, Prev: Invoking Bash, Up: Bash Features | |
ccc6cda3 | 5171 | |
37c41ab1 CR |
5172 | 6.2 Bash Startup Files |
5173 | ====================== | |
ccc6cda3 | 5174 | |
d3ad40de | 5175 | This section describes how Bash executes its startup files. If any of |
37c41ab1 | 5176 | the files exist but cannot be read, Bash reports an error. Tildes are |
122f603c | 5177 | expanded in filenames as described above under Tilde Expansion (*note |
37c41ab1 | 5178 | Tilde Expansion::). |
ccc6cda3 | 5179 | |
6a8fd0ed | 5180 | Interactive shells are described in *note Interactive Shells::. |
ccc6cda3 | 5181 | |
bb70624e JA |
5182 | Invoked as an interactive login shell, or with `--login' |
5183 | ........................................................ | |
cce855bc | 5184 | |
37c41ab1 | 5185 | When Bash is invoked as an interactive login shell, or as a |
bb70624e JA |
5186 | non-interactive shell with the `--login' option, it first reads and |
5187 | executes commands from the file `/etc/profile', if that file exists. | |
5188 | After reading that file, it looks for `~/.bash_profile', | |
5189 | `~/.bash_login', and `~/.profile', in that order, and reads and | |
5190 | executes commands from the first one that exists and is readable. The | |
5191 | `--noprofile' option may be used when the shell is started to inhibit | |
5192 | this behavior. | |
ccc6cda3 | 5193 | |
bb70624e JA |
5194 | When a login shell exits, Bash reads and executes commands from the |
5195 | file `~/.bash_logout', if it exists. | |
ccc6cda3 | 5196 | |
bb70624e JA |
5197 | Invoked as an interactive non-login shell |
5198 | ......................................... | |
ccc6cda3 | 5199 | |
37c41ab1 | 5200 | When an interactive shell that is not a login shell is started, Bash |
bb70624e JA |
5201 | reads and executes commands from `~/.bashrc', if that file exists. |
5202 | This may be inhibited by using the `--norc' option. The `--rcfile | |
5203 | FILE' option will force Bash to read and execute commands from FILE | |
5204 | instead of `~/.bashrc'. | |
ccc6cda3 | 5205 | |
bb70624e JA |
5206 | So, typically, your `~/.bash_profile' contains the line |
5207 | `if [ -f ~/.bashrc ]; then . ~/.bashrc; fi' | |
37c41ab1 | 5208 | after (or before) any login-specific initializations. |
ccc6cda3 | 5209 | |
bb70624e JA |
5210 | Invoked non-interactively |
5211 | ......................... | |
ccc6cda3 | 5212 | |
37c41ab1 | 5213 | When Bash is started non-interactively, to run a shell script, for |
bb70624e JA |
5214 | example, it looks for the variable `BASH_ENV' in the environment, |
5215 | expands its value if it appears there, and uses the expanded value as | |
5216 | the name of a file to read and execute. Bash behaves as if the | |
5217 | following command were executed: | |
5218 | `if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi' | |
37c41ab1 | 5219 | but the value of the `PATH' variable is not used to search for the |
122f603c | 5220 | filename. |
ccc6cda3 | 5221 | |
28ef6c31 JA |
5222 | As noted above, if a non-interactive shell is invoked with the |
5223 | `--login' option, Bash attempts to read and execute commands from the | |
5224 | login shell startup files. | |
5225 | ||
bb70624e JA |
5226 | Invoked with name `sh' |
5227 | ...................... | |
ccc6cda3 | 5228 | |
37c41ab1 | 5229 | If Bash is invoked with the name `sh', it tries to mimic the startup |
bb70624e JA |
5230 | behavior of historical versions of `sh' as closely as possible, while |
5231 | conforming to the POSIX standard as well. | |
ccc6cda3 | 5232 | |
bb70624e JA |
5233 | When invoked as an interactive login shell, or as a non-interactive |
5234 | shell with the `--login' option, it first attempts to read and execute | |
5235 | commands from `/etc/profile' and `~/.profile', in that order. The | |
5236 | `--noprofile' option may be used to inhibit this behavior. When | |
5237 | invoked as an interactive shell with the name `sh', Bash looks for the | |
5238 | variable `ENV', expands its value if it is defined, and uses the | |
5239 | expanded value as the name of a file to read and execute. Since a | |
5240 | shell invoked as `sh' does not attempt to read and execute commands | |
5241 | from any other startup files, the `--rcfile' option has no effect. A | |
5242 | non-interactive shell invoked with the name `sh' does not attempt to | |
5243 | read any other startup files. | |
ccc6cda3 | 5244 | |
bb70624e JA |
5245 | When invoked as `sh', Bash enters POSIX mode after the startup files |
5246 | are read. | |
b72432fd | 5247 | |
bb70624e JA |
5248 | Invoked in POSIX mode |
5249 | ..................... | |
ccc6cda3 | 5250 | |
37c41ab1 CR |
5251 | When Bash is started in POSIX mode, as with the `--posix' command line |
5252 | option, it follows the POSIX standard for startup files. In this mode, | |
5253 | interactive shells expand the `ENV' variable and commands are read and | |
5254 | executed from the file whose name is the expanded value. No other | |
5255 | startup files are read. | |
ccc6cda3 | 5256 | |
bb70624e JA |
5257 | Invoked by remote shell daemon |
5258 | .............................. | |
ccc6cda3 | 5259 | |
c2a47ea9 | 5260 | Bash attempts to determine when it is being run with its standard input |
e05be32d CR |
5261 | connected to a network connection, as when executed by the remote shell |
5262 | daemon, usually `rshd', or the secure shell daemon `sshd'. If Bash | |
5263 | determines it is being run in this fashion, it reads and executes | |
5264 | commands from `~/.bashrc', if that file exists and is readable. It | |
5265 | will not do this if invoked as `sh'. The `--norc' option may be used | |
5266 | to inhibit this behavior, and the `--rcfile' option may be used to | |
5267 | force another file to be read, but `rshd' does not generally invoke the | |
5268 | shell with those options or allow them to be specified. | |
ccc6cda3 | 5269 | |
bb70624e JA |
5270 | Invoked with unequal effective and real UID/GIDs |
5271 | ................................................ | |
5272 | ||
37c41ab1 CR |
5273 | If Bash is started with the effective user (group) id not equal to the |
5274 | real user (group) id, and the `-p' option is not supplied, no startup | |
5275 | files are read, shell functions are not inherited from the environment, | |
8f714a7c CR |
5276 | the `SHELLOPTS', `BASHOPTS', `CDPATH', and `GLOBIGNORE' variables, if |
5277 | they appear in the environment, are ignored, and the effective user id | |
5278 | is set to the real user id. If the `-p' option is supplied at | |
5279 | invocation, the startup behavior is the same, but the effective user id | |
5280 | is not reset. | |
bb70624e JA |
5281 | |
5282 | \1f | |
5283 | File: bashref.info, Node: Interactive Shells, Next: Bash Conditional Expressions, Prev: Bash Startup Files, Up: Bash Features | |
5284 | ||
37c41ab1 CR |
5285 | 6.3 Interactive Shells |
5286 | ====================== | |
bb70624e JA |
5287 | |
5288 | * Menu: | |
5289 | ||
5290 | * What is an Interactive Shell?:: What determines whether a shell is Interactive. | |
5291 | * Is this Shell Interactive?:: How to tell if a shell is interactive. | |
5292 | * Interactive Shell Behavior:: What changes in a interactive shell? | |
5293 | ||
5294 | \1f | |
5295 | File: bashref.info, Node: What is an Interactive Shell?, Next: Is this Shell Interactive?, Up: Interactive Shells | |
5296 | ||
37c41ab1 CR |
5297 | 6.3.1 What is an Interactive Shell? |
5298 | ----------------------------------- | |
bb70624e | 5299 | |
37c41ab1 | 5300 | An interactive shell is one started without non-option arguments, |
d3ad40de CR |
5301 | unless `-s' is specified, without specifying the `-c' option, and whose |
5302 | input and error output are both connected to terminals (as determined | |
5303 | by `isatty(3)'), or one started with the `-i' option. | |
bb70624e JA |
5304 | |
5305 | An interactive shell generally reads from and writes to a user's | |
5306 | terminal. | |
5307 | ||
5308 | The `-s' invocation option may be used to set the positional | |
5309 | parameters when an interactive shell is started. | |
5310 | ||
5311 | \1f | |
5312 | File: bashref.info, Node: Is this Shell Interactive?, Next: Interactive Shell Behavior, Prev: What is an Interactive Shell?, Up: Interactive Shells | |
5313 | ||
37c41ab1 CR |
5314 | 6.3.2 Is this Shell Interactive? |
5315 | -------------------------------- | |
bb70624e | 5316 | |
37c41ab1 | 5317 | To determine within a startup script whether or not Bash is running |
bb70624e JA |
5318 | interactively, test the value of the `-' special parameter. It |
5319 | contains `i' when the shell is interactive. For example: | |
5320 | ||
5321 | case "$-" in | |
5322 | *i*) echo This shell is interactive ;; | |
5323 | *) echo This shell is not interactive ;; | |
5324 | esac | |
5325 | ||
28ef6c31 JA |
5326 | Alternatively, startup scripts may examine the variable `PS1'; it is |
5327 | unset in non-interactive shells, and set in interactive shells. Thus: | |
bb70624e JA |
5328 | |
5329 | if [ -z "$PS1" ]; then | |
5330 | echo This shell is not interactive | |
5331 | else | |
5332 | echo This shell is interactive | |
5333 | fi | |
5334 | ||
5335 | \1f | |
5336 | File: bashref.info, Node: Interactive Shell Behavior, Prev: Is this Shell Interactive?, Up: Interactive Shells | |
5337 | ||
37c41ab1 CR |
5338 | 6.3.3 Interactive Shell Behavior |
5339 | -------------------------------- | |
bb70624e | 5340 | |
37c41ab1 | 5341 | When the shell is running interactively, it changes its behavior in |
bb70624e JA |
5342 | several ways. |
5343 | ||
6a8fd0ed | 5344 | 1. Startup files are read and executed as described in *note Bash |
bb70624e JA |
5345 | Startup Files::. |
5346 | ||
28ef6c31 | 5347 | 2. Job Control (*note Job Control::) is enabled by default. When job |
bb70624e JA |
5348 | control is in effect, Bash ignores the keyboard-generated job |
5349 | control signals `SIGTTIN', `SIGTTOU', and `SIGTSTP'. | |
5350 | ||
28ef6c31 JA |
5351 | 3. Bash expands and displays `PS1' before reading the first line of a |
5352 | command, and expands and displays `PS2' before reading the second | |
5353 | and subsequent lines of a multi-line command. | |
bb70624e JA |
5354 | |
5355 | 4. Bash executes the value of the `PROMPT_COMMAND' variable as a | |
5356 | command before printing the primary prompt, `$PS1' (*note Bash | |
28ef6c31 | 5357 | Variables::). |
bb70624e | 5358 | |
28ef6c31 | 5359 | 5. Readline (*note Command Line Editing::) is used to read commands |
bb70624e JA |
5360 | from the user's terminal. |
5361 | ||
5362 | 6. Bash inspects the value of the `ignoreeof' option to `set -o' | |
5363 | instead of exiting immediately when it receives an `EOF' on its | |
28ef6c31 | 5364 | standard input when reading a command (*note The Set Builtin::). |
bb70624e | 5365 | |
28ef6c31 JA |
5366 | 7. Command history (*note Bash History Facilities::) and history |
5367 | expansion (*note History Interaction::) are enabled by default. | |
bb70624e JA |
5368 | Bash will save the command history to the file named by `$HISTFILE' |
5369 | when an interactive shell exits. | |
5370 | ||
28ef6c31 | 5371 | 8. Alias expansion (*note Aliases::) is performed by default. |
bb70624e JA |
5372 | |
5373 | 9. In the absence of any traps, Bash ignores `SIGTERM' (*note | |
28ef6c31 | 5374 | Signals::). |
bb70624e JA |
5375 | |
5376 | 10. In the absence of any traps, `SIGINT' is caught and handled | |
28ef6c31 | 5377 | ((*note Signals::). `SIGINT' will interrupt some shell builtins. |
bb70624e JA |
5378 | |
5379 | 11. An interactive login shell sends a `SIGHUP' to all jobs on exit if | |
d3ad40de | 5380 | the `huponexit' shell option has been enabled (*note Signals::). |
bb70624e JA |
5381 | |
5382 | 12. The `-n' invocation option is ignored, and `set -n' has no effect | |
28ef6c31 | 5383 | (*note The Set Builtin::). |
bb70624e JA |
5384 | |
5385 | 13. Bash will check for mail periodically, depending on the values of | |
5386 | the `MAIL', `MAILPATH', and `MAILCHECK' shell variables (*note | |
28ef6c31 | 5387 | Bash Variables::). |
bb70624e JA |
5388 | |
5389 | 14. Expansion errors due to references to unbound shell variables after | |
5390 | `set -u' has been enabled will not cause the shell to exit (*note | |
28ef6c31 | 5391 | The Set Builtin::). |
bb70624e JA |
5392 | |
5393 | 15. The shell will not exit on expansion errors caused by VAR being | |
5394 | unset or null in `${VAR:?WORD}' expansions (*note Shell Parameter | |
28ef6c31 | 5395 | Expansion::). |
bb70624e JA |
5396 | |
5397 | 16. Redirection errors encountered by shell builtins will not cause the | |
5398 | shell to exit. | |
5399 | ||
5400 | 17. When running in POSIX mode, a special builtin returning an error | |
28ef6c31 | 5401 | status will not cause the shell to exit (*note Bash POSIX Mode::). |
bb70624e JA |
5402 | |
5403 | 18. A failed `exec' will not cause the shell to exit (*note Bourne | |
28ef6c31 | 5404 | Shell Builtins::). |
bb70624e JA |
5405 | |
5406 | 19. Parser syntax errors will not cause the shell to exit. | |
5407 | ||
5408 | 20. Simple spelling correction for directory arguments to the `cd' | |
5409 | builtin is enabled by default (see the description of the `cdspell' | |
6a8fd0ed | 5410 | option to the `shopt' builtin in *note The Shopt Builtin::). |
bb70624e JA |
5411 | |
5412 | 21. The shell will check the value of the `TMOUT' variable and exit if | |
5413 | a command is not read within the specified number of seconds after | |
28ef6c31 | 5414 | printing `$PS1' (*note Bash Variables::). |
bb70624e JA |
5415 | |
5416 | ||
5417 | \1f | |
5418 | File: bashref.info, Node: Bash Conditional Expressions, Next: Shell Arithmetic, Prev: Interactive Shells, Up: Bash Features | |
5419 | ||
37c41ab1 CR |
5420 | 6.4 Bash Conditional Expressions |
5421 | ================================ | |
bb70624e | 5422 | |
37c41ab1 CR |
5423 | Conditional expressions are used by the `[[' compound command and the |
5424 | `test' and `[' builtin commands. | |
bb70624e JA |
5425 | |
5426 | Expressions may be unary or binary. Unary expressions are often | |
5427 | used to examine the status of a file. There are string operators and | |
5428 | numeric comparison operators as well. If the FILE argument to one of | |
5429 | the primaries is of the form `/dev/fd/N', then file descriptor N is | |
5430 | checked. If the FILE argument to one of the primaries is one of | |
5431 | `/dev/stdin', `/dev/stdout', or `/dev/stderr', file descriptor 0, 1, or | |
5432 | 2, respectively, is checked. | |
5433 | ||
54a1fa7c CR |
5434 | When used with `[[', the `<' and `>' operators sort |
5435 | lexicographically using the current locale. The `test' command uses | |
5436 | ASCII ordering. | |
d6593885 | 5437 | |
37c41ab1 CR |
5438 | Unless otherwise specified, primaries that operate on files follow |
5439 | symbolic links and operate on the target of the link, rather than the | |
5440 | link itself. | |
5441 | ||
bb70624e JA |
5442 | `-a FILE' |
5443 | True if FILE exists. | |
5444 | ||
5445 | `-b FILE' | |
5446 | True if FILE exists and is a block special file. | |
5447 | ||
5448 | `-c FILE' | |
5449 | True if FILE exists and is a character special file. | |
5450 | ||
5451 | `-d FILE' | |
5452 | True if FILE exists and is a directory. | |
5453 | ||
5454 | `-e FILE' | |
5455 | True if FILE exists. | |
5456 | ||
5457 | `-f FILE' | |
5458 | True if FILE exists and is a regular file. | |
5459 | ||
5460 | `-g FILE' | |
5461 | True if FILE exists and its set-group-id bit is set. | |
5462 | ||
5463 | `-h FILE' | |
5464 | True if FILE exists and is a symbolic link. | |
5465 | ||
5466 | `-k FILE' | |
5467 | True if FILE exists and its "sticky" bit is set. | |
5468 | ||
5469 | `-p FILE' | |
5470 | True if FILE exists and is a named pipe (FIFO). | |
5471 | ||
5472 | `-r FILE' | |
5473 | True if FILE exists and is readable. | |
5474 | ||
5475 | `-s FILE' | |
5476 | True if FILE exists and has a size greater than zero. | |
5477 | ||
5478 | `-t FD' | |
5479 | True if file descriptor FD is open and refers to a terminal. | |
ccc6cda3 JA |
5480 | |
5481 | `-u FILE' | |
5482 | True if FILE exists and its set-user-id bit is set. | |
5483 | ||
5484 | `-w FILE' | |
5485 | True if FILE exists and is writable. | |
5486 | ||
5487 | `-x FILE' | |
5488 | True if FILE exists and is executable. | |
5489 | ||
ccc6cda3 JA |
5490 | `-G FILE' |
5491 | True if FILE exists and is owned by the effective group id. | |
5492 | ||
cce855bc JA |
5493 | `-L FILE' |
5494 | True if FILE exists and is a symbolic link. | |
5495 | ||
5cdaaf76 CR |
5496 | `-N FILE' |
5497 | True if FILE exists and has been modified since it was last read. | |
5498 | ||
5499 | `-O FILE' | |
5500 | True if FILE exists and is owned by the effective user id. | |
5501 | ||
cce855bc JA |
5502 | `-S FILE' |
5503 | True if FILE exists and is a socket. | |
5504 | ||
5cdaaf76 CR |
5505 | `FILE1 -ef FILE2' |
5506 | True if FILE1 and FILE2 refer to the same device and inode numbers. | |
cce855bc | 5507 | |
ccc6cda3 | 5508 | `FILE1 -nt FILE2' |
7117c2d2 JA |
5509 | True if FILE1 is newer (according to modification date) than |
5510 | FILE2, or if FILE1 exists and FILE2 does not. | |
ccc6cda3 JA |
5511 | |
5512 | `FILE1 -ot FILE2' | |
7117c2d2 JA |
5513 | True if FILE1 is older than FILE2, or if FILE2 exists and FILE1 |
5514 | does not. | |
ccc6cda3 | 5515 | |
ccc6cda3 | 5516 | `-o OPTNAME' |
220537f2 | 5517 | True if the shell option OPTNAME is enabled. The list of options |
ccc6cda3 | 5518 | appears in the description of the `-o' option to the `set' builtin |
28ef6c31 | 5519 | (*note The Set Builtin::). |
ccc6cda3 | 5520 | |
220537f2 CR |
5521 | `-v VARNAME' |
5522 | True if the shell variable VARNAME is set (has been assigned a | |
5523 | value). | |
5524 | ||
ccc6cda3 JA |
5525 | `-z STRING' |
5526 | True if the length of STRING is zero. | |
5527 | ||
5528 | `-n STRING' | |
5529 | `STRING' | |
5530 | True if the length of STRING is non-zero. | |
5531 | ||
cce855bc | 5532 | `STRING1 == STRING2' |
a3143574 CR |
5533 | `STRING1 = STRING2' |
5534 | True if the strings are equal. `=' should be used with the `test' | |
5535 | command for POSIX conformance. | |
ccc6cda3 JA |
5536 | |
5537 | `STRING1 != STRING2' | |
5538 | True if the strings are not equal. | |
5539 | ||
5540 | `STRING1 < STRING2' | |
4a8bb13f | 5541 | True if STRING1 sorts before STRING2 lexicographically. |
ccc6cda3 JA |
5542 | |
5543 | `STRING1 > STRING2' | |
4a8bb13f | 5544 | True if STRING1 sorts after STRING2 lexicographically. |
ccc6cda3 JA |
5545 | |
5546 | `ARG1 OP ARG2' | |
5547 | `OP' is one of `-eq', `-ne', `-lt', `-le', `-gt', or `-ge'. These | |
5548 | arithmetic binary operators return true if ARG1 is equal to, not | |
5549 | equal to, less than, less than or equal to, greater than, or | |
5550 | greater than or equal to ARG2, respectively. ARG1 and ARG2 may be | |
5551 | positive or negative integers. | |
5552 | ||
ccc6cda3 | 5553 | \1f |
bb70624e | 5554 | File: bashref.info, Node: Shell Arithmetic, Next: Aliases, Prev: Bash Conditional Expressions, Up: Bash Features |
ccc6cda3 | 5555 | |
37c41ab1 CR |
5556 | 6.5 Shell Arithmetic |
5557 | ==================== | |
ccc6cda3 | 5558 | |
37c41ab1 CR |
5559 | The shell allows arithmetic expressions to be evaluated, as one of the |
5560 | shell expansions or by the `let' and the `-i' option to the `declare' | |
5561 | builtins. | |
ccc6cda3 | 5562 | |
7117c2d2 JA |
5563 | Evaluation is done in fixed-width integers with no check for |
5564 | overflow, though division by 0 is trapped and flagged as an error. The | |
d3a24ed2 CR |
5565 | operators and their precedence, associativity, and values are the same |
5566 | as in the C language. The following list of operators is grouped into | |
5567 | levels of equal-precedence operators. The levels are listed in order | |
5568 | of decreasing precedence. | |
cce855bc | 5569 | |
bb70624e JA |
5570 | `ID++ ID--' |
5571 | variable post-increment and post-decrement | |
d166f048 | 5572 | |
bb70624e JA |
5573 | `++ID --ID' |
5574 | variable pre-increment and pre-decrement | |
ccc6cda3 | 5575 | |
bb70624e JA |
5576 | `- +' |
5577 | unary minus and plus | |
ccc6cda3 | 5578 | |
bb70624e JA |
5579 | `! ~' |
5580 | logical and bitwise negation | |
ccc6cda3 | 5581 | |
bb70624e JA |
5582 | `**' |
5583 | exponentiation | |
ccc6cda3 | 5584 | |
bb70624e JA |
5585 | `* / %' |
5586 | multiplication, division, remainder | |
ccc6cda3 | 5587 | |
bb70624e JA |
5588 | `+ -' |
5589 | addition, subtraction | |
ccc6cda3 | 5590 | |
bb70624e JA |
5591 | `<< >>' |
5592 | left and right bitwise shifts | |
cce855bc | 5593 | |
bb70624e JA |
5594 | `<= >= < >' |
5595 | comparison | |
cce855bc | 5596 | |
bb70624e JA |
5597 | `== !=' |
5598 | equality and inequality | |
cce855bc | 5599 | |
bb70624e JA |
5600 | `&' |
5601 | bitwise AND | |
cce855bc | 5602 | |
bb70624e JA |
5603 | `^' |
5604 | bitwise exclusive OR | |
cce855bc | 5605 | |
bb70624e JA |
5606 | `|' |
5607 | bitwise OR | |
cce855bc | 5608 | |
bb70624e JA |
5609 | `&&' |
5610 | logical AND | |
ccc6cda3 | 5611 | |
bb70624e JA |
5612 | `||' |
5613 | logical OR | |
ccc6cda3 | 5614 | |
bb70624e | 5615 | `expr ? expr : expr' |
d3a24ed2 | 5616 | conditional operator |
cce855bc | 5617 | |
bb70624e JA |
5618 | `= *= /= %= += -= <<= >>= &= ^= |=' |
5619 | assignment | |
ccc6cda3 | 5620 | |
bb70624e JA |
5621 | `expr1 , expr2' |
5622 | comma | |
ccc6cda3 | 5623 | |
bb70624e JA |
5624 | Shell variables are allowed as operands; parameter expansion is |
5625 | performed before the expression is evaluated. Within an expression, | |
5626 | shell variables may also be referenced by name without using the | |
d3a24ed2 CR |
5627 | parameter expansion syntax. A shell variable that is null or unset |
5628 | evaluates to 0 when referenced by name without using the parameter | |
5629 | expansion syntax. The value of a variable is evaluated as an | |
5630 | arithmetic expression when it is referenced, or when a variable which | |
5631 | has been given the INTEGER attribute using `declare -i' is assigned a | |
5632 | value. A null value evaluates to 0. A shell variable need not have | |
e05be32d | 5633 | its INTEGER attribute turned on to be used in an expression. |
ccc6cda3 | 5634 | |
bb70624e JA |
5635 | Constants with a leading 0 are interpreted as octal numbers. A |
5636 | leading `0x' or `0X' denotes hexadecimal. Otherwise, numbers take the | |
eb0b2ad8 | 5637 | form [BASE`#']N, where the optional BASE is a decimal number between 2 |
abe2eb5b CR |
5638 | and 64 representing the arithmetic base, and N is a number in that base. |
5639 | If BASE`#' is omitted, then base 10 is used. When specifying N, he | |
5640 | digits greater than 9 are represented by the lowercase letters, the | |
5641 | uppercase letters, `@', and `_', in that order. If BASE is less than | |
5642 | or equal to 36, lowercase and uppercase letters may be used | |
5643 | interchangeably to represent numbers between 10 and 35. | |
ccc6cda3 | 5644 | |
bb70624e JA |
5645 | Operators are evaluated in order of precedence. Sub-expressions in |
5646 | parentheses are evaluated first and may override the precedence rules | |
5647 | above. | |
ccc6cda3 | 5648 | |
bb70624e JA |
5649 | \1f |
5650 | File: bashref.info, Node: Aliases, Next: Arrays, Prev: Shell Arithmetic, Up: Bash Features | |
ccc6cda3 | 5651 | |
37c41ab1 CR |
5652 | 6.6 Aliases |
5653 | =========== | |
ccc6cda3 | 5654 | |
37c41ab1 CR |
5655 | ALIASES allow a string to be substituted for a word when it is used as |
5656 | the first word of a simple command. The shell maintains a list of | |
bb70624e | 5657 | aliases that may be set and unset with the `alias' and `unalias' |
cce855bc JA |
5658 | builtin commands. |
5659 | ||
5660 | The first word of each simple command, if unquoted, is checked to see | |
5661 | if it has an alias. If so, that word is replaced by the text of the | |
de8913bd CR |
5662 | alias. The characters `/', `$', ``', `=' and any of the shell |
5663 | metacharacters or quoting characters listed above may not appear in an | |
5664 | alias name. The replacement text may contain any valid shell input, | |
5665 | including shell metacharacters. The first word of the replacement text | |
5666 | is tested for aliases, but a word that is identical to an alias being | |
5667 | expanded is not expanded a second time. This means that one may alias | |
5668 | `ls' to `"ls -F"', for instance, and Bash does not try to recursively | |
122f603c CR |
5669 | expand the replacement text. If the last character of the alias value |
5670 | is a BLANK, then the next command word following the alias is also | |
5671 | checked for alias expansion. | |
cce855bc JA |
5672 | |
5673 | Aliases are created and listed with the `alias' command, and removed | |
5674 | with the `unalias' command. | |
5675 | ||
5676 | There is no mechanism for using arguments in the replacement text, | |
5677 | as in `csh'. If arguments are needed, a shell function should be used | |
28ef6c31 | 5678 | (*note Shell Functions::). |
cce855bc JA |
5679 | |
5680 | Aliases are not expanded when the shell is not interactive, unless | |
d3ad40de CR |
5681 | the `expand_aliases' shell option is set using `shopt' (*note The Shopt |
5682 | Builtin::). | |
ccc6cda3 | 5683 | |
cce855bc JA |
5684 | The rules concerning the definition and use of aliases are somewhat |
5685 | confusing. Bash always reads at least one complete line of input | |
5686 | before executing any of the commands on that line. Aliases are | |
5687 | expanded when a command is read, not when it is executed. Therefore, an | |
5688 | alias definition appearing on the same line as another command does not | |
5689 | take effect until the next line of input is read. The commands | |
5690 | following the alias definition on that line are not affected by the new | |
5691 | alias. This behavior is also an issue when functions are executed. | |
5692 | Aliases are expanded when a function definition is read, not when the | |
5693 | function is executed, because a function definition is itself a | |
5694 | compound command. As a consequence, aliases defined in a function are | |
5695 | not available until after that function is executed. To be safe, | |
5696 | always put alias definitions on a separate line, and do not use `alias' | |
5697 | in compound commands. | |
ccc6cda3 | 5698 | |
bb70624e | 5699 | For almost every purpose, shell functions are preferred over aliases. |
ccc6cda3 JA |
5700 | |
5701 | \1f | |
cce855bc | 5702 | File: bashref.info, Node: Arrays, Next: The Directory Stack, Prev: Aliases, Up: Bash Features |
ccc6cda3 | 5703 | |
37c41ab1 CR |
5704 | 6.7 Arrays |
5705 | ========== | |
ccc6cda3 | 5706 | |
09767ff0 CR |
5707 | Bash provides one-dimensional indexed and associative array variables. |
5708 | Any variable may be used as an indexed array; the `declare' builtin | |
5709 | will explicitly declare an array. There is no maximum limit on the | |
5710 | size of an array, nor any requirement that members be indexed or | |
5711 | assigned contiguously. Indexed arrays are referenced using integers | |
d9e1f41e | 5712 | (including arithmetic expressions (*note Shell Arithmetic::)) and are |
09767ff0 | 5713 | zero-based; associative arrays use arbitrary strings. |
ccc6cda3 | 5714 | |
09767ff0 CR |
5715 | An indexed array is created automatically if any variable is |
5716 | assigned to using the syntax | |
122f603c | 5717 | NAME[SUBSCRIPT]=VALUE |
ccc6cda3 JA |
5718 | |
5719 | The SUBSCRIPT is treated as an arithmetic expression that must evaluate | |
f6da9f85 | 5720 | to a number. To explicitly declare an array, use |
ccc6cda3 | 5721 | declare -a NAME |
37c41ab1 | 5722 | The syntax |
ccc6cda3 | 5723 | declare -a NAME[SUBSCRIPT] |
09767ff0 CR |
5724 | is also accepted; the SUBSCRIPT is ignored. |
5725 | ||
122f603c | 5726 | Associative arrays are created using |
09767ff0 CR |
5727 | declare -A NAME. |
5728 | ||
5729 | Attributes may be specified for an array variable using the | |
5730 | `declare' and `readonly' builtins. Each attribute applies to all | |
5731 | members of an array. | |
ccc6cda3 JA |
5732 | |
5733 | Arrays are assigned to using compound assignments of the form | |
122f603c | 5734 | NAME=(VALUE1 VALUE2 ... ) |
09767ff0 | 5735 | where each VALUE is of the form `[SUBSCRIPT]='STRING. Indexed array |
122f603c CR |
5736 | assignments do not require anything but STRING. When assigning to |
5737 | indexed arrays, if the optional subscript is supplied, that index is | |
09767ff0 CR |
5738 | assigned to; otherwise the index of the element assigned is the last |
5739 | index assigned to by the statement plus one. Indexing starts at zero. | |
5740 | ||
5741 | When assigning to an associative array, the subscript is required. | |
5742 | ||
5743 | This syntax is also accepted by the `declare' builtin. Individual | |
122f603c | 5744 | array elements may be assigned to using the `NAME[SUBSCRIPT]=VALUE' |
09767ff0 | 5745 | syntax introduced above. |
ccc6cda3 | 5746 | |
122f603c CR |
5747 | Any element of an array may be referenced using `${NAME[SUBSCRIPT]}'. |
5748 | The braces are required to avoid conflicts with the shell's filename | |
5749 | expansion operators. If the SUBSCRIPT is `@' or `*', the word expands | |
5750 | to all members of the array NAME. These subscripts differ only when | |
5751 | the word appears within double quotes. If the word is double-quoted, | |
5752 | `${NAME[*]}' expands to a single word with the value of each array | |
5753 | member separated by the first character of the `IFS' variable, and | |
5754 | `${NAME[@]}' expands each element of NAME to a separate word. When | |
5755 | there are no array members, `${NAME[@]}' expands to nothing. If the | |
5756 | double-quoted expansion occurs within a word, the expansion of the | |
5757 | first parameter is joined with the beginning part of the original word, | |
5758 | and the expansion of the last parameter is joined with the last part of | |
5759 | the original word. This is analogous to the expansion of the special | |
5760 | parameters `@' and `*'. `${#NAME[SUBSCRIPT]}' expands to the length of | |
5761 | `${NAME[SUBSCRIPT]}'. If SUBSCRIPT is `@' or `*', the expansion is the | |
5762 | number of elements in the array. Referencing an array variable without | |
5763 | a subscript is equivalent to referencing with a subscript of 0. If the | |
5764 | SUBSCRIPT used to reference an element of an indexed array evaluates to | |
5765 | a number less than zero, it is used as an offset from one greater than | |
5766 | the array's maximum index (so a subcript of -1 refers to the last | |
5767 | element of the array). | |
ccc6cda3 | 5768 | |
4a8bb13f CR |
5769 | An array variable is considered set if a subscript has been assigned |
5770 | a value. The null string is a valid value. | |
5771 | ||
122f603c CR |
5772 | The `unset' builtin is used to destroy arrays. `unset |
5773 | NAME[SUBSCRIPT]' destroys the array element at index SUBSCRIPT. Care | |
1c72c0cd | 5774 | must be taken to avoid unwanted side effects caused by filename |
122f603c CR |
5775 | expansion. `unset NAME', where NAME is an array, removes the entire |
5776 | array. A subscript of `*' or `@' also removes the entire array. | |
ccc6cda3 JA |
5777 | |
5778 | The `declare', `local', and `readonly' builtins each accept a `-a' | |
09767ff0 | 5779 | option to specify an indexed array and a `-A' option to specify an |
d9e1f41e CR |
5780 | associative array. If both options are supplied, `-A' takes precedence. |
5781 | The `read' builtin accepts a `-a' option to assign a list of words read | |
5782 | from the standard input to an array, and can read values from the | |
5783 | standard input into individual array elements. The `set' and `declare' | |
5784 | builtins display array values in a way that allows them to be reused as | |
5785 | input. | |
ccc6cda3 JA |
5786 | |
5787 | \1f | |
122f603c | 5788 | File: bashref.info, Node: The Directory Stack, Next: Controlling the Prompt, Prev: Arrays, Up: Bash Features |
cce855bc | 5789 | |
37c41ab1 CR |
5790 | 6.8 The Directory Stack |
5791 | ======================= | |
cce855bc | 5792 | |
bb70624e JA |
5793 | * Menu: |
5794 | ||
5795 | * Directory Stack Builtins:: Bash builtin commands to manipulate | |
5796 | the directory stack. | |
5797 | ||
5798 | The directory stack is a list of recently-visited directories. The | |
cce855bc JA |
5799 | `pushd' builtin adds directories to the stack as it changes the current |
5800 | directory, and the `popd' builtin removes specified directories from | |
5801 | the stack and changes the current directory to the directory removed. | |
5802 | The `dirs' builtin displays the contents of the directory stack. | |
5803 | ||
5804 | The contents of the directory stack are also visible as the value of | |
5805 | the `DIRSTACK' shell variable. | |
5806 | ||
bb70624e JA |
5807 | \1f |
5808 | File: bashref.info, Node: Directory Stack Builtins, Up: The Directory Stack | |
5809 | ||
37c41ab1 CR |
5810 | 6.8.1 Directory Stack Builtins |
5811 | ------------------------------ | |
bb70624e | 5812 | |
cce855bc | 5813 | `dirs' |
122f603c CR |
5814 | dirs [-clpv] [+N | -N] |
5815 | ||
cce855bc JA |
5816 | Display the list of currently remembered directories. Directories |
5817 | are added to the list with the `pushd' command; the `popd' command | |
5818 | removes directories from the list. | |
cce855bc JA |
5819 | |
5820 | `-c' | |
5821 | Clears the directory stack by deleting all of the elements. | |
5822 | ||
5823 | `-l' | |
122f603c CR |
5824 | Produces a listing using full pathnames; the default listing |
5825 | format uses a tilde to denote the home directory. | |
cce855bc JA |
5826 | |
5827 | `-p' | |
5828 | Causes `dirs' to print the directory stack with one entry per | |
5829 | line. | |
5830 | ||
5831 | `-v' | |
5832 | Causes `dirs' to print the directory stack with one entry per | |
5833 | line, prefixing each entry with its index in the stack. | |
5834 | ||
122f603c CR |
5835 | `+N' |
5836 | Displays the Nth directory (counting from the left of the | |
5837 | list printed by `dirs' when invoked without options), starting | |
5838 | with zero. | |
5839 | ||
5840 | `-N' | |
5841 | Displays the Nth directory (counting from the right of the | |
5842 | list printed by `dirs' when invoked without options), starting | |
5843 | with zero. | |
5844 | ||
cce855bc | 5845 | `popd' |
122f603c | 5846 | popd [-n] [+N | -N] |
cce855bc JA |
5847 | |
5848 | Remove the top entry from the directory stack, and `cd' to the new | |
5849 | top directory. When no arguments are given, `popd' removes the | |
5850 | top directory from the stack and performs a `cd' to the new top | |
5851 | directory. The elements are numbered from 0 starting at the first | |
122f603c CR |
5852 | directory listed with `dirs'; that is, `popd' is equivalent to |
5853 | `popd +0'. | |
5854 | ||
5855 | `-n' | |
5856 | Suppresses the normal change of directory when removing | |
5857 | directories from the stack, so that only the stack is | |
5858 | manipulated. | |
5859 | ||
cce855bc JA |
5860 | `+N' |
5861 | Removes the Nth directory (counting from the left of the list | |
5862 | printed by `dirs'), starting with zero. | |
5863 | ||
5864 | `-N' | |
5865 | Removes the Nth directory (counting from the right of the | |
5866 | list printed by `dirs'), starting with zero. | |
5867 | ||
cce855bc | 5868 | `pushd' |
122f603c | 5869 | pushd [-n] [+N | -N | DIR] |
cce855bc JA |
5870 | |
5871 | Save the current directory on the top of the directory stack and | |
5872 | then `cd' to DIR. With no arguments, `pushd' exchanges the top | |
5873 | two directories. | |
5874 | ||
d3ad40de CR |
5875 | `-n' |
5876 | Suppresses the normal change of directory when adding | |
5877 | directories to the stack, so that only the stack is | |
5878 | manipulated. | |
5879 | ||
cce855bc JA |
5880 | `+N' |
5881 | Brings the Nth directory (counting from the left of the list | |
5882 | printed by `dirs', starting with zero) to the top of the list | |
5883 | by rotating the stack. | |
5884 | ||
5885 | `-N' | |
5886 | Brings the Nth directory (counting from the right of the list | |
5887 | printed by `dirs', starting with zero) to the top of the list | |
5888 | by rotating the stack. | |
5889 | ||
cce855bc JA |
5890 | `DIR' |
5891 | Makes the current working directory be the top of the stack, | |
122f603c CR |
5892 | making it the new current directory as if it had been |
5893 | supplied as an argument to the `cd' builtin. | |
761783bf | 5894 | |
cce855bc | 5895 | \1f |
122f603c | 5896 | File: bashref.info, Node: Controlling the Prompt, Next: The Restricted Shell, Prev: The Directory Stack, Up: Bash Features |
ccc6cda3 | 5897 | |
37c41ab1 CR |
5898 | 6.9 Controlling the Prompt |
5899 | ========================== | |
ccc6cda3 | 5900 | |
37c41ab1 CR |
5901 | The value of the variable `PROMPT_COMMAND' is examined just before Bash |
5902 | prints each primary prompt. If `PROMPT_COMMAND' is set and has a | |
bb70624e JA |
5903 | non-null value, then the value is executed just as if it had been typed |
5904 | on the command line. | |
ccc6cda3 JA |
5905 | |
5906 | In addition, the following table describes the special characters | |
122f603c | 5907 | which can appear in the prompt variables `PS1' to `PS4': |
ccc6cda3 JA |
5908 | |
5909 | `\a' | |
cce855bc | 5910 | A bell character. |
ccc6cda3 JA |
5911 | |
5912 | `\d' | |
cce855bc | 5913 | The date, in "Weekday Month Date" format (e.g., "Tue May 26"). |
ccc6cda3 | 5914 | |
7117c2d2 JA |
5915 | `\D{FORMAT}' |
5916 | The FORMAT is passed to `strftime'(3) and the result is inserted | |
5917 | into the prompt string; an empty FORMAT results in a | |
5918 | locale-specific time representation. The braces are required. | |
5919 | ||
ccc6cda3 | 5920 | `\e' |
cce855bc | 5921 | An escape character. |
ccc6cda3 JA |
5922 | |
5923 | `\h' | |
cce855bc | 5924 | The hostname, up to the first `.'. |
ccc6cda3 JA |
5925 | |
5926 | `\H' | |
cce855bc | 5927 | The hostname. |
ccc6cda3 | 5928 | |
bb70624e JA |
5929 | `\j' |
5930 | The number of jobs currently managed by the shell. | |
5931 | ||
5932 | `\l' | |
5933 | The basename of the shell's terminal device name. | |
5934 | ||
ccc6cda3 | 5935 | `\n' |
cce855bc JA |
5936 | A newline. |
5937 | ||
5938 | `\r' | |
5939 | A carriage return. | |
ccc6cda3 JA |
5940 | |
5941 | `\s' | |
cce855bc | 5942 | The name of the shell, the basename of `$0' (the portion following |
ccc6cda3 JA |
5943 | the final slash). |
5944 | ||
5945 | `\t' | |
cce855bc | 5946 | The time, in 24-hour HH:MM:SS format. |
ccc6cda3 JA |
5947 | |
5948 | `\T' | |
cce855bc | 5949 | The time, in 12-hour HH:MM:SS format. |
ccc6cda3 JA |
5950 | |
5951 | `\@' | |
cce855bc JA |
5952 | The time, in 12-hour am/pm format. |
5953 | ||
f73dda09 JA |
5954 | `\A' |
5955 | The time, in 24-hour HH:MM format. | |
5956 | ||
cce855bc JA |
5957 | `\u' |
5958 | The username of the current user. | |
ccc6cda3 JA |
5959 | |
5960 | `\v' | |
cce855bc | 5961 | The version of Bash (e.g., 2.00) |
ccc6cda3 JA |
5962 | |
5963 | `\V' | |
cce855bc | 5964 | The release of Bash, version + patchlevel (e.g., 2.00.0) |
ccc6cda3 JA |
5965 | |
5966 | `\w' | |
12d937f9 | 5967 | The current working directory, with `$HOME' abbreviated with a |
09767ff0 | 5968 | tilde (uses the `$PROMPT_DIRTRIM' variable). |
ccc6cda3 JA |
5969 | |
5970 | `\W' | |
12d937f9 | 5971 | The basename of `$PWD', with `$HOME' abbreviated with a tilde. |
ccc6cda3 JA |
5972 | |
5973 | `\!' | |
cce855bc | 5974 | The history number of this command. |
ccc6cda3 JA |
5975 | |
5976 | `\#' | |
cce855bc | 5977 | The command number of this command. |
ccc6cda3 JA |
5978 | |
5979 | `\$' | |
cce855bc | 5980 | If the effective uid is 0, `#', otherwise `$'. |
ccc6cda3 | 5981 | |
cce855bc JA |
5982 | `\NNN' |
5983 | The character whose ASCII code is the octal value NNN. | |
ccc6cda3 JA |
5984 | |
5985 | `\\' | |
cce855bc | 5986 | A backslash. |
ccc6cda3 JA |
5987 | |
5988 | `\[' | |
cce855bc | 5989 | Begin a sequence of non-printing characters. This could be used to |
ccc6cda3 JA |
5990 | embed a terminal control sequence into the prompt. |
5991 | ||
5992 | `\]' | |
cce855bc | 5993 | End a sequence of non-printing characters. |
ccc6cda3 | 5994 | |
bb70624e JA |
5995 | The command number and the history number are usually different: the |
5996 | history number of a command is its position in the history list, which | |
5997 | may include commands restored from the history file (*note Bash History | |
28ef6c31 JA |
5998 | Facilities::), while the command number is the position in the sequence |
5999 | of commands executed during the current shell session. | |
bb70624e JA |
6000 | |
6001 | After the string is decoded, it is expanded via parameter expansion, | |
6002 | command substitution, arithmetic expansion, and quote removal, subject | |
28ef6c31 | 6003 | to the value of the `promptvars' shell option (*note Bash Builtins::). |
bb70624e | 6004 | |
ccc6cda3 | 6005 | \1f |
122f603c | 6006 | File: bashref.info, Node: The Restricted Shell, Next: Bash POSIX Mode, Prev: Controlling the Prompt, Up: Bash Features |
ccc6cda3 | 6007 | |
37c41ab1 CR |
6008 | 6.10 The Restricted Shell |
6009 | ========================= | |
ccc6cda3 | 6010 | |
37c41ab1 CR |
6011 | If Bash is started with the name `rbash', or the `--restricted' or `-r' |
6012 | option is supplied at invocation, the shell becomes restricted. A | |
ccc6cda3 JA |
6013 | restricted shell is used to set up an environment more controlled than |
6014 | the standard shell. A restricted shell behaves identically to `bash' | |
7117c2d2 JA |
6015 | with the exception that the following are disallowed or not performed: |
6016 | ||
ccc6cda3 JA |
6017 | * Changing directories with the `cd' builtin. |
6018 | ||
b72432fd JA |
6019 | * Setting or unsetting the values of the `SHELL', `PATH', `ENV', or |
6020 | `BASH_ENV' variables. | |
ccc6cda3 JA |
6021 | |
6022 | * Specifying command names containing slashes. | |
6023 | ||
6024 | * Specifying a filename containing a slash as an argument to the `.' | |
6025 | builtin command. | |
6026 | ||
bb70624e JA |
6027 | * Specifying a filename containing a slash as an argument to the `-p' |
6028 | option to the `hash' builtin command. | |
6029 | ||
ccc6cda3 JA |
6030 | * Importing function definitions from the shell environment at |
6031 | startup. | |
6032 | ||
cce855bc JA |
6033 | * Parsing the value of `SHELLOPTS' from the shell environment at |
6034 | startup. | |
6035 | ||
ccc6cda3 JA |
6036 | * Redirecting output using the `>', `>|', `<>', `>&', `&>', and `>>' |
6037 | redirection operators. | |
6038 | ||
6039 | * Using the `exec' builtin to replace the shell with another command. | |
6040 | ||
6041 | * Adding or deleting builtin commands with the `-f' and `-d' options | |
6042 | to the `enable' builtin. | |
6043 | ||
7117c2d2 JA |
6044 | * Using the `enable' builtin command to enable disabled shell |
6045 | builtins. | |
6046 | ||
ccc6cda3 JA |
6047 | * Specifying the `-p' option to the `command' builtin. |
6048 | ||
cce855bc | 6049 | * Turning off restricted mode with `set +r' or `set +o restricted'. |
ccc6cda3 | 6050 | |
7117c2d2 JA |
6051 | These restrictions are enforced after any startup files are read. |
6052 | ||
6053 | When a command that is found to be a shell script is executed (*note | |
6054 | Shell Scripts::), `rbash' turns off any restrictions in the shell | |
6055 | spawned to execute the script. | |
6056 | ||
ccc6cda3 JA |
6057 | \1f |
6058 | File: bashref.info, Node: Bash POSIX Mode, Prev: The Restricted Shell, Up: Bash Features | |
6059 | ||
37c41ab1 CR |
6060 | 6.11 Bash POSIX Mode |
6061 | ==================== | |
ccc6cda3 | 6062 | |
37c41ab1 CR |
6063 | Starting Bash with the `--posix' command-line option or executing `set |
6064 | -o posix' while Bash is running will cause Bash to conform more closely | |
ac18b312 CR |
6065 | to the POSIX standard by changing the behavior to match that specified |
6066 | by POSIX in areas where the Bash default differs. | |
ccc6cda3 | 6067 | |
7117c2d2 JA |
6068 | When invoked as `sh', Bash enters POSIX mode after reading the |
6069 | startup files. | |
6070 | ||
ccc6cda3 JA |
6071 | The following list is what's changed when `POSIX mode' is in effect: |
6072 | ||
6073 | 1. When a command in the hash table no longer exists, Bash will | |
6074 | re-search `$PATH' to find the new location. This is also | |
6075 | available with `shopt -s checkhash'. | |
6076 | ||
28ef6c31 JA |
6077 | 2. The message printed by the job control code and builtins when a job |
6078 | exits with a non-zero status is `Done(status)'. | |
ccc6cda3 JA |
6079 | |
6080 | 3. The message printed by the job control code and builtins when a job | |
28ef6c31 JA |
6081 | is stopped is `Stopped(SIGNAME)', where SIGNAME is, for example, |
6082 | `SIGTSTP'. | |
ccc6cda3 | 6083 | |
1c72c0cd CR |
6084 | 4. The `bg' builtin uses the required format to describe each job |
6085 | placed in the background, which does not include an indication of | |
6086 | whether the job is the current or previous job. | |
6087 | ||
6088 | 5. Reserved words appearing in a context where reserved words are | |
3ee6b87d | 6089 | recognized do not undergo alias expansion. |
ccc6cda3 | 6090 | |
ac18b312 CR |
6091 | 6. The POSIX `PS1' and `PS2' expansions of `!' to the history number |
6092 | and `!!' to `!' are enabled, and parameter expansion is performed | |
6093 | on the values of `PS1' and `PS2' regardless of the setting of the | |
6094 | `promptvars' option. | |
ccc6cda3 | 6095 | |
ac18b312 CR |
6096 | 7. The POSIX startup files are executed (`$ENV') rather than the |
6097 | normal Bash files. | |
ccc6cda3 | 6098 | |
1c72c0cd | 6099 | 8. Tilde expansion is only performed on assignments preceding a |
ccc6cda3 JA |
6100 | command name, rather than on all assignment statements on the line. |
6101 | ||
122f603c CR |
6102 | 9. The `command' builtin does not prevent builtins that take |
6103 | assignment statements as arguments from expanding them as | |
6104 | assignment statements; when not in POSIX mode, assignment builtins | |
6105 | lose their assignment statement expansion properties when preceded | |
6106 | by `command'. | |
6107 | ||
6108 | 10. The default history file is `~/.sh_history' (this is the default | |
ccc6cda3 JA |
6109 | value of `$HISTFILE'). |
6110 | ||
122f603c | 6111 | 11. The output of `kill -l' prints all the signal names on a single |
d3a24ed2 CR |
6112 | line, separated by spaces, without the `SIG' prefix. |
6113 | ||
122f603c | 6114 | 12. The `kill' builtin does not accept signal names with a `SIG' |
d3a24ed2 | 6115 | prefix. |
ccc6cda3 | 6116 | |
122f603c | 6117 | 13. Non-interactive shells exit if FILENAME in `.' FILENAME is not |
ccc6cda3 JA |
6118 | found. |
6119 | ||
122f603c | 6120 | 14. Non-interactive shells exit if a syntax error in an arithmetic |
cce855bc JA |
6121 | expansion results in an invalid expression. |
6122 | ||
122f603c | 6123 | 15. Non-interactive shells exit if there is a syntax error in a script |
220537f2 CR |
6124 | read with the `.' or `source' builtins, or in a string processed by |
6125 | the `eval' builtin. | |
6126 | ||
122f603c | 6127 | 16. Redirection operators do not perform filename expansion on the word |
ccc6cda3 JA |
6128 | in the redirection unless the shell is interactive. |
6129 | ||
122f603c | 6130 | 17. Redirection operators do not perform word splitting on the word in |
bb70624e JA |
6131 | the redirection. |
6132 | ||
122f603c | 6133 | 18. Function names must be valid shell `name's. That is, they may not |
ccc6cda3 | 6134 | contain characters other than letters, digits, and underscores, and |
cce855bc | 6135 | may not start with a digit. Declaring a function with an invalid |
ccc6cda3 JA |
6136 | name causes a fatal syntax error in non-interactive shells. |
6137 | ||
122f603c CR |
6138 | 19. Function names may not be the same as one of the POSIX special |
6139 | builtins. | |
6140 | ||
6141 | 20. POSIX special builtins are found before shell functions during | |
ac18b312 | 6142 | command lookup. |
ccc6cda3 | 6143 | |
122f603c | 6144 | 21. The `time' reserved word may be used by itself as a command. When |
220537f2 CR |
6145 | used in this way, it displays timing statistics for the shell and |
6146 | its completed children. The `TIMEFORMAT' variable controls the | |
6147 | format of the timing information. | |
6148 | ||
122f603c | 6149 | 22. When parsing and expanding a ${...} expansion that appears within |
220537f2 CR |
6150 | double quotes, single quotes are no longer special and cannot be |
6151 | used to quote a closing brace or other special character, unless | |
6152 | the operator is one of those defined to perform pattern removal. | |
6153 | In this case, they do not have to appear as matched pairs. | |
6154 | ||
122f603c | 6155 | 23. The parser does not recognize `time' as a reserved word if the next |
9ec5ed66 CR |
6156 | token begins with a `-'. |
6157 | ||
122f603c | 6158 | 24. If a POSIX special builtin returns an error status, a |
ccc6cda3 | 6159 | non-interactive shell exits. The fatal errors are those listed in |
ac18b312 | 6160 | the POSIX standard, and include things like passing incorrect |
ccc6cda3 JA |
6161 | options, redirection errors, variable assignment errors for |
6162 | assignments preceding the command name, and so on. | |
6163 | ||
122f603c | 6164 | 25. A non-interactive shell exits with an error status if a variable |
ccc6cda3 JA |
6165 | assignment error occurs when no command name follows the assignment |
6166 | statements. A variable assignment error occurs, for example, when | |
cce855bc | 6167 | trying to assign a value to a readonly variable. |
ccc6cda3 | 6168 | |
122f603c | 6169 | 26. A non-interactive shell exists with an error status if a variable |
e05be32d CR |
6170 | assignment error occurs in an assignment statement preceding a |
6171 | special builtin, but not with any other simple command. | |
6172 | ||
122f603c | 6173 | 27. A non-interactive shell exits with an error status if the iteration |
ccc6cda3 | 6174 | variable in a `for' statement or the selection variable in a |
cce855bc | 6175 | `select' statement is a readonly variable. |
ccc6cda3 | 6176 | |
122f603c | 6177 | 28. Process substitution is not available. |
ccc6cda3 | 6178 | |
122f603c | 6179 | 29. While variable indirection is available, it may not be applied to |
74d0116b CR |
6180 | the `#' and `?' special parameters. |
6181 | ||
122f603c | 6182 | 30. Assignment statements preceding POSIX special builtins persist in |
ac18b312 | 6183 | the shell environment after the builtin completes. |
ccc6cda3 | 6184 | |
122f603c | 6185 | 31. Assignment statements preceding shell function calls persist in the |
28ef6c31 JA |
6186 | shell environment after the function returns, as if a POSIX |
6187 | special builtin command had been executed. | |
6188 | ||
122f603c | 6189 | 32. The `export' and `readonly' builtin commands display their output |
ac18b312 | 6190 | in the format required by POSIX. |
d166f048 | 6191 | |
122f603c | 6192 | 33. The `trap' builtin displays signal names without the leading `SIG'. |
28ef6c31 | 6193 | |
122f603c | 6194 | 34. The `trap' builtin doesn't check the first argument for a possible |
d3a24ed2 | 6195 | signal specification and revert the signal handling to the original |
8a9c66f6 CR |
6196 | disposition if it is, unless that argument consists solely of |
6197 | digits and is a valid signal number. If users want to reset the | |
6198 | handler for a given signal to the original disposition, they | |
6199 | should use `-' as the first argument. | |
d3a24ed2 | 6200 | |
122f603c | 6201 | 35. The `.' and `source' builtins do not search the current directory |
28ef6c31 JA |
6202 | for the filename argument if it is not found by searching `PATH'. |
6203 | ||
122f603c | 6204 | 36. Subshells spawned to execute command substitutions inherit the |
28ef6c31 JA |
6205 | value of the `-e' option from the parent shell. When not in POSIX |
6206 | mode, Bash clears the `-e' option in such subshells. | |
6207 | ||
122f603c | 6208 | 37. Alias expansion is always enabled, even in non-interactive shells. |
28ef6c31 | 6209 | |
122f603c | 6210 | 38. When the `alias' builtin displays alias definitions, it does not |
d3a24ed2 CR |
6211 | display them with a leading `alias ' unless the `-p' option is |
6212 | supplied. | |
6213 | ||
122f603c | 6214 | 39. When the `set' builtin is invoked without options, it does not |
28ef6c31 JA |
6215 | display shell function names and definitions. |
6216 | ||
122f603c | 6217 | 40. When the `set' builtin is invoked without options, it displays |
f73dda09 JA |
6218 | variable values without quotes, unless they contain shell |
6219 | metacharacters, even if the result contains nonprinting characters. | |
ccc6cda3 | 6220 | |
122f603c | 6221 | 41. When the `cd' builtin is invoked in LOGICAL mode, and the pathname |
7117c2d2 JA |
6222 | constructed from `$PWD' and the directory name supplied as an |
6223 | argument does not refer to an existing directory, `cd' will fail | |
6224 | instead of falling back to PHYSICAL mode. | |
6225 | ||
122f603c | 6226 | 42. The `pwd' builtin verifies that the value it prints is the same as |
1c72c0cd CR |
6227 | the current directory, even if it is not asked to check the file |
6228 | system with the `-P' option. | |
6229 | ||
122f603c | 6230 | 43. When listing the history, the `fc' builtin does not include an |
8a9c66f6 CR |
6231 | indication of whether or not a history entry has been modified. |
6232 | ||
122f603c | 6233 | 44. The default editor used by `fc' is `ed'. |
8a9c66f6 | 6234 | |
122f603c | 6235 | 45. The `type' and `command' builtins will not report a non-executable |
37c41ab1 CR |
6236 | file as having been found, though the shell will attempt to |
6237 | execute such a file if it is the only so-named file found in | |
6238 | `$PATH'. | |
6239 | ||
122f603c | 6240 | 46. The `vi' editing mode will invoke the `vi' editor directly when |
a9fac3b2 | 6241 | the `v' command is run, instead of checking `$VISUAL' and |
1c72c0cd CR |
6242 | `$EDITOR'. |
6243 | ||
122f603c | 6244 | 47. When the `xpg_echo' option is enabled, Bash does not attempt to |
37c41ab1 CR |
6245 | interpret any arguments to `echo' as options. Each argument is |
6246 | displayed, after escape characters are converted. | |
6247 | ||
122f603c | 6248 | 48. The `ulimit' builtin uses a block size of 512 bytes for the `-c' |
09767ff0 CR |
6249 | and `-f' options. |
6250 | ||
122f603c | 6251 | 49. The arrival of `SIGCHLD' when a trap is set on `SIGCHLD' does not |
d5362af8 CR |
6252 | interrupt the `wait' builtin and cause it to return immediately. |
6253 | The trap command is run once for each child that exits. | |
6254 | ||
abe2eb5b CR |
6255 | 50. The `read' builtin may be interrupted by a signal for which a trap |
6256 | has been set. If Bash receives a trapped signal while executing | |
6257 | `read', the trap handler executes and `read' returns an exit | |
6258 | status greater than 128. | |
6259 | ||
8a9c66f6 | 6260 | |
ac18b312 | 6261 | There is other POSIX behavior that Bash does not implement by |
1c72c0cd | 6262 | default even when in POSIX mode. Specifically: |
ccc6cda3 | 6263 | |
1c72c0cd CR |
6264 | 1. The `fc' builtin checks `$EDITOR' as a program to edit history |
6265 | entries if `FCEDIT' is unset, rather than defaulting directly to | |
6266 | `ed'. `fc' uses `ed' if `EDITOR' is unset. | |
ccc6cda3 | 6267 | |
1c72c0cd CR |
6268 | 2. As noted above, Bash requires the `xpg_echo' option to be enabled |
6269 | for the `echo' builtin to be fully conformant. | |
28ef6c31 | 6270 | |
28ef6c31 | 6271 | |
1c72c0cd CR |
6272 | Bash can be configured to be POSIX-conformant by default, by |
6273 | specifying the `--enable-strict-posix-default' to `configure' when | |
6274 | building (*note Optional Features::). | |
28ef6c31 | 6275 | |
ccc6cda3 | 6276 | \1f |
c2a47ea9 | 6277 | File: bashref.info, Node: Job Control, Next: Command Line Editing, Prev: Bash Features, Up: Top |
ccc6cda3 | 6278 | |
37c41ab1 CR |
6279 | 7 Job Control |
6280 | ************* | |
ccc6cda3 | 6281 | |
37c41ab1 CR |
6282 | This chapter discusses what job control is, how it works, and how Bash |
6283 | allows you to access its facilities. | |
ccc6cda3 JA |
6284 | |
6285 | * Menu: | |
6286 | ||
6287 | * Job Control Basics:: How job control works. | |
6288 | * Job Control Builtins:: Bash builtin commands used to interact | |
6289 | with job control. | |
6290 | * Job Control Variables:: Variables Bash uses to customize job | |
6291 | control. | |
6292 | ||
6293 | \1f | |
6294 | File: bashref.info, Node: Job Control Basics, Next: Job Control Builtins, Up: Job Control | |
6295 | ||
37c41ab1 CR |
6296 | 7.1 Job Control Basics |
6297 | ====================== | |
ccc6cda3 | 6298 | |
37c41ab1 | 6299 | Job control refers to the ability to selectively stop (suspend) the |
ccc6cda3 JA |
6300 | execution of processes and continue (resume) their execution at a later |
6301 | point. A user typically employs this facility via an interactive | |
602bb739 CR |
6302 | interface supplied jointly by the operating system kernel's terminal |
6303 | driver and Bash. | |
ccc6cda3 JA |
6304 | |
6305 | The shell associates a JOB with each pipeline. It keeps a table of | |
6306 | currently executing jobs, which may be listed with the `jobs' command. | |
cce855bc | 6307 | When Bash starts a job asynchronously, it prints a line that looks like: |
ccc6cda3 | 6308 | [1] 25647 |
37c41ab1 CR |
6309 | indicating that this job is job number 1 and that the process ID of |
6310 | the last process in the pipeline associated with this job is 25647. | |
6311 | All of the processes in a single pipeline are members of the same job. | |
6312 | Bash uses the JOB abstraction as the basis for job control. | |
ccc6cda3 JA |
6313 | |
6314 | To facilitate the implementation of the user interface to job | |
bb70624e JA |
6315 | control, the operating system maintains the notion of a current terminal |
6316 | process group ID. Members of this process group (processes whose | |
6317 | process group ID is equal to the current terminal process group ID) | |
6318 | receive keyboard-generated signals such as `SIGINT'. These processes | |
6319 | are said to be in the foreground. Background processes are those whose | |
6320 | process group ID differs from the terminal's; such processes are immune | |
6321 | to keyboard-generated signals. Only foreground processes are allowed | |
602bb739 CR |
6322 | to read from or, if the user so specifies with `stty tostop', write to |
6323 | the terminal. Background processes which attempt to read from (write | |
6324 | to when `stty tostop' is in effect) the terminal are sent a `SIGTTIN' | |
6325 | (`SIGTTOU') signal by the kernel's terminal driver, which, unless | |
6326 | caught, suspends the process. | |
ccc6cda3 JA |
6327 | |
6328 | If the operating system on which Bash is running supports job | |
cce855bc JA |
6329 | control, Bash contains facilities to use it. Typing the SUSPEND |
6330 | character (typically `^Z', Control-Z) while a process is running causes | |
6331 | that process to be stopped and returns control to Bash. Typing the | |
6332 | DELAYED SUSPEND character (typically `^Y', Control-Y) causes the | |
6333 | process to be stopped when it attempts to read input from the terminal, | |
6334 | and control to be returned to Bash. The user then manipulates the | |
6335 | state of this job, using the `bg' command to continue it in the | |
6336 | background, the `fg' command to continue it in the foreground, or the | |
6337 | `kill' command to kill it. A `^Z' takes effect immediately, and has | |
6338 | the additional side effect of causing pending output and typeahead to | |
6339 | be discarded. | |
ccc6cda3 JA |
6340 | |
6341 | There are a number of ways to refer to a job in the shell. The | |
a9fac3b2 | 6342 | character `%' introduces a job specification (JOBSPEC). |
bb70624e JA |
6343 | |
6344 | Job number `n' may be referred to as `%n'. The symbols `%%' and | |
6345 | `%+' refer to the shell's notion of the current job, which is the last | |
eb2bb562 CR |
6346 | job stopped while it was in the foreground or started in the background. |
6347 | A single `%' (with no accompanying job specification) also refers to | |
09767ff0 CR |
6348 | the current job. The previous job may be referenced using `%-'. If |
6349 | there is only a single job, `%+' and `%-' can both be used to refer to | |
6350 | that job. In output pertaining to jobs (e.g., the output of the `jobs' | |
6351 | command), the current job is always flagged with a `+', and the | |
6352 | previous job with a `-'. | |
bb70624e JA |
6353 | |
6354 | A job may also be referred to using a prefix of the name used to | |
6355 | start it, or using a substring that appears in its command line. For | |
122f603c CR |
6356 | example, `%ce' refers to a stopped `ce' job. Using `%?ce', on the |
6357 | other hand, refers to any job containing the string `ce' in its command | |
6358 | line. If the prefix or substring matches more than one job, Bash | |
6359 | reports an error. | |
ccc6cda3 JA |
6360 | |
6361 | Simply naming a job can be used to bring it into the foreground: | |
6362 | `%1' is a synonym for `fg %1', bringing job 1 from the background into | |
6363 | the foreground. Similarly, `%1 &' resumes job 1 in the background, | |
6364 | equivalent to `bg %1' | |
6365 | ||
6366 | The shell learns immediately whenever a job changes state. | |
6367 | Normally, Bash waits until it is about to print a prompt before | |
6368 | reporting changes in a job's status so as to not interrupt any other | |
f73dda09 JA |
6369 | output. If the `-b' option to the `set' builtin is enabled, Bash |
6370 | reports such changes immediately (*note The Set Builtin::). Any trap | |
6371 | on `SIGCHLD' is executed for each child process that exits. | |
ccc6cda3 | 6372 | |
d3ad40de | 6373 | If an attempt to exit Bash is made while jobs are stopped, (or |
6a8fd0ed | 6374 | running, if the `checkjobs' option is enabled - see *note The Shopt |
d3ad40de CR |
6375 | Builtin::), the shell prints a warning message, and if the `checkjobs' |
6376 | option is enabled, lists the jobs and their statuses. The `jobs' | |
cce855bc JA |
6377 | command may then be used to inspect their status. If a second attempt |
6378 | to exit is made without an intervening command, Bash does not print | |
d3ad40de | 6379 | another warning, and any stopped jobs are terminated. |
ccc6cda3 JA |
6380 | |
6381 | \1f | |
6382 | File: bashref.info, Node: Job Control Builtins, Next: Job Control Variables, Prev: Job Control Basics, Up: Job Control | |
6383 | ||
37c41ab1 CR |
6384 | 7.2 Job Control Builtins |
6385 | ======================== | |
ccc6cda3 JA |
6386 | |
6387 | `bg' | |
37c41ab1 | 6388 | bg [JOBSPEC ...] |
122f603c | 6389 | |
37c41ab1 | 6390 | Resume each suspended job JOBSPEC in the background, as if it had |
cce855bc JA |
6391 | been started with `&'. If JOBSPEC is not supplied, the current |
6392 | job is used. The return status is zero unless it is run when job | |
1c72c0cd CR |
6393 | control is not enabled, or, when run with job control enabled, any |
6394 | JOBSPEC was not found or specifies a job that was started without | |
6395 | job control. | |
ccc6cda3 JA |
6396 | |
6397 | `fg' | |
6398 | fg [JOBSPEC] | |
122f603c | 6399 | |
cce855bc JA |
6400 | Resume the job JOBSPEC in the foreground and make it the current |
6401 | job. If JOBSPEC is not supplied, the current job is used. The | |
6402 | return status is that of the command placed into the foreground, | |
6403 | or non-zero if run when job control is disabled or, when run with | |
6404 | job control enabled, JOBSPEC does not specify a valid job or | |
6405 | JOBSPEC specifies a job that was started without job control. | |
ccc6cda3 JA |
6406 | |
6407 | `jobs' | |
bb70624e | 6408 | jobs [-lnprs] [JOBSPEC] |
cce855bc | 6409 | jobs -x COMMAND [ARGUMENTS] |
ccc6cda3 JA |
6410 | |
6411 | The first form lists the active jobs. The options have the | |
6412 | following meanings: | |
6413 | ||
6414 | `-l' | |
cce855bc | 6415 | List process IDs in addition to the normal information. |
ccc6cda3 JA |
6416 | |
6417 | `-n' | |
6418 | Display information only about jobs that have changed status | |
cce855bc | 6419 | since the user was last notified of their status. |
ccc6cda3 JA |
6420 | |
6421 | `-p' | |
6422 | List only the process ID of the job's process group leader. | |
6423 | ||
6424 | `-r' | |
122f603c | 6425 | Display only running jobs. |
ccc6cda3 JA |
6426 | |
6427 | `-s' | |
122f603c | 6428 | Display only stopped jobs. |
ccc6cda3 JA |
6429 | |
6430 | If JOBSPEC is given, output is restricted to information about | |
6431 | that job. If JOBSPEC is not supplied, the status of all jobs is | |
6432 | listed. | |
6433 | ||
6434 | If the `-x' option is supplied, `jobs' replaces any JOBSPEC found | |
6435 | in COMMAND or ARGUMENTS with the corresponding process group ID, | |
6436 | and executes COMMAND, passing it ARGUMENTs, returning its exit | |
6437 | status. | |
6438 | ||
6439 | `kill' | |
cce855bc JA |
6440 | kill [-s SIGSPEC] [-n SIGNUM] [-SIGSPEC] JOBSPEC or PID |
6441 | kill -l [EXIT_STATUS] | |
122f603c | 6442 | |
ccc6cda3 | 6443 | Send a signal specified by SIGSPEC or SIGNUM to the process named |
cce855bc | 6444 | by job specification JOBSPEC or process ID PID. SIGSPEC is either |
9f422431 CR |
6445 | a case-insensitive signal name such as `SIGINT' (with or without |
6446 | the `SIG' prefix) or a signal number; SIGNUM is a signal number. | |
6447 | If SIGSPEC and SIGNUM are not present, `SIGTERM' is used. The | |
6448 | `-l' option lists the signal names. If any arguments are supplied | |
6449 | when `-l' is given, the names of the signals corresponding to the | |
6450 | arguments are listed, and the return status is zero. EXIT_STATUS | |
6451 | is a number specifying a signal number or the exit status of a | |
6452 | process terminated by a signal. The return status is zero if at | |
6453 | least one signal was successfully sent, or non-zero if an error | |
6454 | occurs or an invalid option is encountered. | |
ccc6cda3 JA |
6455 | |
6456 | `wait' | |
eb2bb562 | 6457 | wait [JOBSPEC or PID ...] |
122f603c | 6458 | |
eb2bb562 CR |
6459 | Wait until the child process specified by each process ID PID or |
6460 | job specification JOBSPEC exits and return the exit status of the | |
6461 | last command waited for. If a job spec is given, all processes in | |
6462 | the job are waited for. If no arguments are given, all currently | |
cce855bc JA |
6463 | active child processes are waited for, and the return status is |
6464 | zero. If neither JOBSPEC nor PID specifies an active child process | |
6465 | of the shell, the return status is 127. | |
ccc6cda3 JA |
6466 | |
6467 | `disown' | |
cce855bc | 6468 | disown [-ar] [-h] [JOBSPEC ...] |
122f603c CR |
6469 | |
6470 | Without options, remove each JOBSPEC from the table of active jobs. | |
6471 | If the `-h' option is given, the job is not removed from the table, | |
6472 | but is marked so that `SIGHUP' is not sent to the job if the shell | |
6473 | receives a `SIGHUP'. If JOBSPEC is not present, and neither the | |
6474 | `-a' nor `-r' option is supplied, the current job is used. If no | |
6475 | JOBSPEC is supplied, the `-a' option means to remove or mark all | |
6476 | jobs; the `-r' option without a JOBSPEC argument restricts | |
6477 | operation to running jobs. | |
ccc6cda3 JA |
6478 | |
6479 | `suspend' | |
6480 | suspend [-f] | |
122f603c | 6481 | |
ccc6cda3 | 6482 | Suspend the execution of this shell until it receives a `SIGCONT' |
09767ff0 CR |
6483 | signal. A login shell cannot be suspended; the `-f' option can be |
6484 | used to override this and force the suspension. | |
ccc6cda3 JA |
6485 | |
6486 | When job control is not active, the `kill' and `wait' builtins do | |
6487 | not accept JOBSPEC arguments. They must be supplied process IDs. | |
6488 | ||
6489 | \1f | |
6490 | File: bashref.info, Node: Job Control Variables, Prev: Job Control Builtins, Up: Job Control | |
6491 | ||
37c41ab1 CR |
6492 | 7.3 Job Control Variables |
6493 | ========================= | |
ccc6cda3 JA |
6494 | |
6495 | `auto_resume' | |
6496 | This variable controls how the shell interacts with the user and | |
6497 | job control. If this variable exists then single word simple | |
cce855bc JA |
6498 | commands without redirections are treated as candidates for |
6499 | resumption of an existing job. There is no ambiguity allowed; if | |
6500 | there is more than one job beginning with the string typed, then | |
6501 | the most recently accessed job will be selected. The name of a | |
6502 | stopped job, in this context, is the command line used to start | |
6503 | it. If this variable is set to the value `exact', the string | |
6504 | supplied must match the name of a stopped job exactly; if set to | |
ccc6cda3 JA |
6505 | `substring', the string supplied needs to match a substring of the |
6506 | name of a stopped job. The `substring' value provides | |
6507 | functionality analogous to the `%?' job ID (*note Job Control | |
28ef6c31 JA |
6508 | Basics::). If set to any other value, the supplied string must be |
6509 | a prefix of a stopped job's name; this provides functionality | |
ccc6cda3 JA |
6510 | analogous to the `%' job ID. |
6511 | ||
761783bf | 6512 | |
ccc6cda3 | 6513 | \1f |
c2a47ea9 | 6514 | File: bashref.info, Node: Command Line Editing, Next: Using History Interactively, Prev: Job Control, Up: Top |
ccc6cda3 | 6515 | |
37c41ab1 CR |
6516 | 8 Command Line Editing |
6517 | ********************** | |
ccc6cda3 | 6518 | |
37c41ab1 | 6519 | This chapter describes the basic features of the GNU command line |
bb70624e JA |
6520 | editing interface. Command line editing is provided by the Readline |
6521 | library, which is used by several different programs, including Bash. | |
a9fac3b2 CR |
6522 | Command line editing is enabled by default when using an interactive |
6523 | shell, unless the `--noediting' option is supplied at shell invocation. | |
6524 | Line editing is also used when using the `-e' option to the `read' | |
6525 | builtin command (*note Bash Builtins::). By default, the line editing | |
e05be32d | 6526 | commands are similar to those of Emacs. A vi-style line editing |
a9fac3b2 CR |
6527 | interface is also available. Line editing can be enabled at any time |
6528 | using the `-o emacs' or `-o vi' options to the `set' builtin command | |
6529 | (*note The Set Builtin::), or disabled using the `+o emacs' or `+o vi' | |
6530 | options to `set'. | |
ccc6cda3 JA |
6531 | |
6532 | * Menu: | |
6533 | ||
bb70624e JA |
6534 | * Introduction and Notation:: Notation used in this text. |
6535 | * Readline Interaction:: The minimum set of commands for editing a line. | |
6536 | * Readline Init File:: Customizing Readline from a user's view. | |
6537 | * Bindable Readline Commands:: A description of most of the Readline commands | |
6538 | available for binding | |
6539 | * Readline vi Mode:: A short description of how to make Readline | |
6540 | behave like the vi editor. | |
6541 | ||
6542 | * Programmable Completion:: How to specify the possible completions for | |
6543 | a specific command. | |
6544 | * Programmable Completion Builtins:: Builtin commands to specify how to | |
6545 | complete arguments for a particular command. | |
45c0f7f8 CR |
6546 | * A Programmable Completion Example:: An example shell function for |
6547 | generating possible completions. | |
ccc6cda3 JA |
6548 | |
6549 | \1f | |
bb70624e | 6550 | File: bashref.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing |
ccc6cda3 | 6551 | |
37c41ab1 CR |
6552 | 8.1 Introduction to Line Editing |
6553 | ================================ | |
ccc6cda3 | 6554 | |
37c41ab1 | 6555 | The following paragraphs describe the notation used to represent |
bb70624e | 6556 | keystrokes. |
ccc6cda3 | 6557 | |
28ef6c31 | 6558 | The text `C-k' is read as `Control-K' and describes the character |
bb70624e | 6559 | produced when the <k> key is pressed while the Control key is depressed. |
ccc6cda3 | 6560 | |
28ef6c31 | 6561 | The text `M-k' is read as `Meta-K' and describes the character |
bb70624e JA |
6562 | produced when the Meta key (if you have one) is depressed, and the <k> |
6563 | key is pressed. The Meta key is labeled <ALT> on many keyboards. On | |
6564 | keyboards with two keys labeled <ALT> (usually to either side of the | |
6565 | space bar), the <ALT> on the left side is generally set to work as a | |
6566 | Meta key. The <ALT> key on the right may also be configured to work as | |
6567 | a Meta key or may be configured as some other modifier, such as a | |
6568 | Compose key for typing accented characters. | |
6569 | ||
6570 | If you do not have a Meta or <ALT> key, or another key working as a | |
6571 | Meta key, the identical keystroke can be generated by typing <ESC> | |
28ef6c31 JA |
6572 | _first_, and then typing <k>. Either process is known as "metafying" |
6573 | the <k> key. | |
bb70624e | 6574 | |
28ef6c31 JA |
6575 | The text `M-C-k' is read as `Meta-Control-k' and describes the |
6576 | character produced by "metafying" `C-k'. | |
bb70624e JA |
6577 | |
6578 | In addition, several keys have their own names. Specifically, | |
6579 | <DEL>, <ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves | |
28ef6c31 JA |
6580 | when seen in this text, or in an init file (*note Readline Init File::). |
6581 | If your keyboard lacks a <LFD> key, typing <C-j> will produce the | |
6582 | desired character. The <RET> key may be labeled <Return> or <Enter> on | |
6583 | some keyboards. | |
ccc6cda3 JA |
6584 | |
6585 | \1f | |
bb70624e | 6586 | File: bashref.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing |
cce855bc | 6587 | |
37c41ab1 CR |
6588 | 8.2 Readline Interaction |
6589 | ======================== | |
cce855bc | 6590 | |
37c41ab1 | 6591 | Often during an interactive session you type in a long line of text, |
bb70624e JA |
6592 | only to notice that the first word on the line is misspelled. The |
6593 | Readline library gives you a set of commands for manipulating the text | |
6594 | as you type it in, allowing you to just fix your typo, and not forcing | |
6595 | you to retype the majority of the line. Using these editing commands, | |
6596 | you move the cursor to the place that needs correction, and delete or | |
6597 | insert the text of the corrections. Then, when you are satisfied with | |
28ef6c31 JA |
6598 | the line, you simply press <RET>. You do not have to be at the end of |
6599 | the line to press <RET>; the entire line is accepted regardless of the | |
6600 | location of the cursor within the line. | |
cce855bc | 6601 | |
bb70624e | 6602 | * Menu: |
cce855bc | 6603 | |
bb70624e JA |
6604 | * Readline Bare Essentials:: The least you need to know about Readline. |
6605 | * Readline Movement Commands:: Moving about the input line. | |
6606 | * Readline Killing Commands:: How to delete text, and how to get it back! | |
6607 | * Readline Arguments:: Giving numeric arguments to commands. | |
6608 | * Searching:: Searching through previous lines. | |
cce855bc | 6609 | |
bb70624e JA |
6610 | \1f |
6611 | File: bashref.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction | |
cce855bc | 6612 | |
37c41ab1 CR |
6613 | 8.2.1 Readline Bare Essentials |
6614 | ------------------------------ | |
cce855bc | 6615 | |
37c41ab1 CR |
6616 | In order to enter characters into the line, simply type them. The typed |
6617 | character appears where the cursor was, and then the cursor moves one | |
6618 | space to the right. If you mistype a character, you can use your erase | |
6619 | character to back up and delete the mistyped character. | |
cce855bc | 6620 | |
bb70624e JA |
6621 | Sometimes you may mistype a character, and not notice the error |
6622 | until you have typed several other characters. In that case, you can | |
28ef6c31 JA |
6623 | type `C-b' to move the cursor to the left, and then correct your |
6624 | mistake. Afterwards, you can move the cursor to the right with `C-f'. | |
cce855bc | 6625 | |
bb70624e JA |
6626 | When you add text in the middle of a line, you will notice that |
6627 | characters to the right of the cursor are `pushed over' to make room | |
6628 | for the text that you have inserted. Likewise, when you delete text | |
6629 | behind the cursor, characters to the right of the cursor are `pulled | |
6630 | back' to fill in the blank space created by the removal of the text. A | |
6631 | list of the bare essentials for editing the text of an input line | |
6632 | follows. | |
cce855bc | 6633 | |
28ef6c31 | 6634 | `C-b' |
bb70624e | 6635 | Move back one character. |
cce855bc | 6636 | |
28ef6c31 | 6637 | `C-f' |
bb70624e | 6638 | Move forward one character. |
cce855bc | 6639 | |
bb70624e JA |
6640 | <DEL> or <Backspace> |
6641 | Delete the character to the left of the cursor. | |
cce855bc | 6642 | |
28ef6c31 | 6643 | `C-d' |
bb70624e | 6644 | Delete the character underneath the cursor. |
cce855bc | 6645 | |
bb70624e JA |
6646 | Printing characters |
6647 | Insert the character into the line at the cursor. | |
cce855bc | 6648 | |
28ef6c31 | 6649 | `C-_' or `C-x C-u' |
bb70624e JA |
6650 | Undo the last editing command. You can undo all the way back to an |
6651 | empty line. | |
cce855bc | 6652 | |
bb70624e JA |
6653 | (Depending on your configuration, the <Backspace> key be set to delete |
6654 | the character to the left of the cursor and the <DEL> key set to delete | |
28ef6c31 | 6655 | the character underneath the cursor, like `C-d', rather than the |
bb70624e | 6656 | character to the left of the cursor.) |
cce855bc JA |
6657 | |
6658 | \1f | |
bb70624e | 6659 | File: bashref.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction |
ccc6cda3 | 6660 | |
37c41ab1 CR |
6661 | 8.2.2 Readline Movement Commands |
6662 | -------------------------------- | |
ccc6cda3 | 6663 | |
37c41ab1 | 6664 | The above table describes the most basic keystrokes that you need in |
bb70624e | 6665 | order to do editing of the input line. For your convenience, many |
28ef6c31 | 6666 | other commands have been added in addition to `C-b', `C-f', `C-d', and |
bb70624e | 6667 | <DEL>. Here are some commands for moving more rapidly about the line. |
ccc6cda3 | 6668 | |
28ef6c31 | 6669 | `C-a' |
bb70624e | 6670 | Move to the start of the line. |
ccc6cda3 | 6671 | |
28ef6c31 | 6672 | `C-e' |
bb70624e | 6673 | Move to the end of the line. |
ccc6cda3 | 6674 | |
28ef6c31 | 6675 | `M-f' |
bb70624e JA |
6676 | Move forward a word, where a word is composed of letters and |
6677 | digits. | |
ccc6cda3 | 6678 | |
28ef6c31 | 6679 | `M-b' |
bb70624e | 6680 | Move backward a word. |
ccc6cda3 | 6681 | |
28ef6c31 | 6682 | `C-l' |
bb70624e | 6683 | Clear the screen, reprinting the current line at the top. |
ccc6cda3 | 6684 | |
28ef6c31 | 6685 | Notice how `C-f' moves forward a character, while `M-f' moves |
bb70624e JA |
6686 | forward a word. It is a loose convention that control keystrokes |
6687 | operate on characters while meta keystrokes operate on words. | |
ccc6cda3 JA |
6688 | |
6689 | \1f | |
bb70624e | 6690 | File: bashref.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction |
ccc6cda3 | 6691 | |
37c41ab1 CR |
6692 | 8.2.3 Readline Killing Commands |
6693 | ------------------------------- | |
ccc6cda3 | 6694 | |
37c41ab1 CR |
6695 | "Killing" text means to delete the text from the line, but to save it |
6696 | away for later use, usually by "yanking" (re-inserting) it back into | |
bb70624e JA |
6697 | the line. (`Cut' and `paste' are more recent jargon for `kill' and |
6698 | `yank'.) | |
ccc6cda3 | 6699 | |
bb70624e JA |
6700 | If the description for a command says that it `kills' text, then you |
6701 | can be sure that you can get the text back in a different (or the same) | |
6702 | place later. | |
ccc6cda3 | 6703 | |
bb70624e JA |
6704 | When you use a kill command, the text is saved in a "kill-ring". |
6705 | Any number of consecutive kills save all of the killed text together, so | |
6706 | that when you yank it back, you get it all. The kill ring is not line | |
6707 | specific; the text that you killed on a previously typed line is | |
37c41ab1 | 6708 | available to be yanked back later, when you are typing another line. |
ccc6cda3 | 6709 | |
bb70624e | 6710 | Here is the list of commands for killing text. |
ccc6cda3 | 6711 | |
28ef6c31 | 6712 | `C-k' |
bb70624e JA |
6713 | Kill the text from the current cursor position to the end of the |
6714 | line. | |
ccc6cda3 | 6715 | |
28ef6c31 | 6716 | `M-d' |
bb70624e JA |
6717 | Kill from the cursor to the end of the current word, or, if between |
6718 | words, to the end of the next word. Word boundaries are the same | |
28ef6c31 | 6719 | as those used by `M-f'. |
ccc6cda3 | 6720 | |
28ef6c31 | 6721 | `M-<DEL>' |
f73dda09 | 6722 | Kill from the cursor the start of the current word, or, if between |
bb70624e | 6723 | words, to the start of the previous word. Word boundaries are the |
28ef6c31 | 6724 | same as those used by `M-b'. |
ccc6cda3 | 6725 | |
28ef6c31 | 6726 | `C-w' |
ccc6cda3 | 6727 | Kill from the cursor to the previous whitespace. This is |
28ef6c31 | 6728 | different than `M-<DEL>' because the word boundaries differ. |
ccc6cda3 | 6729 | |
761783bf | 6730 | |
cce855bc JA |
6731 | Here is how to "yank" the text back into the line. Yanking means to |
6732 | copy the most-recently-killed text from the kill buffer. | |
ccc6cda3 | 6733 | |
28ef6c31 | 6734 | `C-y' |
ccc6cda3 JA |
6735 | Yank the most recently killed text back into the buffer at the |
6736 | cursor. | |
6737 | ||
28ef6c31 | 6738 | `M-y' |
ccc6cda3 | 6739 | Rotate the kill-ring, and yank the new top. You can only do this |
28ef6c31 | 6740 | if the prior command is `C-y' or `M-y'. |
ccc6cda3 JA |
6741 | |
6742 | \1f | |
6743 | File: bashref.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction | |
6744 | ||
37c41ab1 CR |
6745 | 8.2.4 Readline Arguments |
6746 | ------------------------ | |
ccc6cda3 | 6747 | |
37c41ab1 | 6748 | You can pass numeric arguments to Readline commands. Sometimes the |
ccc6cda3 JA |
6749 | argument acts as a repeat count, other times it is the sign of the |
6750 | argument that is significant. If you pass a negative argument to a | |
6751 | command which normally acts in a forward direction, that command will | |
6752 | act in a backward direction. For example, to kill text back to the | |
6753 | start of the line, you might type `M-- C-k'. | |
6754 | ||
6755 | The general way to pass numeric arguments to a command is to type | |
cce855bc | 6756 | meta digits before the command. If the first `digit' typed is a minus |
bb70624e | 6757 | sign (`-'), then the sign of the argument will be negative. Once you |
cce855bc JA |
6758 | have typed one meta digit to get the argument started, you can type the |
6759 | remainder of the digits, and then the command. For example, to give | |
28ef6c31 JA |
6760 | the `C-d' command an argument of 10, you could type `M-1 0 C-d', which |
6761 | will delete the next ten characters on the input line. | |
ccc6cda3 JA |
6762 | |
6763 | \1f | |
6764 | File: bashref.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction | |
6765 | ||
37c41ab1 CR |
6766 | 8.2.5 Searching for Commands in the History |
6767 | ------------------------------------------- | |
ccc6cda3 | 6768 | |
37c41ab1 | 6769 | Readline provides commands for searching through the command history |
28ef6c31 JA |
6770 | (*note Bash History Facilities::) for lines containing a specified |
6771 | string. There are two search modes: "incremental" and | |
6772 | "non-incremental". | |
ccc6cda3 JA |
6773 | |
6774 | Incremental searches begin before the user has finished typing the | |
6775 | search string. As each character of the search string is typed, | |
cce855bc | 6776 | Readline displays the next entry from the history matching the string |
ccc6cda3 | 6777 | typed so far. An incremental search requires only as many characters |
bb70624e | 6778 | as needed to find the desired history entry. To search backward in the |
28ef6c31 | 6779 | history for a particular string, type `C-r'. Typing `C-s' searches |
bb70624e JA |
6780 | forward through the history. The characters present in the value of |
6781 | the `isearch-terminators' variable are used to terminate an incremental | |
6782 | search. If that variable has not been assigned a value, the <ESC> and | |
28ef6c31 | 6783 | `C-J' characters will terminate an incremental search. `C-g' will |
bb70624e JA |
6784 | abort an incremental search and restore the original line. When the |
6785 | search is terminated, the history entry containing the search string | |
6786 | becomes the current line. | |
6787 | ||
28ef6c31 JA |
6788 | To find other matching entries in the history list, type `C-r' or |
6789 | `C-s' as appropriate. This will search backward or forward in the | |
bb70624e JA |
6790 | history for the next entry matching the search string typed so far. |
6791 | Any other key sequence bound to a Readline command will terminate the | |
6792 | search and execute that command. For instance, a <RET> will terminate | |
6793 | the search and accept the line, thereby executing the command from the | |
28ef6c31 JA |
6794 | history list. A movement command will terminate the search, make the |
6795 | last line found the current line, and begin editing. | |
ccc6cda3 | 6796 | |
f73dda09 JA |
6797 | Readline remembers the last incremental search string. If two |
6798 | `C-r's are typed without any intervening characters defining a new | |
6799 | search string, any remembered search string is used. | |
6800 | ||
ccc6cda3 JA |
6801 | Non-incremental searches read the entire search string before |
6802 | starting to search for matching history lines. The search string may be | |
cce855bc | 6803 | typed by the user or be part of the contents of the current line. |
ccc6cda3 JA |
6804 | |
6805 | \1f | |
6806 | File: bashref.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing | |
6807 | ||
37c41ab1 CR |
6808 | 8.3 Readline Init File |
6809 | ====================== | |
ccc6cda3 | 6810 | |
37c41ab1 | 6811 | Although the Readline library comes with a set of Emacs-like |
cce855bc JA |
6812 | keybindings installed by default, it is possible to use a different set |
6813 | of keybindings. Any user can customize programs that use Readline by | |
bb70624e JA |
6814 | putting commands in an "inputrc" file, conventionally in his home |
6815 | directory. The name of this file is taken from the value of the shell | |
6816 | variable `INPUTRC'. If that variable is unset, the default is | |
d3ad40de CR |
6817 | `~/.inputrc'. If that file does not exist or cannot be read, the |
6818 | ultimate default is `/etc/inputrc'. | |
ccc6cda3 JA |
6819 | |
6820 | When a program which uses the Readline library starts up, the init | |
6821 | file is read, and the key bindings are set. | |
6822 | ||
6823 | In addition, the `C-x C-r' command re-reads this init file, thus | |
6824 | incorporating any changes that you might have made to it. | |
6825 | ||
6826 | * Menu: | |
6827 | ||
6828 | * Readline Init File Syntax:: Syntax for the commands in the inputrc file. | |
6829 | ||
6830 | * Conditional Init Constructs:: Conditional key bindings in the inputrc file. | |
6831 | ||
6832 | * Sample Init File:: An example inputrc file. | |
6833 | ||
6834 | \1f | |
6835 | File: bashref.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File | |
6836 | ||
37c41ab1 CR |
6837 | 8.3.1 Readline Init File Syntax |
6838 | ------------------------------- | |
ccc6cda3 | 6839 | |
37c41ab1 | 6840 | There are only a few basic constructs allowed in the Readline init |
ccc6cda3 JA |
6841 | file. Blank lines are ignored. Lines beginning with a `#' are |
6842 | comments. Lines beginning with a `$' indicate conditional constructs | |
28ef6c31 | 6843 | (*note Conditional Init Constructs::). Other lines denote variable |
ccc6cda3 JA |
6844 | settings and key bindings. |
6845 | ||
6846 | Variable Settings | |
cce855bc JA |
6847 | You can modify the run-time behavior of Readline by altering the |
6848 | values of variables in Readline using the `set' command within the | |
28ef6c31 JA |
6849 | init file. The syntax is simple: |
6850 | ||
6851 | set VARIABLE VALUE | |
6852 | ||
6853 | Here, for example, is how to change from the default Emacs-like | |
6854 | key binding to use `vi' line editing commands: | |
ccc6cda3 JA |
6855 | |
6856 | set editing-mode vi | |
6857 | ||
28ef6c31 | 6858 | Variable names and values, where appropriate, are recognized |
1c72c0cd CR |
6859 | without regard to case. Unrecognized variable names are ignored. |
6860 | ||
6861 | Boolean variables (those that can be set to on or off) are set to | |
6862 | on if the value is null or empty, ON (case-insensitive), or 1. | |
6863 | Any other value results in the variable being set to off. | |
28ef6c31 | 6864 | |
bb70624e JA |
6865 | The `bind -V' command lists the current Readline variable names |
6866 | and values. *Note Bash Builtins::. | |
6867 | ||
cce855bc JA |
6868 | A great deal of run-time behavior is changeable with the following |
6869 | variables. | |
ccc6cda3 JA |
6870 | |
6871 | `bell-style' | |
6872 | Controls what happens when Readline wants to ring the | |
6873 | terminal bell. If set to `none', Readline never rings the | |
6874 | bell. If set to `visible', Readline uses a visible bell if | |
6875 | one is available. If set to `audible' (the default), | |
6876 | Readline attempts to ring the terminal's bell. | |
6877 | ||
eb2bb562 CR |
6878 | `bind-tty-special-chars' |
6879 | If set to `on', Readline attempts to bind the control | |
6880 | characters treated specially by the kernel's terminal driver | |
6881 | to their Readline equivalents. | |
6882 | ||
abe2eb5b CR |
6883 | `colored-stats' |
6884 | If set to `on', Readline displays possible completions using | |
6885 | different colors to indicate their file type. The color | |
6886 | definitions are taken from the value of the `LS_COLORS' | |
6887 | environment variable. The default is `off'. | |
6888 | ||
ccc6cda3 JA |
6889 | `comment-begin' |
6890 | The string to insert at the beginning of the line when the | |
6891 | `insert-comment' command is executed. The default value is | |
6892 | `"#"'. | |
6893 | ||
eb0b2ad8 CR |
6894 | `completion-display-width' |
6895 | The number of screen columns used to display possible matches | |
6896 | when performing completion. The value is ignored if it is | |
6897 | less than 0 or greater than the terminal screen width. A | |
6898 | value of 0 will cause matches to be displayed one per line. | |
6899 | The default value is -1. | |
6900 | ||
cce855bc JA |
6901 | `completion-ignore-case' |
6902 | If set to `on', Readline performs filename matching and | |
6903 | completion in a case-insensitive fashion. The default value | |
6904 | is `off'. | |
6905 | ||
220537f2 CR |
6906 | `completion-map-case' |
6907 | If set to `on', and COMPLETION-IGNORE-CASE is enabled, | |
6908 | Readline treats hyphens (`-') and underscores (`_') as | |
6909 | equivalent when performing case-insensitive filename matching | |
6910 | and completion. | |
6911 | ||
ed35cb4a CR |
6912 | `completion-prefix-display-length' |
6913 | The length in characters of the common prefix of a list of | |
6914 | possible completions that is displayed without modification. | |
6915 | When set to a value greater than zero, common prefixes longer | |
6916 | than this value are replaced with an ellipsis when displaying | |
6917 | possible completions. | |
6918 | ||
ccc6cda3 JA |
6919 | `completion-query-items' |
6920 | The number of possible completions that determines when the | |
d3a24ed2 CR |
6921 | user is asked whether the list of possibilities should be |
6922 | displayed. If the number of possible completions is greater | |
6923 | than this value, Readline will ask the user whether or not he | |
6924 | wishes to view them; otherwise, they are simply listed. This | |
6925 | variable must be set to an integer value greater than or | |
1c72c0cd CR |
6926 | equal to 0. A negative value means Readline should never ask. |
6927 | The default limit is `100'. | |
ccc6cda3 JA |
6928 | |
6929 | `convert-meta' | |
6930 | If set to `on', Readline will convert characters with the | |
cce855bc | 6931 | eighth bit set to an ASCII key sequence by stripping the |
bb70624e | 6932 | eighth bit and prefixing an <ESC> character, converting them |
cce855bc | 6933 | to a meta-prefixed key sequence. The default value is `on'. |
ccc6cda3 JA |
6934 | |
6935 | `disable-completion' | |
cce855bc | 6936 | If set to `On', Readline will inhibit word completion. |
ccc6cda3 JA |
6937 | Completion characters will be inserted into the line as if |
6938 | they had been mapped to `self-insert'. The default is `off'. | |
6939 | ||
6940 | `editing-mode' | |
cce855bc JA |
6941 | The `editing-mode' variable controls which default set of key |
6942 | bindings is used. By default, Readline starts up in Emacs | |
6943 | editing mode, where the keystrokes are most similar to Emacs. | |
6944 | This variable can be set to either `emacs' or `vi'. | |
ccc6cda3 | 6945 | |
a8fd3f3e CR |
6946 | `echo-control-characters' |
6947 | When set to `on', on operating systems that indicate they | |
6948 | support it, readline echoes a character corresponding to a | |
6949 | signal generated from the keyboard. The default is `on'. | |
6950 | ||
ccc6cda3 | 6951 | `enable-keypad' |
cce855bc | 6952 | When set to `on', Readline will try to enable the application |
ccc6cda3 JA |
6953 | keypad when it is called. Some systems need this to enable |
6954 | the arrow keys. The default is `off'. | |
6955 | ||
d5362af8 CR |
6956 | `enable-meta-key' |
6957 | When set to `on', Readline will try to enable any meta | |
6958 | modifier key the terminal claims to support when it is | |
6959 | called. On many terminals, the meta key is used to send | |
6960 | eight-bit characters. The default is `on'. | |
6961 | ||
ccc6cda3 JA |
6962 | `expand-tilde' |
6963 | If set to `on', tilde expansion is performed when Readline | |
6964 | attempts word completion. The default is `off'. | |
6965 | ||
1c72c0cd | 6966 | `history-preserve-point' |
d7f49990 CR |
6967 | If set to `on', the history code attempts to place the point |
6968 | (the current cursor position) at the same location on each | |
6969 | history line retrieved with `previous-history' or | |
6970 | `next-history'. The default is `off'. | |
f73dda09 | 6971 | |
6a8fd0ed CR |
6972 | `history-size' |
6973 | Set the maximum number of history entries saved in the | |
6974 | history list. If set to zero, the number of entries in the | |
6975 | history list is not limited. | |
6976 | ||
ccc6cda3 JA |
6977 | `horizontal-scroll-mode' |
6978 | This variable can be set to either `on' or `off'. Setting it | |
cce855bc | 6979 | to `on' means that the text of the lines being edited will |
ccc6cda3 JA |
6980 | scroll horizontally on a single screen line when they are |
6981 | longer than the width of the screen, instead of wrapping onto | |
6982 | a new screen line. By default, this variable is set to `off'. | |
6983 | ||
b72432fd JA |
6984 | `input-meta' |
6985 | If set to `on', Readline will enable eight-bit input (it will | |
28ef6c31 | 6986 | not clear the eighth bit in the characters it reads), |
b72432fd JA |
6987 | regardless of what the terminal claims it can support. The |
6988 | default value is `off'. The name `meta-flag' is a synonym | |
6989 | for this variable. | |
6990 | ||
6991 | `isearch-terminators' | |
6992 | The string of characters that should terminate an incremental | |
6993 | search without subsequently executing the character as a | |
28ef6c31 JA |
6994 | command (*note Searching::). If this variable has not been |
6995 | given a value, the characters <ESC> and `C-J' will terminate | |
b72432fd JA |
6996 | an incremental search. |
6997 | ||
ccc6cda3 JA |
6998 | `keymap' |
6999 | Sets Readline's idea of the current keymap for key binding | |
7000 | commands. Acceptable `keymap' names are `emacs', | |
28ef6c31 | 7001 | `emacs-standard', `emacs-meta', `emacs-ctlx', `vi', `vi-move', |
ccc6cda3 JA |
7002 | `vi-command', and `vi-insert'. `vi' is equivalent to |
7003 | `vi-command'; `emacs' is equivalent to `emacs-standard'. The | |
7004 | default value is `emacs'. The value of the `editing-mode' | |
7005 | variable also affects the default keymap. | |
7006 | ||
7007 | `mark-directories' | |
7008 | If set to `on', completed directory names have a slash | |
7009 | appended. The default is `on'. | |
7010 | ||
7011 | `mark-modified-lines' | |
cce855bc JA |
7012 | This variable, when set to `on', causes Readline to display an |
7013 | asterisk (`*') at the start of history lines which have been | |
7014 | modified. This variable is `off' by default. | |
ccc6cda3 | 7015 | |
7117c2d2 JA |
7016 | `mark-symlinked-directories' |
7017 | If set to `on', completed names which are symbolic links to | |
7018 | directories have a slash appended (subject to the value of | |
7019 | `mark-directories'). The default is `off'. | |
7020 | ||
f73dda09 JA |
7021 | `match-hidden-files' |
7022 | This variable, when set to `on', causes Readline to match | |
7023 | files whose names begin with a `.' (hidden files) when | |
eb0b2ad8 CR |
7024 | performing filename completion. If set to `off', the leading |
7025 | `.' must be supplied by the user in the filename to be | |
7026 | completed. This variable is `on' by default. | |
f73dda09 | 7027 | |
e05be32d CR |
7028 | `menu-complete-display-prefix' |
7029 | If set to `on', menu completion displays the common prefix of | |
7030 | the list of possible completions (which may be empty) before | |
7031 | cycling through the list. The default is `off'. | |
7032 | ||
ccc6cda3 JA |
7033 | `output-meta' |
7034 | If set to `on', Readline will display characters with the | |
7035 | eighth bit set directly rather than as a meta-prefixed escape | |
7036 | sequence. The default is `off'. | |
7037 | ||
7117c2d2 JA |
7038 | `page-completions' |
7039 | If set to `on', Readline uses an internal `more'-like pager | |
7040 | to display a screenful of possible completions at a time. | |
7041 | This variable is `on' by default. | |
7042 | ||
cce855bc JA |
7043 | `print-completions-horizontally' |
7044 | If set to `on', Readline will display completions with matches | |
7045 | sorted horizontally in alphabetical order, rather than down | |
7046 | the screen. The default is `off'. | |
7047 | ||
ed35cb4a CR |
7048 | `revert-all-at-newline' |
7049 | If set to `on', Readline will undo all changes to history | |
7050 | lines before returning when `accept-line' is executed. By | |
7051 | default, history lines may be modified and retain individual | |
7052 | undo lists across calls to `readline'. The default is `off'. | |
7053 | ||
ccc6cda3 JA |
7054 | `show-all-if-ambiguous' |
7055 | This alters the default behavior of the completion functions. | |
7056 | If set to `on', words which have more than one possible | |
7057 | completion cause the matches to be listed immediately instead | |
7058 | of ringing the bell. The default value is `off'. | |
7059 | ||
d3a24ed2 CR |
7060 | `show-all-if-unmodified' |
7061 | This alters the default behavior of the completion functions | |
7062 | in a fashion similar to SHOW-ALL-IF-AMBIGUOUS. If set to | |
7063 | `on', words which have more than one possible completion | |
7064 | without any possible partial completion (the possible | |
7065 | completions don't share a common prefix) cause the matches to | |
7066 | be listed immediately instead of ringing the bell. The | |
7067 | default value is `off'. | |
7068 | ||
a8fd3f3e CR |
7069 | `skip-completed-text' |
7070 | If set to `on', this alters the default completion behavior | |
7071 | when inserting a single match into the line. It's only | |
7072 | active when performing completion in the middle of a word. | |
7073 | If enabled, readline does not insert characters from the | |
7074 | completion that match characters after point in the word | |
7075 | being completed, so portions of the word following the cursor | |
7076 | are not duplicated. For instance, if this is enabled, | |
7077 | attempting completion when the cursor is after the `e' in | |
7078 | `Makefile' will result in `Makefile' rather than | |
7079 | `Makefilefile', assuming there is a single possible | |
7080 | completion. The default value is `off'. | |
7081 | ||
ccc6cda3 JA |
7082 | `visible-stats' |
7083 | If set to `on', a character denoting a file's type is | |
7084 | appended to the filename when listing possible completions. | |
7085 | The default is `off'. | |
7086 | ||
761783bf | 7087 | |
ccc6cda3 JA |
7088 | Key Bindings |
7089 | The syntax for controlling key bindings in the init file is | |
bb70624e | 7090 | simple. First you need to find the name of the command that you |
cce855bc JA |
7091 | want to change. The following sections contain tables of the |
7092 | command name, the default keybinding, if any, and a short | |
7093 | description of what the command does. | |
ccc6cda3 | 7094 | |
28ef6c31 JA |
7095 | Once you know the name of the command, simply place on a line in |
7096 | the init file the name of the key you wish to bind the command to, | |
d3ad40de CR |
7097 | a colon, and then the name of the command. There can be no space |
7098 | between the key name and the colon - that will be interpreted as | |
7099 | part of the key name. The name of the key can be expressed in | |
7100 | different ways, depending on what you find most comfortable. | |
28ef6c31 JA |
7101 | |
7102 | In addition to command names, readline allows keys to be bound to | |
7103 | a string that is inserted when the key is pressed (a MACRO). | |
ccc6cda3 | 7104 | |
bb70624e JA |
7105 | The `bind -p' command displays Readline function names and |
7106 | bindings in a format that can put directly into an initialization | |
7107 | file. *Note Bash Builtins::. | |
7108 | ||
ccc6cda3 JA |
7109 | KEYNAME: FUNCTION-NAME or MACRO |
7110 | KEYNAME is the name of a key spelled out in English. For | |
7111 | example: | |
7112 | Control-u: universal-argument | |
7113 | Meta-Rubout: backward-kill-word | |
7114 | Control-o: "> output" | |
7115 | ||
28ef6c31 JA |
7116 | In the above example, `C-u' is bound to the function |
7117 | `universal-argument', `M-DEL' is bound to the function | |
7118 | `backward-kill-word', and `C-o' is bound to run the macro | |
ccc6cda3 JA |
7119 | expressed on the right hand side (that is, to insert the text |
7120 | `> output' into the line). | |
7121 | ||
28ef6c31 JA |
7122 | A number of symbolic character names are recognized while |
7123 | processing this key binding syntax: DEL, ESC, ESCAPE, LFD, | |
7124 | NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB. | |
7125 | ||
ccc6cda3 JA |
7126 | "KEYSEQ": FUNCTION-NAME or MACRO |
7127 | KEYSEQ differs from KEYNAME above in that strings denoting an | |
7128 | entire key sequence can be specified, by placing the key | |
7129 | sequence in double quotes. Some GNU Emacs style key escapes | |
7130 | can be used, as in the following example, but the special | |
7131 | character names are not recognized. | |
7132 | ||
7133 | "\C-u": universal-argument | |
7134 | "\C-x\C-r": re-read-init-file | |
7135 | "\e[11~": "Function Key 1" | |
7136 | ||
28ef6c31 | 7137 | In the above example, `C-u' is again bound to the function |
ccc6cda3 | 7138 | `universal-argument' (just as it was in the first example), |
28ef6c31 JA |
7139 | `C-x C-r' is bound to the function `re-read-init-file', and |
7140 | `<ESC> <[> <1> <1> <~>' is bound to insert the text `Function | |
7141 | Key 1'. | |
cce855bc | 7142 | |
761783bf | 7143 | |
cce855bc JA |
7144 | The following GNU Emacs style escape sequences are available when |
7145 | specifying key sequences: | |
7146 | ||
7147 | `\C-' | |
7148 | control prefix | |
7149 | ||
7150 | `\M-' | |
7151 | meta prefix | |
7152 | ||
7153 | `\e' | |
7154 | an escape character | |
7155 | ||
7156 | `\\' | |
7157 | backslash | |
7158 | ||
7159 | `\"' | |
bb70624e | 7160 | <">, a double quotation mark |
cce855bc JA |
7161 | |
7162 | `\'' | |
bb70624e | 7163 | <'>, a single quote or apostrophe |
cce855bc JA |
7164 | |
7165 | In addition to the GNU Emacs style escape sequences, a second set | |
7166 | of backslash escapes is available: | |
ccc6cda3 | 7167 | |
cce855bc JA |
7168 | `\a' |
7169 | alert (bell) | |
7170 | ||
7171 | `\b' | |
7172 | backspace | |
7173 | ||
7174 | `\d' | |
7175 | delete | |
7176 | ||
7177 | `\f' | |
7178 | form feed | |
7179 | ||
7180 | `\n' | |
7181 | newline | |
ccc6cda3 | 7182 | |
cce855bc JA |
7183 | `\r' |
7184 | carriage return | |
ccc6cda3 | 7185 | |
cce855bc JA |
7186 | `\t' |
7187 | horizontal tab | |
ccc6cda3 | 7188 | |
cce855bc JA |
7189 | `\v' |
7190 | vertical tab | |
ccc6cda3 | 7191 | |
cce855bc | 7192 | `\NNN' |
f73dda09 | 7193 | the eight-bit character whose value is the octal value NNN |
cce855bc | 7194 | (one to three digits) |
ccc6cda3 | 7195 | |
f73dda09 JA |
7196 | `\xHH' |
7197 | the eight-bit character whose value is the hexadecimal value | |
7198 | HH (one or two hex digits) | |
7199 | ||
cce855bc JA |
7200 | When entering the text of a macro, single or double quotes must be |
7201 | used to indicate a macro definition. Unquoted text is assumed to | |
7202 | be a function name. In the macro body, the backslash escapes | |
7203 | described above are expanded. Backslash will quote any other | |
7204 | character in the macro text, including `"' and `''. For example, | |
7205 | the following binding will make `C-x \' insert a single `\' into | |
7206 | the line: | |
7207 | "\C-x\\": "\\" | |
ccc6cda3 | 7208 | |
761783bf | 7209 | |
ccc6cda3 JA |
7210 | \1f |
7211 | File: bashref.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File | |
7212 | ||
37c41ab1 CR |
7213 | 8.3.2 Conditional Init Constructs |
7214 | --------------------------------- | |
ccc6cda3 | 7215 | |
37c41ab1 | 7216 | Readline implements a facility similar in spirit to the conditional |
ccc6cda3 JA |
7217 | compilation features of the C preprocessor which allows key bindings |
7218 | and variable settings to be performed as the result of tests. There | |
cce855bc | 7219 | are four parser directives used. |
ccc6cda3 JA |
7220 | |
7221 | `$if' | |
7222 | The `$if' construct allows bindings to be made based on the | |
7223 | editing mode, the terminal being used, or the application using | |
7224 | Readline. The text of the test extends to the end of the line; no | |
7225 | characters are required to isolate it. | |
7226 | ||
7227 | `mode' | |
7228 | The `mode=' form of the `$if' directive is used to test | |
7229 | whether Readline is in `emacs' or `vi' mode. This may be | |
7230 | used in conjunction with the `set keymap' command, for | |
7231 | instance, to set bindings in the `emacs-standard' and | |
7232 | `emacs-ctlx' keymaps only if Readline is starting out in | |
7233 | `emacs' mode. | |
7234 | ||
7235 | `term' | |
7236 | The `term=' form may be used to include terminal-specific key | |
7237 | bindings, perhaps to bind the key sequences output by the | |
7238 | terminal's function keys. The word on the right side of the | |
cce855bc JA |
7239 | `=' is tested against both the full name of the terminal and |
7240 | the portion of the terminal name before the first `-'. This | |
ccc6cda3 JA |
7241 | allows `sun' to match both `sun' and `sun-cmd', for instance. |
7242 | ||
7243 | `application' | |
7244 | The APPLICATION construct is used to include | |
7245 | application-specific settings. Each program using the | |
7246 | Readline library sets the APPLICATION NAME, and you can test | |
28ef6c31 JA |
7247 | for a particular value. This could be used to bind key |
7248 | sequences to functions useful for a specific program. For | |
7249 | instance, the following command adds a key sequence that | |
7250 | quotes the current or previous word in Bash: | |
ccc6cda3 JA |
7251 | $if Bash |
7252 | # Quote the current or previous word | |
7253 | "\C-xq": "\eb\"\ef\"" | |
7254 | $endif | |
7255 | ||
7256 | `$endif' | |
cce855bc JA |
7257 | This command, as seen in the previous example, terminates an `$if' |
7258 | command. | |
ccc6cda3 JA |
7259 | |
7260 | `$else' | |
7261 | Commands in this branch of the `$if' directive are executed if the | |
7262 | test fails. | |
7263 | ||
cce855bc JA |
7264 | `$include' |
7265 | This directive takes a single filename as an argument and reads | |
28ef6c31 JA |
7266 | commands and bindings from that file. For example, the following |
7267 | directive reads from `/etc/inputrc': | |
cce855bc JA |
7268 | $include /etc/inputrc |
7269 | ||
ccc6cda3 JA |
7270 | \1f |
7271 | File: bashref.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File | |
7272 | ||
37c41ab1 CR |
7273 | 8.3.3 Sample Init File |
7274 | ---------------------- | |
ccc6cda3 | 7275 | |
37c41ab1 CR |
7276 | Here is an example of an INPUTRC file. This illustrates key binding, |
7277 | variable assignment, and conditional syntax. | |
ccc6cda3 JA |
7278 | |
7279 | ||
7280 | # This file controls the behaviour of line input editing for | |
7117c2d2 JA |
7281 | # programs that use the GNU Readline library. Existing |
7282 | # programs include FTP, Bash, and GDB. | |
ccc6cda3 JA |
7283 | # |
7284 | # You can re-read the inputrc file with C-x C-r. | |
7285 | # Lines beginning with '#' are comments. | |
cce855bc | 7286 | # |
7117c2d2 JA |
7287 | # First, include any systemwide bindings and variable |
7288 | # assignments from /etc/Inputrc | |
cce855bc | 7289 | $include /etc/Inputrc |
37c41ab1 | 7290 | |
ccc6cda3 JA |
7291 | # |
7292 | # Set various bindings for emacs mode. | |
37c41ab1 | 7293 | |
ccc6cda3 | 7294 | set editing-mode emacs |
37c41ab1 | 7295 | |
ccc6cda3 | 7296 | $if mode=emacs |
37c41ab1 | 7297 | |
ccc6cda3 | 7298 | Meta-Control-h: backward-kill-word Text after the function name is ignored |
37c41ab1 | 7299 | |
ccc6cda3 JA |
7300 | # |
7301 | # Arrow keys in keypad mode | |
7302 | # | |
d166f048 JA |
7303 | #"\M-OD": backward-char |
7304 | #"\M-OC": forward-char | |
7305 | #"\M-OA": previous-history | |
7306 | #"\M-OB": next-history | |
ccc6cda3 JA |
7307 | # |
7308 | # Arrow keys in ANSI mode | |
7309 | # | |
d166f048 JA |
7310 | "\M-[D": backward-char |
7311 | "\M-[C": forward-char | |
7312 | "\M-[A": previous-history | |
7313 | "\M-[B": next-history | |
ccc6cda3 JA |
7314 | # |
7315 | # Arrow keys in 8 bit keypad mode | |
7316 | # | |
d166f048 JA |
7317 | #"\M-\C-OD": backward-char |
7318 | #"\M-\C-OC": forward-char | |
7319 | #"\M-\C-OA": previous-history | |
7320 | #"\M-\C-OB": next-history | |
ccc6cda3 JA |
7321 | # |
7322 | # Arrow keys in 8 bit ANSI mode | |
7323 | # | |
d166f048 JA |
7324 | #"\M-\C-[D": backward-char |
7325 | #"\M-\C-[C": forward-char | |
7326 | #"\M-\C-[A": previous-history | |
7327 | #"\M-\C-[B": next-history | |
37c41ab1 | 7328 | |
ccc6cda3 | 7329 | C-q: quoted-insert |
37c41ab1 | 7330 | |
ccc6cda3 | 7331 | $endif |
37c41ab1 | 7332 | |
ccc6cda3 JA |
7333 | # An old-style binding. This happens to be the default. |
7334 | TAB: complete | |
37c41ab1 | 7335 | |
ccc6cda3 JA |
7336 | # Macros that are convenient for shell interaction |
7337 | $if Bash | |
7338 | # edit the path | |
7339 | "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f" | |
7117c2d2 JA |
7340 | # prepare to type a quoted word -- |
7341 | # insert open and close double quotes | |
ccc6cda3 JA |
7342 | # and move to just after the open quote |
7343 | "\C-x\"": "\"\"\C-b" | |
7117c2d2 JA |
7344 | # insert a backslash (testing backslash escapes |
7345 | # in sequences and macros) | |
ccc6cda3 JA |
7346 | "\C-x\\": "\\" |
7347 | # Quote the current or previous word | |
7348 | "\C-xq": "\eb\"\ef\"" | |
7349 | # Add a binding to refresh the line, which is unbound | |
7350 | "\C-xr": redraw-current-line | |
7351 | # Edit variable on current line. | |
7352 | "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y=" | |
7353 | $endif | |
37c41ab1 | 7354 | |
ccc6cda3 JA |
7355 | # use a visible bell if one is available |
7356 | set bell-style visible | |
37c41ab1 | 7357 | |
ccc6cda3 JA |
7358 | # don't strip characters to 7 bits when reading |
7359 | set input-meta on | |
37c41ab1 | 7360 | |
7117c2d2 JA |
7361 | # allow iso-latin1 characters to be inserted rather |
7362 | # than converted to prefix-meta sequences | |
ccc6cda3 | 7363 | set convert-meta off |
37c41ab1 | 7364 | |
7117c2d2 JA |
7365 | # display characters with the eighth bit set directly |
7366 | # rather than as meta-prefixed characters | |
ccc6cda3 | 7367 | set output-meta on |
37c41ab1 | 7368 | |
7117c2d2 JA |
7369 | # if there are more than 150 possible completions for |
7370 | # a word, ask the user if he wants to see all of them | |
ccc6cda3 | 7371 | set completion-query-items 150 |
37c41ab1 | 7372 | |
ccc6cda3 JA |
7373 | # For FTP |
7374 | $if Ftp | |
7375 | "\C-xg": "get \M-?" | |
7376 | "\C-xt": "put \M-?" | |
7377 | "\M-.": yank-last-arg | |
7378 | $endif | |
7379 | ||
7380 | \1f | |
bb70624e JA |
7381 | File: bashref.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing |
7382 | ||
37c41ab1 CR |
7383 | 8.4 Bindable Readline Commands |
7384 | ============================== | |
bb70624e JA |
7385 | |
7386 | * Menu: | |
7387 | ||
7388 | * Commands For Moving:: Moving about the line. | |
7389 | * Commands For History:: Getting at previous lines. | |
7390 | * Commands For Text:: Commands for changing text. | |
7391 | * Commands For Killing:: Commands for killing and yanking. | |
7392 | * Numeric Arguments:: Specifying numeric arguments, repeat counts. | |
7393 | * Commands For Completion:: Getting Readline to do the typing for you. | |
7394 | * Keyboard Macros:: Saving and re-executing typed characters | |
7395 | * Miscellaneous Commands:: Other miscellaneous commands. | |
7396 | ||
7397 | This section describes Readline commands that may be bound to key | |
7398 | sequences. You can list your key bindings by executing `bind -P' or, | |
7399 | for a more terse format, suitable for an INPUTRC file, `bind -p'. | |
28ef6c31 JA |
7400 | (*Note Bash Builtins::.) Command names without an accompanying key |
7401 | sequence are unbound by default. | |
bb70624e | 7402 | |
28ef6c31 JA |
7403 | In the following descriptions, "point" refers to the current cursor |
7404 | position, and "mark" refers to a cursor position saved by the | |
bb70624e | 7405 | `set-mark' command. The text between the point and mark is referred to |
28ef6c31 | 7406 | as the "region". |
bb70624e JA |
7407 | |
7408 | \1f | |
7409 | File: bashref.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands | |
7410 | ||
37c41ab1 CR |
7411 | 8.4.1 Commands For Moving |
7412 | ------------------------- | |
bb70624e JA |
7413 | |
7414 | `beginning-of-line (C-a)' | |
7415 | Move to the start of the current line. | |
7416 | ||
7417 | `end-of-line (C-e)' | |
7418 | Move to the end of the line. | |
7419 | ||
7420 | `forward-char (C-f)' | |
7421 | Move forward a character. | |
7422 | ||
7423 | `backward-char (C-b)' | |
7424 | Move back a character. | |
7425 | ||
7426 | `forward-word (M-f)' | |
7427 | Move forward to the end of the next word. Words are composed of | |
7428 | letters and digits. | |
7429 | ||
7430 | `backward-word (M-b)' | |
7431 | Move back to the start of the current or previous word. Words are | |
7432 | composed of letters and digits. | |
7433 | ||
a9fac3b2 CR |
7434 | `shell-forward-word ()' |
7435 | Move forward to the end of the next word. Words are delimited by | |
7436 | non-quoted shell metacharacters. | |
7437 | ||
7438 | `shell-backward-word ()' | |
7439 | Move back to the start of the current or previous word. Words are | |
7440 | delimited by non-quoted shell metacharacters. | |
7441 | ||
bb70624e JA |
7442 | `clear-screen (C-l)' |
7443 | Clear the screen and redraw the current line, leaving the current | |
7444 | line at the top of the screen. | |
7445 | ||
7446 | `redraw-current-line ()' | |
7447 | Refresh the current line. By default, this is unbound. | |
7448 | ||
761783bf | 7449 | |
bb70624e JA |
7450 | \1f |
7451 | File: bashref.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands | |
7452 | ||
37c41ab1 CR |
7453 | 8.4.2 Commands For Manipulating The History |
7454 | ------------------------------------------- | |
bb70624e | 7455 | |
28ef6c31 | 7456 | `accept-line (Newline or Return)' |
bb70624e JA |
7457 | Accept the line regardless of where the cursor is. If this line is |
7458 | non-empty, add it to the history list according to the setting of | |
28ef6c31 JA |
7459 | the `HISTCONTROL' and `HISTIGNORE' variables. If this line is a |
7460 | modified history line, then restore the history line to its | |
7461 | original state. | |
bb70624e JA |
7462 | |
7463 | `previous-history (C-p)' | |
28ef6c31 JA |
7464 | Move `back' through the history list, fetching the previous |
7465 | command. | |
bb70624e JA |
7466 | |
7467 | `next-history (C-n)' | |
28ef6c31 | 7468 | Move `forward' through the history list, fetching the next command. |
bb70624e JA |
7469 | |
7470 | `beginning-of-history (M-<)' | |
7471 | Move to the first line in the history. | |
7472 | ||
7473 | `end-of-history (M->)' | |
7474 | Move to the end of the input history, i.e., the line currently | |
7475 | being entered. | |
7476 | ||
7477 | `reverse-search-history (C-r)' | |
7478 | Search backward starting at the current line and moving `up' | |
7479 | through the history as necessary. This is an incremental search. | |
7480 | ||
7481 | `forward-search-history (C-s)' | |
7482 | Search forward starting at the current line and moving `down' | |
7483 | through the the history as necessary. This is an incremental | |
7484 | search. | |
7485 | ||
7486 | `non-incremental-reverse-search-history (M-p)' | |
7487 | Search backward starting at the current line and moving `up' | |
7488 | through the history as necessary using a non-incremental search | |
7489 | for a string supplied by the user. | |
7490 | ||
7491 | `non-incremental-forward-search-history (M-n)' | |
7492 | Search forward starting at the current line and moving `down' | |
7493 | through the the history as necessary using a non-incremental search | |
7494 | for a string supplied by the user. | |
7495 | ||
7496 | `history-search-forward ()' | |
7497 | Search forward through the history for the string of characters | |
74d0116b CR |
7498 | between the start of the current line and the point. The search |
7499 | string must match at the beginning of a history line. This is a | |
bb70624e JA |
7500 | non-incremental search. By default, this command is unbound. |
7501 | ||
7502 | `history-search-backward ()' | |
7503 | Search backward through the history for the string of characters | |
74d0116b CR |
7504 | between the start of the current line and the point. The search |
7505 | string must match at the beginning of a history line. This is a | |
7506 | non-incremental search. By default, this command is unbound. | |
7507 | ||
7508 | `history-substr-search-forward ()' | |
7509 | Search forward through the history for the string of characters | |
7510 | between the start of the current line and the point. The search | |
7511 | string may match anywhere in a history line. This is a | |
7512 | non-incremental search. By default, this command is unbound. | |
7513 | ||
7514 | `history-substr-search-backward ()' | |
7515 | Search backward through the history for the string of characters | |
7516 | between the start of the current line and the point. The search | |
7517 | string may match anywhere in a history line. This is a | |
bb70624e JA |
7518 | non-incremental search. By default, this command is unbound. |
7519 | ||
7520 | `yank-nth-arg (M-C-y)' | |
7521 | Insert the first argument to the previous command (usually the | |
28ef6c31 JA |
7522 | second word on the previous line) at point. With an argument N, |
7523 | insert the Nth word from the previous command (the words in the | |
7524 | previous command begin with word 0). A negative argument inserts | |
eb2bb562 CR |
7525 | the Nth word from the end of the previous command. Once the |
7526 | argument N is computed, the argument is extracted as if the `!N' | |
7527 | history expansion had been specified. | |
bb70624e | 7528 | |
28ef6c31 | 7529 | `yank-last-arg (M-. or M-_)' |
bb70624e | 7530 | Insert last argument to the previous command (the last word of the |
510e20a2 CR |
7531 | previous history entry). With a numeric argument, behave exactly |
7532 | like `yank-nth-arg'. Successive calls to `yank-last-arg' move | |
7533 | back through the history list, inserting the last word (or the | |
7534 | word specified by the argument to the first call) of each line in | |
7535 | turn. Any numeric argument supplied to these successive calls | |
7536 | determines the direction to move through the history. A negative | |
7537 | argument switches the direction through the history (back or | |
7538 | forward). The history expansion facilities are used to extract | |
7539 | the last argument, as if the `!$' history expansion had been | |
7540 | specified. | |
bb70624e | 7541 | |
761783bf | 7542 | |
bb70624e JA |
7543 | \1f |
7544 | File: bashref.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands | |
7545 | ||
37c41ab1 CR |
7546 | 8.4.3 Commands For Changing Text |
7547 | -------------------------------- | |
bb70624e JA |
7548 | |
7549 | `delete-char (C-d)' | |
28ef6c31 JA |
7550 | Delete the character at point. If point is at the beginning of |
7551 | the line, there are no characters in the line, and the last | |
7552 | character typed was not bound to `delete-char', then return EOF. | |
bb70624e JA |
7553 | |
7554 | `backward-delete-char (Rubout)' | |
7555 | Delete the character behind the cursor. A numeric argument means | |
7556 | to kill the characters instead of deleting them. | |
7557 | ||
7558 | `forward-backward-delete-char ()' | |
7559 | Delete the character under the cursor, unless the cursor is at the | |
7560 | end of the line, in which case the character behind the cursor is | |
7561 | deleted. By default, this is not bound to a key. | |
7562 | ||
28ef6c31 | 7563 | `quoted-insert (C-q or C-v)' |
bb70624e | 7564 | Add the next character typed to the line verbatim. This is how to |
28ef6c31 | 7565 | insert key sequences like `C-q', for example. |
bb70624e JA |
7566 | |
7567 | `self-insert (a, b, A, 1, !, ...)' | |
7568 | Insert yourself. | |
7569 | ||
7570 | `transpose-chars (C-t)' | |
7571 | Drag the character before the cursor forward over the character at | |
7572 | the cursor, moving the cursor forward as well. If the insertion | |
7573 | point is at the end of the line, then this transposes the last two | |
7574 | characters of the line. Negative arguments have no effect. | |
7575 | ||
7576 | `transpose-words (M-t)' | |
7577 | Drag the word before point past the word after point, moving point | |
f73dda09 JA |
7578 | past that word as well. If the insertion point is at the end of |
7579 | the line, this transposes the last two words on the line. | |
bb70624e JA |
7580 | |
7581 | `upcase-word (M-u)' | |
7582 | Uppercase the current (or following) word. With a negative | |
7583 | argument, uppercase the previous word, but do not move the cursor. | |
7584 | ||
7585 | `downcase-word (M-l)' | |
7586 | Lowercase the current (or following) word. With a negative | |
7587 | argument, lowercase the previous word, but do not move the cursor. | |
7588 | ||
7589 | `capitalize-word (M-c)' | |
7590 | Capitalize the current (or following) word. With a negative | |
7591 | argument, capitalize the previous word, but do not move the cursor. | |
7592 | ||
7117c2d2 JA |
7593 | `overwrite-mode ()' |
7594 | Toggle overwrite mode. With an explicit positive numeric argument, | |
7595 | switches to overwrite mode. With an explicit non-positive numeric | |
7596 | argument, switches to insert mode. This command affects only | |
7597 | `emacs' mode; `vi' mode does overwrite differently. Each call to | |
7598 | `readline()' starts in insert mode. | |
7599 | ||
7600 | In overwrite mode, characters bound to `self-insert' replace the | |
7601 | text at point rather than pushing the text to the right. | |
7602 | Characters bound to `backward-delete-char' replace the character | |
7603 | before point with a space. | |
7604 | ||
7605 | By default, this command is unbound. | |
7606 | ||
761783bf | 7607 | |
bb70624e JA |
7608 | \1f |
7609 | File: bashref.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands | |
7610 | ||
37c41ab1 CR |
7611 | 8.4.4 Killing And Yanking |
7612 | ------------------------- | |
bb70624e JA |
7613 | |
7614 | `kill-line (C-k)' | |
7615 | Kill the text from point to the end of the line. | |
7616 | ||
7617 | `backward-kill-line (C-x Rubout)' | |
7618 | Kill backward to the beginning of the line. | |
7619 | ||
7620 | `unix-line-discard (C-u)' | |
7621 | Kill backward from the cursor to the beginning of the current line. | |
7622 | ||
7623 | `kill-whole-line ()' | |
28ef6c31 JA |
7624 | Kill all characters on the current line, no matter where point is. |
7625 | By default, this is unbound. | |
bb70624e JA |
7626 | |
7627 | `kill-word (M-d)' | |
7628 | Kill from point to the end of the current word, or if between | |
7629 | words, to the end of the next word. Word boundaries are the same | |
7630 | as `forward-word'. | |
7631 | ||
28ef6c31 | 7632 | `backward-kill-word (M-<DEL>)' |
bb70624e JA |
7633 | Kill the word behind point. Word boundaries are the same as |
7634 | `backward-word'. | |
7635 | ||
a9fac3b2 CR |
7636 | `shell-kill-word ()' |
7637 | Kill from point to the end of the current word, or if between | |
7638 | words, to the end of the next word. Word boundaries are the same | |
7639 | as `shell-forward-word'. | |
7640 | ||
06dff54a | 7641 | `shell-backward-kill-word ()' |
a9fac3b2 CR |
7642 | Kill the word behind point. Word boundaries are the same as |
7643 | `shell-backward-word'. | |
7644 | ||
bb70624e JA |
7645 | `unix-word-rubout (C-w)' |
7646 | Kill the word behind point, using white space as a word boundary. | |
7647 | The killed text is saved on the kill-ring. | |
7648 | ||
113d85a4 CR |
7649 | `unix-filename-rubout ()' |
7650 | Kill the word behind point, using white space and the slash | |
7651 | character as the word boundaries. The killed text is saved on the | |
7652 | kill-ring. | |
7653 | ||
bb70624e JA |
7654 | `delete-horizontal-space ()' |
7655 | Delete all spaces and tabs around point. By default, this is | |
7656 | unbound. | |
7657 | ||
7658 | `kill-region ()' | |
7659 | Kill the text in the current region. By default, this command is | |
7660 | unbound. | |
7661 | ||
7662 | `copy-region-as-kill ()' | |
7663 | Copy the text in the region to the kill buffer, so it can be yanked | |
7664 | right away. By default, this command is unbound. | |
7665 | ||
7666 | `copy-backward-word ()' | |
7667 | Copy the word before point to the kill buffer. The word | |
7668 | boundaries are the same as `backward-word'. By default, this | |
7669 | command is unbound. | |
7670 | ||
7671 | `copy-forward-word ()' | |
7672 | Copy the word following point to the kill buffer. The word | |
7673 | boundaries are the same as `forward-word'. By default, this | |
7674 | command is unbound. | |
7675 | ||
7676 | `yank (C-y)' | |
28ef6c31 | 7677 | Yank the top of the kill ring into the buffer at point. |
bb70624e JA |
7678 | |
7679 | `yank-pop (M-y)' | |
7680 | Rotate the kill-ring, and yank the new top. You can only do this | |
28ef6c31 | 7681 | if the prior command is `yank' or `yank-pop'. |
bb70624e JA |
7682 | |
7683 | \1f | |
7684 | File: bashref.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands | |
7685 | ||
37c41ab1 CR |
7686 | 8.4.5 Specifying Numeric Arguments |
7687 | ---------------------------------- | |
bb70624e JA |
7688 | |
7689 | `digit-argument (M-0, M-1, ... M--)' | |
7690 | Add this digit to the argument already accumulating, or start a new | |
28ef6c31 | 7691 | argument. `M--' starts a negative argument. |
bb70624e JA |
7692 | |
7693 | `universal-argument ()' | |
7694 | This is another way to specify an argument. If this command is | |
7695 | followed by one or more digits, optionally with a leading minus | |
7696 | sign, those digits define the argument. If the command is | |
7697 | followed by digits, executing `universal-argument' again ends the | |
7698 | numeric argument, but is otherwise ignored. As a special case, if | |
7699 | this command is immediately followed by a character that is | |
7700 | neither a digit or minus sign, the argument count for the next | |
7701 | command is multiplied by four. The argument count is initially | |
7702 | one, so executing this function the first time makes the argument | |
7703 | count four, a second time makes the argument count sixteen, and so | |
7704 | on. By default, this is not bound to a key. | |
7705 | ||
7706 | \1f | |
7707 | File: bashref.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands | |
7708 | ||
37c41ab1 CR |
7709 | 8.4.6 Letting Readline Type For You |
7710 | ----------------------------------- | |
bb70624e | 7711 | |
28ef6c31 JA |
7712 | `complete (<TAB>)' |
7713 | Attempt to perform completion on the text before point. The | |
7714 | actual completion performed is application-specific. Bash | |
7715 | attempts completion treating the text as a variable (if the text | |
7716 | begins with `$'), username (if the text begins with `~'), hostname | |
7717 | (if the text begins with `@'), or command (including aliases and | |
7718 | functions) in turn. If none of these produces a match, filename | |
7719 | completion is attempted. | |
bb70624e JA |
7720 | |
7721 | `possible-completions (M-?)' | |
eb0b2ad8 CR |
7722 | List the possible completions of the text before point. When |
7723 | displaying completions, Readline sets the number of columns used | |
7724 | for display to the value of `completion-display-width', the value | |
7725 | of the environment variable `COLUMNS', or the screen width, in | |
7726 | that order. | |
bb70624e JA |
7727 | |
7728 | `insert-completions (M-*)' | |
7729 | Insert all completions of the text before point that would have | |
7730 | been generated by `possible-completions'. | |
7731 | ||
7732 | `menu-complete ()' | |
7733 | Similar to `complete', but replaces the word to be completed with | |
7734 | a single match from the list of possible completions. Repeated | |
7735 | execution of `menu-complete' steps through the list of possible | |
7736 | completions, inserting each match in turn. At the end of the list | |
28ef6c31 JA |
7737 | of completions, the bell is rung (subject to the setting of |
7738 | `bell-style') and the original text is restored. An argument of N | |
7739 | moves N positions forward in the list of matches; a negative | |
7740 | argument may be used to move backward through the list. This | |
7741 | command is intended to be bound to <TAB>, but is unbound by | |
bb70624e JA |
7742 | default. |
7743 | ||
3eb2d94a CR |
7744 | `menu-complete-backward ()' |
7745 | Identical to `menu-complete', but moves backward through the list | |
7746 | of possible completions, as if `menu-complete' had been given a | |
7747 | negative argument. | |
7748 | ||
bb70624e JA |
7749 | `delete-char-or-list ()' |
7750 | Deletes the character under the cursor if not at the beginning or | |
7751 | end of the line (like `delete-char'). If at the end of the line, | |
7752 | behaves identically to `possible-completions'. This command is | |
7753 | unbound by default. | |
7754 | ||
7755 | `complete-filename (M-/)' | |
7756 | Attempt filename completion on the text before point. | |
7757 | ||
7758 | `possible-filename-completions (C-x /)' | |
7759 | List the possible completions of the text before point, treating | |
7760 | it as a filename. | |
7761 | ||
7762 | `complete-username (M-~)' | |
7763 | Attempt completion on the text before point, treating it as a | |
7764 | username. | |
7765 | ||
7766 | `possible-username-completions (C-x ~)' | |
7767 | List the possible completions of the text before point, treating | |
7768 | it as a username. | |
7769 | ||
7770 | `complete-variable (M-$)' | |
7771 | Attempt completion on the text before point, treating it as a | |
7772 | shell variable. | |
7773 | ||
7774 | `possible-variable-completions (C-x $)' | |
7775 | List the possible completions of the text before point, treating | |
7776 | it as a shell variable. | |
7777 | ||
7778 | `complete-hostname (M-@)' | |
7779 | Attempt completion on the text before point, treating it as a | |
7780 | hostname. | |
7781 | ||
7782 | `possible-hostname-completions (C-x @)' | |
7783 | List the possible completions of the text before point, treating | |
7784 | it as a hostname. | |
7785 | ||
7786 | `complete-command (M-!)' | |
7787 | Attempt completion on the text before point, treating it as a | |
7788 | command name. Command completion attempts to match the text | |
7789 | against aliases, reserved words, shell functions, shell builtins, | |
7790 | and finally executable filenames, in that order. | |
7791 | ||
7792 | `possible-command-completions (C-x !)' | |
7793 | List the possible completions of the text before point, treating | |
7794 | it as a command name. | |
7795 | ||
28ef6c31 | 7796 | `dynamic-complete-history (M-<TAB>)' |
bb70624e JA |
7797 | Attempt completion on the text before point, comparing the text |
7798 | against lines from the history list for possible completion | |
7799 | matches. | |
7800 | ||
ed35cb4a CR |
7801 | `dabbrev-expand ()' |
7802 | Attempt menu completion on the text before point, comparing the | |
7803 | text against lines from the history list for possible completion | |
7804 | matches. | |
7805 | ||
bb70624e JA |
7806 | `complete-into-braces (M-{)' |
7807 | Perform filename completion and insert the list of possible | |
7808 | completions enclosed within braces so the list is available to the | |
28ef6c31 | 7809 | shell (*note Brace Expansion::). |
bb70624e | 7810 | |
761783bf | 7811 | |
bb70624e JA |
7812 | \1f |
7813 | File: bashref.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands | |
7814 | ||
37c41ab1 CR |
7815 | 8.4.7 Keyboard Macros |
7816 | --------------------- | |
bb70624e JA |
7817 | |
7818 | `start-kbd-macro (C-x ()' | |
7819 | Begin saving the characters typed into the current keyboard macro. | |
7820 | ||
7821 | `end-kbd-macro (C-x ))' | |
7822 | Stop saving the characters typed into the current keyboard macro | |
7823 | and save the definition. | |
7824 | ||
7825 | `call-last-kbd-macro (C-x e)' | |
7826 | Re-execute the last keyboard macro defined, by making the | |
7827 | characters in the macro appear as if typed at the keyboard. | |
7828 | ||
45c0f7f8 CR |
7829 | `print-last-kbd-macro ()' |
7830 | Print the last keboard macro defined in a format suitable for the | |
7831 | INPUTRC file. | |
7832 | ||
761783bf | 7833 | |
bb70624e JA |
7834 | \1f |
7835 | File: bashref.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands | |
7836 | ||
37c41ab1 CR |
7837 | 8.4.8 Some Miscellaneous Commands |
7838 | --------------------------------- | |
bb70624e JA |
7839 | |
7840 | `re-read-init-file (C-x C-r)' | |
7841 | Read in the contents of the INPUTRC file, and incorporate any | |
7842 | bindings or variable assignments found there. | |
7843 | ||
7844 | `abort (C-g)' | |
7845 | Abort the current editing command and ring the terminal's bell | |
7846 | (subject to the setting of `bell-style'). | |
7847 | ||
7848 | `do-uppercase-version (M-a, M-b, M-X, ...)' | |
7849 | If the metafied character X is lowercase, run the command that is | |
7850 | bound to the corresponding uppercase character. | |
7851 | ||
28ef6c31 JA |
7852 | `prefix-meta (<ESC>)' |
7853 | Metafy the next character typed. This is for keyboards without a | |
7854 | meta key. Typing `<ESC> f' is equivalent to typing `M-f'. | |
bb70624e | 7855 | |
28ef6c31 | 7856 | `undo (C-_ or C-x C-u)' |
bb70624e JA |
7857 | Incremental undo, separately remembered for each line. |
7858 | ||
7859 | `revert-line (M-r)' | |
7860 | Undo all changes made to this line. This is like executing the | |
7861 | `undo' command enough times to get back to the beginning. | |
7862 | ||
7863 | `tilde-expand (M-&)' | |
7864 | Perform tilde expansion on the current word. | |
7865 | ||
7866 | `set-mark (C-@)' | |
28ef6c31 JA |
7867 | Set the mark to the point. If a numeric argument is supplied, the |
7868 | mark is set to that position. | |
bb70624e JA |
7869 | |
7870 | `exchange-point-and-mark (C-x C-x)' | |
7871 | Swap the point with the mark. The current cursor position is set | |
7872 | to the saved position, and the old cursor position is saved as the | |
7873 | mark. | |
7874 | ||
7875 | `character-search (C-])' | |
7876 | A character is read and point is moved to the next occurrence of | |
7877 | that character. A negative count searches for previous | |
7878 | occurrences. | |
7879 | ||
7880 | `character-search-backward (M-C-])' | |
7881 | A character is read and point is moved to the previous occurrence | |
7882 | of that character. A negative count searches for subsequent | |
7883 | occurrences. | |
7884 | ||
8f714a7c CR |
7885 | `skip-csi-sequence ()' |
7886 | Read enough characters to consume a multi-key sequence such as | |
7887 | those defined for keys like Home and End. Such sequences begin | |
7888 | with a Control Sequence Indicator (CSI), usually ESC-[. If this | |
7889 | sequence is bound to "\e[", keys producing such sequences will | |
7890 | have no effect unless explicitly bound to a readline command, | |
7891 | instead of inserting stray characters into the editing buffer. | |
7892 | This is unbound by default, but usually bound to ESC-[. | |
7893 | ||
bb70624e | 7894 | `insert-comment (M-#)' |
7117c2d2 JA |
7895 | Without a numeric argument, the value of the `comment-begin' |
7896 | variable is inserted at the beginning of the current line. If a | |
7897 | numeric argument is supplied, this command acts as a toggle: if | |
7898 | the characters at the beginning of the line do not match the value | |
7899 | of `comment-begin', the value is inserted, otherwise the | |
7900 | characters in `comment-begin' are deleted from the beginning of | |
7901 | the line. In either case, the line is accepted as if a newline | |
7902 | had been typed. The default value of `comment-begin' causes this | |
7903 | command to make the current line a shell comment. If a numeric | |
7904 | argument causes the comment character to be removed, the line will | |
7905 | be executed by the shell. | |
bb70624e JA |
7906 | |
7907 | `dump-functions ()' | |
7908 | Print all of the functions and their key bindings to the Readline | |
7909 | output stream. If a numeric argument is supplied, the output is | |
7910 | formatted in such a way that it can be made part of an INPUTRC | |
7911 | file. This command is unbound by default. | |
7912 | ||
7913 | `dump-variables ()' | |
7914 | Print all of the settable variables and their values to the | |
7915 | Readline output stream. If a numeric argument is supplied, the | |
7916 | output is formatted in such a way that it can be made part of an | |
7917 | INPUTRC file. This command is unbound by default. | |
7918 | ||
7919 | `dump-macros ()' | |
7920 | Print all of the Readline key sequences bound to macros and the | |
28ef6c31 JA |
7921 | strings they output. If a numeric argument is supplied, the |
7922 | output is formatted in such a way that it can be made part of an | |
7923 | INPUTRC file. This command is unbound by default. | |
bb70624e | 7924 | |
7117c2d2 JA |
7925 | `glob-complete-word (M-g)' |
7926 | The word before point is treated as a pattern for pathname | |
7927 | expansion, with an asterisk implicitly appended. This pattern is | |
7928 | used to generate a list of matching file names for possible | |
7929 | completions. | |
7930 | ||
bb70624e JA |
7931 | `glob-expand-word (C-x *)' |
7932 | The word before point is treated as a pattern for pathname | |
7933 | expansion, and the list of matching file names is inserted, | |
7117c2d2 JA |
7934 | replacing the word. If a numeric argument is supplied, a `*' is |
7935 | appended before pathname expansion. | |
bb70624e JA |
7936 | |
7937 | `glob-list-expansions (C-x g)' | |
7938 | The list of expansions that would have been generated by | |
7117c2d2 JA |
7939 | `glob-expand-word' is displayed, and the line is redrawn. If a |
7940 | numeric argument is supplied, a `*' is appended before pathname | |
7941 | expansion. | |
bb70624e JA |
7942 | |
7943 | `display-shell-version (C-x C-v)' | |
7944 | Display version information about the current instance of Bash. | |
7945 | ||
7946 | `shell-expand-line (M-C-e)' | |
7947 | Expand the line as the shell does. This performs alias and | |
7948 | history expansion as well as all of the shell word expansions | |
28ef6c31 | 7949 | (*note Shell Expansions::). |
bb70624e JA |
7950 | |
7951 | `history-expand-line (M-^)' | |
7952 | Perform history expansion on the current line. | |
7953 | ||
7954 | `magic-space ()' | |
7955 | Perform history expansion on the current line and insert a space | |
28ef6c31 | 7956 | (*note History Interaction::). |
bb70624e JA |
7957 | |
7958 | `alias-expand-line ()' | |
28ef6c31 | 7959 | Perform alias expansion on the current line (*note Aliases::). |
bb70624e JA |
7960 | |
7961 | `history-and-alias-expand-line ()' | |
7962 | Perform history and alias expansion on the current line. | |
7963 | ||
28ef6c31 | 7964 | `insert-last-argument (M-. or M-_)' |
bb70624e JA |
7965 | A synonym for `yank-last-arg'. |
7966 | ||
7967 | `operate-and-get-next (C-o)' | |
7968 | Accept the current line for execution and fetch the next line | |
7969 | relative to the current line from the history for editing. Any | |
7970 | argument is ignored. | |
7971 | ||
7117c2d2 JA |
7972 | `edit-and-execute-command (C-xC-e)' |
7973 | Invoke an editor on the current command line, and execute the | |
c2258e1c | 7974 | result as shell commands. Bash attempts to invoke `$VISUAL', |
7117c2d2 | 7975 | `$EDITOR', and `emacs' as the editor, in that order. |
bb70624e | 7976 | |
761783bf | 7977 | |
bb70624e JA |
7978 | \1f |
7979 | File: bashref.info, Node: Readline vi Mode, Next: Programmable Completion, Prev: Bindable Readline Commands, Up: Command Line Editing | |
7980 | ||
37c41ab1 CR |
7981 | 8.5 Readline vi Mode |
7982 | ==================== | |
bb70624e | 7983 | |
37c41ab1 | 7984 | While the Readline library does not have a full set of `vi' editing |
bb70624e | 7985 | functions, it does contain enough to allow simple editing of the line. |
eb0b2ad8 | 7986 | The Readline `vi' mode behaves as specified in the POSIX standard. |
bb70624e JA |
7987 | |
7988 | In order to switch interactively between `emacs' and `vi' editing | |
7989 | modes, use the `set -o emacs' and `set -o vi' commands (*note The Set | |
28ef6c31 | 7990 | Builtin::). The Readline default is `emacs' mode. |
bb70624e JA |
7991 | |
7992 | When you enter a line in `vi' mode, you are already placed in | |
7993 | `insertion' mode, as if you had typed an `i'. Pressing <ESC> switches | |
7994 | you into `command' mode, where you can edit the text of the line with | |
7995 | the standard `vi' movement keys, move to previous history lines with | |
7996 | `k' and subsequent lines with `j', and so forth. | |
7997 | ||
7998 | \1f | |
7999 | File: bashref.info, Node: Programmable Completion, Next: Programmable Completion Builtins, Prev: Readline vi Mode, Up: Command Line Editing | |
8000 | ||
37c41ab1 CR |
8001 | 8.6 Programmable Completion |
8002 | =========================== | |
bb70624e | 8003 | |
37c41ab1 | 8004 | When word completion is attempted for an argument to a command for |
bb70624e | 8005 | which a completion specification (a COMPSPEC) has been defined using |
28ef6c31 | 8006 | the `complete' builtin (*note Programmable Completion Builtins::), the |
bb70624e JA |
8007 | programmable completion facilities are invoked. |
8008 | ||
8009 | First, the command name is identified. If a compspec has been | |
8010 | defined for that command, the compspec is used to generate the list of | |
8f714a7c CR |
8011 | possible completions for the word. If the command word is the empty |
8012 | string (completion attempted at the beginning of an empty line), any | |
8013 | compspec defined with the `-E' option to `complete' is used. If the | |
8014 | command word is a full pathname, a compspec for the full pathname is | |
8015 | searched for first. If no compspec is found for the full pathname, an | |
8016 | attempt is made to find a compspec for the portion following the final | |
8017 | slash. If those searches do not result in a compspec, any compspec | |
8018 | defined with the `-D' option to `complete' is used as the default. | |
bb70624e JA |
8019 | |
8020 | Once a compspec has been found, it is used to generate the list of | |
8021 | matching words. If a compspec is not found, the default Bash completion | |
28ef6c31 | 8022 | described above (*note Commands For Completion::) is performed. |
bb70624e JA |
8023 | |
8024 | First, the actions specified by the compspec are used. Only matches | |
8025 | which are prefixed by the word being completed are returned. When the | |
8026 | `-f' or `-d' option is used for filename or directory name completion, | |
8027 | the shell variable `FIGNORE' is used to filter the matches. *Note Bash | |
8028 | Variables::, for a description of `FIGNORE'. | |
8029 | ||
8030 | Any completions specified by a filename expansion pattern to the | |
8031 | `-G' option are generated next. The words generated by the pattern | |
8032 | need not match the word being completed. The `GLOBIGNORE' shell | |
8033 | variable is not used to filter the matches, but the `FIGNORE' shell | |
8034 | variable is used. | |
8035 | ||
8036 | Next, the string specified as the argument to the `-W' option is | |
8037 | considered. The string is first split using the characters in the `IFS' | |
8038 | special variable as delimiters. Shell quoting is honored. Each word | |
8039 | is then expanded using brace expansion, tilde expansion, parameter and | |
2206f89a CR |
8040 | variable expansion, command substitution, and arithmetic expansion, as |
8041 | described above (*note Shell Expansions::). The results are split | |
8042 | using the rules described above (*note Word Splitting::). The results | |
8043 | of the expansion are prefix-matched against the word being completed, | |
8044 | and the matching words become the possible completions. | |
bb70624e JA |
8045 | |
8046 | After these matches have been generated, any shell function or | |
8047 | command specified with the `-F' and `-C' options is invoked. When the | |
d3ad40de CR |
8048 | command or function is invoked, the `COMP_LINE', `COMP_POINT', |
8049 | `COMP_KEY', and `COMP_TYPE' variables are assigned values as described | |
8050 | above (*note Bash Variables::). If a shell function is being invoked, | |
8051 | the `COMP_WORDS' and `COMP_CWORD' variables are also set. When the | |
45c0f7f8 CR |
8052 | function or command is invoked, the first argument ($1) is the name of |
8053 | the command whose arguments are being completed, the second argument | |
8054 | ($2) is the word being completed, and the third argument ($3) is the | |
8055 | word preceding the word being completed on the current command line. | |
8056 | No filtering of the generated completions against the word being | |
8057 | completed is performed; the function or command has complete freedom in | |
8058 | generating the matches. | |
bb70624e JA |
8059 | |
8060 | Any function specified with `-F' is invoked first. The function may | |
6a8fd0ed CR |
8061 | use any of the shell facilities, including the `compgen' and `compopt' |
8062 | builtins described below (*note Programmable Completion Builtins::), to | |
8063 | generate the matches. It must put the possible completions in the | |
45c0f7f8 | 8064 | `COMPREPLY' array variable, one per array element. |
bb70624e JA |
8065 | |
8066 | Next, any command specified with the `-C' option is invoked in an | |
8067 | environment equivalent to command substitution. It should print a list | |
8068 | of completions, one per line, to the standard output. Backslash may be | |
8069 | used to escape a newline, if necessary. | |
8070 | ||
8071 | After all of the possible completions are generated, any filter | |
8072 | specified with the `-X' option is applied to the list. The filter is a | |
8073 | pattern as used for pathname expansion; a `&' in the pattern is | |
8074 | replaced with the text of the word being completed. A literal `&' may | |
8075 | be escaped with a backslash; the backslash is removed before attempting | |
8076 | a match. Any completion that matches the pattern will be removed from | |
8077 | the list. A leading `!' negates the pattern; in this case any | |
8078 | completion not matching the pattern will be removed. | |
8079 | ||
8080 | Finally, any prefix and suffix specified with the `-P' and `-S' | |
8081 | options are added to each member of the completion list, and the result | |
8082 | is returned to the Readline completion code as the list of possible | |
8083 | completions. | |
8084 | ||
28ef6c31 JA |
8085 | If the previously-applied actions do not generate any matches, and |
8086 | the `-o dirnames' option was supplied to `complete' when the compspec | |
8087 | was defined, directory name completion is attempted. | |
8088 | ||
d3a24ed2 CR |
8089 | If the `-o plusdirs' option was supplied to `complete' when the |
8090 | compspec was defined, directory name completion is attempted and any | |
8091 | matches are added to the results of the other actions. | |
8092 | ||
28ef6c31 JA |
8093 | By default, if a compspec is found, whatever it generates is |
8094 | returned to the completion code as the full set of possible completions. | |
8095 | The default Bash completions are not attempted, and the Readline default | |
d3a24ed2 CR |
8096 | of filename completion is disabled. If the `-o bashdefault' option was |
8097 | supplied to `complete' when the compspec was defined, the default Bash | |
8098 | completions are attempted if the compspec generates no matches. If the | |
8099 | `-o default' option was supplied to `complete' when the compspec was | |
8100 | defined, Readline's default completion will be performed if the | |
8101 | compspec (and, if attempted, the default Bash completions) generate no | |
28ef6c31 | 8102 | matches. |
bb70624e | 8103 | |
7117c2d2 JA |
8104 | When a compspec indicates that directory name completion is desired, |
8105 | the programmable completion functions force Readline to append a slash | |
8106 | to completed names which are symbolic links to directories, subject to | |
8107 | the value of the MARK-DIRECTORIES Readline variable, regardless of the | |
8108 | setting of the MARK-SYMLINKED-DIRECTORIES Readline variable. | |
8109 | ||
8f714a7c CR |
8110 | There is some support for dynamically modifying completions. This is |
8111 | most useful when used in combination with a default completion specified | |
8112 | with `-D'. It's possible for shell functions executed as completion | |
8113 | handlers to indicate that completion should be retried by returning an | |
8114 | exit status of 124. If a shell function returns 124, and changes the | |
8115 | compspec associated with the command on which completion is being | |
8116 | attempted (supplied as the first argument when the function is | |
8117 | executed), programmable completion restarts from the beginning, with an | |
eb0b2ad8 | 8118 | attempt to find a new compspec for that command. This allows a set of |
8f714a7c CR |
8119 | completions to be built dynamically as completion is attempted, rather |
8120 | than being loaded all at once. | |
8121 | ||
8122 | For instance, assuming that there is a library of compspecs, each | |
8123 | kept in a file corresponding to the name of the command, the following | |
8124 | default completion function would load completions dynamically: | |
8125 | ||
8126 | _completion_loader() | |
8127 | { | |
45c0f7f8 | 8128 | . "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124 |
8f714a7c CR |
8129 | } |
8130 | complete -D -F _completion_loader | |
8131 | ||
bb70624e | 8132 | \1f |
45c0f7f8 | 8133 | File: bashref.info, Node: Programmable Completion Builtins, Next: A Programmable Completion Example, Prev: Programmable Completion, Up: Command Line Editing |
bb70624e | 8134 | |
37c41ab1 CR |
8135 | 8.7 Programmable Completion Builtins |
8136 | ==================================== | |
bb70624e | 8137 | |
45c0f7f8 CR |
8138 | Three builtin commands are available to manipulate the programmable |
8139 | completion facilities: one to specify how the arguments to a particular | |
8140 | command are to be completed, and two to modify the completion as it is | |
8141 | happening. | |
bb70624e JA |
8142 | |
8143 | `compgen' | |
8144 | `compgen [OPTION] [WORD]' | |
8145 | ||
8146 | Generate possible completion matches for WORD according to the | |
8147 | OPTIONs, which may be any option accepted by the `complete' | |
8148 | builtin with the exception of `-p' and `-r', and write the matches | |
8149 | to the standard output. When using the `-F' or `-C' options, the | |
8150 | various shell variables set by the programmable completion | |
8151 | facilities, while available, will not have useful values. | |
8152 | ||
8153 | The matches will be generated in the same way as if the | |
8154 | programmable completion code had generated them directly from a | |
8155 | completion specification with the same flags. If WORD is | |
8156 | specified, only those completions matching WORD will be displayed. | |
8157 | ||
8158 | The return value is true unless an invalid option is supplied, or | |
8159 | no matches were generated. | |
8160 | ||
8161 | `complete' | |
3eb2d94a | 8162 | `complete [-abcdefgjksuv] [-o COMP-OPTION] [-DE] [-A ACTION] [-G GLOBPAT] [-W WORDLIST] |
d3ad40de CR |
8163 | [-F FUNCTION] [-C COMMAND] [-X FILTERPAT] |
8164 | [-P PREFIX] [-S SUFFIX] NAME [NAME ...]' | |
3eb2d94a | 8165 | `complete -pr [-DE] [NAME ...]' |
bb70624e JA |
8166 | |
8167 | Specify how arguments to each NAME should be completed. If the | |
8168 | `-p' option is supplied, or if no options are supplied, existing | |
8169 | completion specifications are printed in a way that allows them to | |
8170 | be reused as input. The `-r' option removes a completion | |
8171 | specification for each NAME, or, if no NAMEs are supplied, all | |
3eb2d94a CR |
8172 | completion specifications. The `-D' option indicates that the |
8173 | remaining options and actions should apply to the "default" | |
8174 | command completion; that is, completion attempted on a command for | |
8175 | which no completion has previously been defined. The `-E' option | |
8176 | indicates that the remaining options and actions should apply to | |
8177 | "empty" command completion; that is, completion attempted on a | |
8178 | blank line. | |
bb70624e JA |
8179 | |
8180 | The process of applying these completion specifications when word | |
8181 | completion is attempted is described above (*note Programmable | |
8f714a7c | 8182 | Completion::). The `-D' option takes precedence over `-E'. |
bb70624e JA |
8183 | |
8184 | Other options, if specified, have the following meanings. The | |
8185 | arguments to the `-G', `-W', and `-X' options (and, if necessary, | |
8186 | the `-P' and `-S' options) should be quoted to protect them from | |
8187 | expansion before the `complete' builtin is invoked. | |
8188 | ||
28ef6c31 JA |
8189 | `-o COMP-OPTION' |
8190 | The COMP-OPTION controls several aspects of the compspec's | |
8191 | behavior beyond the simple generation of completions. | |
8192 | COMP-OPTION may be one of: | |
8193 | ||
d3a24ed2 CR |
8194 | `bashdefault' |
8195 | Perform the rest of the default Bash completions if the | |
8196 | compspec generates no matches. | |
8197 | ||
28ef6c31 | 8198 | `default' |
7117c2d2 JA |
8199 | Use Readline's default filename completion if the |
8200 | compspec generates no matches. | |
28ef6c31 JA |
8201 | |
8202 | `dirnames' | |
8203 | Perform directory name completion if the compspec | |
8204 | generates no matches. | |
8205 | ||
8206 | `filenames' | |
8207 | Tell Readline that the compspec generates filenames, so | |
d3a24ed2 | 8208 | it can perform any filename-specific processing (like |
a9fac3b2 CR |
8209 | adding a slash to directory names quoting special |
8210 | characters, or suppressing trailing spaces). This | |
8211 | option is intended to be used with shell functions | |
8212 | specified with `-F'. | |
28ef6c31 | 8213 | |
45c0f7f8 CR |
8214 | `noquote' |
8215 | Tell Readline not to quote the completed words if they | |
8216 | are filenames (quoting filenames is the default). | |
8217 | ||
7117c2d2 JA |
8218 | `nospace' |
8219 | Tell Readline not to append a space (the default) to | |
8220 | words completed at the end of the line. | |
8221 | ||
22e63b05 CR |
8222 | `plusdirs' |
8223 | After any matches defined by the compspec are generated, | |
8224 | directory name completion is attempted and any matches | |
8225 | are added to the results of the other actions. | |
8226 | ||
8227 | ||
bb70624e JA |
8228 | `-A ACTION' |
8229 | The ACTION may be one of the following to generate a list of | |
8230 | possible completions: | |
8231 | ||
8232 | `alias' | |
8233 | Alias names. May also be specified as `-a'. | |
8234 | ||
8235 | `arrayvar' | |
8236 | Array variable names. | |
8237 | ||
8238 | `binding' | |
8239 | Readline key binding names (*note Bindable Readline | |
28ef6c31 | 8240 | Commands::). |
bb70624e JA |
8241 | |
8242 | `builtin' | |
8243 | Names of shell builtin commands. May also be specified | |
8244 | as `-b'. | |
8245 | ||
8246 | `command' | |
8247 | Command names. May also be specified as `-c'. | |
8248 | ||
8249 | `directory' | |
8250 | Directory names. May also be specified as `-d'. | |
8251 | ||
8252 | `disabled' | |
8253 | Names of disabled shell builtins. | |
8254 | ||
8255 | `enabled' | |
8256 | Names of enabled shell builtins. | |
8257 | ||
8258 | `export' | |
8259 | Names of exported shell variables. May also be | |
8260 | specified as `-e'. | |
8261 | ||
8262 | `file' | |
8263 | File names. May also be specified as `-f'. | |
8264 | ||
8265 | `function' | |
8266 | Names of shell functions. | |
8267 | ||
f73dda09 JA |
8268 | `group' |
8269 | Group names. May also be specified as `-g'. | |
8270 | ||
bb70624e JA |
8271 | `helptopic' |
8272 | Help topics as accepted by the `help' builtin (*note | |
28ef6c31 | 8273 | Bash Builtins::). |
bb70624e JA |
8274 | |
8275 | `hostname' | |
8276 | Hostnames, as taken from the file specified by the | |
28ef6c31 | 8277 | `HOSTFILE' shell variable (*note Bash Variables::). |
bb70624e JA |
8278 | |
8279 | `job' | |
8280 | Job names, if job control is active. May also be | |
8281 | specified as `-j'. | |
8282 | ||
8283 | `keyword' | |
8284 | Shell reserved words. May also be specified as `-k'. | |
8285 | ||
8286 | `running' | |
8287 | Names of running jobs, if job control is active. | |
8288 | ||
7117c2d2 JA |
8289 | `service' |
8290 | Service names. May also be specified as `-s'. | |
8291 | ||
bb70624e JA |
8292 | `setopt' |
8293 | Valid arguments for the `-o' option to the `set' builtin | |
28ef6c31 | 8294 | (*note The Set Builtin::). |
bb70624e JA |
8295 | |
8296 | `shopt' | |
8297 | Shell option names as accepted by the `shopt' builtin | |
28ef6c31 | 8298 | (*note Bash Builtins::). |
bb70624e JA |
8299 | |
8300 | `signal' | |
8301 | Signal names. | |
8302 | ||
8303 | `stopped' | |
8304 | Names of stopped jobs, if job control is active. | |
8305 | ||
8306 | `user' | |
8307 | User names. May also be specified as `-u'. | |
8308 | ||
8309 | `variable' | |
8310 | Names of all shell variables. May also be specified as | |
8311 | `-v'. | |
8312 | ||
bb70624e JA |
8313 | `-C COMMAND' |
8314 | COMMAND is executed in a subshell environment, and its output | |
8315 | is used as the possible completions. | |
8316 | ||
8317 | `-F FUNCTION' | |
8318 | The shell function FUNCTION is executed in the current shell | |
45c0f7f8 CR |
8319 | environment. When it is executed, $1 is the name of the |
8320 | command whose arguments are being completed, $2 is the word | |
8321 | being completed, and $3 is the word preceding the word being | |
8322 | completed, as described above (*note Programmable | |
8323 | Completion::). When it finishes, the possible completions | |
8324 | are retrieved from the value of the `COMPREPLY' array | |
8325 | variable. | |
bb70624e | 8326 | |
5cdaaf76 CR |
8327 | `-G GLOBPAT' |
8328 | The filename expansion pattern GLOBPAT is expanded to generate | |
8329 | the possible completions. | |
bb70624e JA |
8330 | |
8331 | `-P PREFIX' | |
8332 | PREFIX is added at the beginning of each possible completion | |
8333 | after all other options have been applied. | |
8334 | ||
8335 | `-S SUFFIX' | |
8336 | SUFFIX is appended to each possible completion after all | |
8337 | other options have been applied. | |
8338 | ||
5cdaaf76 CR |
8339 | `-W WORDLIST' |
8340 | The WORDLIST is split using the characters in the `IFS' | |
8341 | special variable as delimiters, and each resultant word is | |
8342 | expanded. The possible completions are the members of the | |
8343 | resultant list which match the word being completed. | |
8344 | ||
8345 | `-X FILTERPAT' | |
8346 | FILTERPAT is a pattern as used for filename expansion. It is | |
8347 | applied to the list of possible completions generated by the | |
8348 | preceding options and arguments, and each completion matching | |
8349 | FILTERPAT is removed from the list. A leading `!' in | |
8350 | FILTERPAT negates the pattern; in this case, any completion | |
8351 | not matching FILTERPAT is removed. | |
8352 | ||
bb70624e JA |
8353 | The return value is true unless an invalid option is supplied, an |
8354 | option other than `-p' or `-r' is supplied without a NAME | |
8355 | argument, an attempt is made to remove a completion specification | |
8356 | for a NAME for which no specification exists, or an error occurs | |
8357 | adding a completion specification. | |
8358 | ||
6a8fd0ed | 8359 | `compopt' |
3eb2d94a | 8360 | `compopt' [-o OPTION] [-DE] [+o OPTION] [NAME] |
6a8fd0ed | 8361 | Modify completion options for each NAME according to the OPTIONs, |
5cdaaf76 | 8362 | or for the currently-executing completion if no NAMEs are supplied. |
6a8fd0ed CR |
8363 | If no OPTIONs are given, display the completion options for each |
8364 | NAME or the current completion. The possible values of OPTION are | |
3eb2d94a CR |
8365 | those valid for the `complete' builtin described above. The `-D' |
8366 | option indicates that the remaining options should apply to the | |
8367 | "default" command completion; that is, completion attempted on a | |
8368 | command for which no completion has previously been defined. The | |
8369 | `-E' option indicates that the remaining options should apply to | |
8370 | "empty" command completion; that is, completion attempted on a | |
8371 | blank line. | |
6a8fd0ed | 8372 | |
8f714a7c CR |
8373 | The `-D' option takes precedence over `-E'. |
8374 | ||
6a8fd0ed CR |
8375 | The return value is true unless an invalid option is supplied, an |
8376 | attempt is made to modify the options for a NAME for which no | |
8377 | completion specification exists, or an output error occurs. | |
8378 | ||
8379 | ||
45c0f7f8 CR |
8380 | \1f |
8381 | File: bashref.info, Node: A Programmable Completion Example, Prev: Programmable Completion Builtins, Up: Command Line Editing | |
8382 | ||
8383 | 8.8 A Programmable Completion Example | |
8384 | ===================================== | |
8385 | ||
8386 | The most common way to obtain additional completion functionality beyond | |
8387 | the default actions `complete' and `compgen' provide is to use a shell | |
8388 | function and bind it to a particular command using `complete -F'. | |
8389 | ||
8390 | The following function provides completions for the `cd' builtin. | |
8391 | It is a reasonably good example of what shell functions must do when | |
8392 | used for completion. This function uses the word passsed as `$2' to | |
8393 | determine the directory name to complete. You can also use the | |
8394 | `COMP_WORDS' array variable; the current word is indexed by the | |
8395 | `COMP_CWORD' variable. | |
8396 | ||
8397 | The function relies on the `complete' and `compgen' builtins to do | |
8398 | much of the work, adding only the things that the Bash `cd' does beyond | |
8399 | accepting basic directory names: tilde expansion (*note Tilde | |
8400 | Expansion::), searching directories in $CDPATH, which is described above | |
8401 | (*note Bourne Shell Builtins::), and basic support for the | |
8402 | `cdable_vars' shell option (*note The Shopt Builtin::). `_comp_cd' | |
8403 | modifies the value of IFS so that it contains only a newline to | |
8404 | accommodate file names containing spaces and tabs - `compgen' prints | |
8405 | the possible completions it generates one per line. | |
8406 | ||
8407 | Possible completions go into the COMPREPLY array variable, one | |
8408 | completion per array element. The programmable completion system | |
8409 | retrieves the completions from there when the function returns. | |
8410 | ||
8411 | # A completion function for the cd builtin | |
8412 | # based on the cd completion function from the bash_completion package | |
8413 | _comp_cd() | |
8414 | { | |
8415 | local IFS=$' \t\n' # normalize IFS | |
8416 | local cur _skipdot _cdpath | |
8417 | local i j k | |
8418 | ||
8419 | # Tilde expansion, with side effect of expanding tilde to full pathname | |
8420 | case "$2" in | |
8421 | \~*) eval cur="$2" ;; | |
8422 | *) cur=$2 ;; | |
8423 | esac | |
8424 | ||
8425 | # no cdpath or absolute pathname -- straight directory completion | |
8426 | if [[ -z "${CDPATH:-}" ]] || [[ "$cur" == @(./*|../*|/*) ]]; then | |
8427 | # compgen prints paths one per line; could also use while loop | |
8428 | IFS=$'\n' | |
8429 | COMPREPLY=( $(compgen -d -- "$cur") ) | |
8430 | IFS=$' \t\n' | |
8431 | # CDPATH+directories in the current directory if not in CDPATH | |
8432 | else | |
8433 | IFS=$'\n' | |
8434 | _skipdot=false | |
8435 | # preprocess CDPATH to convert null directory names to . | |
8436 | _cdpath=${CDPATH/#:/.:} | |
8437 | _cdpath=${_cdpath//::/:.:} | |
8438 | _cdpath=${_cdpath/%:/:.} | |
8439 | for i in ${_cdpath//:/$'\n'}; do | |
8440 | if [[ $i -ef . ]]; then _skipdot=true; fi | |
8441 | k="${#COMPREPLY[@]}" | |
8442 | for j in $( compgen -d -- "$i/$cur" ); do | |
8443 | COMPREPLY[k++]=${j#$i/} # cut off directory | |
8444 | done | |
8445 | done | |
8446 | $_skipdot || COMPREPLY+=( $(compgen -d -- "$cur") ) | |
8447 | IFS=$' \t\n' | |
8448 | fi | |
8449 | ||
8450 | # variable names if appropriate shell option set and no completions | |
8451 | if shopt -q cdable_vars && [[ ${#COMPREPLY[@]} -eq 0 ]]; then | |
8452 | COMPREPLY=( $(compgen -v -- "$cur") ) | |
8453 | fi | |
8454 | ||
8455 | return 0 | |
8456 | } | |
8457 | ||
8458 | We install the completion function using the `-F' option to | |
8459 | `complete': | |
8460 | ||
8461 | # Tell readline to quote appropriate and append slashes to directories; | |
8462 | # use the bash default completion for other arguments | |
8463 | complete -o filenames -o nospace -o bashdefault -F _comp_cd cd | |
8464 | ||
8465 | Since we'd like Bash and Readline to take care of some of the other | |
8466 | details for us, we use several other options to tell Bash and Readline | |
8467 | what to do. The `-o filenames' option tells Readline that the possible | |
8468 | completions should be treated as filenames, and quoted appropriately. | |
8469 | That option will also cause Readline to append a slash to filenames it | |
8470 | can determine are directories (which is why we might want to extend | |
8471 | `_comp_cd' to append a slash if we're using directories found via | |
8472 | CDPATH: Readline can't tell those completions are directories). The | |
8473 | `-o nospace' option tells Readline to not append a space character to | |
8474 | the directory name, in case we want to append to it. The `-o | |
8475 | bashdefault' option brings in the rest of the "Bash default" | |
8476 | completions - possible completion that Bash adds to the default Readline | |
8477 | set. These include things like command name completion, variable | |
8478 | completion for words beginning with `{', completions containing pathname | |
8479 | expansion patterns (*note Filename Expansion::), and so on. | |
8480 | ||
8481 | Once installed using `complete', `_comp_cd' will be called every | |
8482 | time we attempt word completion for a `cd' command. | |
8483 | ||
8484 | Many more examples - an extensive collection of completions for most | |
8485 | of the common GNU, Unix, and Linux commands - are available as part of | |
8486 | the bash_completion project. This is installed by default on many | |
8487 | GNU/Linux distributions. Originally written by Ian Macdonald, the | |
8488 | project now lives at `http://bash-completion.alioth.debian.org/'. | |
8489 | There are ports for other systems such as Solaris and Mac OS X. | |
8490 | ||
8491 | An older version of the bash_completion package is distributed with | |
8492 | bash in the `examples/complete' subdirectory. | |
8493 | ||
bb70624e | 8494 | \1f |
c2a47ea9 | 8495 | File: bashref.info, Node: Using History Interactively, Next: Installing Bash, Prev: Command Line Editing, Up: Top |
bb70624e | 8496 | |
37c41ab1 CR |
8497 | 9 Using History Interactively |
8498 | ***************************** | |
bb70624e | 8499 | |
37c41ab1 | 8500 | This chapter describes how to use the GNU History Library |
bb70624e JA |
8501 | interactively, from a user's standpoint. It should be considered a |
8502 | user's guide. For information on using the GNU History Library in | |
8503 | other programs, see the GNU Readline Library Manual. | |
8504 | ||
8505 | * Menu: | |
8506 | ||
8507 | * Bash History Facilities:: How Bash lets you manipulate your command | |
8508 | history. | |
8509 | * Bash History Builtins:: The Bash builtin commands that manipulate | |
8510 | the command history. | |
8511 | * History Interaction:: What it feels like using History as a user. | |
8512 | ||
8513 | \1f | |
8514 | File: bashref.info, Node: Bash History Facilities, Next: Bash History Builtins, Up: Using History Interactively | |
8515 | ||
37c41ab1 CR |
8516 | 9.1 Bash History Facilities |
8517 | =========================== | |
bb70624e | 8518 | |
37c41ab1 CR |
8519 | When the `-o history' option to the `set' builtin is enabled (*note The |
8520 | Set Builtin::), the shell provides access to the "command history", the | |
8521 | list of commands previously typed. The value of the `HISTSIZE' shell | |
8522 | variable is used as the number of commands to save in a history list. | |
8523 | The text of the last `$HISTSIZE' commands (default 500) is saved. The | |
8524 | shell stores each command in the history list prior to parameter and | |
8525 | variable expansion but after history expansion is performed, subject to | |
8526 | the values of the shell variables `HISTIGNORE' and `HISTCONTROL'. | |
bb70624e JA |
8527 | |
8528 | When the shell starts up, the history is initialized from the file | |
8529 | named by the `HISTFILE' variable (default `~/.bash_history'). The file | |
8530 | named by the value of `HISTFILE' is truncated, if necessary, to contain | |
8531 | no more than the number of lines specified by the value of the | |
8532 | `HISTFILESIZE' variable. When an interactive shell exits, the last | |
8533 | `$HISTSIZE' lines are copied from the history list to the file named by | |
8534 | `$HISTFILE'. If the `histappend' shell option is set (*note Bash | |
28ef6c31 | 8535 | Builtins::), the lines are appended to the history file, otherwise the |
bb70624e JA |
8536 | history file is overwritten. If `HISTFILE' is unset, or if the history |
8537 | file is unwritable, the history is not saved. After saving the | |
8538 | history, the history file is truncated to contain no more than | |
45c0f7f8 CR |
8539 | `$HISTFILESIZE' lines. If `HISTFILESIZE' is unset, or set to null, a |
8540 | non-numeric value, or a numeric value less than zero, the history file | |
8541 | is not truncated. | |
bb70624e | 8542 | |
d3a24ed2 | 8543 | If the `HISTTIMEFORMAT' is set, the time stamp information |
d3ad40de CR |
8544 | associated with each history entry is written to the history file, |
8545 | marked with the history comment character. When the history file is | |
8546 | read, lines beginning with the history comment character followed | |
8547 | immediately by a digit are interpreted as timestamps for the previous | |
8548 | history line. | |
d3a24ed2 | 8549 | |
bb70624e JA |
8550 | The builtin command `fc' may be used to list or edit and re-execute |
8551 | a portion of the history list. The `history' builtin may be used to | |
8552 | display or modify the history list and manipulate the history file. | |
8553 | When using command-line editing, search commands are available in each | |
8554 | editing mode that provide access to the history list (*note Commands | |
28ef6c31 | 8555 | For History::). |
bb70624e JA |
8556 | |
8557 | The shell allows control over which commands are saved on the history | |
8558 | list. The `HISTCONTROL' and `HISTIGNORE' variables may be set to cause | |
8559 | the shell to save only a subset of the commands entered. The `cmdhist' | |
8560 | shell option, if enabled, causes the shell to attempt to save each line | |
8561 | of a multi-line command in the same history entry, adding semicolons | |
8562 | where necessary to preserve syntactic correctness. The `lithist' shell | |
8563 | option causes the shell to save the command with embedded newlines | |
8564 | instead of semicolons. The `shopt' builtin is used to set these | |
8565 | options. *Note Bash Builtins::, for a description of `shopt'. | |
8566 | ||
8567 | \1f | |
8568 | File: bashref.info, Node: Bash History Builtins, Next: History Interaction, Prev: Bash History Facilities, Up: Using History Interactively | |
8569 | ||
37c41ab1 CR |
8570 | 9.2 Bash History Builtins |
8571 | ========================= | |
bb70624e | 8572 | |
37c41ab1 | 8573 | Bash provides two builtin commands which manipulate the history list |
bb70624e JA |
8574 | and history file. |
8575 | ||
8576 | `fc' | |
d3ad40de | 8577 | `fc [-e ENAME] [-lnr] [FIRST] [LAST]' |
bb70624e JA |
8578 | `fc -s [PAT=REP] [COMMAND]' |
8579 | ||
122f603c CR |
8580 | The first form selects a range of commands from FIRST to LAST from |
8581 | the history list and displays or edits and re-executes them. Both | |
8582 | FIRST and LAST may be specified as a string (to locate the most | |
8583 | recent command beginning with that string) or as a number (an | |
8584 | index into the history list, where a negative number is used as an | |
8585 | offset from the current command number). If LAST is not specified | |
8586 | it is set to FIRST. If FIRST is not specified it is set to the | |
8587 | previous command for editing and -16 for listing. If the `-l' | |
8588 | flag is given, the commands are listed on standard output. The | |
8589 | `-n' flag suppresses the command numbers when listing. The `-r' | |
8590 | flag reverses the order of the listing. Otherwise, the editor | |
8591 | given by ENAME is invoked on a file containing those commands. If | |
8592 | ENAME is not given, the value of the following variable expansion | |
8593 | is used: `${FCEDIT:-${EDITOR:-vi}}'. This says to use the value | |
8594 | of the `FCEDIT' variable if set, or the value of the `EDITOR' | |
8595 | variable if that is set, or `vi' if neither is set. When editing | |
8596 | is complete, the edited commands are echoed and executed. | |
bb70624e JA |
8597 | |
8598 | In the second form, COMMAND is re-executed after each instance of | |
122f603c CR |
8599 | PAT in the selected command is replaced by REP. COMMAND is |
8600 | intepreted the same as FIRST above. | |
bb70624e JA |
8601 | |
8602 | A useful alias to use with the `fc' command is `r='fc -s'', so | |
8603 | that typing `r cc' runs the last command beginning with `cc' and | |
28ef6c31 | 8604 | typing `r' re-executes the last command (*note Aliases::). |
bb70624e JA |
8605 | |
8606 | `history' | |
8607 | history [N] | |
8608 | history -c | |
8609 | history -d OFFSET | |
8610 | history [-anrw] [FILENAME] | |
8611 | history -ps ARG | |
8612 | ||
8613 | With no options, display the history list with line numbers. | |
28ef6c31 | 8614 | Lines prefixed with a `*' have been modified. An argument of N |
d3a24ed2 CR |
8615 | lists only the last N lines. If the shell variable |
8616 | `HISTTIMEFORMAT' is set and not null, it is used as a format | |
8617 | string for STRFTIME to display the time stamp associated with each | |
8618 | displayed history entry. No intervening blank is printed between | |
8619 | the formatted time stamp and the history line. | |
8620 | ||
8621 | Options, if supplied, have the following meanings: | |
bb70624e JA |
8622 | |
8623 | `-c' | |
8624 | Clear the history list. This may be combined with the other | |
8625 | options to replace the history list completely. | |
8626 | ||
8627 | `-d OFFSET' | |
8628 | Delete the history entry at position OFFSET. OFFSET should | |
8629 | be specified as it appears when the history is displayed. | |
8630 | ||
8631 | `-a' | |
8632 | Append the new history lines (history lines entered since the | |
8633 | beginning of the current Bash session) to the history file. | |
8634 | ||
8635 | `-n' | |
8636 | Append the history lines not already read from the history | |
8637 | file to the current history list. These are lines appended | |
8638 | to the history file since the beginning of the current Bash | |
8639 | session. | |
8640 | ||
8641 | `-r' | |
122f603c CR |
8642 | Read the history file and append its contents to the history |
8643 | list. | |
bb70624e JA |
8644 | |
8645 | `-w' | |
122f603c | 8646 | Write out the current history list to the history file. |
bb70624e JA |
8647 | |
8648 | `-p' | |
8649 | Perform history substitution on the ARGs and display the | |
8650 | result on the standard output, without storing the results in | |
8651 | the history list. | |
8652 | ||
8653 | `-s' | |
8654 | The ARGs are added to the end of the history list as a single | |
8655 | entry. | |
8656 | ||
761783bf | 8657 | |
bb70624e JA |
8658 | When any of the `-w', `-r', `-a', or `-n' options is used, if |
8659 | FILENAME is given, then it is used as the history file. If not, | |
8660 | then the value of the `HISTFILE' variable is used. | |
8661 | ||
761783bf | 8662 | |
bb70624e JA |
8663 | \1f |
8664 | File: bashref.info, Node: History Interaction, Prev: Bash History Builtins, Up: Using History Interactively | |
ccc6cda3 | 8665 | |
37c41ab1 CR |
8666 | 9.3 History Expansion |
8667 | ===================== | |
ccc6cda3 | 8668 | |
37c41ab1 CR |
8669 | The History library provides a history expansion feature that is similar |
8670 | to the history expansion provided by `csh'. This section describes the | |
8671 | syntax used to manipulate the history information. | |
ccc6cda3 | 8672 | |
bb70624e JA |
8673 | History expansions introduce words from the history list into the |
8674 | input stream, making it easy to repeat commands, insert the arguments | |
8675 | to a previous command into the current input line, or fix errors in | |
8676 | previous commands quickly. | |
ccc6cda3 | 8677 | |
bb70624e JA |
8678 | History expansion takes place in two parts. The first is to |
8679 | determine which line from the history list should be used during | |
8680 | substitution. The second is to select portions of that line for | |
8681 | inclusion into the current one. The line selected from the history is | |
8682 | called the "event", and the portions of that line that are acted upon | |
8683 | are called "words". Various "modifiers" are available to manipulate | |
8684 | the selected words. The line is broken into words in the same fashion | |
8685 | that Bash does, so that several words surrounded by quotes are | |
8686 | considered one word. History expansions are introduced by the | |
8687 | appearance of the history expansion character, which is `!' by default. | |
8688 | Only `\' and `'' may be used to escape the history expansion character. | |
8689 | ||
8690 | Several shell options settable with the `shopt' builtin (*note Bash | |
28ef6c31 | 8691 | Builtins::) may be used to tailor the behavior of history expansion. |
bb70624e JA |
8692 | If the `histverify' shell option is enabled, and Readline is being |
8693 | used, history substitutions are not immediately passed to the shell | |
8694 | parser. Instead, the expanded line is reloaded into the Readline | |
8695 | editing buffer for further modification. If Readline is being used, | |
8696 | and the `histreedit' shell option is enabled, a failed history | |
8697 | expansion will be reloaded into the Readline editing buffer for | |
8698 | correction. The `-p' option to the `history' builtin command may be | |
8699 | used to see what a history expansion will do before using it. The `-s' | |
8700 | option to the `history' builtin may be used to add commands to the end | |
8701 | of the history list without actually executing them, so that they are | |
8702 | available for subsequent recall. This is most useful in conjunction | |
8703 | with Readline. | |
8704 | ||
8705 | The shell allows control of the various characters used by the | |
d3ad40de CR |
8706 | history expansion mechanism with the `histchars' variable, as explained |
8707 | above (*note Bash Variables::). The shell uses the history comment | |
8708 | character to mark history timestamps when writing the history file. | |
bb70624e JA |
8709 | |
8710 | * Menu: | |
8711 | ||
8712 | * Event Designators:: How to specify which history line to use. | |
8713 | * Word Designators:: Specifying which words are of interest. | |
8714 | * Modifiers:: Modifying the results of substitution. | |
ccc6cda3 JA |
8715 | |
8716 | \1f | |
bb70624e | 8717 | File: bashref.info, Node: Event Designators, Next: Word Designators, Up: History Interaction |
ccc6cda3 | 8718 | |
37c41ab1 CR |
8719 | 9.3.1 Event Designators |
8720 | ----------------------- | |
ccc6cda3 | 8721 | |
37c41ab1 | 8722 | An event designator is a reference to a command line entry in the |
e05be32d CR |
8723 | history list. Unless the reference is absolute, events are relative to |
8724 | the current position in the history list. | |
ccc6cda3 | 8725 | |
bb70624e JA |
8726 | `!' |
8727 | Start a history substitution, except when followed by a space, tab, | |
d3a24ed2 CR |
8728 | the end of the line, `=' or `(' (when the `extglob' shell option |
8729 | is enabled using the `shopt' builtin). | |
ccc6cda3 | 8730 | |
bb70624e JA |
8731 | `!N' |
8732 | Refer to command line N. | |
ccc6cda3 | 8733 | |
bb70624e JA |
8734 | `!-N' |
8735 | Refer to the command N lines back. | |
ccc6cda3 | 8736 | |
bb70624e JA |
8737 | `!!' |
8738 | Refer to the previous command. This is a synonym for `!-1'. | |
ccc6cda3 | 8739 | |
bb70624e | 8740 | `!STRING' |
e05be32d CR |
8741 | Refer to the most recent command preceding the current position in |
8742 | the history list starting with STRING. | |
ccc6cda3 | 8743 | |
bb70624e | 8744 | `!?STRING[?]' |
e05be32d CR |
8745 | Refer to the most recent command preceding the current position in |
8746 | the history list containing STRING. The trailing `?' may be | |
8747 | omitted if the STRING is followed immediately by a newline. | |
ccc6cda3 | 8748 | |
bb70624e JA |
8749 | `^STRING1^STRING2^' |
8750 | Quick Substitution. Repeat the last command, replacing STRING1 | |
8751 | with STRING2. Equivalent to `!!:s/STRING1/STRING2/'. | |
8752 | ||
8753 | `!#' | |
8754 | The entire command line typed so far. | |
ccc6cda3 | 8755 | |
761783bf | 8756 | |
ccc6cda3 | 8757 | \1f |
bb70624e | 8758 | File: bashref.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction |
ccc6cda3 | 8759 | |
37c41ab1 CR |
8760 | 9.3.2 Word Designators |
8761 | ---------------------- | |
ccc6cda3 | 8762 | |
37c41ab1 | 8763 | Word designators are used to select desired words from the event. A |
bb70624e JA |
8764 | `:' separates the event specification from the word designator. It may |
8765 | be omitted if the word designator begins with a `^', `$', `*', `-', or | |
8766 | `%'. Words are numbered from the beginning of the line, with the first | |
8767 | word being denoted by 0 (zero). Words are inserted into the current | |
8768 | line separated by single spaces. | |
ccc6cda3 | 8769 | |
bb70624e | 8770 | For example, |
ccc6cda3 | 8771 | |
bb70624e JA |
8772 | `!!' |
8773 | designates the preceding command. When you type this, the | |
8774 | preceding command is repeated in toto. | |
ccc6cda3 | 8775 | |
bb70624e JA |
8776 | `!!:$' |
8777 | designates the last argument of the preceding command. This may be | |
8778 | shortened to `!$'. | |
ccc6cda3 | 8779 | |
bb70624e JA |
8780 | `!fi:2' |
8781 | designates the second argument of the most recent command starting | |
8782 | with the letters `fi'. | |
ccc6cda3 | 8783 | |
bb70624e | 8784 | Here are the word designators: |
ccc6cda3 | 8785 | |
bb70624e JA |
8786 | `0 (zero)' |
8787 | The `0'th word. For many applications, this is the command word. | |
ccc6cda3 | 8788 | |
bb70624e JA |
8789 | `N' |
8790 | The Nth word. | |
ccc6cda3 | 8791 | |
bb70624e JA |
8792 | `^' |
8793 | The first argument; that is, word 1. | |
ccc6cda3 | 8794 | |
bb70624e JA |
8795 | `$' |
8796 | The last argument. | |
ccc6cda3 | 8797 | |
bb70624e JA |
8798 | `%' |
8799 | The word matched by the most recent `?STRING?' search. | |
ccc6cda3 | 8800 | |
bb70624e JA |
8801 | `X-Y' |
8802 | A range of words; `-Y' abbreviates `0-Y'. | |
ccc6cda3 | 8803 | |
bb70624e JA |
8804 | `*' |
8805 | All of the words, except the `0'th. This is a synonym for `1-$'. | |
8806 | It is not an error to use `*' if there is just one word in the | |
8807 | event; the empty string is returned in that case. | |
8808 | ||
8809 | `X*' | |
8810 | Abbreviates `X-$' | |
8811 | ||
8812 | `X-' | |
8813 | Abbreviates `X-$' like `X*', but omits the last word. | |
8814 | ||
761783bf | 8815 | |
bb70624e JA |
8816 | If a word designator is supplied without an event specification, the |
8817 | previous command is used as the event. | |
ccc6cda3 JA |
8818 | |
8819 | \1f | |
bb70624e | 8820 | File: bashref.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction |
ccc6cda3 | 8821 | |
37c41ab1 CR |
8822 | 9.3.3 Modifiers |
8823 | --------------- | |
ccc6cda3 | 8824 | |
37c41ab1 | 8825 | After the optional word designator, you can add a sequence of one or |
bb70624e | 8826 | more of the following modifiers, each preceded by a `:'. |
ccc6cda3 | 8827 | |
bb70624e JA |
8828 | `h' |
8829 | Remove a trailing pathname component, leaving only the head. | |
ccc6cda3 | 8830 | |
bb70624e | 8831 | `t' |
d3ad40de | 8832 | Remove all leading pathname components, leaving the tail. |
bb70624e JA |
8833 | |
8834 | `r' | |
8835 | Remove a trailing suffix of the form `.SUFFIX', leaving the | |
8836 | basename. | |
8837 | ||
8838 | `e' | |
8839 | Remove all but the trailing suffix. | |
8840 | ||
8841 | `p' | |
8842 | Print the new command but do not execute it. | |
8843 | ||
8844 | `q' | |
8845 | Quote the substituted words, escaping further substitutions. | |
8846 | ||
8847 | `x' | |
8848 | Quote the substituted words as with `q', but break into words at | |
8849 | spaces, tabs, and newlines. | |
8850 | ||
8851 | `s/OLD/NEW/' | |
8852 | Substitute NEW for the first occurrence of OLD in the event line. | |
8853 | Any delimiter may be used in place of `/'. The delimiter may be | |
8854 | quoted in OLD and NEW with a single backslash. If `&' appears in | |
8855 | NEW, it is replaced by OLD. A single backslash will quote the | |
8856 | `&'. The final delimiter is optional if it is the last character | |
8857 | on the input line. | |
8858 | ||
8859 | `&' | |
8860 | Repeat the previous substitution. | |
8861 | ||
8862 | `g' | |
d3a24ed2 | 8863 | `a' |
bb70624e JA |
8864 | Cause changes to be applied over the entire event line. Used in |
8865 | conjunction with `s', as in `gs/OLD/NEW/', or with `&'. | |
8866 | ||
d3a24ed2 CR |
8867 | `G' |
8868 | Apply the following `s' modifier once to each word in the event. | |
8869 | ||
761783bf | 8870 | |
bb70624e | 8871 | \1f |
c2a47ea9 | 8872 | File: bashref.info, Node: Installing Bash, Next: Reporting Bugs, Prev: Using History Interactively, Up: Top |
bb70624e | 8873 | |
37c41ab1 CR |
8874 | 10 Installing Bash |
8875 | ****************** | |
b72432fd | 8876 | |
37c41ab1 | 8877 | This chapter provides basic instructions for installing Bash on the |
bb70624e JA |
8878 | various supported platforms. The distribution supports the GNU |
8879 | operating systems, nearly every version of Unix, and several non-Unix | |
8880 | systems such as BeOS and Interix. Other independent ports exist for | |
d3a24ed2 | 8881 | MS-DOS, OS/2, and Windows platforms. |
ccc6cda3 | 8882 | |
bb70624e | 8883 | * Menu: |
ccc6cda3 | 8884 | |
bb70624e | 8885 | * Basic Installation:: Installation instructions. |
bb70624e JA |
8886 | * Compilers and Options:: How to set special options for various |
8887 | systems. | |
bb70624e JA |
8888 | * Compiling For Multiple Architectures:: How to compile Bash for more |
8889 | than one kind of system from | |
8890 | the same source tree. | |
bb70624e | 8891 | * Installation Names:: How to set the various paths used by the installation. |
bb70624e | 8892 | * Specifying the System Type:: How to configure Bash for a particular system. |
bb70624e JA |
8893 | * Sharing Defaults:: How to share default configuration values among GNU |
8894 | programs. | |
bb70624e | 8895 | * Operation Controls:: Options recognized by the configuration program. |
bb70624e JA |
8896 | * Optional Features:: How to enable and disable optional features when |
8897 | building Bash. | |
ccc6cda3 | 8898 | |
bb70624e JA |
8899 | \1f |
8900 | File: bashref.info, Node: Basic Installation, Next: Compilers and Options, Up: Installing Bash | |
ccc6cda3 | 8901 | |
37c41ab1 CR |
8902 | 10.1 Basic Installation |
8903 | ======================= | |
ccc6cda3 | 8904 | |
37c41ab1 | 8905 | These are installation instructions for Bash. |
ccc6cda3 | 8906 | |
bb70624e | 8907 | The simplest way to compile Bash is: |
ccc6cda3 | 8908 | |
bb70624e JA |
8909 | 1. `cd' to the directory containing the source code and type |
8910 | `./configure' to configure Bash for your system. If you're using | |
8911 | `csh' on an old version of System V, you might need to type `sh | |
8912 | ./configure' instead to prevent `csh' from trying to execute | |
8913 | `configure' itself. | |
ccc6cda3 | 8914 | |
bb70624e JA |
8915 | Running `configure' takes some time. While running, it prints |
8916 | messages telling which features it is checking for. | |
ccc6cda3 | 8917 | |
bb70624e JA |
8918 | 2. Type `make' to compile Bash and build the `bashbug' bug reporting |
8919 | script. | |
ccc6cda3 | 8920 | |
bb70624e | 8921 | 3. Optionally, type `make tests' to run the Bash test suite. |
ccc6cda3 | 8922 | |
bb70624e JA |
8923 | 4. Type `make install' to install `bash' and `bashbug'. This will |
8924 | also install the manual pages and Info file. | |
ccc6cda3 | 8925 | |
ccc6cda3 | 8926 | |
bb70624e JA |
8927 | The `configure' shell script attempts to guess correct values for |
8928 | various system-dependent variables used during compilation. It uses | |
8929 | those values to create a `Makefile' in each directory of the package | |
8930 | (the top directory, the `builtins', `doc', and `support' directories, | |
8931 | each directory under `lib', and several others). It also creates a | |
8932 | `config.h' file containing system-dependent definitions. Finally, it | |
8933 | creates a shell script named `config.status' that you can run in the | |
8934 | future to recreate the current configuration, a file `config.cache' | |
8935 | that saves the results of its tests to speed up reconfiguring, and a | |
8936 | file `config.log' containing compiler output (useful mainly for | |
8937 | debugging `configure'). If at some point `config.cache' contains | |
8938 | results you don't want to keep, you may remove or edit it. | |
ccc6cda3 | 8939 | |
bb70624e JA |
8940 | To find out more about the options and arguments that the |
8941 | `configure' script understands, type | |
ccc6cda3 | 8942 | |
bb70624e | 8943 | bash-2.04$ ./configure --help |
ccc6cda3 | 8944 | |
bb70624e | 8945 | at the Bash prompt in your Bash source directory. |
ccc6cda3 | 8946 | |
bb70624e JA |
8947 | If you need to do unusual things to compile Bash, please try to |
8948 | figure out how `configure' could check whether or not to do them, and | |
8949 | mail diffs or instructions to <bash-maintainers@gnu.org> so they can be | |
8950 | considered for the next release. | |
ccc6cda3 | 8951 | |
bb70624e JA |
8952 | The file `configure.in' is used to create `configure' by a program |
8953 | called Autoconf. You only need `configure.in' if you want to change it | |
8954 | or regenerate `configure' using a newer version of Autoconf. If you do | |
f73dda09 | 8955 | this, make sure you are using Autoconf version 2.50 or newer. |
ccc6cda3 | 8956 | |
bb70624e JA |
8957 | You can remove the program binaries and object files from the source |
8958 | code directory by typing `make clean'. To also remove the files that | |
8959 | `configure' created (so you can compile Bash for a different kind of | |
8960 | computer), type `make distclean'. | |
ccc6cda3 | 8961 | |
bb70624e JA |
8962 | \1f |
8963 | File: bashref.info, Node: Compilers and Options, Next: Compiling For Multiple Architectures, Prev: Basic Installation, Up: Installing Bash | |
ccc6cda3 | 8964 | |
37c41ab1 CR |
8965 | 10.2 Compilers and Options |
8966 | ========================== | |
ccc6cda3 | 8967 | |
37c41ab1 | 8968 | Some systems require unusual options for compilation or linking that |
bb70624e JA |
8969 | the `configure' script does not know about. You can give `configure' |
8970 | initial values for variables by setting them in the environment. Using | |
8971 | a Bourne-compatible shell, you can do that on the command line like | |
8972 | this: | |
ccc6cda3 | 8973 | |
bb70624e | 8974 | CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure |
ccc6cda3 | 8975 | |
bb70624e | 8976 | On systems that have the `env' program, you can do it like this: |
cce855bc | 8977 | |
bb70624e | 8978 | env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure |
b72432fd | 8979 | |
bb70624e | 8980 | The configuration process uses GCC to build Bash if it is available. |
ccc6cda3 | 8981 | |
bb70624e JA |
8982 | \1f |
8983 | File: bashref.info, Node: Compiling For Multiple Architectures, Next: Installation Names, Prev: Compilers and Options, Up: Installing Bash | |
ccc6cda3 | 8984 | |
37c41ab1 CR |
8985 | 10.3 Compiling For Multiple Architectures |
8986 | ========================================= | |
ccc6cda3 | 8987 | |
37c41ab1 | 8988 | You can compile Bash for more than one kind of computer at the same |
bb70624e JA |
8989 | time, by placing the object files for each architecture in their own |
8990 | directory. To do this, you must use a version of `make' that supports | |
8991 | the `VPATH' variable, such as GNU `make'. `cd' to the directory where | |
8992 | you want the object files and executables to go and run the `configure' | |
8993 | script from the source directory. You may need to supply the | |
8994 | `--srcdir=PATH' argument to tell `configure' where the source files | |
8995 | are. `configure' automatically checks for the source code in the | |
8996 | directory that `configure' is in and in `..'. | |
ccc6cda3 | 8997 | |
bb70624e JA |
8998 | If you have to use a `make' that does not supports the `VPATH' |
8999 | variable, you can compile Bash for one architecture at a time in the | |
9000 | source code directory. After you have installed Bash for one | |
9001 | architecture, use `make distclean' before reconfiguring for another | |
9002 | architecture. | |
ccc6cda3 | 9003 | |
bb70624e JA |
9004 | Alternatively, if your system supports symbolic links, you can use |
9005 | the `support/mkclone' script to create a build tree which has symbolic | |
9006 | links back to each file in the source directory. Here's an example | |
9007 | that creates a build directory in the current directory from a source | |
9008 | directory `/usr/gnu/src/bash-2.0': | |
ccc6cda3 | 9009 | |
bb70624e | 9010 | bash /usr/gnu/src/bash-2.0/support/mkclone -s /usr/gnu/src/bash-2.0 . |
ccc6cda3 | 9011 | |
bb70624e JA |
9012 | The `mkclone' script requires Bash, so you must have already built Bash |
9013 | for at least one architecture before you can create build directories | |
9014 | for other architectures. | |
ccc6cda3 | 9015 | |
bb70624e JA |
9016 | \1f |
9017 | File: bashref.info, Node: Installation Names, Next: Specifying the System Type, Prev: Compiling For Multiple Architectures, Up: Installing Bash | |
ccc6cda3 | 9018 | |
37c41ab1 CR |
9019 | 10.4 Installation Names |
9020 | ======================= | |
ccc6cda3 | 9021 | |
37c41ab1 | 9022 | By default, `make install' will install into `/usr/local/bin', |
bb70624e | 9023 | `/usr/local/man', etc. You can specify an installation prefix other |
f73dda09 JA |
9024 | than `/usr/local' by giving `configure' the option `--prefix=PATH', or |
9025 | by specifying a value for the `DESTDIR' `make' variable when running | |
9026 | `make install'. | |
ccc6cda3 | 9027 | |
bb70624e JA |
9028 | You can specify separate installation prefixes for |
9029 | architecture-specific files and architecture-independent files. If you | |
9030 | give `configure' the option `--exec-prefix=PATH', `make install' will | |
9031 | use PATH as the prefix for installing programs and libraries. | |
9032 | Documentation and other data files will still use the regular prefix. | |
ccc6cda3 JA |
9033 | |
9034 | \1f | |
bb70624e | 9035 | File: bashref.info, Node: Specifying the System Type, Next: Sharing Defaults, Prev: Installation Names, Up: Installing Bash |
ccc6cda3 | 9036 | |
37c41ab1 CR |
9037 | 10.5 Specifying the System Type |
9038 | =============================== | |
ccc6cda3 | 9039 | |
37c41ab1 | 9040 | There may be some features `configure' can not figure out |
f73dda09 | 9041 | automatically, but need to determine by the type of host Bash will run |
bb70624e JA |
9042 | on. Usually `configure' can figure that out, but if it prints a |
9043 | message saying it can not guess the host type, give it the | |
9044 | `--host=TYPE' option. `TYPE' can either be a short name for the system | |
9045 | type, such as `sun4', or a canonical name with three fields: | |
f73dda09 | 9046 | `CPU-COMPANY-SYSTEM' (e.g., `i386-unknown-freebsd4.2'). |
ccc6cda3 | 9047 | |
bb70624e JA |
9048 | See the file `support/config.sub' for the possible values of each |
9049 | field. | |
ccc6cda3 | 9050 | |
bb70624e JA |
9051 | \1f |
9052 | File: bashref.info, Node: Sharing Defaults, Next: Operation Controls, Prev: Specifying the System Type, Up: Installing Bash | |
9053 | ||
37c41ab1 CR |
9054 | 10.6 Sharing Defaults |
9055 | ===================== | |
bb70624e | 9056 | |
37c41ab1 CR |
9057 | If you want to set default values for `configure' scripts to share, you |
9058 | can create a site shell script called `config.site' that gives default | |
9059 | values for variables like `CC', `cache_file', and `prefix'. `configure' | |
9060 | looks for `PREFIX/share/config.site' if it exists, then | |
bb70624e JA |
9061 | `PREFIX/etc/config.site' if it exists. Or, you can set the |
9062 | `CONFIG_SITE' environment variable to the location of the site script. | |
9063 | A warning: the Bash `configure' looks for a site script, but not all | |
9064 | `configure' scripts do. | |
ccc6cda3 JA |
9065 | |
9066 | \1f | |
bb70624e | 9067 | File: bashref.info, Node: Operation Controls, Next: Optional Features, Prev: Sharing Defaults, Up: Installing Bash |
ccc6cda3 | 9068 | |
37c41ab1 CR |
9069 | 10.7 Operation Controls |
9070 | ======================= | |
ccc6cda3 | 9071 | |
37c41ab1 | 9072 | `configure' recognizes the following options to control how it operates. |
ccc6cda3 | 9073 | |
bb70624e JA |
9074 | `--cache-file=FILE' |
9075 | Use and save the results of the tests in FILE instead of | |
9076 | `./config.cache'. Set FILE to `/dev/null' to disable caching, for | |
9077 | debugging `configure'. | |
ccc6cda3 | 9078 | |
bb70624e JA |
9079 | `--help' |
9080 | Print a summary of the options to `configure', and exit. | |
ccc6cda3 | 9081 | |
bb70624e JA |
9082 | `--quiet' |
9083 | `--silent' | |
9084 | `-q' | |
9085 | Do not print messages saying which checks are being made. | |
ccc6cda3 | 9086 | |
bb70624e JA |
9087 | `--srcdir=DIR' |
9088 | Look for the Bash source code in directory DIR. Usually | |
9089 | `configure' can determine that directory automatically. | |
ccc6cda3 | 9090 | |
bb70624e JA |
9091 | `--version' |
9092 | Print the version of Autoconf used to generate the `configure' | |
9093 | script, and exit. | |
ccc6cda3 | 9094 | |
bb70624e JA |
9095 | `configure' also accepts some other, not widely used, boilerplate |
9096 | options. `configure --help' prints the complete list. | |
ccc6cda3 | 9097 | |
bb70624e JA |
9098 | \1f |
9099 | File: bashref.info, Node: Optional Features, Prev: Operation Controls, Up: Installing Bash | |
ccc6cda3 | 9100 | |
37c41ab1 CR |
9101 | 10.8 Optional Features |
9102 | ====================== | |
ccc6cda3 | 9103 | |
37c41ab1 CR |
9104 | The Bash `configure' has a number of `--enable-FEATURE' options, where |
9105 | FEATURE indicates an optional part of Bash. There are also several | |
9106 | `--with-PACKAGE' options, where PACKAGE is something like `bash-malloc' | |
9107 | or `purify'. To turn off the default use of a package, use | |
9108 | `--without-PACKAGE'. To configure Bash without a feature that is | |
bb70624e | 9109 | enabled by default, use `--disable-FEATURE'. |
ccc6cda3 | 9110 | |
bb70624e JA |
9111 | Here is a complete list of the `--enable-' and `--with-' options |
9112 | that the Bash `configure' recognizes. | |
ccc6cda3 | 9113 | |
bb70624e JA |
9114 | `--with-afs' |
9115 | Define if you are using the Andrew File System from Transarc. | |
ccc6cda3 | 9116 | |
bb70624e | 9117 | `--with-bash-malloc' |
1c72c0cd CR |
9118 | Use the Bash version of `malloc' in the directory `lib/malloc'. |
9119 | This is not the same `malloc' that appears in GNU libc, but an | |
9120 | older version originally derived from the 4.2 BSD `malloc'. This | |
9121 | `malloc' is very fast, but wastes some space on each allocation. | |
9122 | This option is enabled by default. The `NOTES' file contains a | |
9123 | list of systems for which this should be turned off, and | |
9124 | `configure' disables this option automatically for a number of | |
9125 | systems. | |
ccc6cda3 | 9126 | |
bb70624e JA |
9127 | `--with-curses' |
9128 | Use the curses library instead of the termcap library. This should | |
9129 | be supplied if your system has an inadequate or incomplete termcap | |
9130 | database. | |
ccc6cda3 | 9131 | |
bb70624e JA |
9132 | `--with-gnu-malloc' |
9133 | A synonym for `--with-bash-malloc'. | |
ccc6cda3 | 9134 | |
f73dda09 | 9135 | `--with-installed-readline[=PREFIX]' |
bb70624e JA |
9136 | Define this to make Bash link with a locally-installed version of |
9137 | Readline rather than the version in `lib/readline'. This works | |
01ed5ba4 | 9138 | only with Readline 5.0 and later versions. If PREFIX is `yes' or |
f73dda09 JA |
9139 | not supplied, `configure' uses the values of the make variables |
9140 | `includedir' and `libdir', which are subdirectories of `prefix' by | |
9141 | default, to find the installed version of Readline if it is not in | |
9142 | the standard system include and library directories. If PREFIX is | |
9143 | `no', Bash links with the version in `lib/readline'. If PREFIX is | |
9144 | set to any other value, `configure' treats it as a directory | |
9145 | pathname and looks for the installed version of Readline in | |
9146 | subdirectories of that directory (include files in | |
9147 | PREFIX/`include' and the library in PREFIX/`lib'). | |
ccc6cda3 | 9148 | |
bb70624e JA |
9149 | `--with-purify' |
9150 | Define this to use the Purify memory allocation checker from | |
9151 | Rational Software. | |
ccc6cda3 | 9152 | |
bb70624e JA |
9153 | `--enable-minimal-config' |
9154 | This produces a shell with minimal features, close to the | |
9155 | historical Bourne shell. | |
ccc6cda3 | 9156 | |
bb70624e JA |
9157 | There are several `--enable-' options that alter how Bash is |
9158 | compiled and linked, rather than changing run-time features. | |
ccc6cda3 | 9159 | |
f73dda09 JA |
9160 | `--enable-largefile' |
9161 | Enable support for large files | |
9162 | (http://www.sas.com/standards/large_file/x_open.20Mar96.html) if | |
9163 | the operating system requires special compiler options to build | |
7117c2d2 JA |
9164 | programs which can access large files. This is enabled by |
9165 | default, if the operating system provides large file support. | |
f73dda09 | 9166 | |
bb70624e JA |
9167 | `--enable-profiling' |
9168 | This builds a Bash binary that produces profiling information to be | |
9169 | processed by `gprof' each time it is executed. | |
cce855bc | 9170 | |
bb70624e JA |
9171 | `--enable-static-link' |
9172 | This causes Bash to be linked statically, if `gcc' is being used. | |
9173 | This could be used to build a version to use as root's shell. | |
d166f048 | 9174 | |
bb70624e JA |
9175 | The `minimal-config' option can be used to disable all of the |
9176 | following options, but it is processed first, so individual options may | |
9177 | be enabled using `enable-FEATURE'. | |
d166f048 | 9178 | |
bb70624e JA |
9179 | All of the following options except for `disabled-builtins' and |
9180 | `xpg-echo-default' are enabled by default, unless the operating system | |
9181 | does not provide the necessary support. | |
ccc6cda3 | 9182 | |
bb70624e JA |
9183 | `--enable-alias' |
9184 | Allow alias expansion and include the `alias' and `unalias' | |
28ef6c31 | 9185 | builtins (*note Aliases::). |
ccc6cda3 | 9186 | |
bb70624e JA |
9187 | `--enable-arith-for-command' |
9188 | Include support for the alternate form of the `for' command that | |
9189 | behaves like the C language `for' statement (*note Looping | |
28ef6c31 | 9190 | Constructs::). |
ccc6cda3 | 9191 | |
bb70624e JA |
9192 | `--enable-array-variables' |
9193 | Include support for one-dimensional array shell variables (*note | |
28ef6c31 | 9194 | Arrays::). |
ccc6cda3 | 9195 | |
bb70624e JA |
9196 | `--enable-bang-history' |
9197 | Include support for `csh'-like history substitution (*note History | |
28ef6c31 | 9198 | Interaction::). |
ccc6cda3 | 9199 | |
bb70624e JA |
9200 | `--enable-brace-expansion' |
9201 | Include `csh'-like brace expansion ( `b{a,b}c' ==> `bac bbc' ). | |
6a8fd0ed | 9202 | See *note Brace Expansion::, for a complete description. |
ccc6cda3 | 9203 | |
09767ff0 CR |
9204 | `--enable-casemod-attributes' |
9205 | Include support for case-modifying attributes in the `declare' | |
9206 | builtin and assignment statements. Variables with the UPPERCASE | |
9207 | attribute, for example, will have their values converted to | |
9208 | uppercase upon assignment. | |
9209 | ||
9210 | `--enable-casemod-expansion' | |
9211 | Include support for case-modifying word expansions. | |
9212 | ||
bb70624e JA |
9213 | `--enable-command-timing' |
9214 | Include support for recognizing `time' as a reserved word and for | |
9215 | displaying timing statistics for the pipeline following `time' | |
28ef6c31 | 9216 | (*note Pipelines::). This allows pipelines as well as shell |
bb70624e | 9217 | builtins and functions to be timed. |
ccc6cda3 | 9218 | |
bb70624e | 9219 | `--enable-cond-command' |
5e13499c CR |
9220 | Include support for the `[[' conditional command. (*note |
9221 | Conditional Constructs::). | |
9222 | ||
9223 | `--enable-cond-regexp' | |
9224 | Include support for matching POSIX regular expressions using the | |
9225 | `=~' binary operator in the `[[' conditional command. (*note | |
28ef6c31 | 9226 | Conditional Constructs::). |
ccc6cda3 | 9227 | |
8e1a6eaa CR |
9228 | `--enable-coprocesses' |
9229 | Include support for coprocesses and the `coproc' reserved word | |
9230 | (*note Pipelines::). | |
9231 | ||
01ed5ba4 CR |
9232 | `--enable-debugger' |
9233 | Include support for the bash debugger (distributed separately). | |
9234 | ||
bb70624e JA |
9235 | `--enable-directory-stack' |
9236 | Include support for a `csh'-like directory stack and the `pushd', | |
28ef6c31 | 9237 | `popd', and `dirs' builtins (*note The Directory Stack::). |
ccc6cda3 | 9238 | |
bb70624e JA |
9239 | `--enable-disabled-builtins' |
9240 | Allow builtin commands to be invoked via `builtin xxx' even after | |
6a8fd0ed | 9241 | `xxx' has been disabled using `enable -n xxx'. See *note Bash |
bb70624e JA |
9242 | Builtins::, for details of the `builtin' and `enable' builtin |
9243 | commands. | |
ccc6cda3 | 9244 | |
bb70624e JA |
9245 | `--enable-dparen-arithmetic' |
9246 | Include support for the `((...))' command (*note Conditional | |
28ef6c31 | 9247 | Constructs::). |
ccc6cda3 | 9248 | |
bb70624e JA |
9249 | `--enable-extended-glob' |
9250 | Include support for the extended pattern matching features | |
6a8fd0ed | 9251 | described above under *note Pattern Matching::. |
ccc6cda3 | 9252 | |
8f714a7c CR |
9253 | `--enable-extended-glob-default' |
9254 | Set the default value of the EXTGLOB shell option described above | |
9255 | under *note The Shopt Builtin:: to be enabled. | |
9256 | ||
bb70624e JA |
9257 | `--enable-help-builtin' |
9258 | Include the `help' builtin, which displays help on shell builtins | |
28ef6c31 | 9259 | and variables (*note Bash Builtins::). |
ccc6cda3 | 9260 | |
bb70624e JA |
9261 | `--enable-history' |
9262 | Include command history and the `fc' and `history' builtin | |
28ef6c31 | 9263 | commands (*note Bash History Facilities::). |
ccc6cda3 | 9264 | |
bb70624e | 9265 | `--enable-job-control' |
28ef6c31 | 9266 | This enables the job control features (*note Job Control::), if |
bb70624e | 9267 | the operating system supports them. |
ccc6cda3 | 9268 | |
d3a24ed2 CR |
9269 | `--enable-multibyte' |
9270 | This enables support for multibyte characters if the operating | |
9271 | system provides the necessary support. | |
9272 | ||
bb70624e JA |
9273 | `--enable-net-redirections' |
9274 | This enables the special handling of filenames of the form | |
9275 | `/dev/tcp/HOST/PORT' and `/dev/udp/HOST/PORT' when used in | |
28ef6c31 | 9276 | redirections (*note Redirections::). |
ccc6cda3 | 9277 | |
bb70624e | 9278 | `--enable-process-substitution' |
28ef6c31 JA |
9279 | This enables process substitution (*note Process Substitution::) if |
9280 | the operating system provides the necessary support. | |
ccc6cda3 | 9281 | |
01ed5ba4 CR |
9282 | `--enable-progcomp' |
9283 | Enable the programmable completion facilities (*note Programmable | |
9284 | Completion::). If Readline is not enabled, this option has no | |
9285 | effect. | |
9286 | ||
bb70624e JA |
9287 | `--enable-prompt-string-decoding' |
9288 | Turn on the interpretation of a number of backslash-escaped | |
9289 | characters in the `$PS1', `$PS2', `$PS3', and `$PS4' prompt | |
122f603c CR |
9290 | strings. See *note Controlling the Prompt::, for a complete list |
9291 | of prompt string escape sequences. | |
ccc6cda3 | 9292 | |
bb70624e JA |
9293 | `--enable-readline' |
9294 | Include support for command-line editing and history with the Bash | |
28ef6c31 | 9295 | version of the Readline library (*note Command Line Editing::). |
ccc6cda3 | 9296 | |
bb70624e JA |
9297 | `--enable-restricted' |
9298 | Include support for a "restricted shell". If this is enabled, | |
6a8fd0ed | 9299 | Bash, when called as `rbash', enters a restricted mode. See *note |
bb70624e | 9300 | The Restricted Shell::, for a description of restricted mode. |
ccc6cda3 | 9301 | |
bb70624e | 9302 | `--enable-select' |
54a1fa7c CR |
9303 | Include the `select' compound command, which allows the generation |
9304 | of simple menus (*note Conditional Constructs::). | |
ccc6cda3 | 9305 | |
01ed5ba4 CR |
9306 | `--enable-separate-helpfiles' |
9307 | Use external files for the documentation displayed by the `help' | |
9308 | builtin instead of storing the text internally. | |
9309 | ||
9310 | `--enable-single-help-strings' | |
9311 | Store the text displayed by the `help' builtin as a single string | |
9312 | for each help topic. This aids in translating the text to | |
9313 | different languages. You may need to disable this if your | |
9314 | compiler cannot handle very long string literals. | |
9315 | ||
1c72c0cd CR |
9316 | `--enable-strict-posix-default' |
9317 | Make Bash POSIX-conformant by default (*note Bash POSIX Mode::). | |
9318 | ||
bb70624e JA |
9319 | `--enable-usg-echo-default' |
9320 | A synonym for `--enable-xpg-echo-default'. | |
ccc6cda3 | 9321 | |
bb70624e JA |
9322 | `--enable-xpg-echo-default' |
9323 | Make the `echo' builtin expand backslash-escaped characters by | |
9324 | default, without requiring the `-e' option. This sets the default | |
9325 | value of the `xpg_echo' shell option to `on', which makes the Bash | |
9326 | `echo' behave more like the version specified in the Single Unix | |
01ed5ba4 | 9327 | Specification, version 3. *Note Bash Builtins::, for a |
bb70624e | 9328 | description of the escape sequences that `echo' recognizes. |
ccc6cda3 | 9329 | |
bb70624e JA |
9330 | The file `config-top.h' contains C Preprocessor `#define' statements |
9331 | for options which are not settable from `configure'. Some of these are | |
9332 | not meant to be changed; beware of the consequences if you do. Read | |
9333 | the comments associated with each definition for more information about | |
9334 | its effect. | |
ccc6cda3 | 9335 | |
bb70624e JA |
9336 | \1f |
9337 | File: bashref.info, Node: Reporting Bugs, Next: Major Differences From The Bourne Shell, Prev: Installing Bash, Up: Top | |
d166f048 | 9338 | |
37c41ab1 CR |
9339 | Appendix A Reporting Bugs |
9340 | ************************* | |
ccc6cda3 | 9341 | |
37c41ab1 | 9342 | Please report all bugs you find in Bash. But first, you should make |
bb70624e | 9343 | sure that it really is a bug, and that it appears in the latest version |
d3a24ed2 | 9344 | of Bash. The latest version of Bash is always available for FTP from |
4a8bb13f | 9345 | `ftp://ftp.gnu.org/pub/gnu/bash/'. |
ccc6cda3 | 9346 | |
bb70624e JA |
9347 | Once you have determined that a bug actually exists, use the |
9348 | `bashbug' command to submit a bug report. If you have a fix, you are | |
9349 | encouraged to mail that as well! Suggestions and `philosophical' bug | |
9350 | reports may be mailed to <bug-bash@gnu.org> or posted to the Usenet | |
9351 | newsgroup `gnu.bash.bug'. | |
ccc6cda3 | 9352 | |
bb70624e JA |
9353 | All bug reports should include: |
9354 | * The version number of Bash. | |
ccc6cda3 | 9355 | |
bb70624e | 9356 | * The hardware and operating system. |
ccc6cda3 | 9357 | |
bb70624e | 9358 | * The compiler used to compile Bash. |
ccc6cda3 | 9359 | |
bb70624e | 9360 | * A description of the bug behaviour. |
ccc6cda3 | 9361 | |
bb70624e JA |
9362 | * A short script or `recipe' which exercises the bug and may be used |
9363 | to reproduce it. | |
ccc6cda3 | 9364 | |
bb70624e JA |
9365 | `bashbug' inserts the first three items automatically into the template |
9366 | it provides for filing a bug report. | |
9367 | ||
6932f7f5 CR |
9368 | Please send all reports concerning this manual to |
9369 | <chet.ramey@case.edu>. | |
ccc6cda3 JA |
9370 | |
9371 | \1f | |
c2a47ea9 | 9372 | File: bashref.info, Node: Major Differences From The Bourne Shell, Next: GNU Free Documentation License, Prev: Reporting Bugs, Up: Top |
ccc6cda3 | 9373 | |
37c41ab1 CR |
9374 | Appendix B Major Differences From The Bourne Shell |
9375 | ************************************************** | |
ccc6cda3 | 9376 | |
37c41ab1 | 9377 | Bash implements essentially the same grammar, parameter and variable |
bb70624e | 9378 | expansion, redirection, and quoting as the Bourne Shell. Bash uses the |
ac18b312 CR |
9379 | POSIX standard as the specification of how these features are to be |
9380 | implemented. There are some differences between the traditional Bourne | |
9381 | shell and Bash; this section quickly details the differences of | |
bb70624e JA |
9382 | significance. A number of these differences are explained in greater |
9383 | depth in previous sections. This section uses the version of `sh' | |
1c72c0cd CR |
9384 | included in SVR4.2 (the last version of the historical Bourne shell) as |
9385 | the baseline reference. | |
ccc6cda3 | 9386 | |
bb70624e | 9387 | * Bash is POSIX-conformant, even where the POSIX specification |
28ef6c31 | 9388 | differs from traditional `sh' behavior (*note Bash POSIX Mode::). |
ccc6cda3 | 9389 | |
bb70624e | 9390 | * Bash has multi-character invocation options (*note Invoking |
28ef6c31 | 9391 | Bash::). |
ccc6cda3 | 9392 | |
28ef6c31 | 9393 | * Bash has command-line editing (*note Command Line Editing::) and |
bb70624e | 9394 | the `bind' builtin. |
ccc6cda3 | 9395 | |
bb70624e | 9396 | * Bash provides a programmable word completion mechanism (*note |
6a8fd0ed CR |
9397 | Programmable Completion::), and builtin commands `complete', |
9398 | `compgen', and `compopt', to manipulate it. | |
ccc6cda3 | 9399 | |
28ef6c31 | 9400 | * Bash has command history (*note Bash History Facilities::) and the |
5e13499c CR |
9401 | `history' and `fc' builtins to manipulate it. The Bash history |
9402 | list maintains timestamp information and uses the value of the | |
9403 | `HISTTIMEFORMAT' variable to display it. | |
ccc6cda3 | 9404 | |
bb70624e | 9405 | * Bash implements `csh'-like history expansion (*note History |
28ef6c31 | 9406 | Interaction::). |
ccc6cda3 | 9407 | |
28ef6c31 | 9408 | * Bash has one-dimensional array variables (*note Arrays::), and the |
bb70624e JA |
9409 | appropriate variable expansions and assignment syntax to use them. |
9410 | Several of the Bash builtins take options to act on arrays. Bash | |
9411 | provides a number of built-in array variables. | |
ccc6cda3 | 9412 | |
bb70624e JA |
9413 | * The `$'...'' quoting syntax, which expands ANSI-C |
9414 | backslash-escaped characters in the text between the single quotes, | |
28ef6c31 | 9415 | is supported (*note ANSI-C Quoting::). |
ccc6cda3 | 9416 | |
bb70624e JA |
9417 | * Bash supports the `$"..."' quoting syntax to do locale-specific |
9418 | translation of the characters between the double quotes. The | |
9419 | `-D', `--dump-strings', and `--dump-po-strings' invocation options | |
9420 | list the translatable strings found in a script (*note Locale | |
28ef6c31 | 9421 | Translation::). |
ccc6cda3 | 9422 | |
bb70624e | 9423 | * Bash implements the `!' keyword to negate the return value of a |
28ef6c31 | 9424 | pipeline (*note Pipelines::). Very useful when an `if' statement |
1c72c0cd CR |
9425 | needs to act only if a test fails. The Bash `-o pipefail' option |
9426 | to `set' will cause a pipeline to return a failure status if any | |
9427 | command fails. | |
ccc6cda3 | 9428 | |
bb70624e | 9429 | * Bash has the `time' reserved word and command timing (*note |
28ef6c31 | 9430 | Pipelines::). The display of the timing statistics may be |
bb70624e | 9431 | controlled with the `TIMEFORMAT' variable. |
ccc6cda3 | 9432 | |
bb70624e JA |
9433 | * Bash implements the `for (( EXPR1 ; EXPR2 ; EXPR3 ))' arithmetic |
9434 | for command, similar to the C language (*note Looping | |
28ef6c31 | 9435 | Constructs::). |
ccc6cda3 | 9436 | |
bb70624e | 9437 | * Bash includes the `select' compound command, which allows the |
28ef6c31 | 9438 | generation of simple menus (*note Conditional Constructs::). |
ccc6cda3 | 9439 | |
bb70624e | 9440 | * Bash includes the `[[' compound command, which makes conditional |
1c72c0cd CR |
9441 | testing part of the shell grammar (*note Conditional |
9442 | Constructs::), including optional regular expression matching. | |
9443 | ||
9444 | * Bash provides optional case-insensitive matching for the `case' and | |
9445 | `[[' constructs. | |
ccc6cda3 | 9446 | |
28ef6c31 JA |
9447 | * Bash includes brace expansion (*note Brace Expansion::) and tilde |
9448 | expansion (*note Tilde Expansion::). | |
ccc6cda3 | 9449 | |
bb70624e | 9450 | * Bash implements command aliases and the `alias' and `unalias' |
28ef6c31 | 9451 | builtins (*note Aliases::). |
ccc6cda3 | 9452 | |
bb70624e | 9453 | * Bash provides shell arithmetic, the `((' compound command (*note |
28ef6c31 JA |
9454 | Conditional Constructs::), and arithmetic expansion (*note Shell |
9455 | Arithmetic::). | |
ccc6cda3 | 9456 | |
bb70624e JA |
9457 | * Variables present in the shell's initial environment are |
9458 | automatically exported to child processes. The Bourne shell does | |
9459 | not normally do this unless the variables are explicitly marked | |
9460 | using the `export' command. | |
ccc6cda3 | 9461 | |
1c72c0cd CR |
9462 | * Bash supports the `+=' assignment operator, which appends to the |
9463 | value of the variable named on the left hand side. | |
9464 | ||
bb70624e JA |
9465 | * Bash includes the POSIX pattern removal `%', `#', `%%' and `##' |
9466 | expansions to remove leading or trailing substrings from variable | |
28ef6c31 | 9467 | values (*note Shell Parameter Expansion::). |
ccc6cda3 | 9468 | |
bb70624e | 9469 | * The expansion `${#xx}', which returns the length of `${xx}', is |
28ef6c31 | 9470 | supported (*note Shell Parameter Expansion::). |
ccc6cda3 | 9471 | |
bb70624e JA |
9472 | * The expansion `${var:'OFFSET`[:'LENGTH`]}', which expands to the |
9473 | substring of `var''s value of length LENGTH, beginning at OFFSET, | |
28ef6c31 | 9474 | is present (*note Shell Parameter Expansion::). |
ccc6cda3 | 9475 | |
bb70624e JA |
9476 | * The expansion `${var/[/]'PATTERN`[/'REPLACEMENT`]}', which matches |
9477 | PATTERN and replaces it with REPLACEMENT in the value of `var', is | |
28ef6c31 | 9478 | available (*note Shell Parameter Expansion::). |
ccc6cda3 | 9479 | |
bb70624e JA |
9480 | * The expansion `${!PREFIX}*' expansion, which expands to the names |
9481 | of all shell variables whose names begin with PREFIX, is available | |
28ef6c31 | 9482 | (*note Shell Parameter Expansion::). |
ccc6cda3 | 9483 | |
bb70624e | 9484 | * Bash has INDIRECT variable expansion using `${!word}' (*note Shell |
28ef6c31 | 9485 | Parameter Expansion::). |
ccc6cda3 | 9486 | |
bb70624e | 9487 | * Bash can expand positional parameters beyond `$9' using `${NUM}'. |
ccc6cda3 | 9488 | |
bb70624e | 9489 | * The POSIX `$()' form of command substitution is implemented (*note |
28ef6c31 | 9490 | Command Substitution::), and preferred to the Bourne shell's ```' |
bb70624e | 9491 | (which is also implemented for backwards compatibility). |
ccc6cda3 | 9492 | |
28ef6c31 | 9493 | * Bash has process substitution (*note Process Substitution::). |
ccc6cda3 | 9494 | |
bb70624e JA |
9495 | * Bash automatically assigns variables that provide information |
9496 | about the current user (`UID', `EUID', and `GROUPS'), the current | |
9497 | host (`HOSTTYPE', `OSTYPE', `MACHTYPE', and `HOSTNAME'), and the | |
9498 | instance of Bash that is running (`BASH', `BASH_VERSION', and | |
9499 | `BASH_VERSINFO'). *Note Bash Variables::, for details. | |
ccc6cda3 | 9500 | |
bb70624e | 9501 | * The `IFS' variable is used to split only the results of expansion, |
28ef6c31 | 9502 | not all words (*note Word Splitting::). This closes a |
bb70624e | 9503 | longstanding shell security hole. |
ccc6cda3 | 9504 | |
ac18b312 CR |
9505 | * Bash implements the full set of POSIX filename expansion operators, |
9506 | including CHARACTER CLASSES, EQUIVALENCE CLASSES, and COLLATING | |
9507 | SYMBOLS (*note Filename Expansion::). | |
ccc6cda3 | 9508 | |
bb70624e | 9509 | * Bash implements extended pattern matching features when the |
28ef6c31 | 9510 | `extglob' shell option is enabled (*note Pattern Matching::). |
ccc6cda3 | 9511 | |
bb70624e JA |
9512 | * It is possible to have a variable and a function with the same |
9513 | name; `sh' does not separate the two name spaces. | |
ccc6cda3 | 9514 | |
bb70624e JA |
9515 | * Bash functions are permitted to have local variables using the |
9516 | `local' builtin, and thus useful recursive functions may be written | |
28ef6c31 | 9517 | (*note Bash Builtins::). |
ccc6cda3 | 9518 | |
bb70624e | 9519 | * Variable assignments preceding commands affect only that command, |
28ef6c31 | 9520 | even builtins and functions (*note Environment::). In `sh', all |
bb70624e JA |
9521 | variable assignments preceding commands are global unless the |
9522 | command is executed from the file system. | |
ccc6cda3 | 9523 | |
bb70624e | 9524 | * Bash performs filename expansion on filenames specified as operands |
28ef6c31 | 9525 | to input and output redirection operators (*note Redirections::). |
ccc6cda3 | 9526 | |
bb70624e JA |
9527 | * Bash contains the `<>' redirection operator, allowing a file to be |
9528 | opened for both reading and writing, and the `&>' redirection | |
9529 | operator, for directing standard output and standard error to the | |
28ef6c31 | 9530 | same file (*note Redirections::). |
d166f048 | 9531 | |
1c72c0cd CR |
9532 | * Bash includes the `<<<' redirection operator, allowing a string to |
9533 | be used as the standard input to a command. | |
9534 | ||
9535 | * Bash implements the `[n]<&WORD' and `[n]>&WORD' redirection | |
9536 | operators, which move one file descriptor to another. | |
9537 | ||
bb70624e | 9538 | * Bash treats a number of filenames specially when they are used in |
28ef6c31 | 9539 | redirection operators (*note Redirections::). |
ccc6cda3 | 9540 | |
bb70624e | 9541 | * Bash can open network connections to arbitrary machines and |
28ef6c31 | 9542 | services with the redirection operators (*note Redirections::). |
ccc6cda3 | 9543 | |
bb70624e | 9544 | * The `noclobber' option is available to avoid overwriting existing |
28ef6c31 JA |
9545 | files with output redirection (*note The Set Builtin::). The `>|' |
9546 | redirection operator may be used to override `noclobber'. | |
ccc6cda3 | 9547 | |
28ef6c31 JA |
9548 | * The Bash `cd' and `pwd' builtins (*note Bourne Shell Builtins::) |
9549 | each take `-L' and `-P' options to switch between logical and | |
bb70624e | 9550 | physical modes. |
b72432fd | 9551 | |
bb70624e JA |
9552 | * Bash allows a function to override a builtin with the same name, |
9553 | and provides access to that builtin's functionality within the | |
9554 | function via the `builtin' and `command' builtins (*note Bash | |
28ef6c31 | 9555 | Builtins::). |
ccc6cda3 | 9556 | |
bb70624e | 9557 | * The `command' builtin allows selective disabling of functions when |
28ef6c31 | 9558 | command lookup is performed (*note Bash Builtins::). |
ccc6cda3 | 9559 | |
bb70624e | 9560 | * Individual builtins may be enabled or disabled using the `enable' |
28ef6c31 | 9561 | builtin (*note Bash Builtins::). |
cce855bc | 9562 | |
bb70624e JA |
9563 | * The Bash `exec' builtin takes additional options that allow users |
9564 | to control the contents of the environment passed to the executed | |
9565 | command, and what the zeroth argument to the command is to be | |
28ef6c31 | 9566 | (*note Bourne Shell Builtins::). |
cce855bc | 9567 | |
bb70624e | 9568 | * Shell functions may be exported to children via the environment |
28ef6c31 | 9569 | using `export -f' (*note Shell Functions::). |
cce855bc | 9570 | |
bb70624e JA |
9571 | * The Bash `export', `readonly', and `declare' builtins can take a |
9572 | `-f' option to act on shell functions, a `-p' option to display | |
9573 | variables with various attributes set in a format that can be used | |
9574 | as shell input, a `-n' option to remove various variable | |
9575 | attributes, and `name=value' arguments to set variable attributes | |
9576 | and values simultaneously. | |
ccc6cda3 | 9577 | |
bb70624e JA |
9578 | * The Bash `hash' builtin allows a name to be associated with an |
9579 | arbitrary filename, even when that filename cannot be found by | |
9580 | searching the `$PATH', using `hash -p' (*note Bourne Shell | |
28ef6c31 | 9581 | Builtins::). |
ccc6cda3 | 9582 | |
bb70624e | 9583 | * Bash includes a `help' builtin for quick reference to shell |
28ef6c31 | 9584 | facilities (*note Bash Builtins::). |
ccc6cda3 | 9585 | |
bb70624e | 9586 | * The `printf' builtin is available to display formatted output |
28ef6c31 | 9587 | (*note Bash Builtins::). |
ccc6cda3 | 9588 | |
28ef6c31 | 9589 | * The Bash `read' builtin (*note Bash Builtins::) will read a line |
bb70624e JA |
9590 | ending in `\' with the `-r' option, and will use the `REPLY' |
9591 | variable as a default if no non-option arguments are supplied. | |
9592 | The Bash `read' builtin also accepts a prompt string with the `-p' | |
9593 | option and will use Readline to obtain the line when given the | |
9594 | `-e' option. The `read' builtin also has additional options to | |
9595 | control input: the `-s' option will turn off echoing of input | |
9596 | characters as they are read, the `-t' option will allow `read' to | |
9597 | time out if input does not arrive within a specified number of | |
9598 | seconds, the `-n' option will allow reading only a specified | |
9599 | number of characters rather than a full line, and the `-d' option | |
9600 | will read until a particular character rather than newline. | |
ccc6cda3 | 9601 | |
bb70624e JA |
9602 | * The `return' builtin may be used to abort execution of scripts |
9603 | executed with the `.' or `source' builtins (*note Bourne Shell | |
28ef6c31 | 9604 | Builtins::). |
d166f048 | 9605 | |
bb70624e | 9606 | * Bash includes the `shopt' builtin, for finer control of shell |
d3ad40de CR |
9607 | optional capabilities (*note The Shopt Builtin::), and allows |
9608 | these options to be set and unset at shell invocation (*note | |
9609 | Invoking Bash::). | |
d166f048 | 9610 | |
bb70624e | 9611 | * Bash has much more optional behavior controllable with the `set' |
28ef6c31 | 9612 | builtin (*note The Set Builtin::). |
cce855bc | 9613 | |
5e13499c CR |
9614 | * The `-x' (`xtrace') option displays commands other than simple |
9615 | commands when performing an execution trace (*note The Set | |
9616 | Builtin::). | |
9617 | ||
28ef6c31 | 9618 | * The `test' builtin (*note Bourne Shell Builtins::) is slightly |
bb70624e JA |
9619 | different, as it implements the POSIX algorithm, which specifies |
9620 | the behavior based on the number of arguments. | |
ccc6cda3 | 9621 | |
5e13499c CR |
9622 | * Bash includes the `caller' builtin, which displays the context of |
9623 | any active subroutine call (a shell function or a script executed | |
9624 | with the `.' or `source' builtins). This supports the bash | |
9625 | debugger. | |
9626 | ||
28ef6c31 | 9627 | * The `trap' builtin (*note Bourne Shell Builtins::) allows a |
bb70624e | 9628 | `DEBUG' pseudo-signal specification, similar to `EXIT'. Commands |
d3a24ed2 CR |
9629 | specified with a `DEBUG' trap are executed before every simple |
9630 | command, `for' command, `case' command, `select' command, every | |
9631 | arithmetic `for' command, and before the first command executes in | |
9632 | a shell function. The `DEBUG' trap is not inherited by shell | |
9633 | functions unless the function has been given the `trace' attribute | |
9634 | or the `functrace' option has been enabled using the `shopt' | |
9635 | builtin. The `extdebug' shell option has additional effects on the | |
9636 | `DEBUG' trap. | |
d166f048 | 9637 | |
f73dda09 JA |
9638 | The `trap' builtin (*note Bourne Shell Builtins::) allows an `ERR' |
9639 | pseudo-signal specification, similar to `EXIT' and `DEBUG'. | |
9640 | Commands specified with an `ERR' trap are executed after a simple | |
9641 | command fails, with a few exceptions. The `ERR' trap is not | |
d3a24ed2 CR |
9642 | inherited by shell functions unless the `-o errtrace' option to |
9643 | the `set' builtin is enabled. | |
9644 | ||
9645 | The `trap' builtin (*note Bourne Shell Builtins::) allows a | |
9646 | `RETURN' pseudo-signal specification, similar to `EXIT' and | |
9647 | `DEBUG'. Commands specified with an `RETURN' trap are executed | |
9648 | before execution resumes after a shell function or a shell script | |
9649 | executed with `.' or `source' returns. The `RETURN' trap is not | |
8fed3589 CR |
9650 | inherited by shell functions unless the function has been given |
9651 | the `trace' attribute or the `functrace' option has been enabled | |
9652 | using the `shopt' builtin. | |
f73dda09 | 9653 | |
bb70624e | 9654 | * The Bash `type' builtin is more extensive and gives more |
28ef6c31 | 9655 | information about the names it finds (*note Bash Builtins::). |
cce855bc | 9656 | |
bb70624e JA |
9657 | * The Bash `umask' builtin permits a `-p' option to cause the output |
9658 | to be displayed in the form of a `umask' command that may be | |
28ef6c31 | 9659 | reused as input (*note Bourne Shell Builtins::). |
d166f048 | 9660 | |
bb70624e JA |
9661 | * Bash implements a `csh'-like directory stack, and provides the |
9662 | `pushd', `popd', and `dirs' builtins to manipulate it (*note The | |
28ef6c31 | 9663 | Directory Stack::). Bash also makes the directory stack visible |
bb70624e | 9664 | as the value of the `DIRSTACK' shell variable. |
d166f048 | 9665 | |
bb70624e | 9666 | * Bash interprets special backslash-escaped characters in the prompt |
122f603c | 9667 | strings when interactive (*note Controlling the Prompt::). |
d166f048 | 9668 | |
bb70624e | 9669 | * The Bash restricted mode is more useful (*note The Restricted |
28ef6c31 | 9670 | Shell::); the SVR4.2 shell restricted mode is too limited. |
ccc6cda3 | 9671 | |
bb70624e | 9672 | * The `disown' builtin can remove a job from the internal shell job |
28ef6c31 | 9673 | table (*note Job Control Builtins::) or suppress the sending of |
bb70624e | 9674 | `SIGHUP' to a job when the shell exits as the result of a `SIGHUP'. |
ccc6cda3 | 9675 | |
1c72c0cd CR |
9676 | * Bash includes a number of features to support a separate debugger |
9677 | for shell scripts. | |
9678 | ||
bb70624e JA |
9679 | * The SVR4.2 shell has two privilege-related builtins (`mldmode' and |
9680 | `priv') not present in Bash. | |
ccc6cda3 | 9681 | |
bb70624e | 9682 | * Bash does not have the `stop' or `newgrp' builtins. |
d166f048 | 9683 | |
bb70624e JA |
9684 | * Bash does not use the `SHACCT' variable or perform shell |
9685 | accounting. | |
d166f048 | 9686 | |
bb70624e | 9687 | * The SVR4.2 `sh' uses a `TIMEOUT' variable like Bash uses `TMOUT'. |
ccc6cda3 | 9688 | |
28ef6c31 | 9689 | |
6a8fd0ed | 9690 | More features unique to Bash may be found in *note Bash Features::. |
ccc6cda3 | 9691 | |
37c41ab1 CR |
9692 | B.1 Implementation Differences From The SVR4.2 Shell |
9693 | ==================================================== | |
ccc6cda3 | 9694 | |
37c41ab1 CR |
9695 | Since Bash is a completely new implementation, it does not suffer from |
9696 | many of the limitations of the SVR4.2 shell. For instance: | |
ccc6cda3 | 9697 | |
bb70624e JA |
9698 | * Bash does not fork a subshell when redirecting into or out of a |
9699 | shell control structure such as an `if' or `while' statement. | |
ccc6cda3 | 9700 | |
bb70624e JA |
9701 | * Bash does not allow unbalanced quotes. The SVR4.2 shell will |
9702 | silently insert a needed closing quote at `EOF' under certain | |
9703 | circumstances. This can be the cause of some hard-to-find errors. | |
ccc6cda3 | 9704 | |
bb70624e JA |
9705 | * The SVR4.2 shell uses a baroque memory management scheme based on |
9706 | trapping `SIGSEGV'. If the shell is started from a process with | |
9707 | `SIGSEGV' blocked (e.g., by using the `system()' C library | |
9708 | function call), it misbehaves badly. | |
ccc6cda3 | 9709 | |
bb70624e JA |
9710 | * In a questionable attempt at security, the SVR4.2 shell, when |
9711 | invoked without the `-p' option, will alter its real and effective | |
9712 | UID and GID if they are less than some magic threshold value, | |
9713 | commonly 100. This can lead to unexpected results. | |
ccc6cda3 | 9714 | |
bb70624e JA |
9715 | * The SVR4.2 shell does not allow users to trap `SIGSEGV', |
9716 | `SIGALRM', or `SIGCHLD'. | |
ccc6cda3 | 9717 | |
bb70624e JA |
9718 | * The SVR4.2 shell does not allow the `IFS', `MAILCHECK', `PATH', |
9719 | `PS1', or `PS2' variables to be unset. | |
ccc6cda3 | 9720 | |
bb70624e | 9721 | * The SVR4.2 shell treats `^' as the undocumented equivalent of `|'. |
ccc6cda3 | 9722 | |
bb70624e JA |
9723 | * Bash allows multiple option arguments when it is invoked (`-x -v'); |
9724 | the SVR4.2 shell allows only one option argument (`-xv'). In | |
9725 | fact, some versions of the shell dump core if the second argument | |
9726 | begins with a `-'. | |
ccc6cda3 | 9727 | |
bb70624e | 9728 | * The SVR4.2 shell exits a script if any builtin fails; Bash exits a |
ac18b312 CR |
9729 | script only if one of the POSIX special builtins fails, and only |
9730 | for certain failures, as enumerated in the POSIX standard. | |
ccc6cda3 | 9731 | |
bb70624e JA |
9732 | * The SVR4.2 shell behaves differently when invoked as `jsh' (it |
9733 | turns on job control). | |
ccc6cda3 JA |
9734 | |
9735 | \1f | |
c2a47ea9 | 9736 | File: bashref.info, Node: GNU Free Documentation License, Next: Indexes, Prev: Major Differences From The Bourne Shell, Up: Top |
d3a24ed2 | 9737 | |
c2a47ea9 CR |
9738 | Appendix C GNU Free Documentation License |
9739 | ***************************************** | |
d3a24ed2 | 9740 | |
1231ac47 | 9741 | Version 1.3, 3 November 2008 |
37c41ab1 | 9742 | |
1231ac47 CR |
9743 | Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. |
9744 | `http://fsf.org/' | |
37c41ab1 | 9745 | |
d3a24ed2 CR |
9746 | Everyone is permitted to copy and distribute verbatim copies |
9747 | of this license document, but changing it is not allowed. | |
9748 | ||
9749 | 0. PREAMBLE | |
9750 | ||
9751 | The purpose of this License is to make a manual, textbook, or other | |
9752 | functional and useful document "free" in the sense of freedom: to | |
9753 | assure everyone the effective freedom to copy and redistribute it, | |
9754 | with or without modifying it, either commercially or | |
9755 | noncommercially. Secondarily, this License preserves for the | |
9756 | author and publisher a way to get credit for their work, while not | |
9757 | being considered responsible for modifications made by others. | |
9758 | ||
9759 | This License is a kind of "copyleft", which means that derivative | |
9760 | works of the document must themselves be free in the same sense. | |
9761 | It complements the GNU General Public License, which is a copyleft | |
9762 | license designed for free software. | |
9763 | ||
9764 | We have designed this License in order to use it for manuals for | |
9765 | free software, because free software needs free documentation: a | |
9766 | free program should come with manuals providing the same freedoms | |
9767 | that the software does. But this License is not limited to | |
9768 | software manuals; it can be used for any textual work, regardless | |
9769 | of subject matter or whether it is published as a printed book. | |
9770 | We recommend this License principally for works whose purpose is | |
9771 | instruction or reference. | |
9772 | ||
9773 | 1. APPLICABILITY AND DEFINITIONS | |
9774 | ||
9775 | This License applies to any manual or other work, in any medium, | |
9776 | that contains a notice placed by the copyright holder saying it | |
9777 | can be distributed under the terms of this License. Such a notice | |
9778 | grants a world-wide, royalty-free license, unlimited in duration, | |
9779 | to use that work under the conditions stated herein. The | |
9780 | "Document", below, refers to any such manual or work. Any member | |
9781 | of the public is a licensee, and is addressed as "you". You | |
9782 | accept the license if you copy, modify or distribute the work in a | |
9783 | way requiring permission under copyright law. | |
9784 | ||
9785 | A "Modified Version" of the Document means any work containing the | |
9786 | Document or a portion of it, either copied verbatim, or with | |
9787 | modifications and/or translated into another language. | |
9788 | ||
9789 | A "Secondary Section" is a named appendix or a front-matter section | |
9790 | of the Document that deals exclusively with the relationship of the | |
9791 | publishers or authors of the Document to the Document's overall | |
9792 | subject (or to related matters) and contains nothing that could | |
9793 | fall directly within that overall subject. (Thus, if the Document | |
9794 | is in part a textbook of mathematics, a Secondary Section may not | |
9795 | explain any mathematics.) The relationship could be a matter of | |
9796 | historical connection with the subject or with related matters, or | |
9797 | of legal, commercial, philosophical, ethical or political position | |
9798 | regarding them. | |
9799 | ||
9800 | The "Invariant Sections" are certain Secondary Sections whose | |
9801 | titles are designated, as being those of Invariant Sections, in | |
9802 | the notice that says that the Document is released under this | |
9803 | License. If a section does not fit the above definition of | |
9804 | Secondary then it is not allowed to be designated as Invariant. | |
9805 | The Document may contain zero Invariant Sections. If the Document | |
9806 | does not identify any Invariant Sections then there are none. | |
9807 | ||
9808 | The "Cover Texts" are certain short passages of text that are | |
9809 | listed, as Front-Cover Texts or Back-Cover Texts, in the notice | |
9810 | that says that the Document is released under this License. A | |
9811 | Front-Cover Text may be at most 5 words, and a Back-Cover Text may | |
9812 | be at most 25 words. | |
9813 | ||
9814 | A "Transparent" copy of the Document means a machine-readable copy, | |
9815 | represented in a format whose specification is available to the | |
9816 | general public, that is suitable for revising the document | |
9817 | straightforwardly with generic text editors or (for images | |
9818 | composed of pixels) generic paint programs or (for drawings) some | |
9819 | widely available drawing editor, and that is suitable for input to | |
9820 | text formatters or for automatic translation to a variety of | |
9821 | formats suitable for input to text formatters. A copy made in an | |
9822 | otherwise Transparent file format whose markup, or absence of | |
9823 | markup, has been arranged to thwart or discourage subsequent | |
9824 | modification by readers is not Transparent. An image format is | |
9825 | not Transparent if used for any substantial amount of text. A | |
9826 | copy that is not "Transparent" is called "Opaque". | |
9827 | ||
9828 | Examples of suitable formats for Transparent copies include plain | |
9829 | ASCII without markup, Texinfo input format, LaTeX input format, | |
9830 | SGML or XML using a publicly available DTD, and | |
9831 | standard-conforming simple HTML, PostScript or PDF designed for | |
9832 | human modification. Examples of transparent image formats include | |
9833 | PNG, XCF and JPG. Opaque formats include proprietary formats that | |
9834 | can be read and edited only by proprietary word processors, SGML or | |
9835 | XML for which the DTD and/or processing tools are not generally | |
9836 | available, and the machine-generated HTML, PostScript or PDF | |
9837 | produced by some word processors for output purposes only. | |
9838 | ||
9839 | The "Title Page" means, for a printed book, the title page itself, | |
9840 | plus such following pages as are needed to hold, legibly, the | |
9841 | material this License requires to appear in the title page. For | |
9842 | works in formats which do not have any title page as such, "Title | |
9843 | Page" means the text near the most prominent appearance of the | |
9844 | work's title, preceding the beginning of the body of the text. | |
9845 | ||
1231ac47 CR |
9846 | The "publisher" means any person or entity that distributes copies |
9847 | of the Document to the public. | |
9848 | ||
d3a24ed2 CR |
9849 | A section "Entitled XYZ" means a named subunit of the Document |
9850 | whose title either is precisely XYZ or contains XYZ in parentheses | |
9851 | following text that translates XYZ in another language. (Here XYZ | |
9852 | stands for a specific section name mentioned below, such as | |
9853 | "Acknowledgements", "Dedications", "Endorsements", or "History".) | |
9854 | To "Preserve the Title" of such a section when you modify the | |
9855 | Document means that it remains a section "Entitled XYZ" according | |
9856 | to this definition. | |
9857 | ||
9858 | The Document may include Warranty Disclaimers next to the notice | |
9859 | which states that this License applies to the Document. These | |
9860 | Warranty Disclaimers are considered to be included by reference in | |
9861 | this License, but only as regards disclaiming warranties: any other | |
9862 | implication that these Warranty Disclaimers may have is void and | |
9863 | has no effect on the meaning of this License. | |
9864 | ||
9865 | 2. VERBATIM COPYING | |
9866 | ||
9867 | You may copy and distribute the Document in any medium, either | |
9868 | commercially or noncommercially, provided that this License, the | |
9869 | copyright notices, and the license notice saying this License | |
9870 | applies to the Document are reproduced in all copies, and that you | |
9871 | add no other conditions whatsoever to those of this License. You | |
9872 | may not use technical measures to obstruct or control the reading | |
9873 | or further copying of the copies you make or distribute. However, | |
9874 | you may accept compensation in exchange for copies. If you | |
9875 | distribute a large enough number of copies you must also follow | |
9876 | the conditions in section 3. | |
9877 | ||
9878 | You may also lend copies, under the same conditions stated above, | |
9879 | and you may publicly display copies. | |
9880 | ||
9881 | 3. COPYING IN QUANTITY | |
9882 | ||
9883 | If you publish printed copies (or copies in media that commonly | |
9884 | have printed covers) of the Document, numbering more than 100, and | |
9885 | the Document's license notice requires Cover Texts, you must | |
9886 | enclose the copies in covers that carry, clearly and legibly, all | |
9887 | these Cover Texts: Front-Cover Texts on the front cover, and | |
9888 | Back-Cover Texts on the back cover. Both covers must also clearly | |
9889 | and legibly identify you as the publisher of these copies. The | |
9890 | front cover must present the full title with all words of the | |
9891 | title equally prominent and visible. You may add other material | |
9892 | on the covers in addition. Copying with changes limited to the | |
9893 | covers, as long as they preserve the title of the Document and | |
9894 | satisfy these conditions, can be treated as verbatim copying in | |
9895 | other respects. | |
9896 | ||
9897 | If the required texts for either cover are too voluminous to fit | |
9898 | legibly, you should put the first ones listed (as many as fit | |
9899 | reasonably) on the actual cover, and continue the rest onto | |
9900 | adjacent pages. | |
9901 | ||
9902 | If you publish or distribute Opaque copies of the Document | |
9903 | numbering more than 100, you must either include a | |
9904 | machine-readable Transparent copy along with each Opaque copy, or | |
9905 | state in or with each Opaque copy a computer-network location from | |
9906 | which the general network-using public has access to download | |
9907 | using public-standard network protocols a complete Transparent | |
9908 | copy of the Document, free of added material. If you use the | |
9909 | latter option, you must take reasonably prudent steps, when you | |
9910 | begin distribution of Opaque copies in quantity, to ensure that | |
9911 | this Transparent copy will remain thus accessible at the stated | |
9912 | location until at least one year after the last time you | |
9913 | distribute an Opaque copy (directly or through your agents or | |
9914 | retailers) of that edition to the public. | |
9915 | ||
9916 | It is requested, but not required, that you contact the authors of | |
9917 | the Document well before redistributing any large number of | |
9918 | copies, to give them a chance to provide you with an updated | |
9919 | version of the Document. | |
9920 | ||
9921 | 4. MODIFICATIONS | |
9922 | ||
9923 | You may copy and distribute a Modified Version of the Document | |
9924 | under the conditions of sections 2 and 3 above, provided that you | |
9925 | release the Modified Version under precisely this License, with | |
9926 | the Modified Version filling the role of the Document, thus | |
9927 | licensing distribution and modification of the Modified Version to | |
9928 | whoever possesses a copy of it. In addition, you must do these | |
9929 | things in the Modified Version: | |
9930 | ||
9931 | A. Use in the Title Page (and on the covers, if any) a title | |
9932 | distinct from that of the Document, and from those of | |
9933 | previous versions (which should, if there were any, be listed | |
9934 | in the History section of the Document). You may use the | |
9935 | same title as a previous version if the original publisher of | |
9936 | that version gives permission. | |
9937 | ||
9938 | B. List on the Title Page, as authors, one or more persons or | |
9939 | entities responsible for authorship of the modifications in | |
9940 | the Modified Version, together with at least five of the | |
9941 | principal authors of the Document (all of its principal | |
9942 | authors, if it has fewer than five), unless they release you | |
9943 | from this requirement. | |
9944 | ||
9945 | C. State on the Title page the name of the publisher of the | |
9946 | Modified Version, as the publisher. | |
9947 | ||
9948 | D. Preserve all the copyright notices of the Document. | |
9949 | ||
9950 | E. Add an appropriate copyright notice for your modifications | |
9951 | adjacent to the other copyright notices. | |
9952 | ||
9953 | F. Include, immediately after the copyright notices, a license | |
9954 | notice giving the public permission to use the Modified | |
9955 | Version under the terms of this License, in the form shown in | |
9956 | the Addendum below. | |
9957 | ||
9958 | G. Preserve in that license notice the full lists of Invariant | |
9959 | Sections and required Cover Texts given in the Document's | |
9960 | license notice. | |
9961 | ||
9962 | H. Include an unaltered copy of this License. | |
9963 | ||
9964 | I. Preserve the section Entitled "History", Preserve its Title, | |
9965 | and add to it an item stating at least the title, year, new | |
9966 | authors, and publisher of the Modified Version as given on | |
9967 | the Title Page. If there is no section Entitled "History" in | |
9968 | the Document, create one stating the title, year, authors, | |
9969 | and publisher of the Document as given on its Title Page, | |
9970 | then add an item describing the Modified Version as stated in | |
9971 | the previous sentence. | |
9972 | ||
9973 | J. Preserve the network location, if any, given in the Document | |
9974 | for public access to a Transparent copy of the Document, and | |
9975 | likewise the network locations given in the Document for | |
9976 | previous versions it was based on. These may be placed in | |
9977 | the "History" section. You may omit a network location for a | |
9978 | work that was published at least four years before the | |
9979 | Document itself, or if the original publisher of the version | |
9980 | it refers to gives permission. | |
9981 | ||
9982 | K. For any section Entitled "Acknowledgements" or "Dedications", | |
9983 | Preserve the Title of the section, and preserve in the | |
9984 | section all the substance and tone of each of the contributor | |
9985 | acknowledgements and/or dedications given therein. | |
9986 | ||
9987 | L. Preserve all the Invariant Sections of the Document, | |
9988 | unaltered in their text and in their titles. Section numbers | |
9989 | or the equivalent are not considered part of the section | |
9990 | titles. | |
9991 | ||
9992 | M. Delete any section Entitled "Endorsements". Such a section | |
9993 | may not be included in the Modified Version. | |
9994 | ||
9995 | N. Do not retitle any existing section to be Entitled | |
9996 | "Endorsements" or to conflict in title with any Invariant | |
9997 | Section. | |
9998 | ||
9999 | O. Preserve any Warranty Disclaimers. | |
10000 | ||
10001 | If the Modified Version includes new front-matter sections or | |
10002 | appendices that qualify as Secondary Sections and contain no | |
10003 | material copied from the Document, you may at your option | |
10004 | designate some or all of these sections as invariant. To do this, | |
10005 | add their titles to the list of Invariant Sections in the Modified | |
10006 | Version's license notice. These titles must be distinct from any | |
10007 | other section titles. | |
10008 | ||
10009 | You may add a section Entitled "Endorsements", provided it contains | |
10010 | nothing but endorsements of your Modified Version by various | |
10011 | parties--for example, statements of peer review or that the text | |
10012 | has been approved by an organization as the authoritative | |
10013 | definition of a standard. | |
10014 | ||
10015 | You may add a passage of up to five words as a Front-Cover Text, | |
10016 | and a passage of up to 25 words as a Back-Cover Text, to the end | |
10017 | of the list of Cover Texts in the Modified Version. Only one | |
10018 | passage of Front-Cover Text and one of Back-Cover Text may be | |
10019 | added by (or through arrangements made by) any one entity. If the | |
10020 | Document already includes a cover text for the same cover, | |
10021 | previously added by you or by arrangement made by the same entity | |
10022 | you are acting on behalf of, you may not add another; but you may | |
10023 | replace the old one, on explicit permission from the previous | |
10024 | publisher that added the old one. | |
10025 | ||
10026 | The author(s) and publisher(s) of the Document do not by this | |
10027 | License give permission to use their names for publicity for or to | |
10028 | assert or imply endorsement of any Modified Version. | |
10029 | ||
10030 | 5. COMBINING DOCUMENTS | |
10031 | ||
10032 | You may combine the Document with other documents released under | |
10033 | this License, under the terms defined in section 4 above for | |
10034 | modified versions, provided that you include in the combination | |
10035 | all of the Invariant Sections of all of the original documents, | |
10036 | unmodified, and list them all as Invariant Sections of your | |
10037 | combined work in its license notice, and that you preserve all | |
10038 | their Warranty Disclaimers. | |
10039 | ||
10040 | The combined work need only contain one copy of this License, and | |
10041 | multiple identical Invariant Sections may be replaced with a single | |
10042 | copy. If there are multiple Invariant Sections with the same name | |
10043 | but different contents, make the title of each such section unique | |
10044 | by adding at the end of it, in parentheses, the name of the | |
10045 | original author or publisher of that section if known, or else a | |
10046 | unique number. Make the same adjustment to the section titles in | |
10047 | the list of Invariant Sections in the license notice of the | |
10048 | combined work. | |
10049 | ||
10050 | In the combination, you must combine any sections Entitled | |
10051 | "History" in the various original documents, forming one section | |
10052 | Entitled "History"; likewise combine any sections Entitled | |
10053 | "Acknowledgements", and any sections Entitled "Dedications". You | |
10054 | must delete all sections Entitled "Endorsements." | |
10055 | ||
10056 | 6. COLLECTIONS OF DOCUMENTS | |
10057 | ||
10058 | You may make a collection consisting of the Document and other | |
10059 | documents released under this License, and replace the individual | |
10060 | copies of this License in the various documents with a single copy | |
10061 | that is included in the collection, provided that you follow the | |
10062 | rules of this License for verbatim copying of each of the | |
10063 | documents in all other respects. | |
10064 | ||
10065 | You may extract a single document from such a collection, and | |
10066 | distribute it individually under this License, provided you insert | |
10067 | a copy of this License into the extracted document, and follow | |
10068 | this License in all other respects regarding verbatim copying of | |
10069 | that document. | |
10070 | ||
10071 | 7. AGGREGATION WITH INDEPENDENT WORKS | |
10072 | ||
10073 | A compilation of the Document or its derivatives with other | |
10074 | separate and independent documents or works, in or on a volume of | |
10075 | a storage or distribution medium, is called an "aggregate" if the | |
10076 | copyright resulting from the compilation is not used to limit the | |
10077 | legal rights of the compilation's users beyond what the individual | |
c2a47ea9 | 10078 | works permit. When the Document is included in an aggregate, this |
d3a24ed2 CR |
10079 | License does not apply to the other works in the aggregate which |
10080 | are not themselves derivative works of the Document. | |
10081 | ||
10082 | If the Cover Text requirement of section 3 is applicable to these | |
10083 | copies of the Document, then if the Document is less than one half | |
10084 | of the entire aggregate, the Document's Cover Texts may be placed | |
10085 | on covers that bracket the Document within the aggregate, or the | |
10086 | electronic equivalent of covers if the Document is in electronic | |
10087 | form. Otherwise they must appear on printed covers that bracket | |
10088 | the whole aggregate. | |
10089 | ||
10090 | 8. TRANSLATION | |
10091 | ||
10092 | Translation is considered a kind of modification, so you may | |
10093 | distribute translations of the Document under the terms of section | |
10094 | 4. Replacing Invariant Sections with translations requires special | |
10095 | permission from their copyright holders, but you may include | |
10096 | translations of some or all Invariant Sections in addition to the | |
10097 | original versions of these Invariant Sections. You may include a | |
10098 | translation of this License, and all the license notices in the | |
10099 | Document, and any Warranty Disclaimers, provided that you also | |
10100 | include the original English version of this License and the | |
10101 | original versions of those notices and disclaimers. In case of a | |
10102 | disagreement between the translation and the original version of | |
10103 | this License or a notice or disclaimer, the original version will | |
10104 | prevail. | |
10105 | ||
10106 | If a section in the Document is Entitled "Acknowledgements", | |
10107 | "Dedications", or "History", the requirement (section 4) to | |
10108 | Preserve its Title (section 1) will typically require changing the | |
10109 | actual title. | |
10110 | ||
10111 | 9. TERMINATION | |
10112 | ||
10113 | You may not copy, modify, sublicense, or distribute the Document | |
1231ac47 CR |
10114 | except as expressly provided under this License. Any attempt |
10115 | otherwise to copy, modify, sublicense, or distribute it is void, | |
10116 | and will automatically terminate your rights under this License. | |
10117 | ||
10118 | However, if you cease all violation of this License, then your | |
10119 | license from a particular copyright holder is reinstated (a) | |
10120 | provisionally, unless and until the copyright holder explicitly | |
10121 | and finally terminates your license, and (b) permanently, if the | |
10122 | copyright holder fails to notify you of the violation by some | |
10123 | reasonable means prior to 60 days after the cessation. | |
10124 | ||
10125 | Moreover, your license from a particular copyright holder is | |
10126 | reinstated permanently if the copyright holder notifies you of the | |
10127 | violation by some reasonable means, this is the first time you have | |
10128 | received notice of violation of this License (for any work) from | |
10129 | that copyright holder, and you cure the violation prior to 30 days | |
10130 | after your receipt of the notice. | |
10131 | ||
10132 | Termination of your rights under this section does not terminate | |
10133 | the licenses of parties who have received copies or rights from | |
10134 | you under this License. If your rights have been terminated and | |
10135 | not permanently reinstated, receipt of a copy of some or all of | |
10136 | the same material does not give you any rights to use it. | |
d3a24ed2 CR |
10137 | |
10138 | 10. FUTURE REVISIONS OF THIS LICENSE | |
10139 | ||
10140 | The Free Software Foundation may publish new, revised versions of | |
10141 | the GNU Free Documentation License from time to time. Such new | |
10142 | versions will be similar in spirit to the present version, but may | |
10143 | differ in detail to address new problems or concerns. See | |
10144 | `http://www.gnu.org/copyleft/'. | |
10145 | ||
10146 | Each version of the License is given a distinguishing version | |
10147 | number. If the Document specifies that a particular numbered | |
10148 | version of this License "or any later version" applies to it, you | |
10149 | have the option of following the terms and conditions either of | |
10150 | that specified version or of any later version that has been | |
10151 | published (not as a draft) by the Free Software Foundation. If | |
10152 | the Document does not specify a version number of this License, | |
10153 | you may choose any version ever published (not as a draft) by the | |
1231ac47 CR |
10154 | Free Software Foundation. If the Document specifies that a proxy |
10155 | can decide which future versions of this License can be used, that | |
10156 | proxy's public statement of acceptance of a version permanently | |
10157 | authorizes you to choose that version for the Document. | |
10158 | ||
10159 | 11. RELICENSING | |
10160 | ||
10161 | "Massive Multiauthor Collaboration Site" (or "MMC Site") means any | |
10162 | World Wide Web server that publishes copyrightable works and also | |
10163 | provides prominent facilities for anybody to edit those works. A | |
10164 | public wiki that anybody can edit is an example of such a server. | |
10165 | A "Massive Multiauthor Collaboration" (or "MMC") contained in the | |
10166 | site means any set of copyrightable works thus published on the MMC | |
10167 | site. | |
10168 | ||
10169 | "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 | |
10170 | license published by Creative Commons Corporation, a not-for-profit | |
10171 | corporation with a principal place of business in San Francisco, | |
10172 | California, as well as future copyleft versions of that license | |
10173 | published by that same organization. | |
10174 | ||
10175 | "Incorporate" means to publish or republish a Document, in whole or | |
10176 | in part, as part of another Document. | |
10177 | ||
10178 | An MMC is "eligible for relicensing" if it is licensed under this | |
10179 | License, and if all works that were first published under this | |
10180 | License somewhere other than this MMC, and subsequently | |
10181 | incorporated in whole or in part into the MMC, (1) had no cover | |
10182 | texts or invariant sections, and (2) were thus incorporated prior | |
10183 | to November 1, 2008. | |
10184 | ||
10185 | The operator of an MMC Site may republish an MMC contained in the | |
10186 | site under CC-BY-SA on the same site at any time before August 1, | |
10187 | 2009, provided the MMC is eligible for relicensing. | |
10188 | ||
d3a24ed2 | 10189 | |
c2a47ea9 CR |
10190 | ADDENDUM: How to use this License for your documents |
10191 | ==================================================== | |
d3a24ed2 | 10192 | |
37c41ab1 | 10193 | To use this License in a document you have written, include a copy of |
d3a24ed2 CR |
10194 | the License in the document and put the following copyright and license |
10195 | notices just after the title page: | |
10196 | ||
10197 | Copyright (C) YEAR YOUR NAME. | |
10198 | Permission is granted to copy, distribute and/or modify this document | |
1231ac47 | 10199 | under the terms of the GNU Free Documentation License, Version 1.3 |
d3a24ed2 | 10200 | or any later version published by the Free Software Foundation; |
c2a47ea9 CR |
10201 | with no Invariant Sections, no Front-Cover Texts, and no Back-Cover |
10202 | Texts. A copy of the license is included in the section entitled ``GNU | |
d3a24ed2 CR |
10203 | Free Documentation License''. |
10204 | ||
10205 | If you have Invariant Sections, Front-Cover Texts and Back-Cover | |
10206 | Texts, replace the "with...Texts." line with this: | |
10207 | ||
10208 | with the Invariant Sections being LIST THEIR TITLES, with | |
10209 | the Front-Cover Texts being LIST, and with the Back-Cover Texts | |
10210 | being LIST. | |
10211 | ||
10212 | If you have Invariant Sections without Cover Texts, or some other | |
10213 | combination of the three, merge those two alternatives to suit the | |
10214 | situation. | |
10215 | ||
10216 | If your document contains nontrivial examples of program code, we | |
10217 | recommend releasing these examples in parallel under your choice of | |
10218 | free software license, such as the GNU General Public License, to | |
10219 | permit their use in free software. | |
10220 | ||
10221 | \1f | |
c2a47ea9 | 10222 | File: bashref.info, Node: Indexes, Prev: GNU Free Documentation License, Up: Top |
d3ad40de CR |
10223 | |
10224 | Appendix D Indexes | |
10225 | ****************** | |
10226 | ||
10227 | * Menu: | |
10228 | ||
10229 | * Builtin Index:: Index of Bash builtin commands. | |
10230 | * Reserved Word Index:: Index of Bash reserved words. | |
10231 | * Variable Index:: Quick reference helps you find the | |
10232 | variable you want. | |
10233 | * Function Index:: Index of bindable Readline functions. | |
10234 | * Concept Index:: General index for concepts described in | |
10235 | this manual. | |
10236 | ||
10237 | \1f | |
10238 | File: bashref.info, Node: Builtin Index, Next: Reserved Word Index, Up: Indexes | |
5cfe250d | 10239 | |
d3ad40de CR |
10240 | D.1 Index of Shell Builtin Commands |
10241 | =================================== | |
ccc6cda3 | 10242 | |
37c41ab1 | 10243 | \0\b[index\0\b] |
ccc6cda3 JA |
10244 | * Menu: |
10245 | ||
e8ce775d | 10246 | * .: Bourne Shell Builtins. |
122f603c | 10247 | (line 17) |
e8ce775d | 10248 | * :: Bourne Shell Builtins. |
37c41ab1 | 10249 | (line 11) |
e8ce775d | 10250 | * [: Bourne Shell Builtins. |
45c0f7f8 | 10251 | (line 254) |
37c41ab1 | 10252 | * alias: Bash Builtins. (line 11) |
e8ce775d | 10253 | * bg: Job Control Builtins. |
37c41ab1 CR |
10254 | (line 7) |
10255 | * bind: Bash Builtins. (line 21) | |
e8ce775d | 10256 | * break: Bourne Shell Builtins. |
122f603c | 10257 | (line 31) |
45c0f7f8 CR |
10258 | * builtin: Bash Builtins. (line 102) |
10259 | * caller: Bash Builtins. (line 111) | |
e8ce775d | 10260 | * cd: Bourne Shell Builtins. |
122f603c | 10261 | (line 39) |
45c0f7f8 | 10262 | * command: Bash Builtins. (line 129) |
bb70624e | 10263 | * compgen: Programmable Completion Builtins. |
45c0f7f8 | 10264 | (line 12) |
bb70624e | 10265 | * complete: Programmable Completion Builtins. |
45c0f7f8 | 10266 | (line 30) |
6a8fd0ed | 10267 | * compopt: Programmable Completion Builtins. |
45c0f7f8 | 10268 | (line 228) |
e8ce775d | 10269 | * continue: Bourne Shell Builtins. |
45c0f7f8 CR |
10270 | (line 76) |
10271 | * declare: Bash Builtins. (line 149) | |
bb70624e | 10272 | * dirs: Directory Stack Builtins. |
37c41ab1 | 10273 | (line 7) |
e8ce775d | 10274 | * disown: Job Control Builtins. |
122f603c | 10275 | (line 87) |
45c0f7f8 CR |
10276 | * echo: Bash Builtins. (line 233) |
10277 | * enable: Bash Builtins. (line 295) | |
e8ce775d | 10278 | * eval: Bourne Shell Builtins. |
45c0f7f8 | 10279 | (line 85) |
e8ce775d | 10280 | * exec: Bourne Shell Builtins. |
45c0f7f8 | 10281 | (line 93) |
e8ce775d | 10282 | * exit: Bourne Shell Builtins. |
45c0f7f8 | 10283 | (line 110) |
e8ce775d | 10284 | * export: Bourne Shell Builtins. |
45c0f7f8 | 10285 | (line 117) |
cce855bc | 10286 | * fc: Bash History Builtins. |
37c41ab1 | 10287 | (line 10) |
e8ce775d | 10288 | * fg: Job Control Builtins. |
122f603c | 10289 | (line 17) |
e8ce775d | 10290 | * getopts: Bourne Shell Builtins. |
45c0f7f8 | 10291 | (line 133) |
e8ce775d | 10292 | * hash: Bourne Shell Builtins. |
45c0f7f8 CR |
10293 | (line 176) |
10294 | * help: Bash Builtins. (line 324) | |
cce855bc | 10295 | * history: Bash History Builtins. |
122f603c | 10296 | (line 40) |
e8ce775d | 10297 | * jobs: Job Control Builtins. |
122f603c | 10298 | (line 27) |
e8ce775d | 10299 | * kill: Job Control Builtins. |
122f603c | 10300 | (line 59) |
45c0f7f8 CR |
10301 | * let: Bash Builtins. (line 345) |
10302 | * local: Bash Builtins. (line 353) | |
10303 | * logout: Bash Builtins. (line 364) | |
10304 | * mapfile: Bash Builtins. (line 369) | |
bb70624e | 10305 | * popd: Directory Stack Builtins. |
122f603c | 10306 | (line 39) |
45c0f7f8 | 10307 | * printf: Bash Builtins. (line 417) |
bb70624e | 10308 | * pushd: Directory Stack Builtins. |
122f603c | 10309 | (line 61) |
e8ce775d | 10310 | * pwd: Bourne Shell Builtins. |
45c0f7f8 CR |
10311 | (line 196) |
10312 | * read: Bash Builtins. (line 463) | |
10313 | * readarray: Bash Builtins. (line 547) | |
e8ce775d | 10314 | * readonly: Bourne Shell Builtins. |
45c0f7f8 | 10315 | (line 206) |
e8ce775d | 10316 | * return: Bourne Shell Builtins. |
45c0f7f8 | 10317 | (line 225) |
d3ad40de | 10318 | * set: The Set Builtin. (line 11) |
e8ce775d | 10319 | * shift: Bourne Shell Builtins. |
45c0f7f8 | 10320 | (line 241) |
d3ad40de | 10321 | * shopt: The Shopt Builtin. (line 9) |
45c0f7f8 | 10322 | * source: Bash Builtins. (line 556) |
e8ce775d | 10323 | * suspend: Job Control Builtins. |
122f603c | 10324 | (line 99) |
e8ce775d | 10325 | * test: Bourne Shell Builtins. |
45c0f7f8 | 10326 | (line 254) |
e8ce775d | 10327 | * times: Bourne Shell Builtins. |
45c0f7f8 | 10328 | (line 330) |
e8ce775d | 10329 | * trap: Bourne Shell Builtins. |
45c0f7f8 CR |
10330 | (line 336) |
10331 | * type: Bash Builtins. (line 561) | |
10332 | * typeset: Bash Builtins. (line 593) | |
10333 | * ulimit: Bash Builtins. (line 599) | |
e8ce775d | 10334 | * umask: Bourne Shell Builtins. |
45c0f7f8 CR |
10335 | (line 383) |
10336 | * unalias: Bash Builtins. (line 690) | |
e8ce775d | 10337 | * unset: Bourne Shell Builtins. |
45c0f7f8 | 10338 | (line 401) |
e8ce775d | 10339 | * wait: Job Control Builtins. |
122f603c | 10340 | (line 76) |
ccc6cda3 JA |
10341 | |
10342 | \1f | |
d3ad40de | 10343 | File: bashref.info, Node: Reserved Word Index, Next: Variable Index, Prev: Builtin Index, Up: Indexes |
ccc6cda3 | 10344 | |
d3ad40de CR |
10345 | D.2 Index of Shell Reserved Words |
10346 | ================================= | |
ccc6cda3 | 10347 | |
37c41ab1 | 10348 | \0\b[index\0\b] |
ccc6cda3 JA |
10349 | * Menu: |
10350 | ||
ed35cb4a | 10351 | * !: Pipelines. (line 9) |
cce855bc | 10352 | * [[: Conditional Constructs. |
ed35cb4a | 10353 | (line 117) |
cce855bc | 10354 | * ]]: Conditional Constructs. |
ed35cb4a | 10355 | (line 117) |
e8ce775d | 10356 | * case: Conditional Constructs. |
37c41ab1 CR |
10357 | (line 28) |
10358 | * do: Looping Constructs. (line 12) | |
10359 | * done: Looping Constructs. (line 12) | |
e8ce775d | 10360 | * elif: Conditional Constructs. |
37c41ab1 | 10361 | (line 7) |
e8ce775d | 10362 | * else: Conditional Constructs. |
37c41ab1 | 10363 | (line 7) |
e8ce775d | 10364 | * esac: Conditional Constructs. |
37c41ab1 | 10365 | (line 28) |
e8ce775d | 10366 | * fi: Conditional Constructs. |
37c41ab1 | 10367 | (line 7) |
122f603c | 10368 | * for: Looping Constructs. (line 32) |
37c41ab1 | 10369 | * function: Shell Functions. (line 13) |
e8ce775d | 10370 | * if: Conditional Constructs. |
37c41ab1 | 10371 | (line 7) |
e8ce775d | 10372 | * in: Conditional Constructs. |
37c41ab1 | 10373 | (line 28) |
cce855bc | 10374 | * select: Conditional Constructs. |
ed35cb4a | 10375 | (line 76) |
e8ce775d | 10376 | * then: Conditional Constructs. |
37c41ab1 | 10377 | (line 7) |
ed35cb4a | 10378 | * time: Pipelines. (line 9) |
37c41ab1 | 10379 | * until: Looping Constructs. (line 12) |
122f603c | 10380 | * while: Looping Constructs. (line 22) |
37c41ab1 CR |
10381 | * {: Command Grouping. (line 21) |
10382 | * }: Command Grouping. (line 21) | |
ccc6cda3 JA |
10383 | |
10384 | \1f | |
d3ad40de | 10385 | File: bashref.info, Node: Variable Index, Next: Function Index, Prev: Reserved Word Index, Up: Indexes |
ccc6cda3 | 10386 | |
d3ad40de CR |
10387 | D.3 Parameter and Variable Index |
10388 | ================================ | |
ccc6cda3 | 10389 | |
37c41ab1 | 10390 | \0\b[index\0\b] |
ccc6cda3 JA |
10391 | * Menu: |
10392 | ||
37c41ab1 CR |
10393 | * !: Special Parameters. (line 46) |
10394 | * #: Special Parameters. (line 30) | |
10395 | * $: Special Parameters. (line 42) | |
10396 | * *: Special Parameters. (line 9) | |
10397 | * -: Special Parameters. (line 37) | |
10398 | * 0: Special Parameters. (line 50) | |
10399 | * ?: Special Parameters. (line 33) | |
10400 | * @: Special Parameters. (line 19) | |
10401 | * _: Special Parameters. (line 59) | |
e8ce775d | 10402 | * auto_resume: Job Control Variables. |
37c41ab1 CR |
10403 | (line 6) |
10404 | * BASH: Bash Variables. (line 13) | |
8f714a7c CR |
10405 | * BASH_ALIASES: Bash Variables. (line 30) |
10406 | * BASH_ARGC: Bash Variables. (line 37) | |
10407 | * BASH_ARGV: Bash Variables. (line 47) | |
10408 | * BASH_CMDS: Bash Variables. (line 57) | |
10409 | * BASH_COMMAND: Bash Variables. (line 64) | |
10410 | * BASH_ENV: Bash Variables. (line 69) | |
10411 | * BASH_EXECUTION_STRING: Bash Variables. (line 75) | |
10412 | * BASH_LINENO: Bash Variables. (line 78) | |
9ec5ed66 CR |
10413 | * BASH_REMATCH: Bash Variables. (line 86) |
10414 | * BASH_SOURCE: Bash Variables. (line 94) | |
10415 | * BASH_SUBSHELL: Bash Variables. (line 101) | |
f6da9f85 | 10416 | * BASH_VERSINFO: Bash Variables. (line 106) |
122f603c CR |
10417 | * BASH_VERSION: Bash Variables. (line 129) |
10418 | * BASH_XTRACEFD: Bash Variables. (line 132) | |
8f714a7c CR |
10419 | * BASHOPTS: Bash Variables. (line 16) |
10420 | * BASHPID: Bash Variables. (line 25) | |
e8ce775d | 10421 | * bell-style: Readline Init File Syntax. |
1c72c0cd | 10422 | (line 38) |
eb2bb562 | 10423 | * bind-tty-special-chars: Readline Init File Syntax. |
1c72c0cd | 10424 | (line 45) |
e8ce775d | 10425 | * CDPATH: Bourne Shell Variables. |
37c41ab1 | 10426 | (line 9) |
abe2eb5b CR |
10427 | * colored-stats: Readline Init File Syntax. |
10428 | (line 50) | |
122f603c | 10429 | * COLUMNS: Bash Variables. (line 143) |
e8ce775d | 10430 | * comment-begin: Readline Init File Syntax. |
abe2eb5b | 10431 | (line 56) |
122f603c CR |
10432 | * COMP_CWORD: Bash Variables. (line 148) |
10433 | * COMP_KEY: Bash Variables. (line 177) | |
10434 | * COMP_LINE: Bash Variables. (line 154) | |
10435 | * COMP_POINT: Bash Variables. (line 159) | |
10436 | * COMP_TYPE: Bash Variables. (line 167) | |
10437 | * COMP_WORDBREAKS: Bash Variables. (line 181) | |
10438 | * COMP_WORDS: Bash Variables. (line 187) | |
eb0b2ad8 | 10439 | * completion-display-width: Readline Init File Syntax. |
abe2eb5b | 10440 | (line 61) |
eb0b2ad8 | 10441 | * completion-ignore-case: Readline Init File Syntax. |
abe2eb5b | 10442 | (line 68) |
220537f2 | 10443 | * completion-map-case: Readline Init File Syntax. |
220537f2 | 10444 | (line 73) |
abe2eb5b CR |
10445 | * completion-prefix-display-length: Readline Init File Syntax. |
10446 | (line 79) | |
eb0b2ad8 | 10447 | * completion-query-items: Readline Init File Syntax. |
abe2eb5b | 10448 | (line 86) |
122f603c | 10449 | * COMPREPLY: Bash Variables. (line 195) |
e8ce775d | 10450 | * convert-meta: Readline Init File Syntax. |
abe2eb5b | 10451 | (line 96) |
45c0f7f8 CR |
10452 | * COPROC: Bash Variables. (line 201) |
10453 | * DIRSTACK: Bash Variables. (line 205) | |
e8ce775d | 10454 | * disable-completion: Readline Init File Syntax. |
abe2eb5b | 10455 | (line 102) |
1c72c0cd | 10456 | * editing-mode: Readline Init File Syntax. |
abe2eb5b | 10457 | (line 107) |
45c0f7f8 | 10458 | * EMACS: Bash Variables. (line 215) |
e8ce775d | 10459 | * enable-keypad: Readline Init File Syntax. |
abe2eb5b | 10460 | (line 118) |
45c0f7f8 CR |
10461 | * ENV: Bash Variables. (line 220) |
10462 | * EUID: Bash Variables. (line 224) | |
e8ce775d | 10463 | * expand-tilde: Readline Init File Syntax. |
abe2eb5b | 10464 | (line 129) |
45c0f7f8 CR |
10465 | * FCEDIT: Bash Variables. (line 228) |
10466 | * FIGNORE: Bash Variables. (line 232) | |
10467 | * FUNCNAME: Bash Variables. (line 238) | |
10468 | * FUNCNEST: Bash Variables. (line 256) | |
10469 | * GLOBIGNORE: Bash Variables. (line 261) | |
10470 | * GROUPS: Bash Variables. (line 267) | |
10471 | * histchars: Bash Variables. (line 273) | |
10472 | * HISTCMD: Bash Variables. (line 288) | |
10473 | * HISTCONTROL: Bash Variables. (line 293) | |
10474 | * HISTFILE: Bash Variables. (line 309) | |
10475 | * HISTFILESIZE: Bash Variables. (line 313) | |
10476 | * HISTIGNORE: Bash Variables. (line 324) | |
f73dda09 | 10477 | * history-preserve-point: Readline Init File Syntax. |
220537f2 | 10478 | (line 133) |
abe2eb5b CR |
10479 | * history-size: Readline Init File Syntax. |
10480 | (line 139) | |
45c0f7f8 CR |
10481 | * HISTSIZE: Bash Variables. (line 343) |
10482 | * HISTTIMEFORMAT: Bash Variables. (line 350) | |
e8ce775d | 10483 | * HOME: Bourne Shell Variables. |
37c41ab1 | 10484 | (line 13) |
e8ce775d | 10485 | * horizontal-scroll-mode: Readline Init File Syntax. |
abe2eb5b | 10486 | (line 144) |
45c0f7f8 CR |
10487 | * HOSTFILE: Bash Variables. (line 359) |
10488 | * HOSTNAME: Bash Variables. (line 370) | |
10489 | * HOSTTYPE: Bash Variables. (line 373) | |
e8ce775d | 10490 | * IFS: Bourne Shell Variables. |
37c41ab1 | 10491 | (line 18) |
45c0f7f8 | 10492 | * IGNOREEOF: Bash Variables. (line 376) |
e8ce775d | 10493 | * input-meta: Readline Init File Syntax. |
abe2eb5b | 10494 | (line 151) |
45c0f7f8 | 10495 | * INPUTRC: Bash Variables. (line 386) |
b72432fd | 10496 | * isearch-terminators: Readline Init File Syntax. |
abe2eb5b | 10497 | (line 158) |
eb0b2ad8 | 10498 | * keymap: Readline Init File Syntax. |
abe2eb5b | 10499 | (line 165) |
45c0f7f8 CR |
10500 | * LANG: Bash Variables. (line 390) |
10501 | * LC_ALL: Bash Variables. (line 394) | |
10502 | * LC_COLLATE: Bash Variables. (line 398) | |
10503 | * LC_CTYPE: Bash Variables. (line 405) | |
37c41ab1 | 10504 | * LC_MESSAGES <1>: Locale Translation. (line 11) |
45c0f7f8 CR |
10505 | * LC_MESSAGES: Bash Variables. (line 410) |
10506 | * LC_NUMERIC: Bash Variables. (line 414) | |
10507 | * LINENO: Bash Variables. (line 418) | |
10508 | * LINES: Bash Variables. (line 422) | |
10509 | * MACHTYPE: Bash Variables. (line 427) | |
e8ce775d | 10510 | * MAIL: Bourne Shell Variables. |
37c41ab1 | 10511 | (line 22) |
45c0f7f8 | 10512 | * MAILCHECK: Bash Variables. (line 431) |
e8ce775d | 10513 | * MAILPATH: Bourne Shell Variables. |
37c41ab1 | 10514 | (line 27) |
45c0f7f8 | 10515 | * MAPFILE: Bash Variables. (line 439) |
e8ce775d | 10516 | * mark-modified-lines: Readline Init File Syntax. |
abe2eb5b | 10517 | (line 178) |
a8fd3f3e | 10518 | * mark-symlinked-directories: Readline Init File Syntax. |
abe2eb5b | 10519 | (line 183) |
a8fd3f3e | 10520 | * match-hidden-files: Readline Init File Syntax. |
abe2eb5b | 10521 | (line 188) |
e05be32d | 10522 | * menu-complete-display-prefix: Readline Init File Syntax. |
abe2eb5b | 10523 | (line 195) |
e8ce775d | 10524 | * meta-flag: Readline Init File Syntax. |
abe2eb5b | 10525 | (line 151) |
45c0f7f8 | 10526 | * OLDPWD: Bash Variables. (line 443) |
e8ce775d | 10527 | * OPTARG: Bourne Shell Variables. |
37c41ab1 | 10528 | (line 34) |
45c0f7f8 | 10529 | * OPTERR: Bash Variables. (line 446) |
e8ce775d | 10530 | * OPTIND: Bourne Shell Variables. |
37c41ab1 | 10531 | (line 38) |
45c0f7f8 | 10532 | * OSTYPE: Bash Variables. (line 450) |
e8ce775d | 10533 | * output-meta: Readline Init File Syntax. |
abe2eb5b | 10534 | (line 200) |
e05be32d | 10535 | * page-completions: Readline Init File Syntax. |
abe2eb5b | 10536 | (line 205) |
e8ce775d | 10537 | * PATH: Bourne Shell Variables. |
37c41ab1 | 10538 | (line 42) |
45c0f7f8 CR |
10539 | * PIPESTATUS: Bash Variables. (line 453) |
10540 | * POSIXLY_CORRECT: Bash Variables. (line 458) | |
10541 | * PPID: Bash Variables. (line 467) | |
10542 | * PROMPT_COMMAND: Bash Variables. (line 471) | |
10543 | * PROMPT_DIRTRIM: Bash Variables. (line 475) | |
e8ce775d | 10544 | * PS1: Bourne Shell Variables. |
37c41ab1 | 10545 | (line 48) |
e8ce775d | 10546 | * PS2: Bourne Shell Variables. |
37c41ab1 | 10547 | (line 53) |
45c0f7f8 CR |
10548 | * PS3: Bash Variables. (line 481) |
10549 | * PS4: Bash Variables. (line 486) | |
10550 | * PWD: Bash Variables. (line 492) | |
10551 | * RANDOM: Bash Variables. (line 495) | |
10552 | * READLINE_LINE: Bash Variables. (line 500) | |
10553 | * READLINE_POINT: Bash Variables. (line 504) | |
10554 | * REPLY: Bash Variables. (line 508) | |
ed35cb4a | 10555 | * revert-all-at-newline: Readline Init File Syntax. |
abe2eb5b | 10556 | (line 215) |
45c0f7f8 CR |
10557 | * SECONDS: Bash Variables. (line 511) |
10558 | * SHELL: Bash Variables. (line 517) | |
10559 | * SHELLOPTS: Bash Variables. (line 522) | |
10560 | * SHLVL: Bash Variables. (line 531) | |
220537f2 | 10561 | * show-all-if-ambiguous: Readline Init File Syntax. |
e05be32d | 10562 | (line 221) |
abe2eb5b CR |
10563 | * show-all-if-unmodified: Readline Init File Syntax. |
10564 | (line 227) | |
a8fd3f3e | 10565 | * skip-completed-text: Readline Init File Syntax. |
abe2eb5b | 10566 | (line 236) |
37c41ab1 CR |
10567 | * TEXTDOMAIN: Locale Translation. (line 11) |
10568 | * TEXTDOMAINDIR: Locale Translation. (line 11) | |
45c0f7f8 CR |
10569 | * TIMEFORMAT: Bash Variables. (line 536) |
10570 | * TMOUT: Bash Variables. (line 574) | |
10571 | * TMPDIR: Bash Variables. (line 586) | |
10572 | * UID: Bash Variables. (line 590) | |
e8ce775d | 10573 | * visible-stats: Readline Init File Syntax. |
abe2eb5b | 10574 | (line 249) |
ccc6cda3 JA |
10575 | |
10576 | \1f | |
d3ad40de | 10577 | File: bashref.info, Node: Function Index, Next: Concept Index, Prev: Variable Index, Up: Indexes |
ccc6cda3 | 10578 | |
d3ad40de CR |
10579 | D.4 Function Index |
10580 | ================== | |
ccc6cda3 | 10581 | |
37c41ab1 | 10582 | \0\b[index\0\b] |
ccc6cda3 JA |
10583 | * Menu: |
10584 | ||
e8ce775d | 10585 | * abort (C-g): Miscellaneous Commands. |
37c41ab1 CR |
10586 | (line 10) |
10587 | * accept-line (Newline or Return): Commands For History. (line 6) | |
10588 | * backward-char (C-b): Commands For Moving. (line 15) | |
10589 | * backward-delete-char (Rubout): Commands For Text. (line 11) | |
10590 | * backward-kill-line (C-x Rubout): Commands For Killing. (line 9) | |
10591 | * backward-kill-word (M-<DEL>): Commands For Killing. (line 24) | |
10592 | * backward-word (M-b): Commands For Moving. (line 22) | |
10593 | * beginning-of-history (M-<): Commands For History. (line 20) | |
10594 | * beginning-of-line (C-a): Commands For Moving. (line 6) | |
10595 | * call-last-kbd-macro (C-x e): Keyboard Macros. (line 13) | |
10596 | * capitalize-word (M-c): Commands For Text. (line 46) | |
e8ce775d | 10597 | * character-search (C-]): Miscellaneous Commands. |
37c41ab1 | 10598 | (line 41) |
e8ce775d | 10599 | * character-search-backward (M-C-]): Miscellaneous Commands. |
37c41ab1 | 10600 | (line 46) |
a9fac3b2 | 10601 | * clear-screen (C-l): Commands For Moving. (line 34) |
28ef6c31 | 10602 | * complete (<TAB>): Commands For Completion. |
37c41ab1 | 10603 | (line 6) |
a9fac3b2 CR |
10604 | * copy-backward-word (): Commands For Killing. (line 58) |
10605 | * copy-forward-word (): Commands For Killing. (line 63) | |
10606 | * copy-region-as-kill (): Commands For Killing. (line 54) | |
37c41ab1 | 10607 | * delete-char (C-d): Commands For Text. (line 6) |
b72432fd | 10608 | * delete-char-or-list (): Commands For Completion. |
eb0b2ad8 | 10609 | (line 43) |
a9fac3b2 | 10610 | * delete-horizontal-space (): Commands For Killing. (line 46) |
37c41ab1 | 10611 | * digit-argument (M-0, M-1, ... M--): Numeric Arguments. (line 6) |
ccc6cda3 | 10612 | * do-uppercase-version (M-a, M-b, M-X, ...): Miscellaneous Commands. |
37c41ab1 CR |
10613 | (line 14) |
10614 | * downcase-word (M-l): Commands For Text. (line 42) | |
e8ce775d | 10615 | * dump-functions (): Miscellaneous Commands. |
8f714a7c | 10616 | (line 73) |
e8ce775d | 10617 | * dump-macros (): Miscellaneous Commands. |
8f714a7c | 10618 | (line 85) |
e8ce775d | 10619 | * dump-variables (): Miscellaneous Commands. |
8f714a7c | 10620 | (line 79) |
37c41ab1 CR |
10621 | * end-kbd-macro (C-x )): Keyboard Macros. (line 9) |
10622 | * end-of-history (M->): Commands For History. (line 23) | |
10623 | * end-of-line (C-e): Commands For Moving. (line 9) | |
e8ce775d | 10624 | * exchange-point-and-mark (C-x C-x): Miscellaneous Commands. |
37c41ab1 CR |
10625 | (line 36) |
10626 | * forward-backward-delete-char (): Commands For Text. (line 15) | |
10627 | * forward-char (C-f): Commands For Moving. (line 12) | |
10628 | * forward-search-history (C-s): Commands For History. (line 31) | |
10629 | * forward-word (M-f): Commands For Moving. (line 18) | |
74d0116b | 10630 | * history-search-backward (): Commands For History. (line 52) |
37c41ab1 | 10631 | * history-search-forward (): Commands For History. (line 46) |
74d0116b CR |
10632 | * history-substr-search-backward (): Commands For History. (line 64) |
10633 | * history-substr-search-forward (): Commands For History. (line 58) | |
e8ce775d | 10634 | * insert-comment (M-#): Miscellaneous Commands. |
8f714a7c | 10635 | (line 60) |
e8ce775d | 10636 | * insert-completions (M-*): Commands For Completion. |
eb0b2ad8 | 10637 | (line 22) |
37c41ab1 | 10638 | * kill-line (C-k): Commands For Killing. (line 6) |
a9fac3b2 | 10639 | * kill-region (): Commands For Killing. (line 50) |
37c41ab1 CR |
10640 | * kill-whole-line (): Commands For Killing. (line 15) |
10641 | * kill-word (M-d): Commands For Killing. (line 19) | |
cce855bc | 10642 | * menu-complete (): Commands For Completion. |
eb0b2ad8 | 10643 | (line 26) |
3eb2d94a | 10644 | * menu-complete-backward (): Commands For Completion. |
eb0b2ad8 | 10645 | (line 38) |
37c41ab1 | 10646 | * next-history (C-n): Commands For History. (line 17) |
ccc6cda3 | 10647 | * non-incremental-forward-search-history (M-n): Commands For History. |
37c41ab1 | 10648 | (line 41) |
ccc6cda3 | 10649 | * non-incremental-reverse-search-history (M-p): Commands For History. |
37c41ab1 CR |
10650 | (line 36) |
10651 | * overwrite-mode (): Commands For Text. (line 50) | |
e8ce775d | 10652 | * possible-completions (M-?): Commands For Completion. |
37c41ab1 | 10653 | (line 15) |
28ef6c31 | 10654 | * prefix-meta (<ESC>): Miscellaneous Commands. |
37c41ab1 CR |
10655 | (line 18) |
10656 | * previous-history (C-p): Commands For History. (line 13) | |
45c0f7f8 | 10657 | * print-last-kbd-macro (): Keyboard Macros. (line 17) |
37c41ab1 | 10658 | * quoted-insert (C-q or C-v): Commands For Text. (line 20) |
e8ce775d | 10659 | * re-read-init-file (C-x C-r): Miscellaneous Commands. |
37c41ab1 | 10660 | (line 6) |
a9fac3b2 | 10661 | * redraw-current-line (): Commands For Moving. (line 38) |
37c41ab1 | 10662 | * reverse-search-history (C-r): Commands For History. (line 27) |
e8ce775d | 10663 | * revert-line (M-r): Miscellaneous Commands. |
37c41ab1 CR |
10664 | (line 25) |
10665 | * self-insert (a, b, A, 1, !, ...): Commands For Text. (line 24) | |
e8ce775d | 10666 | * set-mark (C-@): Miscellaneous Commands. |
37c41ab1 | 10667 | (line 32) |
8f714a7c CR |
10668 | * skip-csi-sequence (): Miscellaneous Commands. |
10669 | (line 51) | |
37c41ab1 CR |
10670 | * start-kbd-macro (C-x (): Keyboard Macros. (line 6) |
10671 | * transpose-chars (C-t): Commands For Text. (line 27) | |
10672 | * transpose-words (M-t): Commands For Text. (line 33) | |
28ef6c31 | 10673 | * undo (C-_ or C-x C-u): Miscellaneous Commands. |
37c41ab1 CR |
10674 | (line 22) |
10675 | * universal-argument (): Numeric Arguments. (line 10) | |
a9fac3b2 | 10676 | * unix-filename-rubout (): Commands For Killing. (line 41) |
37c41ab1 | 10677 | * unix-line-discard (C-u): Commands For Killing. (line 12) |
a9fac3b2 | 10678 | * unix-word-rubout (C-w): Commands For Killing. (line 37) |
37c41ab1 | 10679 | * upcase-word (M-u): Commands For Text. (line 38) |
a9fac3b2 | 10680 | * yank (C-y): Commands For Killing. (line 68) |
74d0116b CR |
10681 | * yank-last-arg (M-. or M-_): Commands For History. (line 79) |
10682 | * yank-nth-arg (M-C-y): Commands For History. (line 70) | |
a9fac3b2 | 10683 | * yank-pop (M-y): Commands For Killing. (line 71) |
ccc6cda3 JA |
10684 | |
10685 | \1f | |
d3ad40de | 10686 | File: bashref.info, Node: Concept Index, Prev: Function Index, Up: Indexes |
ccc6cda3 | 10687 | |
d3ad40de CR |
10688 | D.5 Concept Index |
10689 | ================= | |
ccc6cda3 | 10690 | |
37c41ab1 | 10691 | \0\b[index\0\b] |
ccc6cda3 JA |
10692 | * Menu: |
10693 | ||
37c41ab1 CR |
10694 | * alias expansion: Aliases. (line 6) |
10695 | * arithmetic evaluation: Shell Arithmetic. (line 6) | |
e8ce775d | 10696 | * arithmetic expansion: Arithmetic Expansion. |
37c41ab1 CR |
10697 | (line 6) |
10698 | * arithmetic, shell: Shell Arithmetic. (line 6) | |
10699 | * arrays: Arrays. (line 6) | |
10700 | * background: Job Control Basics. (line 6) | |
10701 | * Bash configuration: Basic Installation. (line 6) | |
10702 | * Bash installation: Basic Installation. (line 6) | |
e8ce775d | 10703 | * Bourne shell: Basic Shell Features. |
37c41ab1 CR |
10704 | (line 6) |
10705 | * brace expansion: Brace Expansion. (line 6) | |
ac18b312 | 10706 | * builtin: Definitions. (line 17) |
e8ce775d | 10707 | * command editing: Readline Bare Essentials. |
37c41ab1 | 10708 | (line 6) |
e8ce775d | 10709 | * command execution: Command Search and Execution. |
37c41ab1 | 10710 | (line 6) |
cce855bc | 10711 | * command expansion: Simple Command Expansion. |
37c41ab1 | 10712 | (line 6) |
e8ce775d | 10713 | * command history: Bash History Facilities. |
37c41ab1 | 10714 | (line 6) |
e8ce775d | 10715 | * command search: Command Search and Execution. |
37c41ab1 | 10716 | (line 6) |
e8ce775d | 10717 | * command substitution: Command Substitution. |
37c41ab1 | 10718 | (line 6) |
ed35cb4a | 10719 | * command timing: Pipelines. (line 9) |
37c41ab1 | 10720 | * commands, compound: Compound Commands. (line 6) |
e8ce775d | 10721 | * commands, conditional: Conditional Constructs. |
37c41ab1 CR |
10722 | (line 6) |
10723 | * commands, grouping: Command Grouping. (line 6) | |
10724 | * commands, lists: Lists. (line 6) | |
10725 | * commands, looping: Looping Constructs. (line 6) | |
10726 | * commands, pipelines: Pipelines. (line 6) | |
10727 | * commands, shell: Shell Commands. (line 6) | |
10728 | * commands, simple: Simple Commands. (line 6) | |
10729 | * comments, shell: Comments. (line 6) | |
bb70624e | 10730 | * completion builtins: Programmable Completion Builtins. |
37c41ab1 CR |
10731 | (line 6) |
10732 | * configuration: Basic Installation. (line 6) | |
ac18b312 | 10733 | * control operator: Definitions. (line 21) |
8e1a6eaa | 10734 | * coprocess: Coprocesses. (line 6) |
37c41ab1 | 10735 | * directory stack: The Directory Stack. (line 6) |
e8ce775d | 10736 | * editing command lines: Readline Bare Essentials. |
37c41ab1 CR |
10737 | (line 6) |
10738 | * environment: Environment. (line 6) | |
10739 | * evaluation, arithmetic: Shell Arithmetic. (line 6) | |
10740 | * event designators: Event Designators. (line 6) | |
cce855bc | 10741 | * execution environment: Command Execution Environment. |
37c41ab1 CR |
10742 | (line 6) |
10743 | * exit status <1>: Exit Status. (line 6) | |
ed35cb4a | 10744 | * exit status: Definitions. (line 26) |
37c41ab1 | 10745 | * expansion: Shell Expansions. (line 6) |
e8ce775d | 10746 | * expansion, arithmetic: Arithmetic Expansion. |
37c41ab1 CR |
10747 | (line 6) |
10748 | * expansion, brace: Brace Expansion. (line 6) | |
10749 | * expansion, filename: Filename Expansion. (line 9) | |
e8ce775d | 10750 | * expansion, parameter: Shell Parameter Expansion. |
37c41ab1 CR |
10751 | (line 6) |
10752 | * expansion, pathname: Filename Expansion. (line 9) | |
10753 | * expansion, tilde: Tilde Expansion. (line 6) | |
10754 | * expressions, arithmetic: Shell Arithmetic. (line 6) | |
e8ce775d | 10755 | * expressions, conditional: Bash Conditional Expressions. |
37c41ab1 | 10756 | (line 6) |
ed35cb4a CR |
10757 | * field: Definitions. (line 30) |
10758 | * filename: Definitions. (line 35) | |
37c41ab1 CR |
10759 | * filename expansion: Filename Expansion. (line 9) |
10760 | * foreground: Job Control Basics. (line 6) | |
10761 | * functions, shell: Shell Functions. (line 6) | |
cce855bc | 10762 | * history builtins: Bash History Builtins. |
37c41ab1 | 10763 | (line 6) |
e05be32d | 10764 | * history events: Event Designators. (line 8) |
37c41ab1 | 10765 | * history expansion: History Interaction. (line 6) |
e8ce775d | 10766 | * history list: Bash History Facilities. |
37c41ab1 | 10767 | (line 6) |
45c0f7f8 CR |
10768 | * History, how to use: A Programmable Completion Example. |
10769 | (line 114) | |
ed35cb4a | 10770 | * identifier: Definitions. (line 51) |
37c41ab1 CR |
10771 | * initialization file, readline: Readline Init File. (line 6) |
10772 | * installation: Basic Installation. (line 6) | |
e8ce775d | 10773 | * interaction, readline: Readline Interaction. |
37c41ab1 CR |
10774 | (line 6) |
10775 | * interactive shell <1>: Interactive Shells. (line 6) | |
122f603c | 10776 | * interactive shell: Invoking Bash. (line 125) |
37c41ab1 | 10777 | * internationalization: Locale Translation. (line 6) |
ed35cb4a | 10778 | * job: Definitions. (line 38) |
c2a47ea9 | 10779 | * job control <1>: Job Control Basics. (line 6) |
ed35cb4a | 10780 | * job control: Definitions. (line 42) |
e8ce775d | 10781 | * kill ring: Readline Killing Commands. |
37c41ab1 | 10782 | (line 19) |
e8ce775d | 10783 | * killing text: Readline Killing Commands. |
37c41ab1 CR |
10784 | (line 6) |
10785 | * localization: Locale Translation. (line 6) | |
122f603c | 10786 | * login shell: Invoking Bash. (line 122) |
37c41ab1 | 10787 | * matching, pattern: Pattern Matching. (line 6) |
ed35cb4a CR |
10788 | * metacharacter: Definitions. (line 46) |
10789 | * name: Definitions. (line 51) | |
37c41ab1 | 10790 | * native languages: Locale Translation. (line 6) |
e8ce775d | 10791 | * notation, readline: Readline Bare Essentials. |
37c41ab1 | 10792 | (line 6) |
ed35cb4a | 10793 | * operator, shell: Definitions. (line 57) |
e8ce775d | 10794 | * parameter expansion: Shell Parameter Expansion. |
37c41ab1 CR |
10795 | (line 6) |
10796 | * parameters: Shell Parameters. (line 6) | |
e8ce775d | 10797 | * parameters, positional: Positional Parameters. |
37c41ab1 CR |
10798 | (line 6) |
10799 | * parameters, special: Special Parameters. (line 6) | |
10800 | * pathname expansion: Filename Expansion. (line 9) | |
10801 | * pattern matching: Pattern Matching. (line 6) | |
10802 | * pipeline: Pipelines. (line 6) | |
10803 | * POSIX: Definitions. (line 9) | |
10804 | * POSIX Mode: Bash POSIX Mode. (line 6) | |
a9fac3b2 CR |
10805 | * process group: Definitions. (line 62) |
10806 | * process group ID: Definitions. (line 66) | |
e8ce775d | 10807 | * process substitution: Process Substitution. |
37c41ab1 | 10808 | (line 6) |
bb70624e | 10809 | * programmable completion: Programmable Completion. |
37c41ab1 | 10810 | (line 6) |
122f603c CR |
10811 | * prompting: Controlling the Prompt. |
10812 | (line 6) | |
37c41ab1 CR |
10813 | * quoting: Quoting. (line 6) |
10814 | * quoting, ANSI: ANSI-C Quoting. (line 6) | |
bb70624e | 10815 | * Readline, how to use: Job Control Variables. |
37c41ab1 CR |
10816 | (line 24) |
10817 | * redirection: Redirections. (line 6) | |
a9fac3b2 | 10818 | * reserved word: Definitions. (line 70) |
e8ce775d | 10819 | * restricted shell: The Restricted Shell. |
37c41ab1 | 10820 | (line 6) |
a9fac3b2 | 10821 | * return status: Definitions. (line 75) |
37c41ab1 CR |
10822 | * shell arithmetic: Shell Arithmetic. (line 6) |
10823 | * shell function: Shell Functions. (line 6) | |
10824 | * shell script: Shell Scripts. (line 6) | |
10825 | * shell variable: Shell Parameters. (line 6) | |
10826 | * shell, interactive: Interactive Shells. (line 6) | |
a9fac3b2 | 10827 | * signal: Definitions. (line 78) |
37c41ab1 | 10828 | * signal handling: Signals. (line 6) |
c2a47ea9 | 10829 | * special builtin <1>: Special Builtins. (line 6) |
a9fac3b2 | 10830 | * special builtin: Definitions. (line 82) |
37c41ab1 CR |
10831 | * startup files: Bash Startup Files. (line 6) |
10832 | * suspending jobs: Job Control Basics. (line 6) | |
10833 | * tilde expansion: Tilde Expansion. (line 6) | |
a9fac3b2 | 10834 | * token: Definitions. (line 86) |
37c41ab1 CR |
10835 | * translation, native languages: Locale Translation. (line 6) |
10836 | * variable, shell: Shell Parameters. (line 6) | |
28ef6c31 | 10837 | * variables, readline: Readline Init File Syntax. |
1c72c0cd | 10838 | (line 37) |
a9fac3b2 | 10839 | * word: Definitions. (line 90) |
37c41ab1 | 10840 | * word splitting: Word Splitting. (line 6) |
e8ce775d | 10841 | * yanking text: Readline Killing Commands. |
37c41ab1 | 10842 | (line 6) |
ccc6cda3 JA |
10843 | |
10844 | ||
10845 | \1f | |
10846 | Tag Table: | |
abe2eb5b CR |
10847 | Node: Top\7f1348 |
10848 | Node: Introduction\7f3186 | |
10849 | Node: What is Bash?\7f3414 | |
10850 | Node: What is a shell?\7f4527 | |
10851 | Node: Definitions\7f7066 | |
10852 | Node: Basic Shell Features\7f9984 | |
10853 | Node: Shell Syntax\7f11203 | |
10854 | Node: Shell Operation\7f12233 | |
10855 | Node: Quoting\7f13527 | |
10856 | Node: Escape Character\7f14830 | |
10857 | Node: Single Quotes\7f15315 | |
10858 | Node: Double Quotes\7f15663 | |
10859 | Node: ANSI-C Quoting\7f16788 | |
10860 | Node: Locale Translation\7f18032 | |
10861 | Node: Comments\7f18928 | |
10862 | Node: Shell Commands\7f19546 | |
10863 | Node: Simple Commands\7f20418 | |
10864 | Node: Pipelines\7f21049 | |
10865 | Node: Lists\7f23748 | |
10866 | Node: Compound Commands\7f25477 | |
10867 | Node: Looping Constructs\7f26483 | |
10868 | Node: Conditional Constructs\7f28946 | |
10869 | Node: Command Grouping\7f39650 | |
10870 | Node: Coprocesses\7f41129 | |
10871 | Node: GNU Parallel\7f42803 | |
10872 | Node: Shell Functions\7f45271 | |
10873 | Node: Shell Parameters\7f50355 | |
10874 | Node: Positional Parameters\7f52960 | |
10875 | Node: Special Parameters\7f53860 | |
10876 | Node: Shell Expansions\7f56824 | |
10877 | Node: Brace Expansion\7f58750 | |
10878 | Node: Tilde Expansion\7f61504 | |
10879 | Node: Shell Parameter Expansion\7f63853 | |
10880 | Node: Command Substitution\7f73201 | |
10881 | Node: Arithmetic Expansion\7f74534 | |
10882 | Node: Process Substitution\7f75384 | |
10883 | Node: Word Splitting\7f76434 | |
10884 | Node: Filename Expansion\7f78057 | |
10885 | Node: Pattern Matching\7f80222 | |
10886 | Node: Quote Removal\7f83922 | |
10887 | Node: Redirections\7f84217 | |
10888 | Node: Executing Commands\7f93429 | |
10889 | Node: Simple Command Expansion\7f94099 | |
10890 | Node: Command Search and Execution\7f96029 | |
10891 | Node: Command Execution Environment\7f98366 | |
10892 | Node: Environment\7f101352 | |
10893 | Node: Exit Status\7f103011 | |
10894 | Node: Signals\7f104633 | |
10895 | Node: Shell Scripts\7f106601 | |
10896 | Node: Shell Builtin Commands\7f109119 | |
10897 | Node: Bourne Shell Builtins\7f111147 | |
10898 | Node: Bash Builtins\7f130528 | |
10899 | Node: Modifying Shell Behavior\7f157142 | |
10900 | Node: The Set Builtin\7f157487 | |
10901 | Node: The Shopt Builtin\7f167235 | |
10902 | Node: Special Builtins\7f181286 | |
10903 | Node: Shell Variables\7f182265 | |
10904 | Node: Bourne Shell Variables\7f182705 | |
10905 | Node: Bash Variables\7f184736 | |
10906 | Node: Bash Features\7f210247 | |
10907 | Node: Invoking Bash\7f211146 | |
10908 | Node: Bash Startup Files\7f216924 | |
10909 | Node: Interactive Shells\7f221943 | |
10910 | Node: What is an Interactive Shell?\7f222353 | |
10911 | Node: Is this Shell Interactive?\7f223002 | |
10912 | Node: Interactive Shell Behavior\7f223817 | |
10913 | Node: Bash Conditional Expressions\7f227097 | |
10914 | Node: Shell Arithmetic\7f230885 | |
10915 | Node: Aliases\7f233661 | |
10916 | Node: Arrays\7f236217 | |
10917 | Node: The Directory Stack\7f240425 | |
10918 | Node: Directory Stack Builtins\7f241144 | |
10919 | Node: Controlling the Prompt\7f244100 | |
10920 | Node: The Restricted Shell\7f246872 | |
10921 | Node: Bash POSIX Mode\7f248709 | |
10922 | Node: Job Control\7f258096 | |
10923 | Node: Job Control Basics\7f258556 | |
10924 | Node: Job Control Builtins\7f263275 | |
10925 | Node: Job Control Variables\7f267627 | |
10926 | Node: Command Line Editing\7f268785 | |
10927 | Node: Introduction and Notation\7f270457 | |
10928 | Node: Readline Interaction\7f272079 | |
10929 | Node: Readline Bare Essentials\7f273270 | |
10930 | Node: Readline Movement Commands\7f275059 | |
10931 | Node: Readline Killing Commands\7f276024 | |
10932 | Node: Readline Arguments\7f277944 | |
10933 | Node: Searching\7f278988 | |
10934 | Node: Readline Init File\7f281174 | |
10935 | Node: Readline Init File Syntax\7f282321 | |
10936 | Node: Conditional Init Constructs\7f297943 | |
10937 | Node: Sample Init File\7f300476 | |
10938 | Node: Bindable Readline Commands\7f303593 | |
10939 | Node: Commands For Moving\7f304800 | |
10940 | Node: Commands For History\7f305944 | |
10941 | Node: Commands For Text\7f310129 | |
10942 | Node: Commands For Killing\7f312802 | |
10943 | Node: Numeric Arguments\7f315259 | |
10944 | Node: Commands For Completion\7f316398 | |
10945 | Node: Keyboard Macros\7f320590 | |
10946 | Node: Miscellaneous Commands\7f321278 | |
10947 | Node: Readline vi Mode\7f327084 | |
10948 | Node: Programmable Completion\7f327991 | |
10949 | Node: Programmable Completion Builtins\7f335241 | |
10950 | Node: A Programmable Completion Example\7f344987 | |
10951 | Node: Using History Interactively\7f350237 | |
10952 | Node: Bash History Facilities\7f350921 | |
10953 | Node: Bash History Builtins\7f353912 | |
10954 | Node: History Interaction\7f357840 | |
10955 | Node: Event Designators\7f360545 | |
10956 | Node: Word Designators\7f361767 | |
10957 | Node: Modifiers\7f363406 | |
10958 | Node: Installing Bash\7f364810 | |
10959 | Node: Basic Installation\7f365947 | |
10960 | Node: Compilers and Options\7f368639 | |
10961 | Node: Compiling For Multiple Architectures\7f369380 | |
10962 | Node: Installation Names\7f371044 | |
10963 | Node: Specifying the System Type\7f371862 | |
10964 | Node: Sharing Defaults\7f372578 | |
10965 | Node: Operation Controls\7f373251 | |
10966 | Node: Optional Features\7f374209 | |
10967 | Node: Reporting Bugs\7f383781 | |
10968 | Node: Major Differences From The Bourne Shell\7f384982 | |
10969 | Node: GNU Free Documentation License\7f401674 | |
10970 | Node: Indexes\7f426870 | |
10971 | Node: Builtin Index\7f427324 | |
10972 | Node: Reserved Word Index\7f434151 | |
10973 | Node: Variable Index\7f436599 | |
10974 | Node: Function Index\7f449835 | |
10975 | Node: Concept Index\7f457063 | |
ccc6cda3 JA |
10976 | \1f |
10977 | End Tag Table |