]>
Commit | Line | Data |
---|---|---|
74091dd4 | 1 | This is bash.info, produced by makeinfo version 6.8 from bashref.texi. |
a0c0a00f CR |
2 | |
3 | This text is a brief description of the features that are present in the | |
74091dd4 | 4 | Bash shell (version 5.2, 19 September 2022). |
a0c0a00f | 5 | |
74091dd4 CR |
6 | This is Edition 5.2, last updated 19 September 2022, of 'The GNU Bash |
7 | Reference Manual', for 'Bash', Version 5.2. | |
a0c0a00f | 8 | |
74091dd4 | 9 | Copyright (C) 1988-2022 Free Software Foundation, Inc. |
a0c0a00f CR |
10 | |
11 | Permission is granted to copy, distribute and/or modify this | |
12 | document under the terms of the GNU Free Documentation License, | |
13 | Version 1.3 or any later version published by the Free Software | |
14 | Foundation; with no Invariant Sections, no Front-Cover Texts, and | |
15 | no Back-Cover Texts. A copy of the license is included in the | |
16 | section entitled "GNU Free Documentation License". | |
17 | INFO-DIR-SECTION Basics | |
18 | START-INFO-DIR-ENTRY | |
19 | * Bash: (bash). The GNU Bourne-Again SHell. | |
20 | END-INFO-DIR-ENTRY | |
21 | ||
22 | \1f | |
23 | File: bash.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) | |
24 | ||
25 | Bash Features | |
26 | ************* | |
27 | ||
28 | This text is a brief description of the features that are present in the | |
74091dd4 | 29 | Bash shell (version 5.2, 19 September 2022). The Bash home page is |
a0c0a00f CR |
30 | <http://www.gnu.org/software/bash/>. |
31 | ||
74091dd4 CR |
32 | This is Edition 5.2, last updated 19 September 2022, of 'The GNU Bash |
33 | Reference Manual', for 'Bash', Version 5.2. | |
a0c0a00f CR |
34 | |
35 | Bash contains features that appear in other popular shells, and some | |
36 | features that only appear in Bash. Some of the shells that Bash has | |
37 | borrowed concepts from are the Bourne Shell ('sh'), the Korn Shell | |
38 | ('ksh'), and the C-shell ('csh' and its successor, 'tcsh'). The | |
39 | following menu breaks the features up into categories, noting which | |
40 | features were inspired by other shells and which are specific to Bash. | |
41 | ||
42 | This manual is meant as a brief introduction to features found in | |
43 | Bash. The Bash manual page should be used as the definitive reference | |
44 | on shell behavior. | |
45 | ||
46 | * Menu: | |
47 | ||
48 | * Introduction:: An introduction to the shell. | |
49 | * Definitions:: Some definitions used in the rest of this | |
50 | manual. | |
51 | * Basic Shell Features:: The shell "building blocks". | |
52 | * Shell Builtin Commands:: Commands that are a part of the shell. | |
53 | * Shell Variables:: Variables used or set by Bash. | |
54 | * Bash Features:: Features found only in Bash. | |
55 | * Job Control:: What job control is and how Bash allows you | |
56 | to use it. | |
57 | * Command Line Editing:: Chapter describing the command line | |
58 | editing features. | |
59 | * Using History Interactively:: Command History Expansion | |
60 | * Installing Bash:: How to build and install Bash on your system. | |
61 | * Reporting Bugs:: How to report bugs in Bash. | |
62 | * Major Differences From The Bourne Shell:: A terse list of the differences | |
63 | between Bash and historical | |
64 | versions of /bin/sh. | |
65 | * GNU Free Documentation License:: Copying and sharing this documentation. | |
66 | * Indexes:: Various indexes for this manual. | |
67 | ||
68 | \1f | |
69 | File: bash.info, Node: Introduction, Next: Definitions, Up: Top | |
70 | ||
71 | 1 Introduction | |
72 | ************** | |
73 | ||
74 | * Menu: | |
75 | ||
76 | * What is Bash?:: A short description of Bash. | |
77 | * What is a shell?:: A brief introduction to shells. | |
78 | ||
79 | \1f | |
80 | File: bash.info, Node: What is Bash?, Next: What is a shell?, Up: Introduction | |
81 | ||
82 | 1.1 What is Bash? | |
83 | ================= | |
84 | ||
85 | Bash is the shell, or command language interpreter, for the GNU | |
86 | operating system. The name is an acronym for the 'Bourne-Again SHell', | |
87 | a pun on Stephen Bourne, the author of the direct ancestor of the | |
88 | current Unix shell 'sh', which appeared in the Seventh Edition Bell Labs | |
89 | Research version of Unix. | |
90 | ||
91 | Bash is largely compatible with 'sh' and incorporates useful features | |
92 | from the Korn shell 'ksh' and the C shell 'csh'. It is intended to be a | |
93 | conformant implementation of the IEEE POSIX Shell and Tools portion of | |
94 | the IEEE POSIX specification (IEEE Standard 1003.1). It offers | |
95 | functional improvements over 'sh' for both interactive and programming | |
96 | use. | |
97 | ||
98 | While the GNU operating system provides other shells, including a | |
99 | version of 'csh', Bash is the default shell. Like other GNU software, | |
100 | Bash is quite portable. It currently runs on nearly every version of | |
101 | Unix and a few other operating systems - independently-supported ports | |
102 | exist for MS-DOS, OS/2, and Windows platforms. | |
103 | ||
104 | \1f | |
105 | File: bash.info, Node: What is a shell?, Prev: What is Bash?, Up: Introduction | |
106 | ||
107 | 1.2 What is a shell? | |
108 | ==================== | |
109 | ||
110 | At its base, a shell is simply a macro processor that executes commands. | |
111 | The term macro processor means functionality where text and symbols are | |
112 | expanded to create larger expressions. | |
113 | ||
114 | A Unix shell is both a command interpreter and a programming | |
115 | language. As a command interpreter, the shell provides the user | |
116 | interface to the rich set of GNU utilities. The programming language | |
117 | features allow these utilities to be combined. Files containing | |
118 | commands can be created, and become commands themselves. These new | |
119 | commands have the same status as system commands in directories such as | |
120 | '/bin', allowing users or groups to establish custom environments to | |
121 | automate their common tasks. | |
122 | ||
123 | Shells may be used interactively or non-interactively. In | |
124 | interactive mode, they accept input typed from the keyboard. When | |
125 | executing non-interactively, shells execute commands read from a file. | |
126 | ||
127 | A shell allows execution of GNU commands, both synchronously and | |
128 | asynchronously. The shell waits for synchronous commands to complete | |
129 | before accepting more input; asynchronous commands continue to execute | |
130 | in parallel with the shell while it reads and executes additional | |
131 | commands. The "redirection" constructs permit fine-grained control of | |
132 | the input and output of those commands. Moreover, the shell allows | |
133 | control over the contents of commands' environments. | |
134 | ||
135 | Shells also provide a small set of built-in commands ("builtins") | |
136 | implementing functionality impossible or inconvenient to obtain via | |
137 | separate utilities. For example, 'cd', 'break', 'continue', and 'exec' | |
138 | cannot be implemented outside of the shell because they directly | |
139 | manipulate the shell itself. The 'history', 'getopts', 'kill', or 'pwd' | |
140 | builtins, among others, could be implemented in separate utilities, but | |
141 | they are more convenient to use as builtin commands. All of the shell | |
142 | builtins are described in subsequent sections. | |
143 | ||
144 | While executing commands is essential, most of the power (and | |
145 | complexity) of shells is due to their embedded programming languages. | |
146 | Like any high-level language, the shell provides variables, flow control | |
147 | constructs, quoting, and functions. | |
148 | ||
149 | Shells offer features geared specifically for interactive use rather | |
150 | than to augment the programming language. These interactive features | |
151 | include job control, command line editing, command history and aliases. | |
152 | Each of these features is described in this manual. | |
153 | ||
154 | \1f | |
155 | File: bash.info, Node: Definitions, Next: Basic Shell Features, Prev: Introduction, Up: Top | |
156 | ||
157 | 2 Definitions | |
158 | ************* | |
159 | ||
160 | These definitions are used throughout the remainder of this manual. | |
161 | ||
162 | 'POSIX' | |
163 | A family of open system standards based on Unix. Bash is primarily | |
164 | concerned with the Shell and Utilities portion of the POSIX 1003.1 | |
165 | standard. | |
166 | ||
167 | 'blank' | |
168 | A space or tab character. | |
169 | ||
170 | 'builtin' | |
171 | A command that is implemented internally by the shell itself, | |
172 | rather than by an executable program somewhere in the file system. | |
173 | ||
174 | 'control operator' | |
175 | A 'token' that performs a control function. It is a 'newline' or | |
176 | one of the following: '||', '&&', '&', ';', ';;', ';&', ';;&', '|', | |
177 | '|&', '(', or ')'. | |
178 | ||
179 | 'exit status' | |
180 | The value returned by a command to its caller. The value is | |
181 | restricted to eight bits, so the maximum value is 255. | |
182 | ||
183 | 'field' | |
184 | A unit of text that is the result of one of the shell expansions. | |
185 | After expansion, when executing a command, the resulting fields are | |
186 | used as the command name and arguments. | |
187 | ||
188 | 'filename' | |
189 | A string of characters used to identify a file. | |
190 | ||
191 | 'job' | |
192 | A set of processes comprising a pipeline, and any processes | |
193 | descended from it, that are all in the same process group. | |
194 | ||
195 | 'job control' | |
196 | A mechanism by which users can selectively stop (suspend) and | |
197 | restart (resume) execution of processes. | |
198 | ||
199 | 'metacharacter' | |
200 | A character that, when unquoted, separates words. A metacharacter | |
201 | is a 'space', 'tab', 'newline', or one of the following characters: | |
202 | '|', '&', ';', '(', ')', '<', or '>'. | |
203 | ||
204 | 'name' | |
205 | A 'word' consisting solely of letters, numbers, and underscores, | |
206 | and beginning with a letter or underscore. 'Name's are used as | |
207 | shell variable and function names. Also referred to as an | |
208 | 'identifier'. | |
209 | ||
210 | 'operator' | |
211 | A 'control operator' or a 'redirection operator'. *Note | |
212 | Redirections::, for a list of redirection operators. Operators | |
213 | contain at least one unquoted 'metacharacter'. | |
214 | ||
215 | 'process group' | |
216 | A collection of related processes each having the same process | |
217 | group ID. | |
218 | ||
219 | 'process group ID' | |
220 | A unique identifier that represents a 'process group' during its | |
221 | lifetime. | |
222 | ||
223 | 'reserved word' | |
224 | A 'word' that has a special meaning to the shell. Most reserved | |
225 | words introduce shell flow control constructs, such as 'for' and | |
226 | 'while'. | |
227 | ||
228 | 'return status' | |
229 | A synonym for 'exit status'. | |
230 | ||
231 | 'signal' | |
232 | A mechanism by which a process may be notified by the kernel of an | |
233 | event occurring in the system. | |
234 | ||
235 | 'special builtin' | |
236 | A shell builtin command that has been classified as special by the | |
237 | POSIX standard. | |
238 | ||
239 | 'token' | |
240 | A sequence of characters considered a single unit by the shell. It | |
241 | is either a 'word' or an 'operator'. | |
242 | ||
243 | 'word' | |
244 | A sequence of characters treated as a unit by the shell. Words may | |
245 | not include unquoted 'metacharacters'. | |
246 | ||
247 | \1f | |
248 | File: bash.info, Node: Basic Shell Features, Next: Shell Builtin Commands, Prev: Definitions, Up: Top | |
249 | ||
250 | 3 Basic Shell Features | |
251 | ********************** | |
252 | ||
253 | Bash is an acronym for 'Bourne-Again SHell'. The Bourne shell is the | |
254 | traditional Unix shell originally written by Stephen Bourne. All of the | |
255 | Bourne shell builtin commands are available in Bash, The rules for | |
256 | evaluation and quoting are taken from the POSIX specification for the | |
257 | 'standard' Unix shell. | |
258 | ||
259 | This chapter briefly summarizes the shell's 'building blocks': | |
260 | commands, control structures, shell functions, shell parameters, shell | |
261 | expansions, redirections, which are a way to direct input and output | |
262 | from and to named files, and how the shell executes commands. | |
263 | ||
264 | * Menu: | |
265 | ||
266 | * Shell Syntax:: What your input means to the shell. | |
267 | * Shell Commands:: The types of commands you can use. | |
268 | * Shell Functions:: Grouping commands by name. | |
269 | * Shell Parameters:: How the shell stores values. | |
270 | * Shell Expansions:: How Bash expands parameters and the various | |
271 | expansions available. | |
272 | * Redirections:: A way to control where input and output go. | |
273 | * Executing Commands:: What happens when you run a command. | |
274 | * Shell Scripts:: Executing files of shell commands. | |
275 | ||
276 | \1f | |
277 | File: bash.info, Node: Shell Syntax, Next: Shell Commands, Up: Basic Shell Features | |
278 | ||
279 | 3.1 Shell Syntax | |
280 | ================ | |
281 | ||
282 | * Menu: | |
283 | ||
284 | * Shell Operation:: The basic operation of the shell. | |
285 | * Quoting:: How to remove the special meaning from characters. | |
286 | * Comments:: How to specify comments. | |
287 | ||
288 | When the shell reads input, it proceeds through a sequence of | |
289 | operations. If the input indicates the beginning of a comment, the | |
290 | shell ignores the comment symbol ('#'), and the rest of that line. | |
291 | ||
292 | Otherwise, roughly speaking, the shell reads its input and divides | |
293 | the input into words and operators, employing the quoting rules to | |
294 | select which meanings to assign various words and characters. | |
295 | ||
296 | The shell then parses these tokens into commands and other | |
297 | constructs, removes the special meaning of certain words or characters, | |
298 | expands others, redirects input and output as needed, executes the | |
299 | specified command, waits for the command's exit status, and makes that | |
300 | exit status available for further inspection or processing. | |
301 | ||
302 | \1f | |
303 | File: bash.info, Node: Shell Operation, Next: Quoting, Up: Shell Syntax | |
304 | ||
305 | 3.1.1 Shell Operation | |
306 | --------------------- | |
307 | ||
308 | The following is a brief description of the shell's operation when it | |
309 | reads and executes a command. Basically, the shell does the following: | |
310 | ||
311 | 1. Reads its input from a file (*note Shell Scripts::), from a string | |
312 | supplied as an argument to the '-c' invocation option (*note | |
313 | Invoking Bash::), or from the user's terminal. | |
314 | ||
315 | 2. Breaks the input into words and operators, obeying the quoting | |
316 | rules described in *note Quoting::. These tokens are separated by | |
317 | 'metacharacters'. Alias expansion is performed by this step (*note | |
318 | Aliases::). | |
319 | ||
320 | 3. Parses the tokens into simple and compound commands (*note Shell | |
321 | Commands::). | |
322 | ||
323 | 4. Performs the various shell expansions (*note Shell Expansions::), | |
324 | breaking the expanded tokens into lists of filenames (*note | |
325 | Filename Expansion::) and commands and arguments. | |
326 | ||
327 | 5. Performs any necessary redirections (*note Redirections::) and | |
328 | removes the redirection operators and their operands from the | |
329 | argument list. | |
330 | ||
331 | 6. Executes the command (*note Executing Commands::). | |
332 | ||
333 | 7. Optionally waits for the command to complete and collects its exit | |
334 | status (*note Exit Status::). | |
335 | ||
336 | \1f | |
337 | File: bash.info, Node: Quoting, Next: Comments, Prev: Shell Operation, Up: Shell Syntax | |
338 | ||
339 | 3.1.2 Quoting | |
340 | ------------- | |
341 | ||
342 | * Menu: | |
343 | ||
344 | * Escape Character:: How to remove the special meaning from a single | |
345 | character. | |
346 | * Single Quotes:: How to inhibit all interpretation of a sequence | |
347 | of characters. | |
348 | * Double Quotes:: How to suppress most of the interpretation of a | |
349 | sequence of characters. | |
350 | * ANSI-C Quoting:: How to expand ANSI-C sequences in quoted strings. | |
351 | * Locale Translation:: How to translate strings into different languages. | |
352 | ||
353 | Quoting is used to remove the special meaning of certain characters or | |
354 | words to the shell. Quoting can be used to disable special treatment | |
355 | for special characters, to prevent reserved words from being recognized | |
356 | as such, and to prevent parameter expansion. | |
357 | ||
358 | Each of the shell metacharacters (*note Definitions::) has special | |
359 | meaning to the shell and must be quoted if it is to represent itself. | |
360 | When the command history expansion facilities are being used (*note | |
74091dd4 | 361 | History Interaction::), the "history expansion" character, usually '!', |
a0c0a00f CR |
362 | must be quoted to prevent history expansion. *Note Bash History |
363 | Facilities::, for more details concerning history expansion. | |
364 | ||
74091dd4 | 365 | There are three quoting mechanisms: the "escape character", single |
a0c0a00f CR |
366 | quotes, and double quotes. |
367 | ||
368 | \1f | |
369 | File: bash.info, Node: Escape Character, Next: Single Quotes, Up: Quoting | |
370 | ||
371 | 3.1.2.1 Escape Character | |
372 | ........................ | |
373 | ||
374 | A non-quoted backslash '\' is the Bash escape character. It preserves | |
375 | the literal value of the next character that follows, with the exception | |
376 | of 'newline'. If a '\newline' pair appears, and the backslash itself is | |
377 | not quoted, the '\newline' is treated as a line continuation (that is, | |
378 | it is removed from the input stream and effectively ignored). | |
379 | ||
380 | \1f | |
381 | File: bash.info, Node: Single Quotes, Next: Double Quotes, Prev: Escape Character, Up: Quoting | |
382 | ||
383 | 3.1.2.2 Single Quotes | |
384 | ..................... | |
385 | ||
386 | Enclosing characters in single quotes (''') preserves the literal value | |
387 | of each character within the quotes. A single quote may not occur | |
388 | between single quotes, even when preceded by a backslash. | |
389 | ||
390 | \1f | |
391 | File: bash.info, Node: Double Quotes, Next: ANSI-C Quoting, Prev: Single Quotes, Up: Quoting | |
392 | ||
393 | 3.1.2.3 Double Quotes | |
394 | ..................... | |
395 | ||
396 | Enclosing characters in double quotes ('"') preserves the literal value | |
397 | of all characters within the quotes, with the exception of '$', '`', | |
398 | '\', and, when history expansion is enabled, '!'. When the shell is in | |
399 | POSIX mode (*note Bash POSIX Mode::), the '!' has no special meaning | |
400 | within double quotes, even when history expansion is enabled. The | |
401 | characters '$' and '`' retain their special meaning within double quotes | |
402 | (*note Shell Expansions::). The backslash retains its special meaning | |
403 | only when followed by one of the following characters: '$', '`', '"', | |
404 | '\', or 'newline'. Within double quotes, backslashes that are followed | |
405 | by one of these characters are removed. Backslashes preceding | |
406 | characters without a special meaning are left unmodified. A double | |
407 | quote may be quoted within double quotes by preceding it with a | |
408 | backslash. If enabled, history expansion will be performed unless an | |
409 | '!' appearing in double quotes is escaped using a backslash. The | |
410 | backslash preceding the '!' is not removed. | |
411 | ||
412 | The special parameters '*' and '@' have special meaning when in | |
413 | double quotes (*note Shell Parameter Expansion::). | |
414 | ||
415 | \1f | |
416 | File: bash.info, Node: ANSI-C Quoting, Next: Locale Translation, Prev: Double Quotes, Up: Quoting | |
417 | ||
418 | 3.1.2.4 ANSI-C Quoting | |
419 | ...................... | |
420 | ||
74091dd4 CR |
421 | Character sequences of the form $'STRING' are treated as a special kind |
422 | of single quotes. The sequence expands to STRING, with | |
423 | backslash-escaped characters in STRING replaced as specified by the ANSI | |
424 | C standard. Backslash escape sequences, if present, are decoded as | |
425 | follows: | |
a0c0a00f CR |
426 | |
427 | '\a' | |
428 | alert (bell) | |
429 | '\b' | |
430 | backspace | |
431 | '\e' | |
432 | '\E' | |
433 | an escape character (not ANSI C) | |
434 | '\f' | |
435 | form feed | |
436 | '\n' | |
437 | newline | |
438 | '\r' | |
439 | carriage return | |
440 | '\t' | |
441 | horizontal tab | |
442 | '\v' | |
443 | vertical tab | |
444 | '\\' | |
445 | backslash | |
446 | '\'' | |
447 | single quote | |
448 | '\"' | |
449 | double quote | |
450 | '\?' | |
451 | question mark | |
452 | '\NNN' | |
453 | the eight-bit character whose value is the octal value NNN (one to | |
d233b485 | 454 | three octal digits) |
a0c0a00f CR |
455 | '\xHH' |
456 | the eight-bit character whose value is the hexadecimal value HH | |
457 | (one or two hex digits) | |
458 | '\uHHHH' | |
459 | the Unicode (ISO/IEC 10646) character whose value is the | |
460 | hexadecimal value HHHH (one to four hex digits) | |
461 | '\UHHHHHHHH' | |
462 | the Unicode (ISO/IEC 10646) character whose value is the | |
463 | hexadecimal value HHHHHHHH (one to eight hex digits) | |
464 | '\cX' | |
465 | a control-X character | |
466 | ||
467 | The expanded result is single-quoted, as if the dollar sign had not been | |
468 | present. | |
469 | ||
470 | \1f | |
471 | File: bash.info, Node: Locale Translation, Prev: ANSI-C Quoting, Up: Quoting | |
472 | ||
473 | 3.1.2.5 Locale-Specific Translation | |
474 | ................................... | |
475 | ||
74091dd4 | 476 | * Menu: |
a0c0a00f | 477 | |
74091dd4 CR |
478 | * Creating Internationalized Scripts:: How to use translations and different |
479 | languages in your scripts. | |
480 | ||
481 | Prefixing a double-quoted string with a dollar sign ('$'), such as | |
482 | $"hello, world", will cause the string to be translated according to the | |
483 | current locale. The 'gettext' infrastructure performs the lookup and | |
484 | translation, using the 'LC_MESSAGES', 'TEXTDOMAINDIR', and 'TEXTDOMAIN' | |
485 | shell variables, as explained below. See the gettext documentation for | |
486 | additional details not covered here. If the current locale is 'C' or | |
487 | 'POSIX', if there are no translations available, of if the string is not | |
488 | translated, the dollar sign is ignored. Since this is a form of double | |
489 | quoting, the string remains double-quoted by default, whether or not it | |
490 | is translated and replaced. If the 'noexpand_translation' option is | |
491 | enabled using the 'shopt' builtin (*note The Shopt Builtin::), | |
492 | translated strings are single-quoted instead of double-quoted. | |
493 | ||
494 | The rest of this section is a brief overview of how you use gettext | |
495 | to create translations for strings in a shell script named SCRIPTNAME. | |
496 | There are more details in the gettext documentation. | |
497 | ||
498 | \1f | |
499 | File: bash.info, Node: Creating Internationalized Scripts, Up: Locale Translation | |
500 | ||
501 | Once you've marked the strings in your script that you want to translate | |
502 | using $"...", you create a gettext "template" file using the command | |
503 | ||
504 | bash --dump-po-strings SCRIPTNAME > DOMAIN.pot | |
505 | ||
506 | The DOMAIN is your "message domain". It's just an arbitrary string | |
507 | that's used to identify the files gettext needs, like a package or | |
508 | script name. It needs to be unique among all the message domains on | |
509 | systems where you install the translations, so gettext knows which | |
510 | translations correspond to your script. You'll use the template file to | |
511 | create translations for each target language. The template file | |
512 | conventionally has the suffix '.pot'. | |
513 | ||
514 | You copy this template file to a separate file for each target | |
515 | language you want to support (called "PO" files, which use the suffix | |
516 | '.po'). PO files use various naming conventions, but when you are | |
517 | working to translate a template file into a particular language, you | |
518 | first copy the template file to a file whose name is the language you | |
519 | want to target, with the '.po' suffix. For instance, the Spanish | |
520 | translations of your strings would be in a file named 'es.po', and to | |
521 | get started using a message domain named "example," you would run | |
522 | ||
523 | cp example.pot es.po | |
524 | ||
525 | Ultimately, PO files are often named DOMAIN.po and installed in | |
526 | directories that contain multiple translation files for a particular | |
527 | language. | |
528 | ||
529 | Whichever naming convention you choose, you will need to translate | |
530 | the strings in the PO files into the appropriate languages. This has to | |
531 | be done manually. | |
532 | ||
533 | When you have the translations and PO files complete, you'll use the | |
534 | gettext tools to produce what are called "MO" files, which are compiled | |
535 | versions of the PO files the gettext tools use to look up translations | |
536 | efficiently. MO files are also called "message catalog" files. You use | |
537 | the 'msgfmt' program to do this. For instance, if you had a file with | |
538 | Spanish translations, you could run | |
539 | ||
540 | msgfmt -o es.mo es.po | |
541 | ||
542 | to produce the corresponding MO file. | |
543 | ||
544 | Once you have the MO files, you decide where to install them and use | |
545 | the 'TEXTDOMAINDIR' shell variable to tell the gettext tools where they | |
546 | are. Make sure to use the same message domain to name the MO files as | |
547 | you did for the PO files when you install them. | |
548 | ||
549 | Your users will use the 'LANG' or 'LC_MESSAGES' shell variables to | |
550 | select the desired language. | |
551 | ||
552 | You set the 'TEXTDOMAIN' variable to the script's message domain. As | |
553 | above, you use the message domain to name your translation files. | |
554 | ||
555 | You, or possibly your users, set the 'TEXTDOMAINDIR' variable to the | |
556 | name of a directory where the message catalog files are stored. If you | |
557 | install the message files into the system's standard message catalog | |
558 | directory, you don't need to worry about this variable. | |
559 | ||
560 | The directory where the message catalog files are stored varies | |
561 | between systems. Some use the message catalog selected by the | |
562 | 'LC_MESSAGES' shell variable. Others create the name of the message | |
563 | catalog from the value of the 'TEXTDOMAIN' shell variable, possibly | |
564 | adding the '.mo' suffix. If you use the 'TEXTDOMAIN' variable, you may | |
565 | need to set the 'TEXTDOMAINDIR' variable to the location of the message | |
566 | catalog files, as above. It's common to use both variables in this | |
567 | fashion: '$TEXTDOMAINDIR'/'$LC_MESSAGES'/LC_MESSAGES/'$TEXTDOMAIN'.mo. | |
568 | ||
569 | If you used that last convention, and you wanted to store the message | |
570 | catalog files with Spanish (es) and Esperanto (eo) translations into a | |
571 | local directory you use for custom translation files, you could run | |
572 | ||
573 | TEXTDOMAIN=example | |
574 | TEXTDOMAINDIR=/usr/local/share/locale | |
575 | ||
576 | cp es.mo ${TEXTDOMAINDIR}/es/LC_MESSAGES/${TEXTDOMAIN}.mo | |
577 | cp eo.mo ${TEXTDOMAINDIR}/eo/LC_MESSAGES/${TEXTDOMAIN}.mo | |
578 | ||
579 | When all of this is done, and the message catalog files containing | |
580 | the compiled translations are installed in the correct location, your | |
581 | users will be able to see translated strings in any of the supported | |
582 | languages by setting the 'LANG' or 'LC_MESSAGES' environment variables | |
583 | before running your script. | |
a0c0a00f CR |
584 | |
585 | \1f | |
586 | File: bash.info, Node: Comments, Prev: Quoting, Up: Shell Syntax | |
587 | ||
588 | 3.1.3 Comments | |
589 | -------------- | |
590 | ||
591 | In a non-interactive shell, or an interactive shell in which the | |
592 | 'interactive_comments' option to the 'shopt' builtin is enabled (*note | |
593 | The Shopt Builtin::), a word beginning with '#' causes that word and all | |
594 | remaining characters on that line to be ignored. An interactive shell | |
595 | without the 'interactive_comments' option enabled does not allow | |
596 | comments. The 'interactive_comments' option is on by default in | |
597 | interactive shells. *Note Interactive Shells::, for a description of | |
598 | what makes a shell interactive. | |
599 | ||
600 | \1f | |
601 | File: bash.info, Node: Shell Commands, Next: Shell Functions, Prev: Shell Syntax, Up: Basic Shell Features | |
602 | ||
603 | 3.2 Shell Commands | |
604 | ================== | |
605 | ||
606 | A simple shell command such as 'echo a b c' consists of the command | |
607 | itself followed by arguments, separated by spaces. | |
608 | ||
609 | More complex shell commands are composed of simple commands arranged | |
610 | together in a variety of ways: in a pipeline in which the output of one | |
611 | command becomes the input of a second, in a loop or conditional | |
612 | construct, or in some other grouping. | |
613 | ||
614 | * Menu: | |
615 | ||
8868edaf | 616 | * Reserved Words:: Words that have special meaning to the shell. |
a0c0a00f CR |
617 | * Simple Commands:: The most common type of command. |
618 | * Pipelines:: Connecting the input and output of several | |
619 | commands. | |
620 | * Lists:: How to execute commands sequentially. | |
621 | * Compound Commands:: Shell commands for control flow. | |
622 | * Coprocesses:: Two-way communication between commands. | |
623 | * GNU Parallel:: Running commands in parallel. | |
624 | ||
625 | \1f | |
8868edaf | 626 | File: bash.info, Node: Reserved Words, Next: Simple Commands, Up: Shell Commands |
a0c0a00f | 627 | |
8868edaf CR |
628 | 3.2.1 Reserved Words |
629 | -------------------- | |
630 | ||
631 | Reserved words are words that have special meaning to the shell. They | |
632 | are used to begin and end the shell's compound commands. | |
633 | ||
634 | The following words are recognized as reserved when unquoted and the | |
635 | first word of a command (see below for exceptions): | |
636 | ||
637 | 'if' 'then' 'elif' 'else' 'fi' 'time' | |
638 | 'for' 'in' 'until' 'while' 'do' 'done' | |
639 | 'case' 'esac' 'coproc''select''function' | |
640 | '{' '}' '[[' ']]' '!' | |
641 | ||
642 | 'in' is recognized as a reserved word if it is the third word of a | |
643 | 'case' or 'select' command. 'in' and 'do' are recognized as reserved | |
644 | words if they are the third word in a 'for' command. | |
645 | ||
646 | \1f | |
647 | File: bash.info, Node: Simple Commands, Next: Pipelines, Prev: Reserved Words, Up: Shell Commands | |
648 | ||
649 | 3.2.2 Simple Commands | |
a0c0a00f CR |
650 | --------------------- |
651 | ||
652 | A simple command is the kind of command encountered most often. It's | |
653 | just a sequence of words separated by 'blank's, terminated by one of the | |
654 | shell's control operators (*note Definitions::). The first word | |
655 | generally specifies a command to be executed, with the rest of the words | |
656 | being that command's arguments. | |
657 | ||
658 | The return status (*note Exit Status::) of a simple command is its | |
659 | exit status as provided by the POSIX 1003.1 'waitpid' function, or 128+N | |
660 | if the command was terminated by signal N. | |
661 | ||
662 | \1f | |
663 | File: bash.info, Node: Pipelines, Next: Lists, Prev: Simple Commands, Up: Shell Commands | |
664 | ||
8868edaf | 665 | 3.2.3 Pipelines |
a0c0a00f CR |
666 | --------------- |
667 | ||
668 | A 'pipeline' is a sequence of one or more commands separated by one of | |
669 | the control operators '|' or '|&'. | |
670 | ||
671 | The format for a pipeline is | |
672 | [time [-p]] [!] COMMAND1 [ | or |& COMMAND2 ] ... | |
673 | ||
674 | The output of each command in the pipeline is connected via a pipe to | |
675 | the input of the next command. That is, each command reads the previous | |
676 | command's output. This connection is performed before any redirections | |
74091dd4 | 677 | specified by COMMAND1. |
a0c0a00f CR |
678 | |
679 | If '|&' is used, COMMAND1's standard error, in addition to its | |
680 | standard output, is connected to COMMAND2's standard input through the | |
681 | pipe; it is shorthand for '2>&1 |'. This implicit redirection of the | |
682 | standard error to the standard output is performed after any | |
74091dd4 | 683 | redirections specified by COMMAND1. |
a0c0a00f CR |
684 | |
685 | The reserved word 'time' causes timing statistics to be printed for | |
686 | the pipeline once it finishes. The statistics currently consist of | |
687 | elapsed (wall-clock) time and user and system time consumed by the | |
688 | command's execution. The '-p' option changes the output format to that | |
689 | specified by POSIX. When the shell is in POSIX mode (*note Bash POSIX | |
690 | Mode::), it does not recognize 'time' as a reserved word if the next | |
691 | token begins with a '-'. The 'TIMEFORMAT' variable may be set to a | |
692 | format string that specifies how the timing information should be | |
693 | displayed. *Note Bash Variables::, for a description of the available | |
694 | formats. The use of 'time' as a reserved word permits the timing of | |
695 | shell builtins, shell functions, and pipelines. An external 'time' | |
696 | command cannot time these easily. | |
697 | ||
698 | When the shell is in POSIX mode (*note Bash POSIX Mode::), 'time' may | |
699 | be followed by a newline. In this case, the shell displays the total | |
700 | user and system time consumed by the shell and its children. The | |
701 | 'TIMEFORMAT' variable may be used to specify the format of the time | |
702 | information. | |
703 | ||
704 | If the pipeline is not executed asynchronously (*note Lists::), the | |
705 | shell waits for all commands in the pipeline to complete. | |
706 | ||
74091dd4 CR |
707 | Each command in a multi-command pipeline, where pipes are created, is |
708 | executed in its own "subshell", which is a separate process (*note | |
709 | Command Execution Environment::). If the 'lastpipe' option is enabled | |
710 | using the 'shopt' builtin (*note The Shopt Builtin::), the last element | |
711 | of a pipeline may be run by the shell process when job control is not | |
712 | active. | |
d233b485 CR |
713 | |
714 | The exit status of a pipeline is the exit status of the last command | |
715 | in the pipeline, unless the 'pipefail' option is enabled (*note The Set | |
716 | Builtin::). If 'pipefail' is enabled, the pipeline's return status is | |
717 | the value of the last (rightmost) command to exit with a non-zero | |
718 | status, or zero if all commands exit successfully. If the reserved word | |
719 | '!' precedes the pipeline, the exit status is the logical negation of | |
720 | the exit status as described above. The shell waits for all commands in | |
721 | the pipeline to terminate before returning a value. | |
a0c0a00f CR |
722 | |
723 | \1f | |
724 | File: bash.info, Node: Lists, Next: Compound Commands, Prev: Pipelines, Up: Shell Commands | |
725 | ||
8868edaf | 726 | 3.2.4 Lists of Commands |
a0c0a00f CR |
727 | ----------------------- |
728 | ||
729 | A 'list' is a sequence of one or more pipelines separated by one of the | |
730 | operators ';', '&', '&&', or '||', and optionally terminated by one of | |
731 | ';', '&', or a 'newline'. | |
732 | ||
733 | Of these list operators, '&&' and '||' have equal precedence, | |
734 | followed by ';' and '&', which have equal precedence. | |
735 | ||
736 | A sequence of one or more newlines may appear in a 'list' to delimit | |
737 | commands, equivalent to a semicolon. | |
738 | ||
739 | If a command is terminated by the control operator '&', the shell | |
740 | executes the command asynchronously in a subshell. This is known as | |
74091dd4 CR |
741 | executing the command in the "background", and these are referred to as |
742 | "asynchronous" commands. The shell does not wait for the command to | |
d233b485 CR |
743 | finish, and the return status is 0 (true). When job control is not |
744 | active (*note Job Control::), the standard input for asynchronous | |
745 | commands, in the absence of any explicit redirections, is redirected | |
746 | from '/dev/null'. | |
a0c0a00f CR |
747 | |
748 | Commands separated by a ';' are executed sequentially; the shell | |
749 | waits for each command to terminate in turn. The return status is the | |
750 | exit status of the last command executed. | |
751 | ||
752 | AND and OR lists are sequences of one or more pipelines separated by | |
753 | the control operators '&&' and '||', respectively. AND and OR lists are | |
754 | executed with left associativity. | |
755 | ||
756 | An AND list has the form | |
757 | COMMAND1 && COMMAND2 | |
758 | ||
759 | COMMAND2 is executed if, and only if, COMMAND1 returns an exit status of | |
d233b485 | 760 | zero (success). |
a0c0a00f CR |
761 | |
762 | An OR list has the form | |
763 | COMMAND1 || COMMAND2 | |
764 | ||
765 | COMMAND2 is executed if, and only if, COMMAND1 returns a non-zero exit | |
766 | status. | |
767 | ||
768 | The return status of AND and OR lists is the exit status of the last | |
769 | command executed in the list. | |
770 | ||
771 | \1f | |
772 | File: bash.info, Node: Compound Commands, Next: Coprocesses, Prev: Lists, Up: Shell Commands | |
773 | ||
8868edaf | 774 | 3.2.5 Compound Commands |
a0c0a00f CR |
775 | ----------------------- |
776 | ||
777 | * Menu: | |
778 | ||
779 | * Looping Constructs:: Shell commands for iterative action. | |
780 | * Conditional Constructs:: Shell commands for conditional execution. | |
781 | * Command Grouping:: Ways to group commands. | |
782 | ||
d233b485 CR |
783 | Compound commands are the shell programming language constructs. Each |
784 | construct begins with a reserved word or control operator and is | |
785 | terminated by a corresponding reserved word or operator. Any | |
786 | redirections (*note Redirections::) associated with a compound command | |
787 | apply to all commands within that compound command unless explicitly | |
788 | overridden. | |
a0c0a00f CR |
789 | |
790 | In most cases a list of commands in a compound command's description | |
791 | may be separated from the rest of the command by one or more newlines, | |
792 | and may be followed by a newline in place of a semicolon. | |
793 | ||
794 | Bash provides looping constructs, conditional commands, and | |
795 | mechanisms to group commands and execute them as a unit. | |
796 | ||
797 | \1f | |
798 | File: bash.info, Node: Looping Constructs, Next: Conditional Constructs, Up: Compound Commands | |
799 | ||
8868edaf | 800 | 3.2.5.1 Looping Constructs |
a0c0a00f CR |
801 | .......................... |
802 | ||
803 | Bash supports the following looping constructs. | |
804 | ||
805 | Note that wherever a ';' appears in the description of a command's | |
806 | syntax, it may be replaced with one or more newlines. | |
807 | ||
808 | 'until' | |
809 | The syntax of the 'until' command is: | |
810 | ||
811 | until TEST-COMMANDS; do CONSEQUENT-COMMANDS; done | |
812 | ||
813 | Execute CONSEQUENT-COMMANDS as long as TEST-COMMANDS has an exit | |
814 | status which is not zero. The return status is the exit status of | |
815 | the last command executed in CONSEQUENT-COMMANDS, or zero if none | |
816 | was executed. | |
817 | ||
818 | 'while' | |
819 | The syntax of the 'while' command is: | |
820 | ||
821 | while TEST-COMMANDS; do CONSEQUENT-COMMANDS; done | |
822 | ||
823 | Execute CONSEQUENT-COMMANDS as long as TEST-COMMANDS has an exit | |
824 | status of zero. The return status is the exit status of the last | |
825 | command executed in CONSEQUENT-COMMANDS, or zero if none was | |
826 | executed. | |
827 | ||
828 | 'for' | |
829 | The syntax of the 'for' command is: | |
830 | ||
831 | for NAME [ [in [WORDS ...] ] ; ] do COMMANDS; done | |
832 | ||
d233b485 CR |
833 | Expand WORDS (*note Shell Expansions::), and execute COMMANDS once |
834 | for each member in the resultant list, with NAME bound to the | |
835 | current member. If 'in WORDS' is not present, the 'for' command | |
836 | executes the COMMANDS once for each positional parameter that is | |
837 | set, as if 'in "$@"' had been specified (*note Special | |
838 | Parameters::). | |
839 | ||
840 | The return status is the exit status of the last command that | |
841 | executes. If there are no items in the expansion of WORDS, no | |
842 | commands are executed, and the return status is zero. | |
a0c0a00f CR |
843 | |
844 | An alternate form of the 'for' command is also supported: | |
845 | ||
846 | for (( EXPR1 ; EXPR2 ; EXPR3 )) ; do COMMANDS ; done | |
847 | ||
848 | First, the arithmetic expression EXPR1 is evaluated according to | |
849 | the rules described below (*note Shell Arithmetic::). The | |
850 | arithmetic expression EXPR2 is then evaluated repeatedly until it | |
851 | evaluates to zero. Each time EXPR2 evaluates to a non-zero value, | |
852 | COMMANDS are executed and the arithmetic expression EXPR3 is | |
853 | evaluated. If any expression is omitted, it behaves as if it | |
854 | evaluates to 1. The return value is the exit status of the last | |
855 | command in COMMANDS that is executed, or false if any of the | |
856 | expressions is invalid. | |
857 | ||
858 | The 'break' and 'continue' builtins (*note Bourne Shell Builtins::) | |
859 | may be used to control loop execution. | |
860 | ||
861 | \1f | |
862 | File: bash.info, Node: Conditional Constructs, Next: Command Grouping, Prev: Looping Constructs, Up: Compound Commands | |
863 | ||
8868edaf | 864 | 3.2.5.2 Conditional Constructs |
a0c0a00f CR |
865 | .............................. |
866 | ||
867 | 'if' | |
868 | The syntax of the 'if' command is: | |
869 | ||
870 | if TEST-COMMANDS; then | |
871 | CONSEQUENT-COMMANDS; | |
872 | [elif MORE-TEST-COMMANDS; then | |
873 | MORE-CONSEQUENTS;] | |
874 | [else ALTERNATE-CONSEQUENTS;] | |
875 | fi | |
876 | ||
877 | The TEST-COMMANDS list is executed, and if its return status is | |
878 | zero, the CONSEQUENT-COMMANDS list is executed. If TEST-COMMANDS | |
879 | returns a non-zero status, each 'elif' list is executed in turn, | |
880 | and if its exit status is zero, the corresponding MORE-CONSEQUENTS | |
881 | is executed and the command completes. If 'else | |
882 | ALTERNATE-CONSEQUENTS' is present, and the final command in the | |
883 | final 'if' or 'elif' clause has a non-zero exit status, then | |
884 | ALTERNATE-CONSEQUENTS is executed. The return status is the exit | |
885 | status of the last command executed, or zero if no condition tested | |
886 | true. | |
887 | ||
888 | 'case' | |
889 | The syntax of the 'case' command is: | |
890 | ||
d233b485 CR |
891 | case WORD in |
892 | [ [(] PATTERN [| PATTERN]...) COMMAND-LIST ;;]... | |
893 | esac | |
a0c0a00f CR |
894 | |
895 | 'case' will selectively execute the COMMAND-LIST corresponding to | |
d233b485 CR |
896 | the first PATTERN that matches WORD. The match is performed |
897 | according to the rules described below in *note Pattern Matching::. | |
898 | If the 'nocasematch' shell option (see the description of 'shopt' | |
899 | in *note The Shopt Builtin::) is enabled, the match is performed | |
900 | without regard to the case of alphabetic characters. The '|' is | |
901 | used to separate multiple patterns, and the ')' operator terminates | |
902 | a pattern list. A list of patterns and an associated command-list | |
903 | is known as a CLAUSE. | |
a0c0a00f CR |
904 | |
905 | Each clause must be terminated with ';;', ';&', or ';;&'. The WORD | |
906 | undergoes tilde expansion, parameter expansion, command | |
d233b485 CR |
907 | substitution, arithmetic expansion, and quote removal (*note Shell |
908 | Parameter Expansion::) before matching is attempted. Each PATTERN | |
909 | undergoes tilde expansion, parameter expansion, command | |
74091dd4 CR |
910 | substitution, arithmetic expansion, process substitution, and quote |
911 | removal. | |
a0c0a00f CR |
912 | |
913 | There may be an arbitrary number of 'case' clauses, each terminated | |
914 | by a ';;', ';&', or ';;&'. The first pattern that matches | |
915 | determines the command-list that is executed. It's a common idiom | |
916 | to use '*' as the final pattern to define the default case, since | |
917 | that pattern will always match. | |
918 | ||
919 | Here is an example using 'case' in a script that could be used to | |
920 | describe one interesting feature of an animal: | |
921 | ||
922 | echo -n "Enter the name of an animal: " | |
923 | read ANIMAL | |
924 | echo -n "The $ANIMAL has " | |
925 | case $ANIMAL in | |
926 | horse | dog | cat) echo -n "four";; | |
927 | man | kangaroo ) echo -n "two";; | |
928 | *) echo -n "an unknown number of";; | |
929 | esac | |
930 | echo " legs." | |
931 | ||
932 | ||
933 | If the ';;' operator is used, no subsequent matches are attempted | |
934 | after the first pattern match. Using ';&' in place of ';;' causes | |
935 | execution to continue with the COMMAND-LIST associated with the | |
936 | next clause, if any. Using ';;&' in place of ';;' causes the shell | |
937 | to test the patterns in the next clause, if any, and execute any | |
8868edaf CR |
938 | associated COMMAND-LIST on a successful match, continuing the case |
939 | statement execution as if the pattern list had not matched. | |
a0c0a00f CR |
940 | |
941 | The return status is zero if no PATTERN is matched. Otherwise, the | |
942 | return status is the exit status of the COMMAND-LIST executed. | |
943 | ||
944 | 'select' | |
945 | ||
946 | The 'select' construct allows the easy generation of menus. It has | |
947 | almost the same syntax as the 'for' command: | |
948 | ||
949 | select NAME [in WORDS ...]; do COMMANDS; done | |
950 | ||
951 | The list of words following 'in' is expanded, generating a list of | |
74091dd4 CR |
952 | items, and the set of expanded words is printed on the standard |
953 | error output stream, each preceded by a number. If the 'in WORDS' | |
954 | is omitted, the positional parameters are printed, as if 'in "$@"' | |
955 | had been specified. 'select' then displays the 'PS3' prompt and | |
956 | reads a line from the standard input. If the line consists of a | |
957 | number corresponding to one of the displayed words, then the value | |
958 | of NAME is set to that word. If the line is empty, the words and | |
959 | prompt are displayed again. If 'EOF' is read, the 'select' command | |
960 | completes and returns 1. Any other value read causes NAME to be | |
961 | set to null. The line read is saved in the variable 'REPLY'. | |
a0c0a00f CR |
962 | |
963 | The COMMANDS are executed after each selection until a 'break' | |
964 | command is executed, at which point the 'select' command completes. | |
965 | ||
966 | Here is an example that allows the user to pick a filename from the | |
967 | current directory, and displays the name and index of the file | |
968 | selected. | |
969 | ||
970 | select fname in *; | |
971 | do | |
972 | echo you picked $fname \($REPLY\) | |
973 | break; | |
974 | done | |
975 | ||
976 | '((...))' | |
977 | (( EXPRESSION )) | |
978 | ||
979 | The arithmetic EXPRESSION is evaluated according to the rules | |
74091dd4 CR |
980 | described below (*note Shell Arithmetic::). The EXPRESSION |
981 | undergoes the same expansions as if it were within double quotes, | |
982 | but double quote characters in EXPRESSION are not treated specially | |
983 | are removed. If the value of the expression is non-zero, the | |
984 | return status is 0; otherwise the return status is 1. | |
a0c0a00f CR |
985 | |
986 | '[[...]]' | |
987 | [[ EXPRESSION ]] | |
988 | ||
989 | Return a status of 0 or 1 depending on the evaluation of the | |
990 | conditional expression EXPRESSION. Expressions are composed of the | |
991 | primaries described below in *note Bash Conditional Expressions::. | |
74091dd4 CR |
992 | The words between the '[[' and ']]' do not undergo word splitting |
993 | and filename expansion. The shell performs tilde expansion, | |
994 | parameter and variable expansion, arithmetic expansion, command | |
995 | substitution, process substitution, and quote removal on those | |
996 | words (the expansions that would occur if the words were enclosed | |
997 | in double quotes). Conditional operators such as '-f' must be | |
998 | unquoted to be recognized as primaries. | |
a0c0a00f CR |
999 | |
1000 | When used with '[[', the '<' and '>' operators sort | |
1001 | lexicographically using the current locale. | |
1002 | ||
1003 | When the '==' and '!=' operators are used, the string to the right | |
1004 | of the operator is considered a pattern and matched according to | |
1005 | the rules described below in *note Pattern Matching::, as if the | |
1006 | 'extglob' shell option were enabled. The '=' operator is identical | |
1007 | to '=='. If the 'nocasematch' shell option (see the description of | |
1008 | 'shopt' in *note The Shopt Builtin::) is enabled, the match is | |
1009 | performed without regard to the case of alphabetic characters. The | |
1010 | return value is 0 if the string matches ('==') or does not match | |
74091dd4 CR |
1011 | ('!=') the pattern, and 1 otherwise. |
1012 | ||
1013 | If you quote any part of the pattern, using any of the shell's | |
1014 | quoting mechanisms, the quoted portion is matched literally. This | |
1015 | means every character in the quoted portion matches itself, instead | |
1016 | of having any special pattern matching meaning. | |
a0c0a00f CR |
1017 | |
1018 | An additional binary operator, '=~', is available, with the same | |
74091dd4 | 1019 | precedence as '==' and '!='. When you use '=~', the string to the |
d233b485 | 1020 | right of the operator is considered a POSIX extended regular |
74091dd4 CR |
1021 | expression pattern and matched accordingly (using the POSIX |
1022 | 'regcomp' and 'regexec' interfaces usually described in regex(3)). | |
1023 | The return value is 0 if the string matches the pattern, and 1 if | |
1024 | it does not. If the regular expression is syntactically incorrect, | |
1025 | the conditional expression returns 2. If the 'nocasematch' shell | |
1026 | option (see the description of 'shopt' in *note The Shopt | |
1027 | Builtin::) is enabled, the match is performed without regard to the | |
1028 | case of alphabetic characters. | |
1029 | ||
1030 | You can quote any part of the pattern to force the quoted portion | |
1031 | to be matched literally instead of as a regular expression (see | |
1032 | above). If the pattern is stored in a shell variable, quoting the | |
1033 | variable expansion forces the entire pattern to be matched | |
1034 | literally. | |
1035 | ||
1036 | The pattern will match if it matches any part of the string. If | |
1037 | you want to force the pattern to match the entire string, anchor | |
1038 | the pattern using the '^' and '$' regular expression operators. | |
a0c0a00f CR |
1039 | |
1040 | For example, the following will match a line (stored in the shell | |
74091dd4 CR |
1041 | variable 'line') if there is a sequence of characters anywhere in |
1042 | the value consisting of any number, including zero, of characters | |
1043 | in the 'space' character class, immediately followed by zero or one | |
1044 | instances of 'a', then a 'b': | |
1045 | ||
8868edaf | 1046 | [[ $line =~ [[:space:]]*(a)?b ]] |
a0c0a00f | 1047 | |
74091dd4 CR |
1048 | That means values for 'line' like 'aab', ' aaaaaab', 'xaby', and ' |
1049 | ab' will all match, as will a line containing a 'b' anywhere in its | |
1050 | value. | |
1051 | ||
1052 | If you want to match a character that's special to the regular | |
1053 | expression grammar ('^$|[]()\.*+?'), it has to be quoted to remove | |
1054 | its special meaning. This means that in the pattern 'xxx.txt', the | |
1055 | '.' matches any character in the string (its usual regular | |
1056 | expression meaning), but in the pattern '"xxx.txt"', it can only | |
1057 | match a literal '.'. | |
1058 | ||
1059 | Likewise, if you want to include a character in your pattern that | |
1060 | has a special meaning to the regular expression grammar, you must | |
1061 | make sure it's not quoted. If you want to anchor a pattern at the | |
1062 | beginning or end of the string, for instance, you cannot quote the | |
1063 | '^' or '$' characters using any form of shell quoting. | |
1064 | ||
1065 | If you want to match 'initial string' at the start of a line, the | |
1066 | following will work: | |
1067 | [[ $line =~ ^"initial string" ]] | |
1068 | but this will not: | |
1069 | [[ $line =~ "^initial string" ]] | |
1070 | because in the second example the '^' is quoted and doesn't have | |
1071 | its usual special meaning. | |
1072 | ||
1073 | It is sometimes difficult to specify a regular expression properly | |
1074 | without using quotes, or to keep track of the quoting used by | |
1075 | regular expressions while paying attention to shell quoting and the | |
1076 | shell's quote removal. Storing the regular expression in a shell | |
1077 | variable is often a useful way to avoid problems with quoting | |
1078 | characters that are special to the shell. For example, the | |
1079 | following is equivalent to the pattern used above: | |
1080 | ||
8868edaf | 1081 | pattern='[[:space:]]*(a)?b' |
a0c0a00f CR |
1082 | [[ $line =~ $pattern ]] |
1083 | ||
a0c0a00f | 1084 | Shell programmers should take special care with backslashes, since |
74091dd4 CR |
1085 | backslashes are used by both the shell and regular expressions to |
1086 | remove the special meaning from the following character. This | |
1087 | means that after the shell's word expansions complete (*note Shell | |
1088 | Expansions::), any backslashes remaining in parts of the pattern | |
1089 | that were originally not quoted can remove the special meaning of | |
1090 | pattern characters. If any part of the pattern is quoted, the | |
1091 | shell does its best to ensure that the regular expression treats | |
1092 | those remaining backslashes as literal, if they appeared in a | |
1093 | quoted portion. | |
1094 | ||
1095 | The following two sets of commands are _not_ equivalent: | |
1096 | ||
a0c0a00f CR |
1097 | pattern='\.' |
1098 | ||
1099 | [[ . =~ $pattern ]] | |
1100 | [[ . =~ \. ]] | |
1101 | ||
1102 | [[ . =~ "$pattern" ]] | |
1103 | [[ . =~ '\.' ]] | |
1104 | ||
1105 | The first two matches will succeed, but the second two will not, | |
1106 | because in the second two the backslash will be part of the pattern | |
74091dd4 CR |
1107 | to be matched. In the first two examples, the pattern passed to |
1108 | the regular expression parser is '\.'. The backslash removes the | |
1109 | special meaning from '.', so the literal '.' matches. In the | |
1110 | second two examples, the pattern passed to the regular expression | |
1111 | parser has the backslash quoted (e.g., '\\\.'), which will not | |
1112 | match the string, since it does not contain a backslash. If the | |
a0c0a00f CR |
1113 | string in the first examples were anything other than '.', say 'a', |
1114 | the pattern would not match, because the quoted '.' in the pattern | |
1115 | loses its special meaning of matching any single character. | |
1116 | ||
74091dd4 CR |
1117 | Bracket expressions in regular expressions can be sources of errors |
1118 | as well, since characters that are normally special in regular | |
1119 | expressions lose their special meanings between brackets. However, | |
1120 | you can use bracket expressions to match special pattern characters | |
1121 | without quoting them, so they are sometimes useful for this | |
1122 | purpose. | |
1123 | ||
1124 | Though it might seem like a strange way to write it, the following | |
1125 | pattern will match a '.' in the string: | |
1126 | ||
1127 | [[ . =~ [.] ]] | |
1128 | ||
1129 | The shell performs any word expansions before passing the pattern | |
1130 | to the regular expression functions, so you can assume that the | |
1131 | shell's quoting takes precedence. As noted above, the regular | |
1132 | expression parser will interpret any unquoted backslashes remaining | |
1133 | in the pattern after shell expansion according to its own rules. | |
1134 | The intention is to avoid making shell programmers quote things | |
1135 | twice as much as possible, so shell quoting should be sufficient to | |
1136 | quote special pattern characters where that's necessary. | |
1137 | ||
1138 | The array variable 'BASH_REMATCH' records which parts of the string | |
1139 | matched the pattern. The element of 'BASH_REMATCH' with index 0 | |
1140 | contains the portion of the string matching the entire regular | |
1141 | expression. Substrings matched by parenthesized subexpressions | |
1142 | within the regular expression are saved in the remaining | |
1143 | 'BASH_REMATCH' indices. The element of 'BASH_REMATCH' with index N | |
1144 | is the portion of the string matching the Nth parenthesized | |
1145 | subexpression. | |
1146 | ||
1147 | Bash sets 'BASH_REMATCH' in the global scope; declaring it as a | |
1148 | local variable will lead to unexpected results. | |
1149 | ||
a0c0a00f CR |
1150 | Expressions may be combined using the following operators, listed |
1151 | in decreasing order of precedence: | |
1152 | ||
1153 | '( EXPRESSION )' | |
1154 | Returns the value of EXPRESSION. This may be used to override | |
1155 | the normal precedence of operators. | |
1156 | ||
1157 | '! EXPRESSION' | |
1158 | True if EXPRESSION is false. | |
1159 | ||
1160 | 'EXPRESSION1 && EXPRESSION2' | |
1161 | True if both EXPRESSION1 and EXPRESSION2 are true. | |
1162 | ||
1163 | 'EXPRESSION1 || EXPRESSION2' | |
1164 | True if either EXPRESSION1 or EXPRESSION2 is true. | |
1165 | ||
1166 | The '&&' and '||' operators do not evaluate EXPRESSION2 if the | |
1167 | value of EXPRESSION1 is sufficient to determine the return value of | |
1168 | the entire conditional expression. | |
1169 | ||
1170 | \1f | |
1171 | File: bash.info, Node: Command Grouping, Prev: Conditional Constructs, Up: Compound Commands | |
1172 | ||
8868edaf | 1173 | 3.2.5.3 Grouping Commands |
a0c0a00f CR |
1174 | ......................... |
1175 | ||
1176 | Bash provides two ways to group a list of commands to be executed as a | |
1177 | unit. When commands are grouped, redirections may be applied to the | |
1178 | entire command list. For example, the output of all the commands in the | |
1179 | list may be redirected to a single stream. | |
1180 | ||
1181 | '()' | |
1182 | ( LIST ) | |
1183 | ||
74091dd4 CR |
1184 | Placing a list of commands between parentheses forces the shell to |
1185 | create a subshell (*note Command Execution Environment::), and each | |
1186 | of the commands in LIST is executed in that subshell environment. | |
a0c0a00f CR |
1187 | Since the LIST is executed in a subshell, variable assignments do |
1188 | not remain in effect after the subshell completes. | |
1189 | ||
1190 | '{}' | |
1191 | { LIST; } | |
1192 | ||
1193 | Placing a list of commands between curly braces causes the list to | |
1194 | be executed in the current shell context. No subshell is created. | |
1195 | The semicolon (or newline) following LIST is required. | |
1196 | ||
1197 | In addition to the creation of a subshell, there is a subtle | |
1198 | difference between these two constructs due to historical reasons. The | |
74091dd4 CR |
1199 | braces are reserved words, so they must be separated from the LIST by |
1200 | 'blank's or other shell metacharacters. The parentheses are operators, | |
1201 | and are recognized as separate tokens by the shell even if they are not | |
1202 | separated from the LIST by whitespace. | |
a0c0a00f CR |
1203 | |
1204 | The exit status of both of these constructs is the exit status of | |
1205 | LIST. | |
1206 | ||
1207 | \1f | |
1208 | File: bash.info, Node: Coprocesses, Next: GNU Parallel, Prev: Compound Commands, Up: Shell Commands | |
1209 | ||
8868edaf | 1210 | 3.2.6 Coprocesses |
a0c0a00f CR |
1211 | ----------------- |
1212 | ||
1213 | A 'coprocess' is a shell command preceded by the 'coproc' reserved word. | |
1214 | A coprocess is executed asynchronously in a subshell, as if the command | |
1215 | had been terminated with the '&' control operator, with a two-way pipe | |
1216 | established between the executing shell and the coprocess. | |
1217 | ||
74091dd4 CR |
1218 | The syntax for a coprocess is: |
1219 | ||
a0c0a00f CR |
1220 | coproc [NAME] COMMAND [REDIRECTIONS] |
1221 | ||
74091dd4 CR |
1222 | This creates a coprocess named NAME. COMMAND may be either a simple |
1223 | command (*note Simple Commands::) or a compound command (*note Compound | |
1224 | Commands::). NAME is a shell variable name. If NAME is not supplied, | |
1225 | the default name is 'COPROC'. | |
1226 | ||
1227 | The recommended form to use for a coprocess is | |
1228 | ||
1229 | coproc NAME { COMMAND; } | |
1230 | ||
1231 | This form is recommended because simple commands result in the coprocess | |
1232 | always being named 'COPROC', and it is simpler to use and more complete | |
1233 | than the other compound commands. | |
1234 | ||
1235 | There are other forms of coprocesses: | |
1236 | ||
1237 | coproc NAME COMPOUND-COMMAND | |
1238 | coproc COMPOUND-COMMAND | |
1239 | coproc SIMPLE-COMMAND | |
1240 | ||
1241 | If COMMAND is a compound command, NAME is optional. The word following | |
1242 | 'coproc' determines whether that word is interpreted as a variable name: | |
1243 | it is interpreted as NAME if it is not a reserved word that introduces a | |
1244 | compound command. If COMMAND is a simple command, NAME is not allowed; | |
1245 | this is to avoid confusion between NAME and the first word of the simple | |
1246 | command. | |
a0c0a00f CR |
1247 | |
1248 | When the coprocess is executed, the shell creates an array variable | |
74091dd4 CR |
1249 | (*note Arrays::) named NAME in the context of the executing shell. The |
1250 | standard output of COMMAND is connected via a pipe to a file descriptor | |
1251 | in the executing shell, and that file descriptor is assigned to NAME[0]. | |
1252 | The standard input of COMMAND is connected via a pipe to a file | |
a0c0a00f | 1253 | descriptor in the executing shell, and that file descriptor is assigned |
74091dd4 CR |
1254 | to NAME[1]. This pipe is established before any redirections specified |
1255 | by the command (*note Redirections::). The file descriptors can be | |
1256 | utilized as arguments to shell commands and redirections using standard | |
1257 | word expansions. Other than those created to execute command and | |
1258 | process substitutions, the file descriptors are not available in | |
a0c0a00f CR |
1259 | subshells. |
1260 | ||
1261 | The process ID of the shell spawned to execute the coprocess is | |
74091dd4 | 1262 | available as the value of the variable 'NAME_PID'. The 'wait' builtin |
a0c0a00f CR |
1263 | command may be used to wait for the coprocess to terminate. |
1264 | ||
1265 | Since the coprocess is created as an asynchronous command, the | |
1266 | 'coproc' command always returns success. The return status of a | |
1267 | coprocess is the exit status of COMMAND. | |
1268 | ||
1269 | \1f | |
1270 | File: bash.info, Node: GNU Parallel, Prev: Coprocesses, Up: Shell Commands | |
1271 | ||
8868edaf | 1272 | 3.2.7 GNU Parallel |
a0c0a00f CR |
1273 | ------------------ |
1274 | ||
1275 | There are ways to run commands in parallel that are not built into Bash. | |
1276 | GNU Parallel is a tool to do just that. | |
1277 | ||
1278 | GNU Parallel, as its name suggests, can be used to build and run | |
1279 | commands in parallel. You may run the same command with different | |
1280 | arguments, whether they are filenames, usernames, hostnames, or lines | |
1281 | read from files. GNU Parallel provides shorthand references to many of | |
1282 | the most common operations (input lines, various portions of the input | |
1283 | line, different ways to specify the input source, and so on). Parallel | |
1284 | can replace 'xargs' or feed commands from its input sources to several | |
1285 | different instances of Bash. | |
1286 | ||
74091dd4 CR |
1287 | For a complete description, refer to the GNU Parallel documentation, |
1288 | which is available at | |
1289 | <https://www.gnu.org/software/parallel/parallel_tutorial.html>. | |
a0c0a00f CR |
1290 | |
1291 | \1f | |
1292 | File: bash.info, Node: Shell Functions, Next: Shell Parameters, Prev: Shell Commands, Up: Basic Shell Features | |
1293 | ||
1294 | 3.3 Shell Functions | |
1295 | =================== | |
1296 | ||
1297 | Shell functions are a way to group commands for later execution using a | |
1298 | single name for the group. They are executed just like a "regular" | |
1299 | command. When the name of a shell function is used as a simple command | |
1300 | name, the list of commands associated with that function name is | |
1301 | executed. Shell functions are executed in the current shell context; no | |
1302 | new process is created to interpret them. | |
1303 | ||
1304 | Functions are declared using this syntax: | |
8868edaf | 1305 | FNAME () COMPOUND-COMMAND [ REDIRECTIONS ] |
a0c0a00f CR |
1306 | |
1307 | or | |
1308 | ||
8868edaf | 1309 | function FNAME [()] COMPOUND-COMMAND [ REDIRECTIONS ] |
a0c0a00f | 1310 | |
8868edaf | 1311 | This defines a shell function named FNAME. The reserved word |
a0c0a00f | 1312 | 'function' is optional. If the 'function' reserved word is supplied, |
74091dd4 CR |
1313 | the parentheses are optional. The "body" of the function is the |
1314 | compound command COMPOUND-COMMAND (*note Compound Commands::). That | |
1315 | command is usually a LIST enclosed between { and }, but may be any | |
1316 | compound command listed above. If the 'function' reserved word is used, | |
1317 | but the parentheses are not supplied, the braces are recommended. | |
8868edaf | 1318 | COMPOUND-COMMAND is executed whenever FNAME is specified as the name of |
74091dd4 CR |
1319 | a simple command. When the shell is in POSIX mode (*note Bash POSIX |
1320 | Mode::), FNAME must be a valid shell name and may not be the same as one | |
1321 | of the special builtins (*note Special Builtins::). In default mode, a | |
8868edaf CR |
1322 | function name can be any unquoted shell word that does not contain '$'. |
1323 | Any redirections (*note Redirections::) associated with the shell | |
1324 | function are performed when the function is executed. A function | |
1325 | definition may be deleted using the '-f' option to the 'unset' builtin | |
1326 | (*note Bourne Shell Builtins::). | |
a0c0a00f CR |
1327 | |
1328 | The exit status of a function definition is zero unless a syntax | |
1329 | error occurs or a readonly function with the same name already exists. | |
1330 | When executed, the exit status of a function is the exit status of the | |
1331 | last command executed in the body. | |
1332 | ||
1333 | Note that for historical reasons, in the most common usage the curly | |
1334 | braces that surround the body of the function must be separated from the | |
1335 | body by 'blank's or newlines. This is because the braces are reserved | |
1336 | words and are only recognized as such when they are separated from the | |
1337 | command list by whitespace or another shell metacharacter. Also, when | |
1338 | using the braces, the LIST must be terminated by a semicolon, a '&', or | |
1339 | a newline. | |
1340 | ||
1341 | When a function is executed, the arguments to the function become the | |
1342 | positional parameters during its execution (*note Positional | |
1343 | Parameters::). The special parameter '#' that expands to the number of | |
1344 | positional parameters is updated to reflect the change. Special | |
1345 | parameter '0' is unchanged. The first element of the 'FUNCNAME' | |
1346 | variable is set to the name of the function while the function is | |
1347 | executing. | |
1348 | ||
1349 | All other aspects of the shell execution environment are identical | |
1350 | between a function and its caller with these exceptions: the 'DEBUG' and | |
1351 | 'RETURN' traps are not inherited unless the function has been given the | |
1352 | 'trace' attribute using the 'declare' builtin or the '-o functrace' | |
1353 | option has been enabled with the 'set' builtin, (in which case all | |
1354 | functions inherit the 'DEBUG' and 'RETURN' traps), and the 'ERR' trap is | |
1355 | not inherited unless the '-o errtrace' shell option has been enabled. | |
1356 | *Note Bourne Shell Builtins::, for the description of the 'trap' | |
1357 | builtin. | |
1358 | ||
1359 | The 'FUNCNEST' variable, if set to a numeric value greater than 0, | |
1360 | defines a maximum function nesting level. Function invocations that | |
1361 | exceed the limit cause the entire command to abort. | |
1362 | ||
1363 | If the builtin command 'return' is executed in a function, the | |
1364 | function completes and execution resumes with the next command after the | |
1365 | function call. Any command associated with the 'RETURN' trap is | |
1366 | executed before execution resumes. When a function completes, the | |
1367 | values of the positional parameters and the special parameter '#' are | |
1368 | restored to the values they had prior to the function's execution. If a | |
1369 | numeric argument is given to 'return', that is the function's return | |
1370 | status; otherwise the function's return status is the exit status of the | |
1371 | last command executed before the 'return'. | |
1372 | ||
1373 | Variables local to the function may be declared with the 'local' | |
74091dd4 CR |
1374 | builtin ("local variables"). Ordinarily, variables and their values are |
1375 | shared between a function and its caller. These variables are visible | |
1376 | only to the function and the commands it invokes. This is particularly | |
1377 | important when a shell function calls other functions. | |
1378 | ||
1379 | In the following description, the "current scope" is a currently- | |
1380 | executing function. Previous scopes consist of that function's caller | |
1381 | and so on, back to the "global" scope, where the shell is not executing | |
1382 | any shell function. Consequently, a local variable at the current local | |
1383 | scope is a variable declared using the 'local' or 'declare' builtins in | |
1384 | the function that is currently executing. | |
d233b485 CR |
1385 | |
1386 | Local variables "shadow" variables with the same name declared at | |
1387 | previous scopes. For instance, a local variable declared in a function | |
1388 | hides a global variable of the same name: references and assignments | |
1389 | refer to the local variable, leaving the global variable unmodified. | |
1390 | When the function returns, the global variable is once again visible. | |
1391 | ||
74091dd4 | 1392 | The shell uses "dynamic scoping" to control a variable's visibility |
d233b485 CR |
1393 | within functions. With dynamic scoping, visible variables and their |
1394 | values are a result of the sequence of function calls that caused | |
1395 | execution to reach the current function. The value of a variable that a | |
1396 | function sees depends on its value within its caller, if any, whether | |
1397 | that caller is the "global" scope or another shell function. This is | |
1398 | also the value that a local variable declaration "shadows", and the | |
1399 | value that is restored when the function returns. | |
1400 | ||
74091dd4 CR |
1401 | For example, if a variable 'var' is declared as local in function |
1402 | 'func1', and 'func1' calls another function 'func2', references to 'var' | |
1403 | made from within 'func2' will resolve to the local variable 'var' from | |
1404 | 'func1', shadowing any global variable named 'var'. | |
d233b485 CR |
1405 | |
1406 | The following script demonstrates this behavior. When executed, the | |
1407 | script displays | |
1408 | ||
1409 | In func2, var = func1 local | |
1410 | ||
1411 | func1() | |
1412 | { | |
1413 | local var='func1 local' | |
1414 | func2 | |
1415 | } | |
1416 | ||
1417 | func2() | |
1418 | { | |
1419 | echo "In func2, var = $var" | |
1420 | } | |
1421 | ||
1422 | var=global | |
1423 | func1 | |
1424 | ||
1425 | The 'unset' builtin also acts using the same dynamic scope: if a | |
1426 | variable is local to the current scope, 'unset' will unset it; otherwise | |
1427 | the unset will refer to the variable found in any calling scope as | |
1428 | described above. If a variable at the current local scope is unset, it | |
74091dd4 CR |
1429 | will remain so (appearing as unset) until it is reset in that scope or |
1430 | until the function returns. Once the function returns, any instance of | |
1431 | the variable at a previous scope will become visible. If the unset acts | |
1432 | on a variable at a previous scope, any instance of a variable with that | |
1433 | name that had been shadowed will become visible (see below how | |
1434 | 'localvar_unset'shell option changes this behavior). | |
a0c0a00f CR |
1435 | |
1436 | Function names and definitions may be listed with the '-f' option to | |
1437 | the 'declare' ('typeset') builtin command (*note Bash Builtins::). The | |
1438 | '-F' option to 'declare' or 'typeset' will list the function names only | |
1439 | (and optionally the source file and line number, if the 'extdebug' shell | |
74091dd4 CR |
1440 | option is enabled). Functions may be exported so that child shell |
1441 | processes (those created when executing a separate shell invocation) | |
a0c0a00f | 1442 | automatically have them defined with the '-f' option to the 'export' |
d233b485 | 1443 | builtin (*note Bourne Shell Builtins::). |
a0c0a00f CR |
1444 | |
1445 | Functions may be recursive. The 'FUNCNEST' variable may be used to | |
1446 | limit the depth of the function call stack and restrict the number of | |
1447 | function invocations. By default, no limit is placed on the number of | |
1448 | recursive calls. | |
1449 | ||
1450 | \1f | |
1451 | File: bash.info, Node: Shell Parameters, Next: Shell Expansions, Prev: Shell Functions, Up: Basic Shell Features | |
1452 | ||
1453 | 3.4 Shell Parameters | |
1454 | ==================== | |
1455 | ||
1456 | * Menu: | |
1457 | ||
1458 | * Positional Parameters:: The shell's command-line arguments. | |
1459 | * Special Parameters:: Parameters denoted by special characters. | |
1460 | ||
74091dd4 CR |
1461 | A "parameter" is an entity that stores values. It can be a 'name', a |
1462 | number, or one of the special characters listed below. A "variable" is | |
1463 | a parameter denoted by a 'name'. A variable has a 'value' and zero or | |
1464 | more 'attributes'. Attributes are assigned using the 'declare' builtin | |
1465 | command (see the description of the 'declare' builtin in *note Bash | |
1466 | Builtins::). | |
a0c0a00f CR |
1467 | |
1468 | A parameter is set if it has been assigned a value. The null string | |
1469 | is a valid value. Once a variable is set, it may be unset only by using | |
1470 | the 'unset' builtin command. | |
1471 | ||
1472 | A variable may be assigned to by a statement of the form | |
1473 | NAME=[VALUE] | |
1474 | If VALUE is not given, the variable is assigned the null string. All | |
1475 | VALUEs undergo tilde expansion, parameter and variable expansion, | |
74091dd4 CR |
1476 | command substitution, arithmetic expansion, and quote removal (*note |
1477 | Shell Parameter Expansion::). If the variable has its 'integer' | |
1478 | attribute set, then VALUE is evaluated as an arithmetic expression even | |
1479 | if the '$((...))' expansion is not used (*note Arithmetic Expansion::). | |
1480 | Word splitting and filename expansion are not performed. Assignment | |
1481 | statements may also appear as arguments to the 'alias', 'declare', | |
1482 | 'typeset', 'export', 'readonly', and 'local' builtin commands | |
1483 | ("declaration" commands). When in POSIX mode (*note Bash POSIX Mode::), | |
1484 | these builtins may appear in a command after one or more instances of | |
1485 | the 'command' builtin and retain these assignment statement properties. | |
a0c0a00f CR |
1486 | |
1487 | In the context where an assignment statement is assigning a value to | |
1488 | a shell variable or array index (*note Arrays::), the '+=' operator can | |
1489 | be used to append to or add to the variable's previous value. This | |
1490 | includes arguments to builtin commands such as 'declare' that accept | |
74091dd4 CR |
1491 | assignment statements (declaration commands). When '+=' is applied to a |
1492 | variable for which the 'integer' attribute has been set, VALUE is | |
a0c0a00f CR |
1493 | evaluated as an arithmetic expression and added to the variable's |
1494 | current value, which is also evaluated. When '+=' is applied to an | |
1495 | array variable using compound assignment (*note Arrays::), the | |
1496 | variable's value is not unset (as it is when using '='), and new values | |
1497 | are appended to the array beginning at one greater than the array's | |
1498 | maximum index (for indexed arrays), or added as additional key-value | |
1499 | pairs in an associative array. When applied to a string-valued | |
1500 | variable, VALUE is expanded and appended to the variable's value. | |
1501 | ||
74091dd4 | 1502 | A variable can be assigned the 'nameref' attribute using the '-n' |
a0c0a00f | 1503 | option to the 'declare' or 'local' builtin commands (*note Bash |
74091dd4 | 1504 | Builtins::) to create a "nameref", or a reference to another variable. |
a0c0a00f CR |
1505 | This allows variables to be manipulated indirectly. Whenever the |
1506 | nameref variable is referenced, assigned to, unset, or has its | |
1507 | attributes modified (other than using or changing the nameref attribute | |
1508 | itself), the operation is actually performed on the variable specified | |
1509 | by the nameref variable's value. A nameref is commonly used within | |
1510 | shell functions to refer to a variable whose name is passed as an | |
1511 | argument to the function. For instance, if a variable name is passed to | |
1512 | a shell function as its first argument, running | |
1513 | declare -n ref=$1 | |
74091dd4 | 1514 | inside the function creates a nameref variable 'ref' whose value is the |
a0c0a00f | 1515 | variable name passed as the first argument. References and assignments |
74091dd4 | 1516 | to 'ref', and changes to its attributes, are treated as references, |
a0c0a00f CR |
1517 | assignments, and attribute modifications to the variable whose name was |
1518 | passed as '$1'. | |
1519 | ||
1520 | If the control variable in a 'for' loop has the nameref attribute, | |
1521 | the list of words can be a list of shell variables, and a name reference | |
1522 | will be established for each word in the list, in turn, when the loop is | |
1523 | executed. Array variables cannot be given the nameref attribute. | |
1524 | However, nameref variables can reference array variables and subscripted | |
1525 | array variables. Namerefs can be unset using the '-n' option to the | |
1526 | 'unset' builtin (*note Bourne Shell Builtins::). Otherwise, if 'unset' | |
1527 | is executed with the name of a nameref variable as an argument, the | |
1528 | variable referenced by the nameref variable will be unset. | |
1529 | ||
1530 | \1f | |
1531 | File: bash.info, Node: Positional Parameters, Next: Special Parameters, Up: Shell Parameters | |
1532 | ||
1533 | 3.4.1 Positional Parameters | |
1534 | --------------------------- | |
1535 | ||
74091dd4 | 1536 | A "positional parameter" is a parameter denoted by one or more digits, |
a0c0a00f CR |
1537 | other than the single digit '0'. Positional parameters are assigned |
1538 | from the shell's arguments when it is invoked, and may be reassigned | |
1539 | using the 'set' builtin command. Positional parameter 'N' may be | |
1540 | referenced as '${N}', or as '$N' when 'N' consists of a single digit. | |
1541 | Positional parameters may not be assigned to with assignment statements. | |
1542 | The 'set' and 'shift' builtins are used to set and unset them (*note | |
1543 | Shell Builtin Commands::). The positional parameters are temporarily | |
1544 | replaced when a shell function is executed (*note Shell Functions::). | |
1545 | ||
1546 | When a positional parameter consisting of more than a single digit is | |
1547 | expanded, it must be enclosed in braces. | |
1548 | ||
1549 | \1f | |
1550 | File: bash.info, Node: Special Parameters, Prev: Positional Parameters, Up: Shell Parameters | |
1551 | ||
1552 | 3.4.2 Special Parameters | |
1553 | ------------------------ | |
1554 | ||
1555 | The shell treats several parameters specially. These parameters may | |
1556 | only be referenced; assignment to them is not allowed. | |
1557 | ||
1558 | '*' | |
1559 | ($*) Expands to the positional parameters, starting from one. When | |
1560 | the expansion is not within double quotes, each positional | |
1561 | parameter expands to a separate word. In contexts where it is | |
1562 | performed, those words are subject to further word splitting and | |
8868edaf | 1563 | filename expansion. When the expansion occurs within double |
a0c0a00f CR |
1564 | quotes, it expands to a single word with the value of each |
1565 | parameter separated by the first character of the 'IFS' special | |
1566 | variable. That is, '"$*"' is equivalent to '"$1C$2C..."', where C | |
1567 | is the first character of the value of the 'IFS' variable. If | |
1568 | 'IFS' is unset, the parameters are separated by spaces. If 'IFS' | |
1569 | is null, the parameters are joined without intervening separators. | |
1570 | ||
1571 | '@' | |
d233b485 CR |
1572 | ($@) Expands to the positional parameters, starting from one. In |
1573 | contexts where word splitting is performed, this expands each | |
1574 | positional parameter to a separate word; if not within double | |
1575 | quotes, these words are subject to word splitting. In contexts | |
1576 | where word splitting is not performed, this expands to a single | |
1577 | word with each positional parameter separated by a space. When the | |
1578 | expansion occurs within double quotes, and word splitting is | |
1579 | performed, each parameter expands to a separate word. That is, | |
1580 | '"$@"' is equivalent to '"$1" "$2" ...'. If the double-quoted | |
1581 | expansion occurs within a word, the expansion of the first | |
1582 | parameter is joined with the beginning part of the original word, | |
1583 | and the expansion of the last parameter is joined with the last | |
1584 | part of the original word. When there are no positional | |
1585 | parameters, '"$@"' and '$@' expand to nothing (i.e., they are | |
1586 | removed). | |
a0c0a00f CR |
1587 | |
1588 | '#' | |
1589 | ($#) Expands to the number of positional parameters in decimal. | |
1590 | ||
1591 | '?' | |
1592 | ($?) Expands to the exit status of the most recently executed | |
1593 | foreground pipeline. | |
1594 | ||
1595 | '-' | |
1596 | ($-, a hyphen.) Expands to the current option flags as specified | |
1597 | upon invocation, by the 'set' builtin command, or those set by the | |
1598 | shell itself (such as the '-i' option). | |
1599 | ||
1600 | '$' | |
74091dd4 CR |
1601 | ($$) Expands to the process ID of the shell. In a subshell, it |
1602 | expands to the process ID of the invoking shell, not the subshell. | |
a0c0a00f CR |
1603 | |
1604 | '!' | |
1605 | ($!) Expands to the process ID of the job most recently placed | |
1606 | into the background, whether executed as an asynchronous command or | |
1607 | using the 'bg' builtin (*note Job Control Builtins::). | |
1608 | ||
1609 | '0' | |
1610 | ($0) Expands to the name of the shell or shell script. This is set | |
1611 | at shell initialization. If Bash is invoked with a file of | |
1612 | commands (*note Shell Scripts::), '$0' is set to the name of that | |
1613 | file. If Bash is started with the '-c' option (*note Invoking | |
1614 | Bash::), then '$0' is set to the first argument after the string to | |
1615 | be executed, if one is present. Otherwise, it is set to the | |
1616 | filename used to invoke Bash, as given by argument zero. | |
1617 | ||
a0c0a00f CR |
1618 | \1f |
1619 | File: bash.info, Node: Shell Expansions, Next: Redirections, Prev: Shell Parameters, Up: Basic Shell Features | |
1620 | ||
1621 | 3.5 Shell Expansions | |
1622 | ==================== | |
1623 | ||
1624 | Expansion is performed on the command line after it has been split into | |
1625 | 'token's. There are seven kinds of expansion performed: | |
1626 | ||
1627 | * brace expansion | |
1628 | * tilde expansion | |
1629 | * parameter and variable expansion | |
1630 | * command substitution | |
1631 | * arithmetic expansion | |
1632 | * word splitting | |
1633 | * filename expansion | |
1634 | ||
1635 | * Menu: | |
1636 | ||
1637 | * Brace Expansion:: Expansion of expressions within braces. | |
1638 | * Tilde Expansion:: Expansion of the ~ character. | |
1639 | * Shell Parameter Expansion:: How Bash expands variables to their values. | |
1640 | * Command Substitution:: Using the output of a command as an argument. | |
1641 | * Arithmetic Expansion:: How to use arithmetic in shell expansions. | |
1642 | * Process Substitution:: A way to write and read to and from a | |
1643 | command. | |
1644 | * Word Splitting:: How the results of expansion are split into separate | |
1645 | arguments. | |
1646 | * Filename Expansion:: A shorthand for specifying filenames matching patterns. | |
1647 | * Quote Removal:: How and when quote characters are removed from | |
1648 | words. | |
1649 | ||
1650 | The order of expansions is: brace expansion; tilde expansion, | |
1651 | parameter and variable expansion, arithmetic expansion, and command | |
1652 | substitution (done in a left-to-right fashion); word splitting; and | |
1653 | filename expansion. | |
1654 | ||
1655 | On systems that can support it, there is an additional expansion | |
74091dd4 CR |
1656 | available: "process substitution". This is performed at the same time |
1657 | as tilde, parameter, variable, and arithmetic expansion and command | |
a0c0a00f CR |
1658 | substitution. |
1659 | ||
1660 | After these expansions are performed, quote characters present in the | |
74091dd4 CR |
1661 | original word are removed unless they have been quoted themselves |
1662 | ("quote removal"). | |
a0c0a00f CR |
1663 | |
1664 | Only brace expansion, word splitting, and filename expansion can | |
d233b485 | 1665 | increase the number of words of the expansion; other expansions expand a |
a0c0a00f | 1666 | single word to a single word. The only exceptions to this are the |
d233b485 CR |
1667 | expansions of '"$@"' and '$*' (*note Special Parameters::), and |
1668 | '"${NAME[@]}"' and '${NAME[*]}' (*note Arrays::). | |
a0c0a00f CR |
1669 | |
1670 | After all expansions, 'quote removal' (*note Quote Removal::) is | |
1671 | performed. | |
1672 | ||
1673 | \1f | |
1674 | File: bash.info, Node: Brace Expansion, Next: Tilde Expansion, Up: Shell Expansions | |
1675 | ||
1676 | 3.5.1 Brace Expansion | |
1677 | --------------------- | |
1678 | ||
1679 | Brace expansion is a mechanism by which arbitrary strings may be | |
74091dd4 | 1680 | generated. This mechanism is similar to "filename expansion" (*note |
a0c0a00f CR |
1681 | Filename Expansion::), but the filenames generated need not exist. |
1682 | Patterns to be brace expanded take the form of an optional PREAMBLE, | |
1683 | followed by either a series of comma-separated strings or a sequence | |
1684 | expression between a pair of braces, followed by an optional POSTSCRIPT. | |
1685 | The preamble is prefixed to each string contained within the braces, and | |
1686 | the postscript is then appended to each resulting string, expanding left | |
1687 | to right. | |
1688 | ||
1689 | Brace expansions may be nested. The results of each expanded string | |
1690 | are not sorted; left to right order is preserved. For example, | |
1691 | bash$ echo a{d,c,b}e | |
1692 | ade ace abe | |
1693 | ||
1694 | A sequence expression takes the form '{X..Y[..INCR]}', where X and Y | |
74091dd4 CR |
1695 | are either integers or letters, and INCR, an optional increment, is an |
1696 | integer. When integers are supplied, the expression expands to each | |
1697 | number between X and Y, inclusive. Supplied integers may be prefixed | |
1698 | with '0' to force each term to have the same width. When either X or Y | |
1699 | begins with a zero, the shell attempts to force all generated terms to | |
1700 | contain the same number of digits, zero-padding where necessary. When | |
1701 | letters are supplied, the expression expands to each character | |
1702 | lexicographically between X and Y, inclusive, using the default C | |
1703 | locale. Note that both X and Y must be of the same type (integer or | |
1704 | letter). When the increment is supplied, it is used as the difference | |
1705 | between each term. The default increment is 1 or -1 as appropriate. | |
a0c0a00f CR |
1706 | |
1707 | Brace expansion is performed before any other expansions, and any | |
1708 | characters special to other expansions are preserved in the result. It | |
1709 | is strictly textual. Bash does not apply any syntactic interpretation | |
d233b485 | 1710 | to the context of the expansion or the text between the braces. |
a0c0a00f CR |
1711 | |
1712 | A correctly-formed brace expansion must contain unquoted opening and | |
1713 | closing braces, and at least one unquoted comma or a valid sequence | |
1714 | expression. Any incorrectly formed brace expansion is left unchanged. | |
1715 | ||
1716 | A { or ',' may be quoted with a backslash to prevent its being | |
1717 | considered part of a brace expression. To avoid conflicts with | |
1718 | parameter expansion, the string '${' is not considered eligible for | |
8868edaf | 1719 | brace expansion, and inhibits brace expansion until the closing '}'. |
a0c0a00f CR |
1720 | |
1721 | This construct is typically used as shorthand when the common prefix | |
1722 | of the strings to be generated is longer than in the above example: | |
1723 | mkdir /usr/local/src/bash/{old,new,dist,bugs} | |
1724 | or | |
1725 | chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}} | |
1726 | ||
1727 | \1f | |
1728 | File: bash.info, Node: Tilde Expansion, Next: Shell Parameter Expansion, Prev: Brace Expansion, Up: Shell Expansions | |
1729 | ||
1730 | 3.5.2 Tilde Expansion | |
1731 | --------------------- | |
1732 | ||
1733 | If a word begins with an unquoted tilde character ('~'), all of the | |
1734 | characters up to the first unquoted slash (or all characters, if there | |
74091dd4 | 1735 | is no unquoted slash) are considered a "tilde-prefix". If none of the |
a0c0a00f | 1736 | characters in the tilde-prefix are quoted, the characters in the |
74091dd4 | 1737 | tilde-prefix following the tilde are treated as a possible "login name". |
a0c0a00f CR |
1738 | If this login name is the null string, the tilde is replaced with the |
1739 | value of the 'HOME' shell variable. If 'HOME' is unset, the home | |
1740 | directory of the user executing the shell is substituted instead. | |
1741 | Otherwise, the tilde-prefix is replaced with the home directory | |
1742 | associated with the specified login name. | |
1743 | ||
1744 | If the tilde-prefix is '~+', the value of the shell variable 'PWD' | |
1745 | replaces the tilde-prefix. If the tilde-prefix is '~-', the value of | |
1746 | the shell variable 'OLDPWD', if it is set, is substituted. | |
1747 | ||
1748 | If the characters following the tilde in the tilde-prefix consist of | |
1749 | a number N, optionally prefixed by a '+' or a '-', the tilde-prefix is | |
1750 | replaced with the corresponding element from the directory stack, as it | |
1751 | would be displayed by the 'dirs' builtin invoked with the characters | |
1752 | following tilde in the tilde-prefix as an argument (*note The Directory | |
1753 | Stack::). If the tilde-prefix, sans the tilde, consists of a number | |
1754 | without a leading '+' or '-', '+' is assumed. | |
1755 | ||
1756 | If the login name is invalid, or the tilde expansion fails, the word | |
1757 | is left unchanged. | |
1758 | ||
1759 | Each variable assignment is checked for unquoted tilde-prefixes | |
1760 | immediately following a ':' or the first '='. In these cases, tilde | |
1761 | expansion is also performed. Consequently, one may use filenames with | |
1762 | tildes in assignments to 'PATH', 'MAILPATH', and 'CDPATH', and the shell | |
1763 | assigns the expanded value. | |
1764 | ||
1765 | The following table shows how Bash treats unquoted tilde-prefixes: | |
1766 | ||
1767 | '~' | |
1768 | The value of '$HOME' | |
1769 | '~/foo' | |
1770 | '$HOME/foo' | |
1771 | ||
1772 | '~fred/foo' | |
1773 | The subdirectory 'foo' of the home directory of the user 'fred' | |
1774 | ||
1775 | '~+/foo' | |
1776 | '$PWD/foo' | |
1777 | ||
1778 | '~-/foo' | |
1779 | '${OLDPWD-'~-'}/foo' | |
1780 | ||
1781 | '~N' | |
1782 | The string that would be displayed by 'dirs +N' | |
1783 | ||
1784 | '~+N' | |
1785 | The string that would be displayed by 'dirs +N' | |
1786 | ||
1787 | '~-N' | |
1788 | The string that would be displayed by 'dirs -N' | |
1789 | ||
d233b485 CR |
1790 | Bash also performs tilde expansion on words satisfying the conditions |
1791 | of variable assignments (*note Shell Parameters::) when they appear as | |
1792 | arguments to simple commands. Bash does not do this, except for the | |
74091dd4 | 1793 | declaration commands listed above, when in POSIX mode. |
d233b485 | 1794 | |
a0c0a00f CR |
1795 | \1f |
1796 | File: bash.info, Node: Shell Parameter Expansion, Next: Command Substitution, Prev: Tilde Expansion, Up: Shell Expansions | |
1797 | ||
1798 | 3.5.3 Shell Parameter Expansion | |
1799 | ------------------------------- | |
1800 | ||
1801 | The '$' character introduces parameter expansion, command substitution, | |
1802 | or arithmetic expansion. The parameter name or symbol to be expanded | |
1803 | may be enclosed in braces, which are optional but serve to protect the | |
1804 | variable to be expanded from characters immediately following it which | |
1805 | could be interpreted as part of the name. | |
1806 | ||
1807 | When braces are used, the matching ending brace is the first '}' not | |
1808 | escaped by a backslash or within a quoted string, and not within an | |
1809 | embedded arithmetic expansion, command substitution, or parameter | |
1810 | expansion. | |
1811 | ||
1812 | The basic form of parameter expansion is ${PARAMETER}. The value of | |
1813 | PARAMETER is substituted. The PARAMETER is a shell parameter as | |
1814 | described above (*note Shell Parameters::) or an array reference (*note | |
1815 | Arrays::). The braces are required when PARAMETER is a positional | |
1816 | parameter with more than one digit, or when PARAMETER is followed by a | |
1817 | character that is not to be interpreted as part of its name. | |
1818 | ||
1819 | If the first character of PARAMETER is an exclamation point (!), and | |
74091dd4 | 1820 | PARAMETER is not a nameref, it introduces a level of indirection. Bash |
d233b485 CR |
1821 | uses the value formed by expanding the rest of PARAMETER as the new |
1822 | PARAMETER; this is then expanded and that value is used in the rest of | |
1823 | the expansion, rather than the expansion of the original PARAMETER. | |
1824 | This is known as 'indirect expansion'. The value is subject to tilde | |
1825 | expansion, parameter expansion, command substitution, and arithmetic | |
1826 | expansion. If PARAMETER is a nameref, this expands to the name of the | |
1827 | variable referenced by PARAMETER instead of performing the complete | |
1828 | indirect expansion. The exceptions to this are the expansions of | |
1829 | ${!PREFIX*} and ${!NAME[@]} described below. The exclamation point must | |
1830 | immediately follow the left brace in order to introduce indirection. | |
a0c0a00f CR |
1831 | |
1832 | In each of the cases below, WORD is subject to tilde expansion, | |
1833 | parameter expansion, command substitution, and arithmetic expansion. | |
1834 | ||
1835 | When not performing substring expansion, using the form described | |
1836 | below (e.g., ':-'), Bash tests for a parameter that is unset or null. | |
1837 | Omitting the colon results in a test only for a parameter that is unset. | |
1838 | Put another way, if the colon is included, the operator tests for both | |
1839 | PARAMETER's existence and that its value is not null; if the colon is | |
1840 | omitted, the operator tests only for existence. | |
1841 | ||
1842 | '${PARAMETER:-WORD}' | |
1843 | If PARAMETER is unset or null, the expansion of WORD is | |
1844 | substituted. Otherwise, the value of PARAMETER is substituted. | |
1845 | ||
74091dd4 CR |
1846 | $ v=123 |
1847 | $ echo ${v-unset} | |
1848 | 123 | |
1849 | ||
a0c0a00f CR |
1850 | '${PARAMETER:=WORD}' |
1851 | If PARAMETER is unset or null, the expansion of WORD is assigned to | |
1852 | PARAMETER. The value of PARAMETER is then substituted. Positional | |
1853 | parameters and special parameters may not be assigned to in this | |
1854 | way. | |
1855 | ||
74091dd4 CR |
1856 | $ var= |
1857 | $ : ${var:=DEFAULT} | |
1858 | $ echo $var | |
1859 | DEFAULT | |
1860 | ||
a0c0a00f CR |
1861 | '${PARAMETER:?WORD}' |
1862 | If PARAMETER is null or unset, the expansion of WORD (or a message | |
1863 | to that effect if WORD is not present) is written to the standard | |
1864 | error and the shell, if it is not interactive, exits. Otherwise, | |
1865 | the value of PARAMETER is substituted. | |
1866 | ||
74091dd4 CR |
1867 | $ var= |
1868 | $ : ${var:?var is unset or null} | |
1869 | bash: var: var is unset or null | |
1870 | ||
a0c0a00f CR |
1871 | '${PARAMETER:+WORD}' |
1872 | If PARAMETER is null or unset, nothing is substituted, otherwise | |
1873 | the expansion of WORD is substituted. | |
1874 | ||
74091dd4 CR |
1875 | $ var=123 |
1876 | $ echo ${var:+var is set and not null} | |
1877 | var is set and not null | |
1878 | ||
a0c0a00f CR |
1879 | '${PARAMETER:OFFSET}' |
1880 | '${PARAMETER:OFFSET:LENGTH}' | |
1881 | This is referred to as Substring Expansion. It expands to up to | |
1882 | LENGTH characters of the value of PARAMETER starting at the | |
74091dd4 CR |
1883 | character specified by OFFSET. If PARAMETER is '@' or '*', an |
1884 | indexed array subscripted by '@' or '*', or an associative array | |
1885 | name, the results differ as described below. If LENGTH is omitted, | |
1886 | it expands to the substring of the value of PARAMETER starting at | |
1887 | the character specified by OFFSET and extending to the end of the | |
a0c0a00f CR |
1888 | value. LENGTH and OFFSET are arithmetic expressions (*note Shell |
1889 | Arithmetic::). | |
1890 | ||
1891 | If OFFSET evaluates to a number less than zero, the value is used | |
1892 | as an offset in characters from the end of the value of PARAMETER. | |
1893 | If LENGTH evaluates to a number less than zero, it is interpreted | |
1894 | as an offset in characters from the end of the value of PARAMETER | |
1895 | rather than a number of characters, and the expansion is the | |
1896 | characters between OFFSET and that result. Note that a negative | |
1897 | offset must be separated from the colon by at least one space to | |
1898 | avoid being confused with the ':-' expansion. | |
1899 | ||
1900 | Here are some examples illustrating substring expansion on | |
1901 | parameters and subscripted arrays: | |
1902 | ||
1903 | $ string=01234567890abcdefgh | |
1904 | $ echo ${string:7} | |
1905 | 7890abcdefgh | |
1906 | $ echo ${string:7:0} | |
d233b485 | 1907 | |
a0c0a00f CR |
1908 | $ echo ${string:7:2} |
1909 | 78 | |
1910 | $ echo ${string:7:-2} | |
1911 | 7890abcdef | |
1912 | $ echo ${string: -7} | |
1913 | bcdefgh | |
1914 | $ echo ${string: -7:0} | |
d233b485 | 1915 | |
a0c0a00f CR |
1916 | $ echo ${string: -7:2} |
1917 | bc | |
1918 | $ echo ${string: -7:-2} | |
1919 | bcdef | |
1920 | $ set -- 01234567890abcdefgh | |
1921 | $ echo ${1:7} | |
1922 | 7890abcdefgh | |
1923 | $ echo ${1:7:0} | |
d233b485 | 1924 | |
a0c0a00f CR |
1925 | $ echo ${1:7:2} |
1926 | 78 | |
1927 | $ echo ${1:7:-2} | |
1928 | 7890abcdef | |
1929 | $ echo ${1: -7} | |
1930 | bcdefgh | |
1931 | $ echo ${1: -7:0} | |
d233b485 | 1932 | |
a0c0a00f CR |
1933 | $ echo ${1: -7:2} |
1934 | bc | |
1935 | $ echo ${1: -7:-2} | |
1936 | bcdef | |
1937 | $ array[0]=01234567890abcdefgh | |
1938 | $ echo ${array[0]:7} | |
1939 | 7890abcdefgh | |
1940 | $ echo ${array[0]:7:0} | |
d233b485 | 1941 | |
a0c0a00f CR |
1942 | $ echo ${array[0]:7:2} |
1943 | 78 | |
1944 | $ echo ${array[0]:7:-2} | |
1945 | 7890abcdef | |
1946 | $ echo ${array[0]: -7} | |
1947 | bcdefgh | |
1948 | $ echo ${array[0]: -7:0} | |
d233b485 | 1949 | |
a0c0a00f CR |
1950 | $ echo ${array[0]: -7:2} |
1951 | bc | |
1952 | $ echo ${array[0]: -7:-2} | |
1953 | bcdef | |
1954 | ||
74091dd4 CR |
1955 | If PARAMETER is '@' or '*', the result is LENGTH positional |
1956 | parameters beginning at OFFSET. A negative OFFSET is taken | |
1957 | relative to one greater than the greatest positional parameter, so | |
1958 | an offset of -1 evaluates to the last positional parameter. It is | |
1959 | an expansion error if LENGTH evaluates to a number less than zero. | |
a0c0a00f CR |
1960 | |
1961 | The following examples illustrate substring expansion using | |
1962 | positional parameters: | |
1963 | ||
1964 | $ set -- 1 2 3 4 5 6 7 8 9 0 a b c d e f g h | |
1965 | $ echo ${@:7} | |
1966 | 7 8 9 0 a b c d e f g h | |
1967 | $ echo ${@:7:0} | |
d233b485 | 1968 | |
a0c0a00f CR |
1969 | $ echo ${@:7:2} |
1970 | 7 8 | |
1971 | $ echo ${@:7:-2} | |
1972 | bash: -2: substring expression < 0 | |
1973 | $ echo ${@: -7:2} | |
1974 | b c | |
1975 | $ echo ${@:0} | |
1976 | ./bash 1 2 3 4 5 6 7 8 9 0 a b c d e f g h | |
1977 | $ echo ${@:0:2} | |
1978 | ./bash 1 | |
1979 | $ echo ${@: -7:0} | |
d233b485 | 1980 | |
a0c0a00f CR |
1981 | |
1982 | If PARAMETER is an indexed array name subscripted by '@' or '*', | |
1983 | the result is the LENGTH members of the array beginning with | |
1984 | '${PARAMETER[OFFSET]}'. A negative OFFSET is taken relative to one | |
1985 | greater than the maximum index of the specified array. It is an | |
1986 | expansion error if LENGTH evaluates to a number less than zero. | |
1987 | ||
1988 | These examples show how you can use substring expansion with | |
1989 | indexed arrays: | |
1990 | ||
1991 | $ array=(0 1 2 3 4 5 6 7 8 9 0 a b c d e f g h) | |
1992 | $ echo ${array[@]:7} | |
1993 | 7 8 9 0 a b c d e f g h | |
1994 | $ echo ${array[@]:7:2} | |
1995 | 7 8 | |
1996 | $ echo ${array[@]: -7:2} | |
1997 | b c | |
1998 | $ echo ${array[@]: -7:-2} | |
1999 | bash: -2: substring expression < 0 | |
2000 | $ echo ${array[@]:0} | |
2001 | 0 1 2 3 4 5 6 7 8 9 0 a b c d e f g h | |
2002 | $ echo ${array[@]:0:2} | |
2003 | 0 1 | |
2004 | $ echo ${array[@]: -7:0} | |
d233b485 | 2005 | |
a0c0a00f CR |
2006 | |
2007 | Substring expansion applied to an associative array produces | |
2008 | undefined results. | |
2009 | ||
2010 | Substring indexing is zero-based unless the positional parameters | |
2011 | are used, in which case the indexing starts at 1 by default. If | |
8868edaf | 2012 | OFFSET is 0, and the positional parameters are used, '$0' is |
a0c0a00f CR |
2013 | prefixed to the list. |
2014 | ||
2015 | '${!PREFIX*}' | |
2016 | '${!PREFIX@}' | |
2017 | Expands to the names of variables whose names begin with PREFIX, | |
2018 | separated by the first character of the 'IFS' special variable. | |
2019 | When '@' is used and the expansion appears within double quotes, | |
2020 | each variable name expands to a separate word. | |
2021 | ||
2022 | '${!NAME[@]}' | |
2023 | '${!NAME[*]}' | |
2024 | If NAME is an array variable, expands to the list of array indices | |
2025 | (keys) assigned in NAME. If NAME is not an array, expands to 0 if | |
2026 | NAME is set and null otherwise. When '@' is used and the expansion | |
2027 | appears within double quotes, each key expands to a separate word. | |
2028 | ||
2029 | '${#PARAMETER}' | |
2030 | The length in characters of the expanded value of PARAMETER is | |
2031 | substituted. If PARAMETER is '*' or '@', the value substituted is | |
2032 | the number of positional parameters. If PARAMETER is an array name | |
2033 | subscripted by '*' or '@', the value substituted is the number of | |
2034 | elements in the array. If PARAMETER is an indexed array name | |
2035 | subscripted by a negative number, that number is interpreted as | |
2036 | relative to one greater than the maximum index of PARAMETER, so | |
2037 | negative indices count back from the end of the array, and an index | |
2038 | of -1 references the last element. | |
2039 | ||
2040 | '${PARAMETER#WORD}' | |
2041 | '${PARAMETER##WORD}' | |
d233b485 CR |
2042 | The WORD is expanded to produce a pattern and matched according to |
2043 | the rules described below (*note Pattern Matching::). If the | |
2044 | pattern matches the beginning of the expanded value of PARAMETER, | |
2045 | then the result of the expansion is the expanded value of PARAMETER | |
2046 | with the shortest matching pattern (the '#' case) or the longest | |
2047 | matching pattern (the '##' case) deleted. If PARAMETER is '@' or | |
2048 | '*', the pattern removal operation is applied to each positional | |
2049 | parameter in turn, and the expansion is the resultant list. If | |
2050 | PARAMETER is an array variable subscripted with '@' or '*', the | |
2051 | pattern removal operation is applied to each member of the array in | |
2052 | turn, and the expansion is the resultant list. | |
a0c0a00f CR |
2053 | |
2054 | '${PARAMETER%WORD}' | |
2055 | '${PARAMETER%%WORD}' | |
d233b485 CR |
2056 | The WORD is expanded to produce a pattern and matched according to |
2057 | the rules described below (*note Pattern Matching::). If the | |
8868edaf CR |
2058 | pattern matches a trailing portion of the expanded value of |
2059 | PARAMETER, then the result of the expansion is the value of | |
2060 | PARAMETER with the shortest matching pattern (the '%' case) or the | |
2061 | longest matching pattern (the '%%' case) deleted. If PARAMETER is | |
2062 | '@' or '*', the pattern removal operation is applied to each | |
2063 | positional parameter in turn, and the expansion is the resultant | |
2064 | list. If PARAMETER is an array variable subscripted with '@' or | |
2065 | '*', the pattern removal operation is applied to each member of the | |
2066 | array in turn, and the expansion is the resultant list. | |
a0c0a00f CR |
2067 | |
2068 | '${PARAMETER/PATTERN/STRING}' | |
74091dd4 CR |
2069 | '${PARAMETER//PATTERN/STRING}' |
2070 | '${PARAMETER/#PATTERN/STRING}' | |
2071 | '${PARAMETER/%PATTERN/STRING}' | |
a0c0a00f CR |
2072 | The PATTERN is expanded to produce a pattern just as in filename |
2073 | expansion. PARAMETER is expanded and the longest match of PATTERN | |
74091dd4 CR |
2074 | against its value is replaced with STRING. STRING undergoes tilde |
2075 | expansion, parameter and variable expansion, arithmetic expansion, | |
2076 | command and process substitution, and quote removal. The match is | |
2077 | performed according to the rules described below (*note Pattern | |
2078 | Matching::). | |
2079 | ||
2080 | In the first form above, only the first match is replaced. If | |
2081 | there are two slashes separating PARAMETER and PATTERN (the second | |
2082 | form above), all matches of PATTERN are replaced with STRING. If | |
2083 | PATTERN is preceded by '#' (the third form above), it must match at | |
2084 | the beginning of the expanded value of PARAMETER. If PATTERN is | |
2085 | preceded by '%' (the fourth form above), it must match at the end | |
2086 | of the expanded value of PARAMETER. If the expansion of STRING is | |
2087 | null, matches of PATTERN are deleted. If STRING is null, matches | |
2088 | of PATTERN are deleted and the '/' following PATTERN may be | |
2089 | omitted. | |
2090 | ||
2091 | If the 'patsub_replacement' shell option is enabled using 'shopt', | |
2092 | any unquoted instances of '&' in STRING are replaced with the | |
2093 | matching portion of PATTERN. This is intended to duplicate a | |
2094 | common 'sed' idiom. | |
2095 | ||
2096 | Quoting any part of STRING inhibits replacement in the expansion of | |
2097 | the quoted portion, including replacement strings stored in shell | |
2098 | variables. Backslash will escape '&' in STRING; the backslash is | |
2099 | removed in order to permit a literal '&' in the replacement string. | |
2100 | Users should take care if STRING is double-quoted to avoid unwanted | |
2101 | interactions between the backslash and double-quoting, since | |
2102 | backslash has special meaning within double quotes. Pattern | |
2103 | substitution performs the check for unquoted '&' after expanding | |
2104 | STRING, so users should ensure to properly quote any occurrences of | |
2105 | '&' they want to be taken literally in the replacement and ensure | |
2106 | any instances of '&' they want to be replaced are unquoted. | |
2107 | ||
2108 | For instance, | |
2109 | ||
2110 | var=abcdef | |
2111 | rep='& ' | |
2112 | echo ${var/abc/& } | |
2113 | echo "${var/abc/& }" | |
2114 | echo ${var/abc/$rep} | |
2115 | echo "${var/abc/$rep}" | |
2116 | ||
2117 | will display four lines of "abc def", while | |
2118 | ||
2119 | var=abcdef | |
2120 | rep='& ' | |
2121 | echo ${var/abc/\& } | |
2122 | echo "${var/abc/\& }" | |
2123 | echo ${var/abc/"& "} | |
2124 | echo ${var/abc/"$rep"} | |
2125 | ||
2126 | will display four lines of "& def". Like the pattern removal | |
2127 | operators, double quotes surrounding the replacement string quote | |
2128 | the expanded characters, while double quotes enclosing the entire | |
2129 | parameter substitution do not, since the expansion is performed in | |
2130 | a context that doesn't take any enclosing double quotes into | |
2131 | account. | |
2132 | ||
2133 | Since backslash can escape '&', it can also escape a backslash in | |
2134 | the replacement string. This means that '\\' will insert a literal | |
2135 | backslash into the replacement, so these two 'echo' commands | |
2136 | ||
2137 | var=abcdef | |
2138 | rep='\\&xyz' | |
2139 | echo ${var/abc/\\&xyz} | |
2140 | echo ${var/abc/$rep} | |
2141 | ||
2142 | will both output '\abcxyzdef'. | |
2143 | ||
2144 | It should rarely be necessary to enclose only STRING in double | |
2145 | quotes. | |
2146 | ||
2147 | If the 'nocasematch' shell option (see the description of 'shopt' | |
2148 | in *note The Shopt Builtin::) is enabled, the match is performed | |
2149 | without regard to the case of alphabetic characters. If PARAMETER | |
2150 | is '@' or '*', the substitution operation is applied to each | |
2151 | positional parameter in turn, and the expansion is the resultant | |
2152 | list. If PARAMETER is an array variable subscripted with '@' or | |
2153 | '*', the substitution operation is applied to each member of the | |
2154 | array in turn, and the expansion is the resultant list. | |
a0c0a00f CR |
2155 | |
2156 | '${PARAMETER^PATTERN}' | |
2157 | '${PARAMETER^^PATTERN}' | |
2158 | '${PARAMETER,PATTERN}' | |
2159 | '${PARAMETER,,PATTERN}' | |
2160 | This expansion modifies the case of alphabetic characters in | |
2161 | PARAMETER. The PATTERN is expanded to produce a pattern just as in | |
2162 | filename expansion. Each character in the expanded value of | |
2163 | PARAMETER is tested against PATTERN, and, if it matches the | |
2164 | pattern, its case is converted. The pattern should not attempt to | |
74091dd4 CR |
2165 | match more than one character. |
2166 | ||
2167 | The '^' operator converts lowercase letters matching PATTERN to | |
2168 | uppercase; the ',' operator converts matching uppercase letters to | |
2169 | lowercase. The '^^' and ',,' expansions convert each matched | |
2170 | character in the expanded value; the '^' and ',' expansions match | |
2171 | and convert only the first character in the expanded value. If | |
2172 | PATTERN is omitted, it is treated like a '?', which matches every | |
2173 | character. | |
2174 | ||
2175 | If PARAMETER is '@' or '*', the case modification operation is | |
2176 | applied to each positional parameter in turn, and the expansion is | |
2177 | the resultant list. If PARAMETER is an array variable subscripted | |
2178 | with '@' or '*', the case modification operation is applied to each | |
2179 | member of the array in turn, and the expansion is the resultant | |
2180 | list. | |
a0c0a00f CR |
2181 | |
2182 | '${PARAMETER@OPERATOR}' | |
2183 | The expansion is either a transformation of the value of PARAMETER | |
2184 | or information about PARAMETER itself, depending on the value of | |
2185 | OPERATOR. Each OPERATOR is a single letter: | |
2186 | ||
8868edaf CR |
2187 | 'U' |
2188 | The expansion is a string that is the value of PARAMETER with | |
2189 | lowercase alphabetic characters converted to uppercase. | |
2190 | 'u' | |
2191 | The expansion is a string that is the value of PARAMETER with | |
2192 | the first character converted to uppercase, if it is | |
2193 | alphabetic. | |
2194 | 'L' | |
2195 | The expansion is a string that is the value of PARAMETER with | |
2196 | uppercase alphabetic characters converted to lowercase. | |
a0c0a00f CR |
2197 | 'Q' |
2198 | The expansion is a string that is the value of PARAMETER | |
2199 | quoted in a format that can be reused as input. | |
2200 | 'E' | |
2201 | The expansion is a string that is the value of PARAMETER with | |
2202 | backslash escape sequences expanded as with the '$'...'' | |
d233b485 | 2203 | quoting mechanism. |
a0c0a00f CR |
2204 | 'P' |
2205 | The expansion is a string that is the result of expanding the | |
2206 | value of PARAMETER as if it were a prompt string (*note | |
2207 | Controlling the Prompt::). | |
2208 | 'A' | |
2209 | The expansion is a string in the form of an assignment | |
2210 | statement or 'declare' command that, if evaluated, will | |
2211 | recreate PARAMETER with its attributes and value. | |
8868edaf CR |
2212 | 'K' |
2213 | Produces a possibly-quoted version of the value of PARAMETER, | |
2214 | except that it prints the values of indexed and associative | |
2215 | arrays as a sequence of quoted key-value pairs (*note | |
2216 | Arrays::). | |
a0c0a00f CR |
2217 | 'a' |
2218 | The expansion is a string consisting of flag values | |
2219 | representing PARAMETER's attributes. | |
74091dd4 CR |
2220 | 'k' |
2221 | Like the 'K' transformation, but expands the keys and values | |
2222 | of indexed and associative arrays to separate words after word | |
2223 | splitting. | |
a0c0a00f CR |
2224 | |
2225 | If PARAMETER is '@' or '*', the operation is applied to each | |
2226 | positional parameter in turn, and the expansion is the resultant | |
2227 | list. If PARAMETER is an array variable subscripted with '@' or | |
2228 | '*', the operation is applied to each member of the array in turn, | |
2229 | and the expansion is the resultant list. | |
2230 | ||
2231 | The result of the expansion is subject to word splitting and | |
8868edaf | 2232 | filename expansion as described below. |
a0c0a00f CR |
2233 | |
2234 | \1f | |
2235 | File: bash.info, Node: Command Substitution, Next: Arithmetic Expansion, Prev: Shell Parameter Expansion, Up: Shell Expansions | |
2236 | ||
2237 | 3.5.4 Command Substitution | |
2238 | -------------------------- | |
2239 | ||
2240 | Command substitution allows the output of a command to replace the | |
2241 | command itself. Command substitution occurs when a command is enclosed | |
2242 | as follows: | |
2243 | $(COMMAND) | |
2244 | or | |
2245 | `COMMAND` | |
2246 | ||
2247 | Bash performs the expansion by executing COMMAND in a subshell | |
2248 | environment and replacing the command substitution with the standard | |
2249 | output of the command, with any trailing newlines deleted. Embedded | |
2250 | newlines are not deleted, but they may be removed during word splitting. | |
2251 | The command substitution '$(cat FILE)' can be replaced by the equivalent | |
2252 | but faster '$(< FILE)'. | |
2253 | ||
2254 | When the old-style backquote form of substitution is used, backslash | |
2255 | retains its literal meaning except when followed by '$', '`', or '\'. | |
2256 | The first backquote not preceded by a backslash terminates the command | |
2257 | substitution. When using the '$(COMMAND)' form, all characters between | |
2258 | the parentheses make up the command; none are treated specially. | |
2259 | ||
2260 | Command substitutions may be nested. To nest when using the | |
2261 | backquoted form, escape the inner backquotes with backslashes. | |
2262 | ||
2263 | If the substitution appears within double quotes, word splitting and | |
2264 | filename expansion are not performed on the results. | |
2265 | ||
2266 | \1f | |
2267 | File: bash.info, Node: Arithmetic Expansion, Next: Process Substitution, Prev: Command Substitution, Up: Shell Expansions | |
2268 | ||
2269 | 3.5.5 Arithmetic Expansion | |
2270 | -------------------------- | |
2271 | ||
2272 | Arithmetic expansion allows the evaluation of an arithmetic expression | |
2273 | and the substitution of the result. The format for arithmetic expansion | |
2274 | is: | |
2275 | ||
2276 | $(( EXPRESSION )) | |
2277 | ||
74091dd4 CR |
2278 | The EXPRESSION undergoes the same expansions as if it were within |
2279 | double quotes, but double quote characters in EXPRESSION are not treated | |
2280 | specially and are removed. All tokens in the expression undergo | |
2281 | parameter and variable expansion, command substitution, and quote | |
2282 | removal. The result is treated as the arithmetic expression to be | |
2283 | evaluated. Arithmetic expansions may be nested. | |
a0c0a00f CR |
2284 | |
2285 | The evaluation is performed according to the rules listed below | |
2286 | (*note Shell Arithmetic::). If the expression is invalid, Bash prints a | |
2287 | message indicating failure to the standard error and no substitution | |
2288 | occurs. | |
2289 | ||
2290 | \1f | |
2291 | File: bash.info, Node: Process Substitution, Next: Word Splitting, Prev: Arithmetic Expansion, Up: Shell Expansions | |
2292 | ||
2293 | 3.5.6 Process Substitution | |
2294 | -------------------------- | |
2295 | ||
2296 | Process substitution allows a process's input or output to be referred | |
2297 | to using a filename. It takes the form of | |
2298 | <(LIST) | |
2299 | or | |
2300 | >(LIST) | |
2301 | The process LIST is run asynchronously, and its input or output appears | |
2302 | as a filename. This filename is passed as an argument to the current | |
2303 | command as the result of the expansion. If the '>(LIST)' form is used, | |
2304 | writing to the file will provide input for LIST. If the '<(LIST)' form | |
2305 | is used, the file passed as an argument should be read to obtain the | |
2306 | output of LIST. Note that no space may appear between the '<' or '>' | |
2307 | and the left parenthesis, otherwise the construct would be interpreted | |
2308 | as a redirection. Process substitution is supported on systems that | |
2309 | support named pipes (FIFOs) or the '/dev/fd' method of naming open | |
2310 | files. | |
2311 | ||
2312 | When available, process substitution is performed simultaneously with | |
2313 | parameter and variable expansion, command substitution, and arithmetic | |
2314 | expansion. | |
2315 | ||
2316 | \1f | |
2317 | File: bash.info, Node: Word Splitting, Next: Filename Expansion, Prev: Process Substitution, Up: Shell Expansions | |
2318 | ||
2319 | 3.5.7 Word Splitting | |
2320 | -------------------- | |
2321 | ||
2322 | The shell scans the results of parameter expansion, command | |
2323 | substitution, and arithmetic expansion that did not occur within double | |
2324 | quotes for word splitting. | |
2325 | ||
2326 | The shell treats each character of '$IFS' as a delimiter, and splits | |
2327 | the results of the other expansions into words using these characters as | |
2328 | field terminators. If 'IFS' is unset, or its value is exactly | |
2329 | '<space><tab><newline>', the default, then sequences of ' <space>', | |
2330 | '<tab>', and '<newline>' at the beginning and end of the results of the | |
2331 | previous expansions are ignored, and any sequence of 'IFS' characters | |
2332 | not at the beginning or end serves to delimit words. If 'IFS' has a | |
2333 | value other than the default, then sequences of the whitespace | |
2334 | characters 'space', 'tab', and 'newline' are ignored at the beginning | |
2335 | and end of the word, as long as the whitespace character is in the value | |
2336 | of 'IFS' (an 'IFS' whitespace character). Any character in 'IFS' that | |
2337 | is not 'IFS' whitespace, along with any adjacent 'IFS' whitespace | |
2338 | characters, delimits a field. A sequence of 'IFS' whitespace characters | |
2339 | is also treated as a delimiter. If the value of 'IFS' is null, no word | |
2340 | splitting occurs. | |
2341 | ||
2342 | Explicit null arguments ('""' or '''') are retained and passed to | |
2343 | commands as empty strings. Unquoted implicit null arguments, resulting | |
2344 | from the expansion of parameters that have no values, are removed. If a | |
2345 | parameter with no value is expanded within double quotes, a null | |
2346 | argument results and is retained and passed to a command as an empty | |
2347 | string. When a quoted null argument appears as part of a word whose | |
2348 | expansion is non-null, the null argument is removed. That is, the word | |
2349 | '-d''' becomes '-d' after word splitting and null argument removal. | |
2350 | ||
2351 | Note that if no expansion occurs, no splitting is performed. | |
2352 | ||
2353 | \1f | |
2354 | File: bash.info, Node: Filename Expansion, Next: Quote Removal, Prev: Word Splitting, Up: Shell Expansions | |
2355 | ||
2356 | 3.5.8 Filename Expansion | |
2357 | ------------------------ | |
2358 | ||
2359 | * Menu: | |
2360 | ||
2361 | * Pattern Matching:: How the shell matches patterns. | |
2362 | ||
2363 | After word splitting, unless the '-f' option has been set (*note The Set | |
2364 | Builtin::), Bash scans each word for the characters '*', '?', and '['. | |
8868edaf CR |
2365 | If one of these characters appears, and is not quoted, then the word is |
2366 | regarded as a PATTERN, and replaced with an alphabetically sorted list | |
2367 | of filenames matching the pattern (*note Pattern Matching::). If no | |
2368 | matching filenames are found, and the shell option 'nullglob' is | |
2369 | disabled, the word is left unchanged. If the 'nullglob' option is set, | |
2370 | and no matches are found, the word is removed. If the 'failglob' shell | |
2371 | option is set, and no matches are found, an error message is printed and | |
2372 | the command is not executed. If the shell option 'nocaseglob' is | |
2373 | enabled, the match is performed without regard to the case of alphabetic | |
2374 | characters. | |
a0c0a00f CR |
2375 | |
2376 | When a pattern is used for filename expansion, the character '.' at | |
2377 | the start of a filename or immediately following a slash must be matched | |
74091dd4 CR |
2378 | explicitly, unless the shell option 'dotglob' is set. In order to match |
2379 | the filenames '.' and '..', the pattern must begin with '.' (for | |
2380 | example, '.?'), even if 'dotglob' is set. If the 'globskipdots' shell | |
2381 | option is enabled, the filenames '.' and '..' are never matched, even if | |
2382 | the pattern begins with a '.'. When not matching filenames, the '.' | |
2383 | character is not treated specially. | |
d233b485 CR |
2384 | |
2385 | When matching a filename, the slash character must always be matched | |
2386 | explicitly by a slash in the pattern, but in other matching contexts it | |
2387 | can be matched by a special pattern character as described below (*note | |
2388 | Pattern Matching::). | |
a0c0a00f CR |
2389 | |
2390 | See the description of 'shopt' in *note The Shopt Builtin::, for a | |
74091dd4 CR |
2391 | description of the 'nocaseglob', 'nullglob', 'globskipdots', 'failglob', |
2392 | and 'dotglob' options. | |
a0c0a00f CR |
2393 | |
2394 | The 'GLOBIGNORE' shell variable may be used to restrict the set of | |
d233b485 CR |
2395 | file names matching a pattern. If 'GLOBIGNORE' is set, each matching |
2396 | file name that also matches one of the patterns in 'GLOBIGNORE' is | |
a0c0a00f CR |
2397 | removed from the list of matches. If the 'nocaseglob' option is set, |
2398 | the matching against the patterns in 'GLOBIGNORE' is performed without | |
2399 | regard to case. The filenames '.' and '..' are always ignored when | |
2400 | 'GLOBIGNORE' is set and not null. However, setting 'GLOBIGNORE' to a | |
2401 | non-null value has the effect of enabling the 'dotglob' shell option, so | |
2402 | all other filenames beginning with a '.' will match. To get the old | |
2403 | behavior of ignoring filenames beginning with a '.', make '.*' one of | |
2404 | the patterns in 'GLOBIGNORE'. The 'dotglob' option is disabled when | |
2405 | 'GLOBIGNORE' is unset. | |
2406 | ||
2407 | \1f | |
2408 | File: bash.info, Node: Pattern Matching, Up: Filename Expansion | |
2409 | ||
2410 | 3.5.8.1 Pattern Matching | |
2411 | ........................ | |
2412 | ||
2413 | Any character that appears in a pattern, other than the special pattern | |
2414 | characters described below, matches itself. The NUL character may not | |
2415 | occur in a pattern. A backslash escapes the following character; the | |
2416 | escaping backslash is discarded when matching. The special pattern | |
2417 | characters must be quoted if they are to be matched literally. | |
2418 | ||
2419 | The special pattern characters have the following meanings: | |
2420 | '*' | |
2421 | Matches any string, including the null string. When the 'globstar' | |
2422 | shell option is enabled, and '*' is used in a filename expansion | |
2423 | context, two adjacent '*'s used as a single pattern will match all | |
2424 | files and zero or more directories and subdirectories. If followed | |
2425 | by a '/', two adjacent '*'s will match only directories and | |
2426 | subdirectories. | |
2427 | '?' | |
2428 | Matches any single character. | |
2429 | '[...]' | |
2430 | Matches any one of the enclosed characters. A pair of characters | |
2431 | separated by a hyphen denotes a RANGE EXPRESSION; any character | |
2432 | that falls between those two characters, inclusive, using the | |
2433 | current locale's collating sequence and character set, is matched. | |
2434 | If the first character following the '[' is a '!' or a '^' then any | |
2435 | character not enclosed is matched. A '-' may be matched by | |
2436 | including it as the first or last character in the set. A ']' may | |
2437 | be matched by including it as the first character in the set. The | |
74091dd4 CR |
2438 | sorting order of characters in range expressions, and the |
2439 | characters included in the range, are determined by the current | |
2440 | locale and the values of the 'LC_COLLATE' and 'LC_ALL' shell | |
2441 | variables, if set. | |
a0c0a00f CR |
2442 | |
2443 | For example, in the default C locale, '[a-dx-z]' is equivalent to | |
2444 | '[abcdxyz]'. Many locales sort characters in dictionary order, and | |
2445 | in these locales '[a-dx-z]' is typically not equivalent to | |
74091dd4 | 2446 | '[abcdxyz]'; it might be equivalent to '[aBbCcDdxYyZz]', for |
a0c0a00f CR |
2447 | example. To obtain the traditional interpretation of ranges in |
2448 | bracket expressions, you can force the use of the C locale by | |
2449 | setting the 'LC_COLLATE' or 'LC_ALL' environment variable to the | |
2450 | value 'C', or enable the 'globasciiranges' shell option. | |
2451 | ||
74091dd4 | 2452 | Within '[' and ']', "character classes" can be specified using the |
a0c0a00f CR |
2453 | syntax '[:'CLASS':]', where CLASS is one of the following classes |
2454 | defined in the POSIX standard: | |
2455 | alnum alpha ascii blank cntrl digit graph lower | |
2456 | print punct space upper word xdigit | |
2457 | A character class matches any character belonging to that class. | |
2458 | The 'word' character class matches letters, digits, and the | |
2459 | character '_'. | |
2460 | ||
74091dd4 CR |
2461 | Within '[' and ']', an "equivalence class" can be specified using |
2462 | the syntax '[='C'=]', which matches all characters with the same | |
a0c0a00f CR |
2463 | collation weight (as defined by the current locale) as the |
2464 | character C. | |
2465 | ||
2466 | Within '[' and ']', the syntax '[.'SYMBOL'.]' matches the collating | |
2467 | symbol SYMBOL. | |
2468 | ||
2469 | If the 'extglob' shell option is enabled using the 'shopt' builtin, | |
74091dd4 CR |
2470 | the shell recognizes several extended pattern matching operators. In |
2471 | the following description, a PATTERN-LIST is a list of one or more | |
2472 | patterns separated by a '|'. When matching filenames, the 'dotglob' | |
2473 | shell option determines the set of filenames that are tested, as | |
2474 | described above. Composite patterns may be formed using one or more of | |
2475 | the following sub-patterns: | |
a0c0a00f CR |
2476 | |
2477 | '?(PATTERN-LIST)' | |
2478 | Matches zero or one occurrence of the given patterns. | |
2479 | ||
2480 | '*(PATTERN-LIST)' | |
2481 | Matches zero or more occurrences of the given patterns. | |
2482 | ||
2483 | '+(PATTERN-LIST)' | |
2484 | Matches one or more occurrences of the given patterns. | |
2485 | ||
2486 | '@(PATTERN-LIST)' | |
2487 | Matches one of the given patterns. | |
2488 | ||
2489 | '!(PATTERN-LIST)' | |
2490 | Matches anything except one of the given patterns. | |
2491 | ||
74091dd4 CR |
2492 | The 'extglob' option changes the behavior of the parser, since the |
2493 | parentheses are normally treated as operators with syntactic meaning. | |
2494 | To ensure that extended matching patterns are parsed correctly, make | |
2495 | sure that 'extglob' is enabled before parsing constructs containing the | |
2496 | patterns, including shell functions and command substitutions. | |
2497 | ||
2498 | When matching filenames, the 'dotglob' shell option determines the | |
2499 | set of filenames that are tested: when 'dotglob' is enabled, the set of | |
2500 | filenames includes all files beginning with '.', but the filenames '.' | |
2501 | and '..' must be matched by a pattern or sub-pattern that begins with a | |
2502 | dot; when it is disabled, the set does not include any filenames | |
2503 | beginning with "." unless the pattern or sub-pattern begins with a '.'. | |
2504 | As above, '.' only has a special meaning when matching filenames. | |
2505 | ||
d233b485 CR |
2506 | Complicated extended pattern matching against long strings is slow, |
2507 | especially when the patterns contain alternations and the strings | |
2508 | contain multiple matches. Using separate matches against shorter | |
2509 | strings, or using arrays of strings instead of a single long string, may | |
2510 | be faster. | |
2511 | ||
a0c0a00f CR |
2512 | \1f |
2513 | File: bash.info, Node: Quote Removal, Prev: Filename Expansion, Up: Shell Expansions | |
2514 | ||
2515 | 3.5.9 Quote Removal | |
2516 | ------------------- | |
2517 | ||
2518 | After the preceding expansions, all unquoted occurrences of the | |
2519 | characters '\', ''', and '"' that did not result from one of the above | |
2520 | expansions are removed. | |
2521 | ||
2522 | \1f | |
2523 | File: bash.info, Node: Redirections, Next: Executing Commands, Prev: Shell Expansions, Up: Basic Shell Features | |
2524 | ||
2525 | 3.6 Redirections | |
2526 | ================ | |
2527 | ||
74091dd4 CR |
2528 | Before a command is executed, its input and output may be "redirected" |
2529 | using a special notation interpreted by the shell. "Redirection" allows | |
a0c0a00f CR |
2530 | commands' file handles to be duplicated, opened, closed, made to refer |
2531 | to different files, and can change the files the command reads from and | |
2532 | writes to. Redirection may also be used to modify file handles in the | |
2533 | current shell execution environment. The following redirection | |
2534 | operators may precede or appear anywhere within a simple command or may | |
2535 | follow a command. Redirections are processed in the order they appear, | |
2536 | from left to right. | |
2537 | ||
2538 | Each redirection that may be preceded by a file descriptor number may | |
2539 | instead be preceded by a word of the form {VARNAME}. In this case, for | |
2540 | each redirection operator except >&- and <&-, the shell will allocate a | |
2541 | file descriptor greater than 10 and assign it to {VARNAME}. If >&- or | |
2542 | <&- is preceded by {VARNAME}, the value of VARNAME defines the file | |
d233b485 CR |
2543 | descriptor to close. If {VARNAME} is supplied, the redirection persists |
2544 | beyond the scope of the command, allowing the shell programmer to manage | |
74091dd4 CR |
2545 | the file descriptor's lifetime manually. The 'varredir_close' shell |
2546 | option manages this behavior (*note The Shopt Builtin::). | |
a0c0a00f CR |
2547 | |
2548 | In the following descriptions, if the file descriptor number is | |
2549 | omitted, and the first character of the redirection operator is '<', the | |
2550 | redirection refers to the standard input (file descriptor 0). If the | |
2551 | first character of the redirection operator is '>', the redirection | |
2552 | refers to the standard output (file descriptor 1). | |
2553 | ||
2554 | The word following the redirection operator in the following | |
2555 | descriptions, unless otherwise noted, is subjected to brace expansion, | |
2556 | tilde expansion, parameter expansion, command substitution, arithmetic | |
2557 | expansion, quote removal, filename expansion, and word splitting. If it | |
2558 | expands to more than one word, Bash reports an error. | |
2559 | ||
2560 | Note that the order of redirections is significant. For example, the | |
2561 | command | |
2562 | ls > DIRLIST 2>&1 | |
2563 | directs both standard output (file descriptor 1) and standard error | |
2564 | (file descriptor 2) to the file DIRLIST, while the command | |
2565 | ls 2>&1 > DIRLIST | |
2566 | directs only the standard output to file DIRLIST, because the standard | |
2567 | error was made a copy of the standard output before the standard output | |
2568 | was redirected to DIRLIST. | |
2569 | ||
2570 | Bash handles several filenames specially when they are used in | |
2571 | redirections, as described in the following table. If the operating | |
2572 | system on which Bash is running provides these special files, bash will | |
2573 | use them; otherwise it will emulate them internally with the behavior | |
2574 | described below. | |
2575 | ||
2576 | '/dev/fd/FD' | |
2577 | If FD is a valid integer, file descriptor FD is duplicated. | |
2578 | ||
2579 | '/dev/stdin' | |
2580 | File descriptor 0 is duplicated. | |
2581 | ||
2582 | '/dev/stdout' | |
2583 | File descriptor 1 is duplicated. | |
2584 | ||
2585 | '/dev/stderr' | |
2586 | File descriptor 2 is duplicated. | |
2587 | ||
2588 | '/dev/tcp/HOST/PORT' | |
2589 | If HOST is a valid hostname or Internet address, and PORT is an | |
2590 | integer port number or service name, Bash attempts to open the | |
2591 | corresponding TCP socket. | |
2592 | ||
2593 | '/dev/udp/HOST/PORT' | |
2594 | If HOST is a valid hostname or Internet address, and PORT is an | |
2595 | integer port number or service name, Bash attempts to open the | |
2596 | corresponding UDP socket. | |
2597 | ||
2598 | A failure to open or create a file causes the redirection to fail. | |
2599 | ||
2600 | Redirections using file descriptors greater than 9 should be used | |
2601 | with care, as they may conflict with file descriptors the shell uses | |
2602 | internally. | |
2603 | ||
2604 | 3.6.1 Redirecting Input | |
2605 | ----------------------- | |
2606 | ||
2607 | Redirection of input causes the file whose name results from the | |
2608 | expansion of WORD to be opened for reading on file descriptor 'n', or | |
2609 | the standard input (file descriptor 0) if 'n' is not specified. | |
2610 | ||
2611 | The general format for redirecting input is: | |
2612 | [N]<WORD | |
2613 | ||
2614 | 3.6.2 Redirecting Output | |
2615 | ------------------------ | |
2616 | ||
2617 | Redirection of output causes the file whose name results from the | |
2618 | expansion of WORD to be opened for writing on file descriptor N, or the | |
2619 | standard output (file descriptor 1) if N is not specified. If the file | |
2620 | does not exist it is created; if it does exist it is truncated to zero | |
2621 | size. | |
2622 | ||
2623 | The general format for redirecting output is: | |
2624 | [N]>[|]WORD | |
2625 | ||
2626 | If the redirection operator is '>', and the 'noclobber' option to the | |
2627 | 'set' builtin has been enabled, the redirection will fail if the file | |
2628 | whose name results from the expansion of WORD exists and is a regular | |
2629 | file. If the redirection operator is '>|', or the redirection operator | |
2630 | is '>' and the 'noclobber' option is not enabled, the redirection is | |
2631 | attempted even if the file named by WORD exists. | |
2632 | ||
2633 | 3.6.3 Appending Redirected Output | |
2634 | --------------------------------- | |
2635 | ||
2636 | Redirection of output in this fashion causes the file whose name results | |
2637 | from the expansion of WORD to be opened for appending on file descriptor | |
2638 | N, or the standard output (file descriptor 1) if N is not specified. If | |
2639 | the file does not exist it is created. | |
2640 | ||
2641 | The general format for appending output is: | |
2642 | [N]>>WORD | |
2643 | ||
2644 | 3.6.4 Redirecting Standard Output and Standard Error | |
2645 | ---------------------------------------------------- | |
2646 | ||
2647 | This construct allows both the standard output (file descriptor 1) and | |
2648 | the standard error output (file descriptor 2) to be redirected to the | |
2649 | file whose name is the expansion of WORD. | |
2650 | ||
2651 | There are two formats for redirecting standard output and standard | |
2652 | error: | |
2653 | &>WORD | |
2654 | and | |
2655 | >&WORD | |
2656 | Of the two forms, the first is preferred. This is semantically | |
2657 | equivalent to | |
2658 | >WORD 2>&1 | |
2659 | When using the second form, WORD may not expand to a number or '-'. | |
2660 | If it does, other redirection operators apply (see Duplicating File | |
2661 | Descriptors below) for compatibility reasons. | |
2662 | ||
2663 | 3.6.5 Appending Standard Output and Standard Error | |
2664 | -------------------------------------------------- | |
2665 | ||
2666 | This construct allows both the standard output (file descriptor 1) and | |
2667 | the standard error output (file descriptor 2) to be appended to the file | |
2668 | whose name is the expansion of WORD. | |
2669 | ||
2670 | The format for appending standard output and standard error is: | |
2671 | &>>WORD | |
2672 | This is semantically equivalent to | |
2673 | >>WORD 2>&1 | |
2674 | (see Duplicating File Descriptors below). | |
2675 | ||
2676 | 3.6.6 Here Documents | |
2677 | -------------------- | |
2678 | ||
2679 | This type of redirection instructs the shell to read input from the | |
2680 | current source until a line containing only WORD (with no trailing | |
2681 | blanks) is seen. All of the lines read up to that point are then used | |
2682 | as the standard input (or file descriptor N if N is specified) for a | |
2683 | command. | |
2684 | ||
2685 | The format of here-documents is: | |
2686 | [N]<<[-]WORD | |
2687 | HERE-DOCUMENT | |
2688 | DELIMITER | |
2689 | ||
2690 | No parameter and variable expansion, command substitution, arithmetic | |
2691 | expansion, or filename expansion is performed on WORD. If any part of | |
2692 | WORD is quoted, the DELIMITER is the result of quote removal on WORD, | |
2693 | and the lines in the here-document are not expanded. If WORD is | |
2694 | unquoted, all lines of the here-document are subjected to parameter | |
2695 | expansion, command substitution, and arithmetic expansion, the character | |
2696 | sequence '\newline' is ignored, and '\' must be used to quote the | |
2697 | characters '\', '$', and '`'. | |
2698 | ||
2699 | If the redirection operator is '<<-', then all leading tab characters | |
2700 | are stripped from input lines and the line containing DELIMITER. This | |
2701 | allows here-documents within shell scripts to be indented in a natural | |
2702 | fashion. | |
2703 | ||
2704 | 3.6.7 Here Strings | |
2705 | ------------------ | |
2706 | ||
2707 | A variant of here documents, the format is: | |
2708 | [N]<<< WORD | |
2709 | ||
d233b485 | 2710 | The WORD undergoes tilde expansion, parameter and variable expansion, |
8868edaf | 2711 | command substitution, arithmetic expansion, and quote removal. Filename |
d233b485 CR |
2712 | expansion and word splitting are not performed. The result is supplied |
2713 | as a single string, with a newline appended, to the command on its | |
2714 | standard input (or file descriptor N if N is specified). | |
a0c0a00f CR |
2715 | |
2716 | 3.6.8 Duplicating File Descriptors | |
2717 | ---------------------------------- | |
2718 | ||
2719 | The redirection operator | |
2720 | [N]<&WORD | |
2721 | is used to duplicate input file descriptors. If WORD expands to one or | |
2722 | more digits, the file descriptor denoted by N is made to be a copy of | |
2723 | that file descriptor. If the digits in WORD do not specify a file | |
2724 | descriptor open for input, a redirection error occurs. If WORD | |
2725 | evaluates to '-', file descriptor N is closed. If N is not specified, | |
2726 | the standard input (file descriptor 0) is used. | |
2727 | ||
2728 | The operator | |
2729 | [N]>&WORD | |
2730 | is used similarly to duplicate output file descriptors. If N is not | |
2731 | specified, the standard output (file descriptor 1) is used. If the | |
2732 | digits in WORD do not specify a file descriptor open for output, a | |
2733 | redirection error occurs. If WORD evaluates to '-', file descriptor N | |
2734 | is closed. As a special case, if N is omitted, and WORD does not expand | |
2735 | to one or more digits or '-', the standard output and standard error are | |
2736 | redirected as described previously. | |
2737 | ||
2738 | 3.6.9 Moving File Descriptors | |
2739 | ----------------------------- | |
2740 | ||
2741 | The redirection operator | |
2742 | [N]<&DIGIT- | |
2743 | moves the file descriptor DIGIT to file descriptor N, or the standard | |
2744 | input (file descriptor 0) if N is not specified. DIGIT is closed after | |
2745 | being duplicated to N. | |
2746 | ||
2747 | Similarly, the redirection operator | |
2748 | [N]>&DIGIT- | |
2749 | moves the file descriptor DIGIT to file descriptor N, or the standard | |
2750 | output (file descriptor 1) if N is not specified. | |
2751 | ||
2752 | 3.6.10 Opening File Descriptors for Reading and Writing | |
2753 | ------------------------------------------------------- | |
2754 | ||
2755 | The redirection operator | |
2756 | [N]<>WORD | |
2757 | causes the file whose name is the expansion of WORD to be opened for | |
2758 | both reading and writing on file descriptor N, or on file descriptor 0 | |
2759 | if N is not specified. If the file does not exist, it is created. | |
2760 | ||
2761 | \1f | |
2762 | File: bash.info, Node: Executing Commands, Next: Shell Scripts, Prev: Redirections, Up: Basic Shell Features | |
2763 | ||
2764 | 3.7 Executing Commands | |
2765 | ====================== | |
2766 | ||
2767 | * Menu: | |
2768 | ||
2769 | * Simple Command Expansion:: How Bash expands simple commands before | |
2770 | executing them. | |
2771 | * Command Search and Execution:: How Bash finds commands and runs them. | |
2772 | * Command Execution Environment:: The environment in which Bash | |
2773 | executes commands that are not | |
2774 | shell builtins. | |
2775 | * Environment:: The environment given to a command. | |
2776 | * Exit Status:: The status returned by commands and how Bash | |
2777 | interprets it. | |
2778 | * Signals:: What happens when Bash or a command it runs | |
2779 | receives a signal. | |
2780 | ||
2781 | \1f | |
2782 | File: bash.info, Node: Simple Command Expansion, Next: Command Search and Execution, Up: Executing Commands | |
2783 | ||
2784 | 3.7.1 Simple Command Expansion | |
2785 | ------------------------------ | |
2786 | ||
2787 | When a simple command is executed, the shell performs the following | |
8868edaf CR |
2788 | expansions, assignments, and redirections, from left to right, in the |
2789 | following order. | |
a0c0a00f CR |
2790 | |
2791 | 1. The words that the parser has marked as variable assignments (those | |
2792 | preceding the command name) and redirections are saved for later | |
2793 | processing. | |
2794 | ||
2795 | 2. The words that are not variable assignments or redirections are | |
2796 | expanded (*note Shell Expansions::). If any words remain after | |
2797 | expansion, the first word is taken to be the name of the command | |
2798 | and the remaining words are the arguments. | |
2799 | ||
2800 | 3. Redirections are performed as described above (*note | |
2801 | Redirections::). | |
2802 | ||
2803 | 4. The text after the '=' in each variable assignment undergoes tilde | |
2804 | expansion, parameter expansion, command substitution, arithmetic | |
2805 | expansion, and quote removal before being assigned to the variable. | |
2806 | ||
2807 | If no command name results, the variable assignments affect the | |
74091dd4 CR |
2808 | current shell environment. In the case of such a command (one that |
2809 | consists only of assignment statements and redirections), assignment | |
2810 | statements are performed before redirections. Otherwise, the variables | |
2811 | are added to the environment of the executed command and do not affect | |
2812 | the current shell environment. If any of the assignments attempts to | |
2813 | assign a value to a readonly variable, an error occurs, and the command | |
2814 | exits with a non-zero status. | |
a0c0a00f CR |
2815 | |
2816 | If no command name results, redirections are performed, but do not | |
2817 | affect the current shell environment. A redirection error causes the | |
2818 | command to exit with a non-zero status. | |
2819 | ||
2820 | If there is a command name left after expansion, execution proceeds | |
2821 | as described below. Otherwise, the command exits. If one of the | |
2822 | expansions contained a command substitution, the exit status of the | |
2823 | command is the exit status of the last command substitution performed. | |
2824 | If there were no command substitutions, the command exits with a status | |
2825 | of zero. | |
2826 | ||
2827 | \1f | |
2828 | File: bash.info, Node: Command Search and Execution, Next: Command Execution Environment, Prev: Simple Command Expansion, Up: Executing Commands | |
2829 | ||
2830 | 3.7.2 Command Search and Execution | |
2831 | ---------------------------------- | |
2832 | ||
2833 | After a command has been split into words, if it results in a simple | |
2834 | command and an optional list of arguments, the following actions are | |
2835 | taken. | |
2836 | ||
2837 | 1. If the command name contains no slashes, the shell attempts to | |
2838 | locate it. If there exists a shell function by that name, that | |
2839 | function is invoked as described in *note Shell Functions::. | |
2840 | ||
2841 | 2. If the name does not match a function, the shell searches for it in | |
2842 | the list of shell builtins. If a match is found, that builtin is | |
2843 | invoked. | |
2844 | ||
2845 | 3. If the name is neither a shell function nor a builtin, and contains | |
2846 | no slashes, Bash searches each element of '$PATH' for a directory | |
2847 | containing an executable file by that name. Bash uses a hash table | |
2848 | to remember the full pathnames of executable files to avoid | |
2849 | multiple 'PATH' searches (see the description of 'hash' in *note | |
2850 | Bourne Shell Builtins::). A full search of the directories in | |
2851 | '$PATH' is performed only if the command is not found in the hash | |
2852 | table. If the search is unsuccessful, the shell searches for a | |
2853 | defined shell function named 'command_not_found_handle'. If that | |
d233b485 CR |
2854 | function exists, it is invoked in a separate execution environment |
2855 | with the original command and the original command's arguments as | |
2856 | its arguments, and the function's exit status becomes the exit | |
2857 | status of that subshell. If that function is not defined, the | |
2858 | shell prints an error message and returns an exit status of 127. | |
a0c0a00f CR |
2859 | |
2860 | 4. If the search is successful, or if the command name contains one or | |
2861 | more slashes, the shell executes the named program in a separate | |
2862 | execution environment. Argument 0 is set to the name given, and | |
2863 | the remaining arguments to the command are set to the arguments | |
2864 | supplied, if any. | |
2865 | ||
2866 | 5. If this execution fails because the file is not in executable | |
2867 | format, and the file is not a directory, it is assumed to be a | |
74091dd4 CR |
2868 | "shell script" and the shell executes it as described in *note |
2869 | Shell Scripts::. | |
a0c0a00f CR |
2870 | |
2871 | 6. If the command was not begun asynchronously, the shell waits for | |
2872 | the command to complete and collects its exit status. | |
2873 | ||
2874 | \1f | |
2875 | File: bash.info, Node: Command Execution Environment, Next: Environment, Prev: Command Search and Execution, Up: Executing Commands | |
2876 | ||
2877 | 3.7.3 Command Execution Environment | |
2878 | ----------------------------------- | |
2879 | ||
74091dd4 CR |
2880 | The shell has an "execution environment", which consists of the |
2881 | following: | |
a0c0a00f CR |
2882 | |
2883 | * open files inherited by the shell at invocation, as modified by | |
2884 | redirections supplied to the 'exec' builtin | |
2885 | ||
2886 | * the current working directory as set by 'cd', 'pushd', or 'popd', | |
2887 | or inherited by the shell at invocation | |
2888 | ||
2889 | * the file creation mode mask as set by 'umask' or inherited from the | |
2890 | shell's parent | |
2891 | ||
2892 | * current traps set by 'trap' | |
2893 | ||
2894 | * shell parameters that are set by variable assignment or with 'set' | |
2895 | or inherited from the shell's parent in the environment | |
2896 | ||
2897 | * shell functions defined during execution or inherited from the | |
2898 | shell's parent in the environment | |
2899 | ||
2900 | * options enabled at invocation (either by default or with | |
2901 | command-line arguments) or by 'set' | |
2902 | ||
2903 | * options enabled by 'shopt' (*note The Shopt Builtin::) | |
2904 | ||
2905 | * shell aliases defined with 'alias' (*note Aliases::) | |
2906 | ||
2907 | * various process IDs, including those of background jobs (*note | |
2908 | Lists::), the value of '$$', and the value of '$PPID' | |
2909 | ||
2910 | When a simple command other than a builtin or shell function is to be | |
2911 | executed, it is invoked in a separate execution environment that | |
2912 | consists of the following. Unless otherwise noted, the values are | |
2913 | inherited from the shell. | |
2914 | ||
2915 | * the shell's open files, plus any modifications and additions | |
2916 | specified by redirections to the command | |
2917 | ||
2918 | * the current working directory | |
2919 | ||
2920 | * the file creation mode mask | |
2921 | ||
2922 | * shell variables and functions marked for export, along with | |
2923 | variables exported for the command, passed in the environment | |
2924 | (*note Environment::) | |
2925 | ||
2926 | * traps caught by the shell are reset to the values inherited from | |
2927 | the shell's parent, and traps ignored by the shell are ignored | |
2928 | ||
2929 | A command invoked in this separate environment cannot affect the | |
2930 | shell's execution environment. | |
2931 | ||
74091dd4 CR |
2932 | A "subshell" is a copy of the shell process. |
2933 | ||
a0c0a00f CR |
2934 | Command substitution, commands grouped with parentheses, and |
2935 | asynchronous commands are invoked in a subshell environment that is a | |
2936 | duplicate of the shell environment, except that traps caught by the | |
2937 | shell are reset to the values that the shell inherited from its parent | |
2938 | at invocation. Builtin commands that are invoked as part of a pipeline | |
2939 | are also executed in a subshell environment. Changes made to the | |
2940 | subshell environment cannot affect the shell's execution environment. | |
2941 | ||
2942 | Subshells spawned to execute command substitutions inherit the value | |
2943 | of the '-e' option from the parent shell. When not in POSIX mode, Bash | |
2944 | clears the '-e' option in such subshells. | |
2945 | ||
2946 | If a command is followed by a '&' and job control is not active, the | |
2947 | default standard input for the command is the empty file '/dev/null'. | |
2948 | Otherwise, the invoked command inherits the file descriptors of the | |
2949 | calling shell as modified by redirections. | |
2950 | ||
2951 | \1f | |
2952 | File: bash.info, Node: Environment, Next: Exit Status, Prev: Command Execution Environment, Up: Executing Commands | |
2953 | ||
2954 | 3.7.4 Environment | |
2955 | ----------------- | |
2956 | ||
2957 | When a program is invoked it is given an array of strings called the | |
74091dd4 | 2958 | "environment". This is a list of name-value pairs, of the form |
a0c0a00f CR |
2959 | 'name=value'. |
2960 | ||
2961 | Bash provides several ways to manipulate the environment. On | |
2962 | invocation, the shell scans its own environment and creates a parameter | |
74091dd4 | 2963 | for each name found, automatically marking it for 'export' to child |
a0c0a00f CR |
2964 | processes. Executed commands inherit the environment. The 'export' and |
2965 | 'declare -x' commands allow parameters and functions to be added to and | |
2966 | deleted from the environment. If the value of a parameter in the | |
2967 | environment is modified, the new value becomes part of the environment, | |
2968 | replacing the old. The environment inherited by any executed command | |
2969 | consists of the shell's initial environment, whose values may be | |
2970 | modified in the shell, less any pairs removed by the 'unset' and 'export | |
2971 | -n' commands, plus any additions via the 'export' and 'declare -x' | |
2972 | commands. | |
2973 | ||
2974 | The environment for any simple command or function may be augmented | |
2975 | temporarily by prefixing it with parameter assignments, as described in | |
2976 | *note Shell Parameters::. These assignment statements affect only the | |
2977 | environment seen by that command. | |
2978 | ||
2979 | If the '-k' option is set (*note The Set Builtin::), then all | |
2980 | parameter assignments are placed in the environment for a command, not | |
2981 | just those that precede the command name. | |
2982 | ||
2983 | When Bash invokes an external command, the variable '$_' is set to | |
2984 | the full pathname of the command and passed to that command in its | |
2985 | environment. | |
2986 | ||
2987 | \1f | |
2988 | File: bash.info, Node: Exit Status, Next: Signals, Prev: Environment, Up: Executing Commands | |
2989 | ||
2990 | 3.7.5 Exit Status | |
2991 | ----------------- | |
2992 | ||
2993 | The exit status of an executed command is the value returned by the | |
74091dd4 CR |
2994 | 'waitpid' system call or equivalent function. Exit statuses fall |
2995 | between 0 and 255, though, as explained below, the shell may use values | |
2996 | above 125 specially. Exit statuses from shell builtins and compound | |
2997 | commands are also limited to this range. Under certain circumstances, | |
2998 | the shell will use special values to indicate specific failure modes. | |
a0c0a00f CR |
2999 | |
3000 | For the shell's purposes, a command which exits with a zero exit | |
3001 | status has succeeded. A non-zero exit status indicates failure. This | |
3002 | seemingly counter-intuitive scheme is used so there is one well-defined | |
3003 | way to indicate success and a variety of ways to indicate various | |
3004 | failure modes. When a command terminates on a fatal signal whose number | |
3005 | is N, Bash uses the value 128+N as the exit status. | |
3006 | ||
3007 | If a command is not found, the child process created to execute it | |
3008 | returns a status of 127. If a command is found but is not executable, | |
3009 | the return status is 126. | |
3010 | ||
3011 | If a command fails because of an error during expansion or | |
3012 | redirection, the exit status is greater than zero. | |
3013 | ||
3014 | The exit status is used by the Bash conditional commands (*note | |
3015 | Conditional Constructs::) and some of the list constructs (*note | |
3016 | Lists::). | |
3017 | ||
3018 | All of the Bash builtins return an exit status of zero if they | |
3019 | succeed and a non-zero status on failure, so they may be used by the | |
3020 | conditional and list constructs. All builtins return an exit status of | |
3021 | 2 to indicate incorrect usage, generally invalid options or missing | |
3022 | arguments. | |
3023 | ||
74091dd4 CR |
3024 | The exit status of the last command is available in the special |
3025 | parameter $? (*note Special Parameters::). | |
3026 | ||
a0c0a00f CR |
3027 | \1f |
3028 | File: bash.info, Node: Signals, Prev: Exit Status, Up: Executing Commands | |
3029 | ||
3030 | 3.7.6 Signals | |
3031 | ------------- | |
3032 | ||
3033 | When Bash is interactive, in the absence of any traps, it ignores | |
3034 | 'SIGTERM' (so that 'kill 0' does not kill an interactive shell), and | |
3035 | 'SIGINT' is caught and handled (so that the 'wait' builtin is | |
3036 | interruptible). When Bash receives a 'SIGINT', it breaks out of any | |
3037 | executing loops. In all cases, Bash ignores 'SIGQUIT'. If job control | |
3038 | is in effect (*note Job Control::), Bash ignores 'SIGTTIN', 'SIGTTOU', | |
3039 | and 'SIGTSTP'. | |
3040 | ||
3041 | Non-builtin commands started by Bash have signal handlers set to the | |
3042 | values inherited by the shell from its parent. When job control is not | |
3043 | in effect, asynchronous commands ignore 'SIGINT' and 'SIGQUIT' in | |
3044 | addition to these inherited handlers. Commands run as a result of | |
3045 | command substitution ignore the keyboard-generated job control signals | |
3046 | 'SIGTTIN', 'SIGTTOU', and 'SIGTSTP'. | |
3047 | ||
3048 | The shell exits by default upon receipt of a 'SIGHUP'. Before | |
3049 | exiting, an interactive shell resends the 'SIGHUP' to all jobs, running | |
3050 | or stopped. Stopped jobs are sent 'SIGCONT' to ensure that they receive | |
3051 | the 'SIGHUP'. To prevent the shell from sending the 'SIGHUP' signal to | |
3052 | a particular job, it should be removed from the jobs table with the | |
3053 | 'disown' builtin (*note Job Control Builtins::) or marked to not receive | |
3054 | 'SIGHUP' using 'disown -h'. | |
3055 | ||
3056 | If the 'huponexit' shell option has been set with 'shopt' (*note The | |
3057 | Shopt Builtin::), Bash sends a 'SIGHUP' to all jobs when an interactive | |
3058 | login shell exits. | |
3059 | ||
3060 | If Bash is waiting for a command to complete and receives a signal | |
3061 | for which a trap has been set, the trap will not be executed until the | |
3062 | command completes. When Bash is waiting for an asynchronous command via | |
3063 | the 'wait' builtin, the reception of a signal for which a trap has been | |
3064 | set will cause the 'wait' builtin to return immediately with an exit | |
3065 | status greater than 128, immediately after which the trap is executed. | |
3066 | ||
74091dd4 CR |
3067 | When job control is not enabled, and Bash is waiting for a foreground |
3068 | command to complete, the shell receives keyboard-generated signals such | |
3069 | as 'SIGINT' (usually generated by '^C') that users commonly intend to | |
3070 | send to that command. This happens because the shell and the command | |
3071 | are in the same process group as the terminal, and '^C' sends 'SIGINT' | |
3072 | to all processes in that process group. See *note Job Control::, for a | |
3073 | more in-depth discussion of process groups. | |
3074 | ||
3075 | When Bash is running without job control enabled and receives | |
3076 | 'SIGINT' while waiting for a foreground command, it waits until that | |
3077 | foreground command terminates and then decides what to do about the | |
3078 | 'SIGINT': | |
3079 | ||
3080 | 1. If the command terminates due to the 'SIGINT', Bash concludes that | |
3081 | the user meant to end the entire script, and acts on the 'SIGINT' | |
3082 | (e.g., by running a 'SIGINT' trap or exiting itself); | |
3083 | ||
3084 | 2. If the pipeline does not terminate due to 'SIGINT', the program | |
3085 | handled the 'SIGINT' itself and did not treat it as a fatal signal. | |
3086 | In that case, Bash does not treat 'SIGINT' as a fatal signal, | |
3087 | either, instead assuming that the 'SIGINT' was used as part of the | |
3088 | program's normal operation (e.g., 'emacs' uses it to abort editing | |
3089 | commands) or deliberately discarded. However, Bash will run any | |
3090 | trap set on 'SIGINT', as it does with any other trapped signal it | |
3091 | receives while it is waiting for the foreground command to | |
3092 | complete, for compatibility. | |
3093 | ||
a0c0a00f CR |
3094 | \1f |
3095 | File: bash.info, Node: Shell Scripts, Prev: Executing Commands, Up: Basic Shell Features | |
3096 | ||
3097 | 3.8 Shell Scripts | |
3098 | ================= | |
3099 | ||
3100 | A shell script is a text file containing shell commands. When such a | |
3101 | file is used as the first non-option argument when invoking Bash, and | |
3102 | neither the '-c' nor '-s' option is supplied (*note Invoking Bash::), | |
3103 | Bash reads and executes commands from the file, then exits. This mode | |
3104 | of operation creates a non-interactive shell. The shell first searches | |
3105 | for the file in the current directory, and looks in the directories in | |
3106 | '$PATH' if not found there. | |
3107 | ||
3108 | When Bash runs a shell script, it sets the special parameter '0' to | |
3109 | the name of the file, rather than the name of the shell, and the | |
3110 | positional parameters are set to the remaining arguments, if any are | |
3111 | given. If no additional arguments are supplied, the positional | |
3112 | parameters are unset. | |
3113 | ||
3114 | A shell script may be made executable by using the 'chmod' command to | |
3115 | turn on the execute bit. When Bash finds such a file while searching | |
74091dd4 CR |
3116 | the '$PATH' for a command, it creates a new instance of itself to |
3117 | execute it. In other words, executing | |
a0c0a00f CR |
3118 | filename ARGUMENTS |
3119 | is equivalent to executing | |
3120 | bash filename ARGUMENTS | |
3121 | ||
3122 | if 'filename' is an executable shell script. This subshell | |
3123 | reinitializes itself, so that the effect is as if a new shell had been | |
3124 | invoked to interpret the script, with the exception that the locations | |
3125 | of commands remembered by the parent (see the description of 'hash' in | |
3126 | *note Bourne Shell Builtins::) are retained by the child. | |
3127 | ||
3128 | Most versions of Unix make this a part of the operating system's | |
3129 | command execution mechanism. If the first line of a script begins with | |
3130 | the two characters '#!', the remainder of the line specifies an | |
8868edaf CR |
3131 | interpreter for the program and, depending on the operating system, one |
3132 | or more optional arguments for that interpreter. Thus, you can specify | |
3133 | Bash, 'awk', Perl, or some other interpreter and write the rest of the | |
3134 | script file in that language. | |
a0c0a00f | 3135 | |
8868edaf CR |
3136 | The arguments to the interpreter consist of one or more optional |
3137 | arguments following the interpreter name on the first line of the script | |
a0c0a00f | 3138 | file, followed by the name of the script file, followed by the rest of |
8868edaf CR |
3139 | the arguments supplied to the script. The details of how the |
3140 | interpreter line is split into an interpreter name and a set of | |
3141 | arguments vary across systems. Bash will perform this action on | |
3142 | operating systems that do not handle it themselves. Note that some | |
3143 | older versions of Unix limit the interpreter name and a single argument | |
3144 | to a maximum of 32 characters, so it's not portable to assume that using | |
3145 | more than one argument will work. | |
a0c0a00f CR |
3146 | |
3147 | Bash scripts often begin with '#! /bin/bash' (assuming that Bash has | |
3148 | been installed in '/bin'), since this ensures that Bash will be used to | |
8868edaf CR |
3149 | interpret the script, even if it is executed under another shell. It's |
3150 | a common idiom to use 'env' to find 'bash' even if it's been installed | |
3151 | in another directory: '#!/usr/bin/env bash' will find the first | |
3152 | occurrence of 'bash' in '$PATH'. | |
a0c0a00f CR |
3153 | |
3154 | \1f | |
3155 | File: bash.info, Node: Shell Builtin Commands, Next: Shell Variables, Prev: Basic Shell Features, Up: Top | |
3156 | ||
3157 | 4 Shell Builtin Commands | |
3158 | ************************ | |
3159 | ||
3160 | * Menu: | |
3161 | ||
3162 | * Bourne Shell Builtins:: Builtin commands inherited from the Bourne | |
3163 | Shell. | |
3164 | * Bash Builtins:: Table of builtins specific to Bash. | |
3165 | * Modifying Shell Behavior:: Builtins to modify shell attributes and | |
3166 | optional behavior. | |
3167 | * Special Builtins:: Builtin commands classified specially by | |
3168 | POSIX. | |
3169 | ||
3170 | Builtin commands are contained within the shell itself. When the name | |
3171 | of a builtin command is used as the first word of a simple command | |
3172 | (*note Simple Commands::), the shell executes the command directly, | |
3173 | without invoking another program. Builtin commands are necessary to | |
3174 | implement functionality impossible or inconvenient to obtain with | |
3175 | separate utilities. | |
3176 | ||
3177 | This section briefly describes the builtins which Bash inherits from | |
3178 | the Bourne Shell, as well as the builtin commands which are unique to or | |
3179 | have been extended in Bash. | |
3180 | ||
3181 | Several builtin commands are described in other chapters: builtin | |
3182 | commands which provide the Bash interface to the job control facilities | |
3183 | (*note Job Control Builtins::), the directory stack (*note Directory | |
3184 | Stack Builtins::), the command history (*note Bash History Builtins::), | |
3185 | and the programmable completion facilities (*note Programmable | |
3186 | Completion Builtins::). | |
3187 | ||
3188 | Many of the builtins have been extended by POSIX or Bash. | |
3189 | ||
3190 | Unless otherwise noted, each builtin command documented as accepting | |
3191 | options preceded by '-' accepts '--' to signify the end of the options. | |
d233b485 CR |
3192 | The ':', 'true', 'false', and 'test'/'[' builtins do not accept options |
3193 | and do not treat '--' specially. The 'exit', 'logout', 'return', | |
3194 | 'break', 'continue', 'let', and 'shift' builtins accept and process | |
3195 | arguments beginning with '-' without requiring '--'. Other builtins | |
3196 | that accept arguments but are not specified as accepting options | |
3197 | interpret arguments beginning with '-' as invalid options and require | |
3198 | '--' to prevent this interpretation. | |
a0c0a00f CR |
3199 | |
3200 | \1f | |
3201 | File: bash.info, Node: Bourne Shell Builtins, Next: Bash Builtins, Up: Shell Builtin Commands | |
3202 | ||
3203 | 4.1 Bourne Shell Builtins | |
3204 | ========================= | |
3205 | ||
3206 | The following shell builtin commands are inherited from the Bourne | |
3207 | Shell. These commands are implemented as specified by the POSIX | |
3208 | standard. | |
3209 | ||
3210 | ': (a colon)' | |
3211 | : [ARGUMENTS] | |
3212 | ||
3213 | Do nothing beyond expanding ARGUMENTS and performing redirections. | |
3214 | The return status is zero. | |
3215 | ||
3216 | '. (a period)' | |
3217 | . FILENAME [ARGUMENTS] | |
3218 | ||
3219 | Read and execute commands from the FILENAME argument in the current | |
3220 | shell context. If FILENAME does not contain a slash, the 'PATH' | |
74091dd4 CR |
3221 | variable is used to find FILENAME, but FILENAME does not need to be |
3222 | executable. When Bash is not in POSIX mode, it searches the | |
3223 | current directory if FILENAME is not found in '$PATH'. If any | |
3224 | ARGUMENTS are supplied, they become the positional parameters when | |
3225 | FILENAME is executed. Otherwise the positional parameters are | |
3226 | unchanged. If the '-T' option is enabled, '.' inherits any trap on | |
3227 | 'DEBUG'; if it is not, any 'DEBUG' trap string is saved and | |
3228 | restored around the call to '.', and '.' unsets the 'DEBUG' trap | |
3229 | while it executes. If '-T' is not set, and the sourced file | |
3230 | changes the 'DEBUG' trap, the new value is retained when '.' | |
3231 | completes. The return status is the exit status of the last | |
3232 | command executed, or zero if no commands are executed. If FILENAME | |
3233 | is not found, or cannot be read, the return status is non-zero. | |
3234 | This builtin is equivalent to 'source'. | |
a0c0a00f CR |
3235 | |
3236 | 'break' | |
3237 | break [N] | |
3238 | ||
3239 | Exit from a 'for', 'while', 'until', or 'select' loop. If N is | |
3240 | supplied, the Nth enclosing loop is exited. N must be greater than | |
3241 | or equal to 1. The return status is zero unless N is not greater | |
3242 | than or equal to 1. | |
3243 | ||
3244 | 'cd' | |
3245 | cd [-L|[-P [-e]] [-@] [DIRECTORY] | |
3246 | ||
3247 | Change the current working directory to DIRECTORY. If DIRECTORY is | |
74091dd4 CR |
3248 | not supplied, the value of the 'HOME' shell variable is used. If |
3249 | the shell variable 'CDPATH' exists, it is used as a search path: | |
3250 | each directory name in 'CDPATH' is searched for DIRECTORY, with | |
a0c0a00f CR |
3251 | alternative directory names in 'CDPATH' separated by a colon (':'). |
3252 | If DIRECTORY begins with a slash, 'CDPATH' is not used. | |
3253 | ||
3254 | The '-P' option means to not follow symbolic links: symbolic links | |
3255 | are resolved while 'cd' is traversing DIRECTORY and before | |
3256 | processing an instance of '..' in DIRECTORY. | |
3257 | ||
3258 | By default, or when the '-L' option is supplied, symbolic links in | |
3259 | DIRECTORY are resolved after 'cd' processes an instance of '..' in | |
3260 | DIRECTORY. | |
3261 | ||
3262 | If '..' appears in DIRECTORY, it is processed by removing the | |
3263 | immediately preceding pathname component, back to a slash or the | |
3264 | beginning of DIRECTORY. | |
3265 | ||
3266 | If the '-e' option is supplied with '-P' and the current working | |
3267 | directory cannot be successfully determined after a successful | |
3268 | directory change, 'cd' will return an unsuccessful status. | |
3269 | ||
3270 | On systems that support it, the '-@' option presents the extended | |
3271 | attributes associated with a file as a directory. | |
3272 | ||
3273 | If DIRECTORY is '-', it is converted to '$OLDPWD' before the | |
3274 | directory change is attempted. | |
3275 | ||
3276 | If a non-empty directory name from 'CDPATH' is used, or if '-' is | |
3277 | the first argument, and the directory change is successful, the | |
3278 | absolute pathname of the new working directory is written to the | |
3279 | standard output. | |
3280 | ||
74091dd4 CR |
3281 | If the directory change is successful, 'cd' sets the value of the |
3282 | 'PWD' environment variable to the new directory name, and sets the | |
3283 | 'OLDPWD' environment variable to the value of the current working | |
3284 | directory before the change. | |
3285 | ||
a0c0a00f CR |
3286 | The return status is zero if the directory is successfully changed, |
3287 | non-zero otherwise. | |
3288 | ||
3289 | 'continue' | |
3290 | continue [N] | |
3291 | ||
3292 | Resume the next iteration of an enclosing 'for', 'while', 'until', | |
3293 | or 'select' loop. If N is supplied, the execution of the Nth | |
3294 | enclosing loop is resumed. N must be greater than or equal to 1. | |
3295 | The return status is zero unless N is not greater than or equal to | |
3296 | 1. | |
3297 | ||
3298 | 'eval' | |
3299 | eval [ARGUMENTS] | |
3300 | ||
3301 | The arguments are concatenated together into a single command, | |
3302 | which is then read and executed, and its exit status returned as | |
3303 | the exit status of 'eval'. If there are no arguments or only empty | |
3304 | arguments, the return status is zero. | |
3305 | ||
3306 | 'exec' | |
3307 | exec [-cl] [-a NAME] [COMMAND [ARGUMENTS]] | |
3308 | ||
3309 | If COMMAND is supplied, it replaces the shell without creating a | |
3310 | new process. If the '-l' option is supplied, the shell places a | |
3311 | dash at the beginning of the zeroth argument passed to COMMAND. | |
3312 | This is what the 'login' program does. The '-c' option causes | |
3313 | COMMAND to be executed with an empty environment. If '-a' is | |
3314 | supplied, the shell passes NAME as the zeroth argument to COMMAND. | |
3315 | If COMMAND cannot be executed for some reason, a non-interactive | |
3316 | shell exits, unless the 'execfail' shell option is enabled. In | |
3317 | that case, it returns failure. An interactive shell returns | |
d233b485 CR |
3318 | failure if the file cannot be executed. A subshell exits |
3319 | unconditionally if 'exec' fails. If no COMMAND is specified, | |
3320 | redirections may be used to affect the current shell environment. | |
3321 | If there are no redirection errors, the return status is zero; | |
3322 | otherwise the return status is non-zero. | |
a0c0a00f CR |
3323 | |
3324 | 'exit' | |
3325 | exit [N] | |
3326 | ||
3327 | Exit the shell, returning a status of N to the shell's parent. If | |
3328 | N is omitted, the exit status is that of the last command executed. | |
3329 | Any trap on 'EXIT' is executed before the shell terminates. | |
3330 | ||
3331 | 'export' | |
3332 | export [-fn] [-p] [NAME[=VALUE]] | |
3333 | ||
3334 | Mark each NAME to be passed to child processes in the environment. | |
3335 | If the '-f' option is supplied, the NAMEs refer to shell functions; | |
3336 | otherwise the names refer to shell variables. The '-n' option | |
74091dd4 | 3337 | means to no longer mark each NAME for export. If no NAMEs are |
a0c0a00f CR |
3338 | supplied, or if the '-p' option is given, a list of names of all |
3339 | exported variables is displayed. The '-p' option displays output | |
3340 | in a form that may be reused as input. If a variable name is | |
3341 | followed by =VALUE, the value of the variable is set to VALUE. | |
3342 | ||
3343 | The return status is zero unless an invalid option is supplied, one | |
3344 | of the names is not a valid shell variable name, or '-f' is | |
3345 | supplied with a name that is not a shell function. | |
3346 | ||
3347 | 'getopts' | |
8868edaf | 3348 | getopts OPTSTRING NAME [ARG ...] |
a0c0a00f CR |
3349 | |
3350 | 'getopts' is used by shell scripts to parse positional parameters. | |
3351 | OPTSTRING contains the option characters to be recognized; if a | |
3352 | character is followed by a colon, the option is expected to have an | |
3353 | argument, which should be separated from it by whitespace. The | |
3354 | colon (':') and question mark ('?') may not be used as option | |
3355 | characters. Each time it is invoked, 'getopts' places the next | |
3356 | option in the shell variable NAME, initializing NAME if it does not | |
3357 | exist, and the index of the next argument to be processed into the | |
3358 | variable 'OPTIND'. 'OPTIND' is initialized to 1 each time the | |
3359 | shell or a shell script is invoked. When an option requires an | |
3360 | argument, 'getopts' places that argument into the variable | |
3361 | 'OPTARG'. The shell does not reset 'OPTIND' automatically; it must | |
3362 | be manually reset between multiple calls to 'getopts' within the | |
3363 | same shell invocation if a new set of parameters is to be used. | |
3364 | ||
3365 | When the end of options is encountered, 'getopts' exits with a | |
3366 | return value greater than zero. 'OPTIND' is set to the index of | |
3367 | the first non-option argument, and NAME is set to '?'. | |
3368 | ||
3369 | 'getopts' normally parses the positional parameters, but if more | |
8868edaf CR |
3370 | arguments are supplied as ARG values, 'getopts' parses those |
3371 | instead. | |
a0c0a00f CR |
3372 | |
3373 | 'getopts' can report errors in two ways. If the first character of | |
3374 | OPTSTRING is a colon, SILENT error reporting is used. In normal | |
3375 | operation, diagnostic messages are printed when invalid options or | |
3376 | missing option arguments are encountered. If the variable 'OPTERR' | |
3377 | is set to 0, no error messages will be displayed, even if the first | |
3378 | character of 'optstring' is not a colon. | |
3379 | ||
3380 | If an invalid option is seen, 'getopts' places '?' into NAME and, | |
3381 | if not silent, prints an error message and unsets 'OPTARG'. If | |
3382 | 'getopts' is silent, the option character found is placed in | |
3383 | 'OPTARG' and no diagnostic message is printed. | |
3384 | ||
3385 | If a required argument is not found, and 'getopts' is not silent, a | |
3386 | question mark ('?') is placed in NAME, 'OPTARG' is unset, and a | |
3387 | diagnostic message is printed. If 'getopts' is silent, then a | |
3388 | colon (':') is placed in NAME and 'OPTARG' is set to the option | |
3389 | character found. | |
3390 | ||
3391 | 'hash' | |
3392 | hash [-r] [-p FILENAME] [-dt] [NAME] | |
3393 | ||
3394 | Each time 'hash' is invoked, it remembers the full pathnames of the | |
3395 | commands specified as NAME arguments, so they need not be searched | |
3396 | for on subsequent invocations. The commands are found by searching | |
3397 | through the directories listed in '$PATH'. Any | |
3398 | previously-remembered pathname is discarded. The '-p' option | |
3399 | inhibits the path search, and FILENAME is used as the location of | |
3400 | NAME. The '-r' option causes the shell to forget all remembered | |
3401 | locations. The '-d' option causes the shell to forget the | |
3402 | remembered location of each NAME. If the '-t' option is supplied, | |
3403 | the full pathname to which each NAME corresponds is printed. If | |
d233b485 | 3404 | multiple NAME arguments are supplied with '-t', the NAME is printed |
a0c0a00f CR |
3405 | before the hashed full pathname. The '-l' option causes output to |
3406 | be displayed in a format that may be reused as input. If no | |
3407 | arguments are given, or if only '-l' is supplied, information about | |
3408 | remembered commands is printed. The return status is zero unless a | |
3409 | NAME is not found or an invalid option is supplied. | |
3410 | ||
3411 | 'pwd' | |
3412 | pwd [-LP] | |
3413 | ||
3414 | Print the absolute pathname of the current working directory. If | |
3415 | the '-P' option is supplied, the pathname printed will not contain | |
3416 | symbolic links. If the '-L' option is supplied, the pathname | |
3417 | printed may contain symbolic links. The return status is zero | |
3418 | unless an error is encountered while determining the name of the | |
3419 | current directory or an invalid option is supplied. | |
3420 | ||
3421 | 'readonly' | |
3422 | readonly [-aAf] [-p] [NAME[=VALUE]] ... | |
3423 | ||
3424 | Mark each NAME as readonly. The values of these names may not be | |
3425 | changed by subsequent assignment. If the '-f' option is supplied, | |
3426 | each NAME refers to a shell function. The '-a' option means each | |
3427 | NAME refers to an indexed array variable; the '-A' option means | |
3428 | each NAME refers to an associative array variable. If both options | |
3429 | are supplied, '-A' takes precedence. If no NAME arguments are | |
3430 | given, or if the '-p' option is supplied, a list of all readonly | |
3431 | names is printed. The other options may be used to restrict the | |
3432 | output to a subset of the set of readonly names. The '-p' option | |
3433 | causes output to be displayed in a format that may be reused as | |
3434 | input. If a variable name is followed by =VALUE, the value of the | |
3435 | variable is set to VALUE. The return status is zero unless an | |
3436 | invalid option is supplied, one of the NAME arguments is not a | |
3437 | valid shell variable or function name, or the '-f' option is | |
3438 | supplied with a name that is not a shell function. | |
3439 | ||
3440 | 'return' | |
3441 | return [N] | |
3442 | ||
3443 | Cause a shell function to stop executing and return the value N to | |
3444 | its caller. If N is not supplied, the return value is the exit | |
3445 | status of the last command executed in the function. If 'return' | |
3446 | is executed by a trap handler, the last command used to determine | |
3447 | the status is the last command executed before the trap handler. | |
d233b485 | 3448 | If 'return' is executed during a 'DEBUG' trap, the last command |
a0c0a00f CR |
3449 | used to determine the status is the last command executed by the |
3450 | trap handler before 'return' was invoked. 'return' may also be | |
3451 | used to terminate execution of a script being executed with the '.' | |
3452 | ('source') builtin, returning either N or the exit status of the | |
3453 | last command executed within the script as the exit status of the | |
3454 | script. If N is supplied, the return value is its least | |
3455 | significant 8 bits. Any command associated with the 'RETURN' trap | |
3456 | is executed before execution resumes after the function or script. | |
3457 | The return status is non-zero if 'return' is supplied a non-numeric | |
3458 | argument or is used outside a function and not during the execution | |
3459 | of a script by '.' or 'source'. | |
3460 | ||
3461 | 'shift' | |
3462 | shift [N] | |
3463 | ||
3464 | Shift the positional parameters to the left by N. The positional | |
3465 | parameters from N+1 ... '$#' are renamed to '$1' ... '$#'-N. | |
8868edaf CR |
3466 | Parameters represented by the numbers '$#' down to '$#'-N+1 are |
3467 | unset. N must be a non-negative number less than or equal to '$#'. | |
3468 | If N is zero or greater than '$#', the positional parameters are | |
3469 | not changed. If N is not supplied, it is assumed to be 1. The | |
3470 | return status is zero unless N is greater than '$#' or less than | |
3471 | zero, non-zero otherwise. | |
a0c0a00f CR |
3472 | |
3473 | 'test' | |
3474 | '[' | |
3475 | test EXPR | |
3476 | ||
3477 | Evaluate a conditional expression EXPR and return a status of 0 | |
3478 | (true) or 1 (false). Each operator and operand must be a separate | |
3479 | argument. Expressions are composed of the primaries described | |
3480 | below in *note Bash Conditional Expressions::. 'test' does not | |
3481 | accept any options, nor does it accept and ignore an argument of | |
3482 | '--' as signifying the end of options. | |
3483 | ||
3484 | When the '[' form is used, the last argument to the command must be | |
3485 | a ']'. | |
3486 | ||
3487 | Expressions may be combined using the following operators, listed | |
3488 | in decreasing order of precedence. The evaluation depends on the | |
3489 | number of arguments; see below. Operator precedence is used when | |
3490 | there are five or more arguments. | |
3491 | ||
3492 | '! EXPR' | |
3493 | True if EXPR is false. | |
3494 | ||
3495 | '( EXPR )' | |
3496 | Returns the value of EXPR. This may be used to override the | |
3497 | normal precedence of operators. | |
3498 | ||
3499 | 'EXPR1 -a EXPR2' | |
3500 | True if both EXPR1 and EXPR2 are true. | |
3501 | ||
3502 | 'EXPR1 -o EXPR2' | |
3503 | True if either EXPR1 or EXPR2 is true. | |
3504 | ||
3505 | The 'test' and '[' builtins evaluate conditional expressions using | |
3506 | a set of rules based on the number of arguments. | |
3507 | ||
3508 | 0 arguments | |
3509 | The expression is false. | |
3510 | ||
3511 | 1 argument | |
d233b485 | 3512 | The expression is true if, and only if, the argument is not |
a0c0a00f CR |
3513 | null. |
3514 | ||
3515 | 2 arguments | |
3516 | If the first argument is '!', the expression is true if and | |
3517 | only if the second argument is null. If the first argument is | |
3518 | one of the unary conditional operators (*note Bash Conditional | |
3519 | Expressions::), the expression is true if the unary test is | |
3520 | true. If the first argument is not a valid unary operator, | |
3521 | the expression is false. | |
3522 | ||
3523 | 3 arguments | |
d233b485 CR |
3524 | The following conditions are applied in the order listed. |
3525 | ||
3526 | 1. If the second argument is one of the binary conditional | |
3527 | operators (*note Bash Conditional Expressions::), the | |
3528 | result of the expression is the result of the binary test | |
3529 | using the first and third arguments as operands. The | |
3530 | '-a' and '-o' operators are considered binary operators | |
3531 | when there are three arguments. | |
3532 | 2. If the first argument is '!', the value is the negation | |
3533 | of the two-argument test using the second and third | |
3534 | arguments. | |
3535 | 3. If the first argument is exactly '(' and the third | |
3536 | argument is exactly ')', the result is the one-argument | |
3537 | test of the second argument. | |
3538 | 4. Otherwise, the expression is false. | |
a0c0a00f CR |
3539 | |
3540 | 4 arguments | |
74091dd4 CR |
3541 | The following conditions are applied in the order listed. |
3542 | ||
3543 | 1. If the first argument is '!', the result is the negation | |
3544 | of the three-argument expression composed of the | |
3545 | remaining arguments. | |
3546 | 2. If the first argument is exactly '(' and the fourth | |
3547 | argument is exactly ')', the result is the two-argument | |
3548 | test of the second and third arguments. | |
3549 | 3. Otherwise, the expression is parsed and evaluated | |
3550 | according to precedence using the rules listed above. | |
a0c0a00f CR |
3551 | |
3552 | 5 or more arguments | |
3553 | The expression is parsed and evaluated according to precedence | |
3554 | using the rules listed above. | |
3555 | ||
3556 | When used with 'test' or '[', the '<' and '>' operators sort | |
3557 | lexicographically using ASCII ordering. | |
3558 | ||
3559 | 'times' | |
3560 | times | |
3561 | ||
3562 | Print out the user and system times used by the shell and its | |
3563 | children. The return status is zero. | |
3564 | ||
3565 | 'trap' | |
3566 | trap [-lp] [ARG] [SIGSPEC ...] | |
3567 | ||
3568 | The commands in ARG are to be read and executed when the shell | |
3569 | receives signal SIGSPEC. If ARG is absent (and there is a single | |
3570 | SIGSPEC) or equal to '-', each specified signal's disposition is | |
3571 | reset to the value it had when the shell was started. If ARG is | |
3572 | the null string, then the signal specified by each SIGSPEC is | |
3573 | ignored by the shell and commands it invokes. If ARG is not | |
3574 | present and '-p' has been supplied, the shell displays the trap | |
3575 | commands associated with each SIGSPEC. If no arguments are | |
3576 | supplied, or only '-p' is given, 'trap' prints the list of commands | |
3577 | associated with each signal number in a form that may be reused as | |
3578 | shell input. The '-l' option causes the shell to print a list of | |
3579 | signal names and their corresponding numbers. Each SIGSPEC is | |
3580 | either a signal name or a signal number. Signal names are case | |
3581 | insensitive and the 'SIG' prefix is optional. | |
3582 | ||
3583 | If a SIGSPEC is '0' or 'EXIT', ARG is executed when the shell | |
3584 | exits. If a SIGSPEC is 'DEBUG', the command ARG is executed before | |
3585 | every simple command, 'for' command, 'case' command, 'select' | |
3586 | command, every arithmetic 'for' command, and before the first | |
3587 | command executes in a shell function. Refer to the description of | |
3588 | the 'extdebug' option to the 'shopt' builtin (*note The Shopt | |
3589 | Builtin::) for details of its effect on the 'DEBUG' trap. If a | |
3590 | SIGSPEC is 'RETURN', the command ARG is executed each time a shell | |
3591 | function or a script executed with the '.' or 'source' builtins | |
3592 | finishes executing. | |
3593 | ||
3594 | If a SIGSPEC is 'ERR', the command ARG is executed whenever a | |
3595 | pipeline (which may consist of a single simple command), a list, or | |
3596 | a compound command returns a non-zero exit status, subject to the | |
3597 | following conditions. The 'ERR' trap is not executed if the failed | |
3598 | command is part of the command list immediately following an | |
3599 | 'until' or 'while' keyword, part of the test following the 'if' or | |
3600 | 'elif' reserved words, part of a command executed in a '&&' or '||' | |
3601 | list except the command following the final '&&' or '||', any | |
3602 | command in a pipeline but the last, or if the command's return | |
3603 | status is being inverted using '!'. These are the same conditions | |
3604 | obeyed by the 'errexit' ('-e') option. | |
3605 | ||
3606 | Signals ignored upon entry to the shell cannot be trapped or reset. | |
3607 | Trapped signals that are not being ignored are reset to their | |
3608 | original values in a subshell or subshell environment when one is | |
3609 | created. | |
3610 | ||
3611 | The return status is zero unless a SIGSPEC does not specify a valid | |
3612 | signal. | |
3613 | ||
3614 | 'umask' | |
3615 | umask [-p] [-S] [MODE] | |
3616 | ||
3617 | Set the shell process's file creation mask to MODE. If MODE begins | |
3618 | with a digit, it is interpreted as an octal number; if not, it is | |
3619 | interpreted as a symbolic mode mask similar to that accepted by the | |
3620 | 'chmod' command. If MODE is omitted, the current value of the mask | |
3621 | is printed. If the '-S' option is supplied without a MODE | |
3622 | argument, the mask is printed in a symbolic format. If the '-p' | |
3623 | option is supplied, and MODE is omitted, the output is in a form | |
3624 | that may be reused as input. The return status is zero if the mode | |
3625 | is successfully changed or if no MODE argument is supplied, and | |
3626 | non-zero otherwise. | |
3627 | ||
3628 | Note that when the mode is interpreted as an octal number, each | |
3629 | number of the umask is subtracted from '7'. Thus, a umask of '022' | |
3630 | results in permissions of '755'. | |
3631 | ||
3632 | 'unset' | |
3633 | unset [-fnv] [NAME] | |
3634 | ||
3635 | Remove each variable or function NAME. If the '-v' option is | |
3636 | given, each NAME refers to a shell variable and that variable is | |
3637 | removed. If the '-f' option is given, the NAMEs refer to shell | |
3638 | functions, and the function definition is removed. If the '-n' | |
74091dd4 | 3639 | option is supplied, and NAME is a variable with the 'nameref' |
a0c0a00f CR |
3640 | attribute, NAME will be unset rather than the variable it |
3641 | references. '-n' has no effect if the '-f' option is supplied. If | |
3642 | no options are supplied, each NAME refers to a variable; if there | |
8868edaf CR |
3643 | is no variable by that name, a function with that name, if any, is |
3644 | unset. Readonly variables and functions may not be unset. Some | |
3645 | shell variables lose their special behavior if they are unset; such | |
3646 | behavior is noted in the description of the individual variables. | |
74091dd4 CR |
3647 | The return status is zero unless a NAME is readonly or may not be |
3648 | unset. | |
a0c0a00f CR |
3649 | |
3650 | \1f | |
3651 | File: bash.info, Node: Bash Builtins, Next: Modifying Shell Behavior, Prev: Bourne Shell Builtins, Up: Shell Builtin Commands | |
3652 | ||
3653 | 4.2 Bash Builtin Commands | |
3654 | ========================= | |
3655 | ||
3656 | This section describes builtin commands which are unique to or have been | |
3657 | extended in Bash. Some of these commands are specified in the POSIX | |
3658 | standard. | |
3659 | ||
3660 | 'alias' | |
3661 | alias [-p] [NAME[=VALUE] ...] | |
3662 | ||
3663 | Without arguments or with the '-p' option, 'alias' prints the list | |
3664 | of aliases on the standard output in a form that allows them to be | |
3665 | reused as input. If arguments are supplied, an alias is defined | |
3666 | for each NAME whose VALUE is given. If no VALUE is given, the name | |
3667 | and value of the alias is printed. Aliases are described in *note | |
3668 | Aliases::. | |
3669 | ||
3670 | 'bind' | |
3671 | bind [-m KEYMAP] [-lpsvPSVX] | |
3672 | bind [-m KEYMAP] [-q FUNCTION] [-u FUNCTION] [-r KEYSEQ] | |
3673 | bind [-m KEYMAP] -f FILENAME | |
3674 | bind [-m KEYMAP] -x KEYSEQ:SHELL-COMMAND | |
3675 | bind [-m KEYMAP] KEYSEQ:FUNCTION-NAME | |
3676 | bind [-m KEYMAP] KEYSEQ:READLINE-COMMAND | |
74091dd4 | 3677 | bind READLINE-COMMAND-LINE |
a0c0a00f CR |
3678 | |
3679 | Display current Readline (*note Command Line Editing::) key and | |
3680 | function bindings, bind a key sequence to a Readline function or | |
3681 | macro, or set a Readline variable. Each non-option argument is a | |
3682 | command as it would appear in a Readline initialization file (*note | |
3683 | Readline Init File::), but each binding or command must be passed | |
3684 | as a separate argument; e.g., '"\C-x\C-r":re-read-init-file'. | |
3685 | ||
3686 | Options, if supplied, have the following meanings: | |
3687 | ||
3688 | '-m KEYMAP' | |
3689 | Use KEYMAP as the keymap to be affected by the subsequent | |
3690 | bindings. Acceptable KEYMAP names are 'emacs', | |
3691 | 'emacs-standard', 'emacs-meta', 'emacs-ctlx', 'vi', 'vi-move', | |
3692 | 'vi-command', and 'vi-insert'. 'vi' is equivalent to | |
3693 | 'vi-command' ('vi-move' is also a synonym); 'emacs' is | |
3694 | equivalent to 'emacs-standard'. | |
3695 | ||
3696 | '-l' | |
3697 | List the names of all Readline functions. | |
3698 | ||
3699 | '-p' | |
3700 | Display Readline function names and bindings in such a way | |
3701 | that they can be used as input or in a Readline initialization | |
3702 | file. | |
3703 | ||
3704 | '-P' | |
3705 | List current Readline function names and bindings. | |
3706 | ||
3707 | '-v' | |
3708 | Display Readline variable names and values in such a way that | |
3709 | they can be used as input or in a Readline initialization | |
3710 | file. | |
3711 | ||
3712 | '-V' | |
3713 | List current Readline variable names and values. | |
3714 | ||
3715 | '-s' | |
3716 | Display Readline key sequences bound to macros and the strings | |
3717 | they output in such a way that they can be used as input or in | |
3718 | a Readline initialization file. | |
3719 | ||
3720 | '-S' | |
3721 | Display Readline key sequences bound to macros and the strings | |
3722 | they output. | |
3723 | ||
3724 | '-f FILENAME' | |
3725 | Read key bindings from FILENAME. | |
3726 | ||
3727 | '-q FUNCTION' | |
3728 | Query about which keys invoke the named FUNCTION. | |
3729 | ||
3730 | '-u FUNCTION' | |
3731 | Unbind all keys bound to the named FUNCTION. | |
3732 | ||
3733 | '-r KEYSEQ' | |
3734 | Remove any current binding for KEYSEQ. | |
3735 | ||
3736 | '-x KEYSEQ:SHELL-COMMAND' | |
3737 | Cause SHELL-COMMAND to be executed whenever KEYSEQ is entered. | |
3738 | When SHELL-COMMAND is executed, the shell sets the | |
3739 | 'READLINE_LINE' variable to the contents of the Readline line | |
8868edaf CR |
3740 | buffer and the 'READLINE_POINT' and 'READLINE_MARK' variables |
3741 | to the current location of the insertion point and the saved | |
74091dd4 CR |
3742 | insertion point (the MARK), respectively. The shell assigns |
3743 | any numeric argument the user supplied to the | |
3744 | 'READLINE_ARGUMENT' variable. If there was no argument, that | |
3745 | variable is not set. If the executed command changes the | |
3746 | value of any of 'READLINE_LINE', 'READLINE_POINT', or | |
3747 | 'READLINE_MARK', those new values will be reflected in the | |
3748 | editing state. | |
a0c0a00f CR |
3749 | |
3750 | '-X' | |
3751 | List all key sequences bound to shell commands and the | |
3752 | associated commands in a format that can be reused as input. | |
3753 | ||
3754 | The return status is zero unless an invalid option is supplied or | |
3755 | an error occurs. | |
3756 | ||
3757 | 'builtin' | |
3758 | builtin [SHELL-BUILTIN [ARGS]] | |
3759 | ||
3760 | Run a shell builtin, passing it ARGS, and return its exit status. | |
3761 | This is useful when defining a shell function with the same name as | |
3762 | a shell builtin, retaining the functionality of the builtin within | |
3763 | the function. The return status is non-zero if SHELL-BUILTIN is | |
3764 | not a shell builtin command. | |
3765 | ||
3766 | 'caller' | |
3767 | caller [EXPR] | |
3768 | ||
3769 | Returns the context of any active subroutine call (a shell function | |
3770 | or a script executed with the '.' or 'source' builtins). | |
3771 | ||
3772 | Without EXPR, 'caller' displays the line number and source filename | |
3773 | of the current subroutine call. If a non-negative integer is | |
3774 | supplied as EXPR, 'caller' displays the line number, subroutine | |
3775 | name, and source file corresponding to that position in the current | |
3776 | execution call stack. This extra information may be used, for | |
3777 | example, to print a stack trace. The current frame is frame 0. | |
3778 | ||
3779 | The return value is 0 unless the shell is not executing a | |
3780 | subroutine call or EXPR does not correspond to a valid position in | |
3781 | the call stack. | |
3782 | ||
3783 | 'command' | |
3784 | command [-pVv] COMMAND [ARGUMENTS ...] | |
3785 | ||
3786 | Runs COMMAND with ARGUMENTS ignoring any shell function named | |
3787 | COMMAND. Only shell builtin commands or commands found by | |
3788 | searching the 'PATH' are executed. If there is a shell function | |
3789 | named 'ls', running 'command ls' within the function will execute | |
3790 | the external command 'ls' instead of calling the function | |
3791 | recursively. The '-p' option means to use a default value for | |
3792 | 'PATH' that is guaranteed to find all of the standard utilities. | |
3793 | The return status in this case is 127 if COMMAND cannot be found or | |
3794 | an error occurred, and the exit status of COMMAND otherwise. | |
3795 | ||
3796 | If either the '-V' or '-v' option is supplied, a description of | |
3797 | COMMAND is printed. The '-v' option causes a single word | |
3798 | indicating the command or file name used to invoke COMMAND to be | |
3799 | displayed; the '-V' option produces a more verbose description. In | |
3800 | this case, the return status is zero if COMMAND is found, and | |
3801 | non-zero if not. | |
3802 | ||
3803 | 'declare' | |
8868edaf | 3804 | declare [-aAfFgiIlnrtux] [-p] [NAME[=VALUE] ...] |
a0c0a00f CR |
3805 | |
3806 | Declare variables and give them attributes. If no NAMEs are given, | |
3807 | then display the values of variables instead. | |
3808 | ||
3809 | The '-p' option will display the attributes and values of each | |
3810 | NAME. When '-p' is used with NAME arguments, additional options, | |
3811 | other than '-f' and '-F', are ignored. | |
3812 | ||
3813 | When '-p' is supplied without NAME arguments, 'declare' will | |
3814 | display the attributes and values of all variables having the | |
3815 | attributes specified by the additional options. If no other | |
3816 | options are supplied with '-p', 'declare' will display the | |
3817 | attributes and values of all shell variables. The '-f' option will | |
3818 | restrict the display to shell functions. | |
3819 | ||
3820 | The '-F' option inhibits the display of function definitions; only | |
3821 | the function name and attributes are printed. If the 'extdebug' | |
3822 | shell option is enabled using 'shopt' (*note The Shopt Builtin::), | |
3823 | the source file name and line number where each NAME is defined are | |
3824 | displayed as well. '-F' implies '-f'. | |
3825 | ||
3826 | The '-g' option forces variables to be created or modified at the | |
3827 | global scope, even when 'declare' is executed in a shell function. | |
3828 | It is ignored in all other cases. | |
3829 | ||
8868edaf | 3830 | The '-I' option causes local variables to inherit the attributes |
74091dd4 | 3831 | (except the 'nameref' attribute) and value of any existing variable |
8868edaf CR |
3832 | with the same NAME at a surrounding scope. If there is no existing |
3833 | variable, the local variable is initially unset. | |
3834 | ||
a0c0a00f CR |
3835 | The following options can be used to restrict output to variables |
3836 | with the specified attributes or to give variables attributes: | |
3837 | ||
3838 | '-a' | |
3839 | Each NAME is an indexed array variable (*note Arrays::). | |
3840 | ||
3841 | '-A' | |
3842 | Each NAME is an associative array variable (*note Arrays::). | |
3843 | ||
3844 | '-f' | |
3845 | Use function names only. | |
3846 | ||
3847 | '-i' | |
3848 | The variable is to be treated as an integer; arithmetic | |
3849 | evaluation (*note Shell Arithmetic::) is performed when the | |
3850 | variable is assigned a value. | |
3851 | ||
3852 | '-l' | |
3853 | When the variable is assigned a value, all upper-case | |
3854 | characters are converted to lower-case. The upper-case | |
3855 | attribute is disabled. | |
3856 | ||
3857 | '-n' | |
74091dd4 | 3858 | Give each NAME the 'nameref' attribute, making it a name |
a0c0a00f CR |
3859 | reference to another variable. That other variable is defined |
3860 | by the value of NAME. All references, assignments, and | |
3861 | attribute modifications to NAME, except for those using or | |
3862 | changing the '-n' attribute itself, are performed on the | |
3863 | variable referenced by NAME's value. The nameref attribute | |
3864 | cannot be applied to array variables. | |
3865 | ||
3866 | '-r' | |
3867 | Make NAMEs readonly. These names cannot then be assigned | |
3868 | values by subsequent assignment statements or unset. | |
3869 | ||
3870 | '-t' | |
3871 | Give each NAME the 'trace' attribute. Traced functions | |
3872 | inherit the 'DEBUG' and 'RETURN' traps from the calling shell. | |
3873 | The trace attribute has no special meaning for variables. | |
3874 | ||
3875 | '-u' | |
3876 | When the variable is assigned a value, all lower-case | |
3877 | characters are converted to upper-case. The lower-case | |
3878 | attribute is disabled. | |
3879 | ||
3880 | '-x' | |
3881 | Mark each NAME for export to subsequent commands via the | |
3882 | environment. | |
3883 | ||
3884 | Using '+' instead of '-' turns off the attribute instead, with the | |
d233b485 CR |
3885 | exceptions that '+a' and '+A' may not be used to destroy array |
3886 | variables and '+r' will not remove the readonly attribute. When | |
3887 | used in a function, 'declare' makes each NAME local, as with the | |
3888 | 'local' command, unless the '-g' option is used. If a variable | |
3889 | name is followed by =VALUE, the value of the variable is set to | |
3890 | VALUE. | |
a0c0a00f CR |
3891 | |
3892 | When using '-a' or '-A' and the compound assignment syntax to | |
3893 | create array variables, additional attributes do not take effect | |
3894 | until subsequent assignments. | |
3895 | ||
3896 | The return status is zero unless an invalid option is encountered, | |
3897 | an attempt is made to define a function using '-f foo=bar', an | |
3898 | attempt is made to assign a value to a readonly variable, an | |
3899 | attempt is made to assign a value to an array variable without | |
3900 | using the compound assignment syntax (*note Arrays::), one of the | |
74091dd4 | 3901 | NAMEs is not a valid shell variable name, an attempt is made to |
a0c0a00f CR |
3902 | turn off readonly status for a readonly variable, an attempt is |
3903 | made to turn off array status for an array variable, or an attempt | |
3904 | is made to display a non-existent function with '-f'. | |
3905 | ||
3906 | 'echo' | |
3907 | echo [-neE] [ARG ...] | |
3908 | ||
3909 | Output the ARGs, separated by spaces, terminated with a newline. | |
3910 | The return status is 0 unless a write error occurs. If '-n' is | |
3911 | specified, the trailing newline is suppressed. If the '-e' option | |
3912 | is given, interpretation of the following backslash-escaped | |
3913 | characters is enabled. The '-E' option disables the interpretation | |
3914 | of these escape characters, even on systems where they are | |
3915 | interpreted by default. The 'xpg_echo' shell option may be used to | |
3916 | dynamically determine whether or not 'echo' expands these escape | |
3917 | characters by default. 'echo' does not interpret '--' to mean the | |
3918 | end of options. | |
3919 | ||
3920 | 'echo' interprets the following escape sequences: | |
3921 | '\a' | |
3922 | alert (bell) | |
3923 | '\b' | |
3924 | backspace | |
3925 | '\c' | |
3926 | suppress further output | |
3927 | '\e' | |
3928 | '\E' | |
3929 | escape | |
3930 | '\f' | |
3931 | form feed | |
3932 | '\n' | |
3933 | new line | |
3934 | '\r' | |
3935 | carriage return | |
3936 | '\t' | |
3937 | horizontal tab | |
3938 | '\v' | |
3939 | vertical tab | |
3940 | '\\' | |
3941 | backslash | |
3942 | '\0NNN' | |
3943 | the eight-bit character whose value is the octal value NNN | |
3944 | (zero to three octal digits) | |
3945 | '\xHH' | |
3946 | the eight-bit character whose value is the hexadecimal value | |
3947 | HH (one or two hex digits) | |
3948 | '\uHHHH' | |
3949 | the Unicode (ISO/IEC 10646) character whose value is the | |
3950 | hexadecimal value HHHH (one to four hex digits) | |
3951 | '\UHHHHHHHH' | |
3952 | the Unicode (ISO/IEC 10646) character whose value is the | |
3953 | hexadecimal value HHHHHHHH (one to eight hex digits) | |
3954 | ||
3955 | 'enable' | |
3956 | enable [-a] [-dnps] [-f FILENAME] [NAME ...] | |
3957 | ||
3958 | Enable and disable builtin shell commands. Disabling a builtin | |
3959 | allows a disk command which has the same name as a shell builtin to | |
3960 | be executed without specifying a full pathname, even though the | |
3961 | shell normally searches for builtins before disk commands. If '-n' | |
3962 | is used, the NAMEs become disabled. Otherwise NAMEs are enabled. | |
3963 | For example, to use the 'test' binary found via '$PATH' instead of | |
3964 | the shell builtin version, type 'enable -n test'. | |
3965 | ||
3966 | If the '-p' option is supplied, or no NAME arguments appear, a list | |
3967 | of shell builtins is printed. With no other arguments, the list | |
3968 | consists of all enabled shell builtins. The '-a' option means to | |
3969 | list each builtin with an indication of whether or not it is | |
3970 | enabled. | |
3971 | ||
3972 | The '-f' option means to load the new builtin command NAME from | |
3973 | shared object FILENAME, on systems that support dynamic loading. | |
74091dd4 CR |
3974 | Bash will use the value of the 'BASH_LOADABLES_PATH' variable as a |
3975 | colon-separated list of directories in which to search for | |
3976 | FILENAME. The default is system-dependent. The '-d' option will | |
3977 | delete a builtin loaded with '-f'. | |
a0c0a00f CR |
3978 | |
3979 | If there are no options, a list of the shell builtins is displayed. | |
3980 | The '-s' option restricts 'enable' to the POSIX special builtins. | |
3981 | If '-s' is used with '-f', the new builtin becomes a special | |
3982 | builtin (*note Special Builtins::). | |
3983 | ||
74091dd4 CR |
3984 | If no options are supplied and a NAME is not a shell builtin, |
3985 | 'enable' will attempt to load NAME from a shared object named NAME, | |
3986 | as if the command were 'enable -f NAME NAME'. | |
3987 | ||
a0c0a00f CR |
3988 | The return status is zero unless a NAME is not a shell builtin or |
3989 | there is an error loading a new builtin from a shared object. | |
3990 | ||
3991 | 'help' | |
3992 | help [-dms] [PATTERN] | |
3993 | ||
3994 | Display helpful information about builtin commands. If PATTERN is | |
3995 | specified, 'help' gives detailed help on all commands matching | |
3996 | PATTERN, otherwise a list of the builtins is printed. | |
3997 | ||
3998 | Options, if supplied, have the following meanings: | |
3999 | ||
4000 | '-d' | |
4001 | Display a short description of each PATTERN | |
4002 | '-m' | |
4003 | Display the description of each PATTERN in a manpage-like | |
4004 | format | |
4005 | '-s' | |
4006 | Display only a short usage synopsis for each PATTERN | |
4007 | ||
4008 | The return status is zero unless no command matches PATTERN. | |
4009 | ||
4010 | 'let' | |
4011 | let EXPRESSION [EXPRESSION ...] | |
4012 | ||
4013 | The 'let' builtin allows arithmetic to be performed on shell | |
4014 | variables. Each EXPRESSION is evaluated according to the rules | |
4015 | given below in *note Shell Arithmetic::. If the last EXPRESSION | |
4016 | evaluates to 0, 'let' returns 1; otherwise 0 is returned. | |
4017 | ||
4018 | 'local' | |
4019 | local [OPTION] NAME[=VALUE] ... | |
4020 | ||
4021 | For each argument, a local variable named NAME is created, and | |
4022 | assigned VALUE. The OPTION can be any of the options accepted by | |
4023 | 'declare'. 'local' can only be used within a function; it makes | |
4024 | the variable NAME have a visible scope restricted to that function | |
4025 | and its children. If NAME is '-', the set of shell options is made | |
4026 | local to the function in which 'local' is invoked: shell options | |
4027 | changed using the 'set' builtin inside the function are restored to | |
8868edaf CR |
4028 | their original values when the function returns. The restore is |
4029 | effected as if a series of 'set' commands were executed to restore | |
4030 | the values that were in place before the function. The return | |
4031 | status is zero unless 'local' is used outside a function, an | |
4032 | invalid NAME is supplied, or NAME is a readonly variable. | |
a0c0a00f CR |
4033 | |
4034 | 'logout' | |
4035 | logout [N] | |
4036 | ||
4037 | Exit a login shell, returning a status of N to the shell's parent. | |
4038 | ||
4039 | 'mapfile' | |
d233b485 CR |
4040 | mapfile [-d DELIM] [-n COUNT] [-O ORIGIN] [-s COUNT] |
4041 | [-t] [-u FD] [-C CALLBACK] [-c QUANTUM] [ARRAY] | |
a0c0a00f CR |
4042 | |
4043 | Read lines from the standard input into the indexed array variable | |
4044 | ARRAY, or from file descriptor FD if the '-u' option is supplied. | |
4045 | The variable 'MAPFILE' is the default ARRAY. Options, if supplied, | |
4046 | have the following meanings: | |
4047 | ||
4048 | '-d' | |
4049 | The first character of DELIM is used to terminate each input | |
d233b485 CR |
4050 | line, rather than newline. If DELIM is the empty string, |
4051 | 'mapfile' will terminate a line when it reads a NUL character. | |
a0c0a00f CR |
4052 | '-n' |
4053 | Copy at most COUNT lines. If COUNT is 0, all lines are | |
4054 | copied. | |
4055 | '-O' | |
4056 | Begin assigning to ARRAY at index ORIGIN. The default index | |
4057 | is 0. | |
4058 | '-s' | |
4059 | Discard the first COUNT lines read. | |
4060 | '-t' | |
4061 | Remove a trailing DELIM (default newline) from each line read. | |
4062 | '-u' | |
4063 | Read lines from file descriptor FD instead of the standard | |
4064 | input. | |
4065 | '-C' | |
d233b485 | 4066 | Evaluate CALLBACK each time QUANTUM lines are read. The '-c' |
a0c0a00f CR |
4067 | option specifies QUANTUM. |
4068 | '-c' | |
4069 | Specify the number of lines read between each call to | |
4070 | CALLBACK. | |
4071 | ||
4072 | If '-C' is specified without '-c', the default quantum is 5000. | |
4073 | When CALLBACK is evaluated, it is supplied the index of the next | |
4074 | array element to be assigned and the line to be assigned to that | |
4075 | element as additional arguments. CALLBACK is evaluated after the | |
4076 | line is read but before the array element is assigned. | |
4077 | ||
4078 | If not supplied with an explicit origin, 'mapfile' will clear ARRAY | |
4079 | before assigning to it. | |
4080 | ||
4081 | 'mapfile' returns successfully unless an invalid option or option | |
4082 | argument is supplied, ARRAY is invalid or unassignable, or ARRAY is | |
4083 | not an indexed array. | |
4084 | ||
4085 | 'printf' | |
4086 | printf [-v VAR] FORMAT [ARGUMENTS] | |
4087 | ||
4088 | Write the formatted ARGUMENTS to the standard output under the | |
4089 | control of the FORMAT. The '-v' option causes the output to be | |
4090 | assigned to the variable VAR rather than being printed to the | |
4091 | standard output. | |
4092 | ||
4093 | The FORMAT is a character string which contains three types of | |
4094 | objects: plain characters, which are simply copied to standard | |
4095 | output, character escape sequences, which are converted and copied | |
4096 | to the standard output, and format specifications, each of which | |
4097 | causes printing of the next successive ARGUMENT. In addition to | |
4098 | the standard 'printf(1)' formats, 'printf' interprets the following | |
4099 | extensions: | |
4100 | ||
4101 | '%b' | |
4102 | Causes 'printf' to expand backslash escape sequences in the | |
4103 | corresponding ARGUMENT in the same way as 'echo -e' (*note | |
4104 | Bash Builtins::). | |
4105 | '%q' | |
4106 | Causes 'printf' to output the corresponding ARGUMENT in a | |
4107 | format that can be reused as shell input. | |
74091dd4 CR |
4108 | '%Q' |
4109 | like '%q', but applies any supplied precision to the ARGUMENT | |
4110 | before quoting it. | |
a0c0a00f CR |
4111 | '%(DATEFMT)T' |
4112 | Causes 'printf' to output the date-time string resulting from | |
4113 | using DATEFMT as a format string for 'strftime'(3). The | |
4114 | corresponding ARGUMENT is an integer representing the number | |
4115 | of seconds since the epoch. Two special argument values may | |
4116 | be used: -1 represents the current time, and -2 represents the | |
4117 | time the shell was invoked. If no argument is specified, | |
4118 | conversion behaves as if -1 had been given. This is an | |
4119 | exception to the usual 'printf' behavior. | |
4120 | ||
8868edaf CR |
4121 | The %b, %q, and %T directives all use the field width and precision |
4122 | arguments from the format specification and write that many bytes | |
4123 | from (or use that wide a field for) the expanded argument, which | |
4124 | usually contains more characters than the original. | |
4125 | ||
a0c0a00f CR |
4126 | Arguments to non-string format specifiers are treated as C language |
4127 | constants, except that a leading plus or minus sign is allowed, and | |
4128 | if the leading character is a single or double quote, the value is | |
4129 | the ASCII value of the following character. | |
4130 | ||
4131 | The FORMAT is reused as necessary to consume all of the ARGUMENTS. | |
4132 | If the FORMAT requires more ARGUMENTS than are supplied, the extra | |
4133 | format specifications behave as if a zero value or null string, as | |
4134 | appropriate, had been supplied. The return value is zero on | |
4135 | success, non-zero on failure. | |
4136 | ||
4137 | 'read' | |
4138 | read [-ers] [-a ANAME] [-d DELIM] [-i TEXT] [-n NCHARS] | |
4139 | [-N NCHARS] [-p PROMPT] [-t TIMEOUT] [-u FD] [NAME ...] | |
4140 | ||
4141 | One line is read from the standard input, or from the file | |
4142 | descriptor FD supplied as an argument to the '-u' option, split | |
4143 | into words as described above in *note Word Splitting::, and the | |
4144 | first word is assigned to the first NAME, the second word to the | |
4145 | second NAME, and so on. If there are more words than names, the | |
4146 | remaining words and their intervening delimiters are assigned to | |
4147 | the last NAME. If there are fewer words read from the input stream | |
4148 | than names, the remaining names are assigned empty values. The | |
4149 | characters in the value of the 'IFS' variable are used to split the | |
4150 | line into words using the same rules the shell uses for expansion | |
4151 | (described above in *note Word Splitting::). The backslash | |
4152 | character '\' may be used to remove any special meaning for the | |
8868edaf | 4153 | next character read and for line continuation. |
a0c0a00f CR |
4154 | |
4155 | Options, if supplied, have the following meanings: | |
4156 | ||
4157 | '-a ANAME' | |
4158 | The words are assigned to sequential indices of the array | |
4159 | variable ANAME, starting at 0. All elements are removed from | |
4160 | ANAME before the assignment. Other NAME arguments are | |
4161 | ignored. | |
4162 | ||
4163 | '-d DELIM' | |
4164 | The first character of DELIM is used to terminate the input | |
d233b485 CR |
4165 | line, rather than newline. If DELIM is the empty string, |
4166 | 'read' will terminate a line when it reads a NUL character. | |
a0c0a00f CR |
4167 | |
4168 | '-e' | |
4169 | Readline (*note Command Line Editing::) is used to obtain the | |
4170 | line. Readline uses the current (or default, if line editing | |
d233b485 CR |
4171 | was not previously active) editing settings, but uses |
4172 | Readline's default filename completion. | |
a0c0a00f CR |
4173 | |
4174 | '-i TEXT' | |
4175 | If Readline is being used to read the line, TEXT is placed | |
4176 | into the editing buffer before editing begins. | |
4177 | ||
4178 | '-n NCHARS' | |
4179 | 'read' returns after reading NCHARS characters rather than | |
4180 | waiting for a complete line of input, but honors a delimiter | |
4181 | if fewer than NCHARS characters are read before the delimiter. | |
4182 | ||
4183 | '-N NCHARS' | |
4184 | 'read' returns after reading exactly NCHARS characters rather | |
4185 | than waiting for a complete line of input, unless EOF is | |
4186 | encountered or 'read' times out. Delimiter characters | |
4187 | encountered in the input are not treated specially and do not | |
4188 | cause 'read' to return until NCHARS characters are read. The | |
4189 | result is not split on the characters in 'IFS'; the intent is | |
4190 | that the variable is assigned exactly the characters read | |
4191 | (with the exception of backslash; see the '-r' option below). | |
4192 | ||
4193 | '-p PROMPT' | |
4194 | Display PROMPT, without a trailing newline, before attempting | |
4195 | to read any input. The prompt is displayed only if input is | |
4196 | coming from a terminal. | |
4197 | ||
4198 | '-r' | |
4199 | If this option is given, backslash does not act as an escape | |
4200 | character. The backslash is considered to be part of the | |
d233b485 CR |
4201 | line. In particular, a backslash-newline pair may not then be |
4202 | used as a line continuation. | |
a0c0a00f CR |
4203 | |
4204 | '-s' | |
4205 | Silent mode. If input is coming from a terminal, characters | |
4206 | are not echoed. | |
4207 | ||
4208 | '-t TIMEOUT' | |
4209 | Cause 'read' to time out and return failure if a complete line | |
4210 | of input (or a specified number of characters) is not read | |
4211 | within TIMEOUT seconds. TIMEOUT may be a decimal number with | |
4212 | a fractional portion following the decimal point. This option | |
4213 | is only effective if 'read' is reading input from a terminal, | |
4214 | pipe, or other special file; it has no effect when reading | |
4215 | from regular files. If 'read' times out, 'read' saves any | |
4216 | partial input read into the specified variable NAME. If | |
4217 | TIMEOUT is 0, 'read' returns immediately, without trying to | |
8868edaf | 4218 | read any data. The exit status is 0 if input is available on |
74091dd4 CR |
4219 | the specified file descriptor, or the read will return EOF, |
4220 | non-zero otherwise. The exit status is greater than 128 if | |
4221 | the timeout is exceeded. | |
a0c0a00f CR |
4222 | |
4223 | '-u FD' | |
4224 | Read input from file descriptor FD. | |
4225 | ||
8868edaf CR |
4226 | If no NAMEs are supplied, the line read, without the ending |
4227 | delimiter but otherwise unmodified, is assigned to the variable | |
4228 | 'REPLY'. The exit status is zero, unless end-of-file is | |
4229 | encountered, 'read' times out (in which case the status is greater | |
4230 | than 128), a variable assignment error (such as assigning to a | |
4231 | readonly variable) occurs, or an invalid file descriptor is | |
4232 | supplied as the argument to '-u'. | |
4233 | ||
a0c0a00f | 4234 | 'readarray' |
d233b485 CR |
4235 | readarray [-d DELIM] [-n COUNT] [-O ORIGIN] [-s COUNT] |
4236 | [-t] [-u FD] [-C CALLBACK] [-c QUANTUM] [ARRAY] | |
a0c0a00f CR |
4237 | |
4238 | Read lines from the standard input into the indexed array variable | |
4239 | ARRAY, or from file descriptor FD if the '-u' option is supplied. | |
4240 | ||
4241 | A synonym for 'mapfile'. | |
4242 | ||
4243 | 'source' | |
4244 | source FILENAME | |
4245 | ||
4246 | A synonym for '.' (*note Bourne Shell Builtins::). | |
4247 | ||
4248 | 'type' | |
4249 | type [-afptP] [NAME ...] | |
4250 | ||
4251 | For each NAME, indicate how it would be interpreted if used as a | |
4252 | command name. | |
4253 | ||
4254 | If the '-t' option is used, 'type' prints a single word which is | |
4255 | one of 'alias', 'function', 'builtin', 'file' or 'keyword', if NAME | |
4256 | is an alias, shell function, shell builtin, disk file, or shell | |
4257 | reserved word, respectively. If the NAME is not found, then | |
4258 | nothing is printed, and 'type' returns a failure status. | |
4259 | ||
4260 | If the '-p' option is used, 'type' either returns the name of the | |
4261 | disk file that would be executed, or nothing if '-t' would not | |
4262 | return 'file'. | |
4263 | ||
4264 | The '-P' option forces a path search for each NAME, even if '-t' | |
4265 | would not return 'file'. | |
4266 | ||
4267 | If a command is hashed, '-p' and '-P' print the hashed value, which | |
4268 | is not necessarily the file that appears first in '$PATH'. | |
4269 | ||
4270 | If the '-a' option is used, 'type' returns all of the places that | |
4271 | contain an executable named FILE. This includes aliases and | |
4272 | functions, if and only if the '-p' option is not also used. | |
4273 | ||
4274 | If the '-f' option is used, 'type' does not attempt to find shell | |
4275 | functions, as with the 'command' builtin. | |
4276 | ||
74091dd4 | 4277 | The return status is zero if all of the NAMEs are found, non-zero |
a0c0a00f CR |
4278 | if any are not found. |
4279 | ||
4280 | 'typeset' | |
4281 | typeset [-afFgrxilnrtux] [-p] [NAME[=VALUE] ...] | |
4282 | ||
4283 | The 'typeset' command is supplied for compatibility with the Korn | |
4284 | shell. It is a synonym for the 'declare' builtin command. | |
4285 | ||
4286 | 'ulimit' | |
8868edaf CR |
4287 | ulimit [-HS] -a |
4288 | ulimit [-HS] [-bcdefiklmnpqrstuvxPRT] [LIMIT] | |
a0c0a00f CR |
4289 | |
4290 | 'ulimit' provides control over the resources available to processes | |
4291 | started by the shell, on systems that allow such control. If an | |
4292 | option is given, it is interpreted as follows: | |
4293 | ||
4294 | '-S' | |
4295 | Change and report the soft limit associated with a resource. | |
4296 | ||
4297 | '-H' | |
4298 | Change and report the hard limit associated with a resource. | |
4299 | ||
4300 | '-a' | |
8868edaf | 4301 | All current limits are reported; no limits are set. |
a0c0a00f CR |
4302 | |
4303 | '-b' | |
4304 | The maximum socket buffer size. | |
4305 | ||
4306 | '-c' | |
4307 | The maximum size of core files created. | |
4308 | ||
4309 | '-d' | |
4310 | The maximum size of a process's data segment. | |
4311 | ||
4312 | '-e' | |
4313 | The maximum scheduling priority ("nice"). | |
4314 | ||
4315 | '-f' | |
4316 | The maximum size of files written by the shell and its | |
4317 | children. | |
4318 | ||
4319 | '-i' | |
4320 | The maximum number of pending signals. | |
4321 | ||
4322 | '-k' | |
4323 | The maximum number of kqueues that may be allocated. | |
4324 | ||
4325 | '-l' | |
4326 | The maximum size that may be locked into memory. | |
4327 | ||
4328 | '-m' | |
4329 | The maximum resident set size (many systems do not honor this | |
4330 | limit). | |
4331 | ||
4332 | '-n' | |
4333 | The maximum number of open file descriptors (most systems do | |
4334 | not allow this value to be set). | |
4335 | ||
4336 | '-p' | |
4337 | The pipe buffer size. | |
4338 | ||
4339 | '-q' | |
4340 | The maximum number of bytes in POSIX message queues. | |
4341 | ||
4342 | '-r' | |
4343 | The maximum real-time scheduling priority. | |
4344 | ||
4345 | '-s' | |
4346 | The maximum stack size. | |
4347 | ||
4348 | '-t' | |
4349 | The maximum amount of cpu time in seconds. | |
4350 | ||
4351 | '-u' | |
4352 | The maximum number of processes available to a single user. | |
4353 | ||
4354 | '-v' | |
4355 | The maximum amount of virtual memory available to the shell, | |
4356 | and, on some systems, to its children. | |
4357 | ||
4358 | '-x' | |
4359 | The maximum number of file locks. | |
4360 | ||
4361 | '-P' | |
4362 | The maximum number of pseudoterminals. | |
4363 | ||
8868edaf CR |
4364 | '-R' |
4365 | The maximum time a real-time process can run before blocking, | |
4366 | in microseconds. | |
4367 | ||
a0c0a00f CR |
4368 | '-T' |
4369 | The maximum number of threads. | |
4370 | ||
4371 | If LIMIT is given, and the '-a' option is not used, LIMIT is the | |
4372 | new value of the specified resource. The special LIMIT values | |
4373 | 'hard', 'soft', and 'unlimited' stand for the current hard limit, | |
4374 | the current soft limit, and no limit, respectively. A hard limit | |
4375 | cannot be increased by a non-root user once it is set; a soft limit | |
4376 | may be increased up to the value of the hard limit. Otherwise, the | |
4377 | current value of the soft limit for the specified resource is | |
8868edaf CR |
4378 | printed, unless the '-H' option is supplied. When more than one |
4379 | resource is specified, the limit name and unit, if appropriate, are | |
4380 | printed before the value. When setting new limits, if neither '-H' | |
4381 | nor '-S' is supplied, both the hard and soft limits are set. If no | |
4382 | option is given, then '-f' is assumed. Values are in 1024-byte | |
4383 | increments, except for '-t', which is in seconds; '-R', which is in | |
4384 | microseconds; '-p', which is in units of 512-byte blocks; '-P', | |
4385 | '-T', '-b', '-k', '-n' and '-u', which are unscaled values; and, | |
4386 | when in POSIX Mode (*note Bash POSIX Mode::), '-c' and '-f', which | |
4387 | are in 512-byte increments. | |
a0c0a00f CR |
4388 | |
4389 | The return status is zero unless an invalid option or argument is | |
4390 | supplied, or an error occurs while setting a new limit. | |
4391 | ||
4392 | 'unalias' | |
4393 | unalias [-a] [NAME ... ] | |
4394 | ||
4395 | Remove each NAME from the list of aliases. If '-a' is supplied, | |
4396 | all aliases are removed. Aliases are described in *note Aliases::. | |
4397 | ||
4398 | \1f | |
4399 | File: bash.info, Node: Modifying Shell Behavior, Next: Special Builtins, Prev: Bash Builtins, Up: Shell Builtin Commands | |
4400 | ||
4401 | 4.3 Modifying Shell Behavior | |
4402 | ============================ | |
4403 | ||
4404 | * Menu: | |
4405 | ||
4406 | * The Set Builtin:: Change the values of shell attributes and | |
4407 | positional parameters. | |
4408 | * The Shopt Builtin:: Modify shell optional behavior. | |
4409 | ||
4410 | \1f | |
4411 | File: bash.info, Node: The Set Builtin, Next: The Shopt Builtin, Up: Modifying Shell Behavior | |
4412 | ||
4413 | 4.3.1 The Set Builtin | |
4414 | --------------------- | |
4415 | ||
4416 | This builtin is so complicated that it deserves its own section. 'set' | |
4417 | allows you to change the values of shell options and set the positional | |
4418 | parameters, or to display the names and values of shell variables. | |
4419 | ||
4420 | 'set' | |
74091dd4 CR |
4421 | set [-abefhkmnptuvxBCEHPT] [-o OPTION-NAME] [--] [-] [ARGUMENT ...] |
4422 | set [+abefhkmnptuvxBCEHPT] [+o OPTION-NAME] [--] [-] [ARGUMENT ...] | |
a0c0a00f CR |
4423 | |
4424 | If no options or arguments are supplied, 'set' displays the names | |
4425 | and values of all shell variables and functions, sorted according | |
4426 | to the current locale, in a format that may be reused as input for | |
4427 | setting or resetting the currently-set variables. Read-only | |
4428 | variables cannot be reset. In POSIX mode, only shell variables are | |
4429 | listed. | |
4430 | ||
4431 | When options are supplied, they set or unset shell attributes. | |
4432 | Options, if specified, have the following meanings: | |
4433 | ||
4434 | '-a' | |
4435 | Each variable or function that is created or modified is given | |
4436 | the export attribute and marked for export to the environment | |
4437 | of subsequent commands. | |
4438 | ||
4439 | '-b' | |
4440 | Cause the status of terminated background jobs to be reported | |
4441 | immediately, rather than before printing the next primary | |
4442 | prompt. | |
4443 | ||
4444 | '-e' | |
4445 | Exit immediately if a pipeline (*note Pipelines::), which may | |
4446 | consist of a single simple command (*note Simple Commands::), | |
4447 | a list (*note Lists::), or a compound command (*note Compound | |
4448 | Commands::) returns a non-zero status. The shell does not | |
4449 | exit if the command that fails is part of the command list | |
4450 | immediately following a 'while' or 'until' keyword, part of | |
4451 | the test in an 'if' statement, part of any command executed in | |
4452 | a '&&' or '||' list except the command following the final | |
4453 | '&&' or '||', any command in a pipeline but the last, or if | |
4454 | the command's return status is being inverted with '!'. If a | |
4455 | compound command other than a subshell returns a non-zero | |
4456 | status because a command failed while '-e' was being ignored, | |
4457 | the shell does not exit. A trap on 'ERR', if set, is executed | |
4458 | before the shell exits. | |
4459 | ||
4460 | This option applies to the shell environment and each subshell | |
4461 | environment separately (*note Command Execution | |
4462 | Environment::), and may cause subshells to exit before | |
4463 | executing all the commands in the subshell. | |
4464 | ||
4465 | If a compound command or shell function executes in a context | |
4466 | where '-e' is being ignored, none of the commands executed | |
4467 | within the compound command or function body will be affected | |
4468 | by the '-e' setting, even if '-e' is set and a command returns | |
4469 | a failure status. If a compound command or shell function | |
4470 | sets '-e' while executing in a context where '-e' is ignored, | |
4471 | that setting will not have any effect until the compound | |
4472 | command or the command containing the function call completes. | |
4473 | ||
4474 | '-f' | |
4475 | Disable filename expansion (globbing). | |
4476 | ||
4477 | '-h' | |
4478 | Locate and remember (hash) commands as they are looked up for | |
4479 | execution. This option is enabled by default. | |
4480 | ||
4481 | '-k' | |
4482 | All arguments in the form of assignment statements are placed | |
4483 | in the environment for a command, not just those that precede | |
4484 | the command name. | |
4485 | ||
4486 | '-m' | |
4487 | Job control is enabled (*note Job Control::). All processes | |
4488 | run in a separate process group. When a background job | |
4489 | completes, the shell prints a line containing its exit status. | |
4490 | ||
4491 | '-n' | |
4492 | Read commands but do not execute them. This may be used to | |
4493 | check a script for syntax errors. This option is ignored by | |
4494 | interactive shells. | |
4495 | ||
4496 | '-o OPTION-NAME' | |
4497 | ||
4498 | Set the option corresponding to OPTION-NAME: | |
4499 | ||
4500 | 'allexport' | |
4501 | Same as '-a'. | |
4502 | ||
4503 | 'braceexpand' | |
4504 | Same as '-B'. | |
4505 | ||
4506 | 'emacs' | |
4507 | Use an 'emacs'-style line editing interface (*note | |
4508 | Command Line Editing::). This also affects the editing | |
4509 | interface used for 'read -e'. | |
4510 | ||
4511 | 'errexit' | |
4512 | Same as '-e'. | |
4513 | ||
4514 | 'errtrace' | |
4515 | Same as '-E'. | |
4516 | ||
4517 | 'functrace' | |
4518 | Same as '-T'. | |
4519 | ||
4520 | 'hashall' | |
4521 | Same as '-h'. | |
4522 | ||
4523 | 'histexpand' | |
4524 | Same as '-H'. | |
4525 | ||
4526 | 'history' | |
4527 | Enable command history, as described in *note Bash | |
4528 | History Facilities::. This option is on by default in | |
4529 | interactive shells. | |
4530 | ||
4531 | 'ignoreeof' | |
4532 | An interactive shell will not exit upon reading EOF. | |
4533 | ||
4534 | 'keyword' | |
4535 | Same as '-k'. | |
4536 | ||
4537 | 'monitor' | |
4538 | Same as '-m'. | |
4539 | ||
4540 | 'noclobber' | |
4541 | Same as '-C'. | |
4542 | ||
4543 | 'noexec' | |
4544 | Same as '-n'. | |
4545 | ||
4546 | 'noglob' | |
4547 | Same as '-f'. | |
4548 | ||
4549 | 'nolog' | |
4550 | Currently ignored. | |
4551 | ||
4552 | 'notify' | |
4553 | Same as '-b'. | |
4554 | ||
4555 | 'nounset' | |
4556 | Same as '-u'. | |
4557 | ||
4558 | 'onecmd' | |
4559 | Same as '-t'. | |
4560 | ||
4561 | 'physical' | |
4562 | Same as '-P'. | |
4563 | ||
4564 | 'pipefail' | |
4565 | If set, the return value of a pipeline is the value of | |
4566 | the last (rightmost) command to exit with a non-zero | |
4567 | status, or zero if all commands in the pipeline exit | |
4568 | successfully. This option is disabled by default. | |
4569 | ||
4570 | 'posix' | |
4571 | Change the behavior of Bash where the default operation | |
4572 | differs from the POSIX standard to match the standard | |
4573 | (*note Bash POSIX Mode::). This is intended to make Bash | |
4574 | behave as a strict superset of that standard. | |
4575 | ||
4576 | 'privileged' | |
4577 | Same as '-p'. | |
4578 | ||
4579 | 'verbose' | |
4580 | Same as '-v'. | |
4581 | ||
4582 | 'vi' | |
4583 | Use a 'vi'-style line editing interface. This also | |
4584 | affects the editing interface used for 'read -e'. | |
4585 | ||
4586 | 'xtrace' | |
4587 | Same as '-x'. | |
4588 | ||
4589 | '-p' | |
4590 | Turn on privileged mode. In this mode, the '$BASH_ENV' and | |
4591 | '$ENV' files are not processed, shell functions are not | |
4592 | inherited from the environment, and the 'SHELLOPTS', | |
4593 | 'BASHOPTS', 'CDPATH' and 'GLOBIGNORE' variables, if they | |
4594 | appear in the environment, are ignored. If the shell is | |
4595 | started with the effective user (group) id not equal to the | |
4596 | real user (group) id, and the '-p' option is not supplied, | |
4597 | these actions are taken and the effective user id is set to | |
4598 | the real user id. If the '-p' option is supplied at startup, | |
4599 | the effective user id is not reset. Turning this option off | |
4600 | causes the effective user and group ids to be set to the real | |
4601 | user and group ids. | |
4602 | ||
74091dd4 CR |
4603 | '-r' |
4604 | Enable restricted shell mode. This option cannot be unset | |
4605 | once it has been set. | |
4606 | ||
a0c0a00f CR |
4607 | '-t' |
4608 | Exit after reading and executing one command. | |
4609 | ||
4610 | '-u' | |
4611 | Treat unset variables and parameters other than the special | |
74091dd4 CR |
4612 | parameters '@' or '*', or array variables subscripted with '@' |
4613 | or '*', as an error when performing parameter expansion. An | |
4614 | error message will be written to the standard error, and a | |
4615 | non-interactive shell will exit. | |
a0c0a00f CR |
4616 | |
4617 | '-v' | |
4618 | Print shell input lines as they are read. | |
4619 | ||
4620 | '-x' | |
4621 | Print a trace of simple commands, 'for' commands, 'case' | |
4622 | commands, 'select' commands, and arithmetic 'for' commands and | |
4623 | their arguments or associated word lists after they are | |
4624 | expanded and before they are executed. The value of the 'PS4' | |
4625 | variable is expanded and the resultant value is printed before | |
4626 | the command and its expanded arguments. | |
4627 | ||
4628 | '-B' | |
4629 | The shell will perform brace expansion (*note Brace | |
4630 | Expansion::). This option is on by default. | |
4631 | ||
4632 | '-C' | |
4633 | Prevent output redirection using '>', '>&', and '<>' from | |
4634 | overwriting existing files. | |
4635 | ||
4636 | '-E' | |
4637 | If set, any trap on 'ERR' is inherited by shell functions, | |
4638 | command substitutions, and commands executed in a subshell | |
4639 | environment. The 'ERR' trap is normally not inherited in such | |
4640 | cases. | |
4641 | ||
4642 | '-H' | |
4643 | Enable '!' style history substitution (*note History | |
4644 | Interaction::). This option is on by default for interactive | |
4645 | shells. | |
4646 | ||
4647 | '-P' | |
4648 | If set, do not resolve symbolic links when performing commands | |
4649 | such as 'cd' which change the current directory. The physical | |
4650 | directory is used instead. By default, Bash follows the | |
4651 | logical chain of directories when performing commands which | |
4652 | change the current directory. | |
4653 | ||
4654 | For example, if '/usr/sys' is a symbolic link to | |
4655 | '/usr/local/sys' then: | |
4656 | $ cd /usr/sys; echo $PWD | |
4657 | /usr/sys | |
4658 | $ cd ..; pwd | |
4659 | /usr | |
4660 | ||
4661 | If 'set -P' is on, then: | |
4662 | $ cd /usr/sys; echo $PWD | |
4663 | /usr/local/sys | |
4664 | $ cd ..; pwd | |
4665 | /usr/local | |
4666 | ||
4667 | '-T' | |
4668 | If set, any trap on 'DEBUG' and 'RETURN' are inherited by | |
4669 | shell functions, command substitutions, and commands executed | |
4670 | in a subshell environment. The 'DEBUG' and 'RETURN' traps are | |
4671 | normally not inherited in such cases. | |
4672 | ||
4673 | '--' | |
4674 | If no arguments follow this option, then the positional | |
4675 | parameters are unset. Otherwise, the positional parameters | |
4676 | are set to the ARGUMENTS, even if some of them begin with a | |
4677 | '-'. | |
4678 | ||
4679 | '-' | |
4680 | Signal the end of options, cause all remaining ARGUMENTS to be | |
4681 | assigned to the positional parameters. The '-x' and '-v' | |
4682 | options are turned off. If there are no arguments, the | |
4683 | positional parameters remain unchanged. | |
4684 | ||
4685 | Using '+' rather than '-' causes these options to be turned off. | |
4686 | The options can also be used upon invocation of the shell. The | |
4687 | current set of options may be found in '$-'. | |
4688 | ||
4689 | The remaining N ARGUMENTS are positional parameters and are | |
4690 | assigned, in order, to '$1', '$2', ... '$N'. The special parameter | |
4691 | '#' is set to N. | |
4692 | ||
4693 | The return status is always zero unless an invalid option is | |
4694 | supplied. | |
4695 | ||
4696 | \1f | |
4697 | File: bash.info, Node: The Shopt Builtin, Prev: The Set Builtin, Up: Modifying Shell Behavior | |
4698 | ||
4699 | 4.3.2 The Shopt Builtin | |
4700 | ----------------------- | |
4701 | ||
4702 | This builtin allows you to change additional shell optional behavior. | |
4703 | ||
4704 | 'shopt' | |
4705 | shopt [-pqsu] [-o] [OPTNAME ...] | |
4706 | ||
4707 | Toggle the values of settings controlling optional shell behavior. | |
4708 | The settings can be either those listed below, or, if the '-o' | |
4709 | option is used, those available with the '-o' option to the 'set' | |
4710 | builtin command (*note The Set Builtin::). With no options, or | |
4711 | with the '-p' option, a list of all settable options is displayed, | |
74091dd4 | 4712 | with an indication of whether or not each is set; if OPTNAMEs are |
d233b485 CR |
4713 | supplied, the output is restricted to those options. The '-p' |
4714 | option causes output to be displayed in a form that may be reused | |
4715 | as input. Other options have the following meanings: | |
a0c0a00f CR |
4716 | |
4717 | '-s' | |
4718 | Enable (set) each OPTNAME. | |
4719 | ||
4720 | '-u' | |
4721 | Disable (unset) each OPTNAME. | |
4722 | ||
4723 | '-q' | |
4724 | Suppresses normal output; the return status indicates whether | |
4725 | the OPTNAME is set or unset. If multiple OPTNAME arguments | |
74091dd4 | 4726 | are given with '-q', the return status is zero if all OPTNAMEs |
a0c0a00f CR |
4727 | are enabled; non-zero otherwise. |
4728 | ||
4729 | '-o' | |
4730 | Restricts the values of OPTNAME to be those defined for the | |
4731 | '-o' option to the 'set' builtin (*note The Set Builtin::). | |
4732 | ||
4733 | If either '-s' or '-u' is used with no OPTNAME arguments, 'shopt' | |
4734 | shows only those options which are set or unset, respectively. | |
4735 | ||
4736 | Unless otherwise noted, the 'shopt' options are disabled (off) by | |
4737 | default. | |
4738 | ||
74091dd4 | 4739 | The return status when listing options is zero if all OPTNAMEs are |
a0c0a00f CR |
4740 | enabled, non-zero otherwise. When setting or unsetting options, |
4741 | the return status is zero unless an OPTNAME is not a valid shell | |
4742 | option. | |
4743 | ||
4744 | The list of 'shopt' options is: | |
4745 | ||
d233b485 CR |
4746 | 'assoc_expand_once' |
4747 | If set, the shell suppresses multiple evaluation of | |
4748 | associative array subscripts during arithmetic expression | |
4749 | evaluation, while executing builtins that can perform variable | |
4750 | assignments, and while executing builtins that perform array | |
4751 | dereferencing. | |
4752 | ||
a0c0a00f CR |
4753 | 'autocd' |
4754 | If set, a command name that is the name of a directory is | |
4755 | executed as if it were the argument to the 'cd' command. This | |
4756 | option is only used by interactive shells. | |
4757 | ||
4758 | 'cdable_vars' | |
4759 | If this is set, an argument to the 'cd' builtin command that | |
4760 | is not a directory is assumed to be the name of a variable | |
4761 | whose value is the directory to change to. | |
4762 | ||
4763 | 'cdspell' | |
4764 | If set, minor errors in the spelling of a directory component | |
4765 | in a 'cd' command will be corrected. The errors checked for | |
4766 | are transposed characters, a missing character, and a | |
4767 | character too many. If a correction is found, the corrected | |
4768 | path is printed, and the command proceeds. This option is | |
4769 | only used by interactive shells. | |
4770 | ||
4771 | 'checkhash' | |
4772 | If this is set, Bash checks that a command found in the hash | |
4773 | table exists before trying to execute it. If a hashed command | |
4774 | no longer exists, a normal path search is performed. | |
4775 | ||
4776 | 'checkjobs' | |
4777 | If set, Bash lists the status of any stopped and running jobs | |
4778 | before exiting an interactive shell. If any jobs are running, | |
4779 | this causes the exit to be deferred until a second exit is | |
4780 | attempted without an intervening command (*note Job | |
4781 | Control::). The shell always postpones exiting if any jobs | |
4782 | are stopped. | |
4783 | ||
4784 | 'checkwinsize' | |
d233b485 CR |
4785 | If set, Bash checks the window size after each external |
4786 | (non-builtin) command and, if necessary, updates the values of | |
4787 | 'LINES' and 'COLUMNS'. This option is enabled by default. | |
a0c0a00f CR |
4788 | |
4789 | 'cmdhist' | |
4790 | If set, Bash attempts to save all lines of a multiple-line | |
4791 | command in the same history entry. This allows easy | |
d233b485 CR |
4792 | re-editing of multi-line commands. This option is enabled by |
4793 | default, but only has an effect if command history is enabled | |
4794 | (*note Bash History Facilities::). | |
a0c0a00f CR |
4795 | |
4796 | 'compat31' | |
a0c0a00f | 4797 | 'compat32' |
a0c0a00f | 4798 | 'compat40' |
a0c0a00f | 4799 | 'compat41' |
a0c0a00f | 4800 | 'compat42' |
a0c0a00f | 4801 | 'compat43' |
d233b485 | 4802 | 'compat44' |
8868edaf CR |
4803 | These control aspects of the shell's compatibility mode (*note |
4804 | Shell Compatibility Mode::). | |
d233b485 | 4805 | |
a0c0a00f CR |
4806 | 'complete_fullquote' |
4807 | If set, Bash quotes all shell metacharacters in filenames and | |
4808 | directory names when performing completion. If not set, Bash | |
4809 | removes metacharacters such as the dollar sign from the set of | |
4810 | characters that will be quoted in completed filenames when | |
4811 | these metacharacters appear in shell variable references in | |
4812 | words to be completed. This means that dollar signs in | |
4813 | variable names that expand to directories will not be quoted; | |
4814 | however, any dollar signs appearing in filenames will not be | |
4815 | quoted, either. This is active only when bash is using | |
4816 | backslashes to quote completed filenames. This variable is | |
4817 | set by default, which is the default Bash behavior in versions | |
4818 | through 4.2. | |
4819 | ||
4820 | 'direxpand' | |
4821 | If set, Bash replaces directory names with the results of word | |
4822 | expansion when performing filename completion. This changes | |
74091dd4 | 4823 | the contents of the Readline editing buffer. If not set, Bash |
a0c0a00f CR |
4824 | attempts to preserve what the user typed. |
4825 | ||
4826 | 'dirspell' | |
4827 | If set, Bash attempts spelling correction on directory names | |
4828 | during word completion if the directory name initially | |
4829 | supplied does not exist. | |
4830 | ||
4831 | 'dotglob' | |
4832 | If set, Bash includes filenames beginning with a '.' in the | |
d233b485 CR |
4833 | results of filename expansion. The filenames '.' and '..' |
4834 | must always be matched explicitly, even if 'dotglob' is set. | |
a0c0a00f CR |
4835 | |
4836 | 'execfail' | |
4837 | If this is set, a non-interactive shell will not exit if it | |
4838 | cannot execute the file specified as an argument to the 'exec' | |
4839 | builtin command. An interactive shell does not exit if 'exec' | |
4840 | fails. | |
4841 | ||
4842 | 'expand_aliases' | |
4843 | If set, aliases are expanded as described below under Aliases, | |
4844 | *note Aliases::. This option is enabled by default for | |
4845 | interactive shells. | |
4846 | ||
4847 | 'extdebug' | |
8868edaf CR |
4848 | If set at shell invocation, or in a shell startup file, |
4849 | arrange to execute the debugger profile before the shell | |
4850 | starts, identical to the '--debugger' option. If set after | |
4851 | invocation, behavior intended for use by debuggers is enabled: | |
a0c0a00f CR |
4852 | |
4853 | 1. The '-F' option to the 'declare' builtin (*note Bash | |
4854 | Builtins::) displays the source file name and line number | |
4855 | corresponding to each function name supplied as an | |
4856 | argument. | |
4857 | ||
4858 | 2. If the command run by the 'DEBUG' trap returns a non-zero | |
4859 | value, the next command is skipped and not executed. | |
4860 | ||
4861 | 3. If the command run by the 'DEBUG' trap returns a value of | |
4862 | 2, and the shell is executing in a subroutine (a shell | |
4863 | function or a shell script executed by the '.' or | |
4864 | 'source' builtins), the shell simulates a call to | |
4865 | 'return'. | |
4866 | ||
4867 | 4. 'BASH_ARGC' and 'BASH_ARGV' are updated as described in | |
4868 | their descriptions (*note Bash Variables::). | |
4869 | ||
4870 | 5. Function tracing is enabled: command substitution, shell | |
4871 | functions, and subshells invoked with '( COMMAND )' | |
4872 | inherit the 'DEBUG' and 'RETURN' traps. | |
4873 | ||
4874 | 6. Error tracing is enabled: command substitution, shell | |
4875 | functions, and subshells invoked with '( COMMAND )' | |
4876 | inherit the 'ERR' trap. | |
4877 | ||
4878 | 'extglob' | |
4879 | If set, the extended pattern matching features described above | |
4880 | (*note Pattern Matching::) are enabled. | |
4881 | ||
4882 | 'extquote' | |
4883 | If set, '$'STRING'' and '$"STRING"' quoting is performed | |
4884 | within '${PARAMETER}' expansions enclosed in double quotes. | |
4885 | This option is enabled by default. | |
4886 | ||
4887 | 'failglob' | |
4888 | If set, patterns which fail to match filenames during filename | |
4889 | expansion result in an expansion error. | |
4890 | ||
4891 | 'force_fignore' | |
4892 | If set, the suffixes specified by the 'FIGNORE' shell variable | |
4893 | cause words to be ignored when performing word completion even | |
4894 | if the ignored words are the only possible completions. *Note | |
4895 | Bash Variables::, for a description of 'FIGNORE'. This option | |
4896 | is enabled by default. | |
4897 | ||
4898 | 'globasciiranges' | |
4899 | If set, range expressions used in pattern matching bracket | |
4900 | expressions (*note Pattern Matching::) behave as if in the | |
4901 | traditional C locale when performing comparisons. That is, | |
4902 | the current locale's collating sequence is not taken into | |
4903 | account, so 'b' will not collate between 'A' and 'B', and | |
4904 | upper-case and lower-case ASCII characters will collate | |
4905 | together. | |
4906 | ||
74091dd4 CR |
4907 | 'globskipdots' |
4908 | If set, filename expansion will never match the filenames '.' | |
4909 | and '..', even if the pattern begins with a '.'. This option | |
4910 | is enabled by default. | |
4911 | ||
a0c0a00f CR |
4912 | 'globstar' |
4913 | If set, the pattern '**' used in a filename expansion context | |
4914 | will match all files and zero or more directories and | |
4915 | subdirectories. If the pattern is followed by a '/', only | |
4916 | directories and subdirectories match. | |
4917 | ||
4918 | 'gnu_errfmt' | |
4919 | If set, shell error messages are written in the standard GNU | |
4920 | error message format. | |
4921 | ||
4922 | 'histappend' | |
4923 | If set, the history list is appended to the file named by the | |
4924 | value of the 'HISTFILE' variable when the shell exits, rather | |
4925 | than overwriting the file. | |
4926 | ||
4927 | 'histreedit' | |
4928 | If set, and Readline is being used, a user is given the | |
4929 | opportunity to re-edit a failed history substitution. | |
4930 | ||
4931 | 'histverify' | |
4932 | If set, and Readline is being used, the results of history | |
4933 | substitution are not immediately passed to the shell parser. | |
4934 | Instead, the resulting line is loaded into the Readline | |
4935 | editing buffer, allowing further modification. | |
4936 | ||
4937 | 'hostcomplete' | |
4938 | If set, and Readline is being used, Bash will attempt to | |
4939 | perform hostname completion when a word containing a '@' is | |
4940 | being completed (*note Commands For Completion::). This | |
4941 | option is enabled by default. | |
4942 | ||
4943 | 'huponexit' | |
4944 | If set, Bash will send 'SIGHUP' to all jobs when an | |
4945 | interactive login shell exits (*note Signals::). | |
4946 | ||
4947 | 'inherit_errexit' | |
4948 | If set, command substitution inherits the value of the | |
4949 | 'errexit' option, instead of unsetting it in the subshell | |
4950 | environment. This option is enabled when POSIX mode is | |
4951 | enabled. | |
4952 | ||
4953 | 'interactive_comments' | |
4954 | Allow a word beginning with '#' to cause that word and all | |
4955 | remaining characters on that line to be ignored in an | |
4956 | interactive shell. This option is enabled by default. | |
4957 | ||
4958 | 'lastpipe' | |
4959 | If set, and job control is not active, the shell runs the last | |
4960 | command of a pipeline not executed in the background in the | |
4961 | current shell environment. | |
4962 | ||
4963 | 'lithist' | |
4964 | If enabled, and the 'cmdhist' option is enabled, multi-line | |
4965 | commands are saved to the history with embedded newlines | |
4966 | rather than using semicolon separators where possible. | |
4967 | ||
d233b485 CR |
4968 | 'localvar_inherit' |
4969 | If set, local variables inherit the value and attributes of a | |
4970 | variable of the same name that exists at a previous scope | |
74091dd4 | 4971 | before any new value is assigned. The 'nameref' attribute is |
d233b485 CR |
4972 | not inherited. |
4973 | ||
4974 | 'localvar_unset' | |
4975 | If set, calling 'unset' on local variables in previous | |
4976 | function scopes marks them so subsequent lookups find them | |
4977 | unset until that function returns. This is identical to the | |
4978 | behavior of unsetting local variables at the current function | |
4979 | scope. | |
4980 | ||
a0c0a00f CR |
4981 | 'login_shell' |
4982 | The shell sets this option if it is started as a login shell | |
4983 | (*note Invoking Bash::). The value may not be changed. | |
4984 | ||
4985 | 'mailwarn' | |
4986 | If set, and a file that Bash is checking for mail has been | |
4987 | accessed since the last time it was checked, the message '"The | |
4988 | mail in MAILFILE has been read"' is displayed. | |
4989 | ||
4990 | 'no_empty_cmd_completion' | |
4991 | If set, and Readline is being used, Bash will not attempt to | |
4992 | search the 'PATH' for possible completions when completion is | |
4993 | attempted on an empty line. | |
4994 | ||
4995 | 'nocaseglob' | |
4996 | If set, Bash matches filenames in a case-insensitive fashion | |
4997 | when performing filename expansion. | |
4998 | ||
4999 | 'nocasematch' | |
5000 | If set, Bash matches patterns in a case-insensitive fashion | |
5001 | when performing matching while executing 'case' or '[[' | |
74091dd4 CR |
5002 | conditional commands (*note Conditional Constructs::, when |
5003 | performing pattern substitution word expansions, or when | |
5004 | filtering possible completions as part of programmable | |
5005 | completion. | |
5006 | ||
5007 | 'noexpand_translation' | |
5008 | If set, Bash encloses the translated results of $"..." | |
5009 | quoting in single quotes instead of double quotes. If the | |
5010 | string is not translated, this has no effect. | |
a0c0a00f CR |
5011 | |
5012 | 'nullglob' | |
5013 | If set, Bash allows filename patterns which match no files to | |
5014 | expand to a null string, rather than themselves. | |
5015 | ||
74091dd4 CR |
5016 | 'patsub_replacement' |
5017 | If set, Bash expands occurrences of '&' in the replacement | |
5018 | string of pattern substitution to the text matched by the | |
5019 | pattern, as described above (*note Shell Parameter | |
5020 | Expansion::). This option is enabled by default. | |
5021 | ||
a0c0a00f CR |
5022 | 'progcomp' |
5023 | If set, the programmable completion facilities (*note | |
5024 | Programmable Completion::) are enabled. This option is | |
5025 | enabled by default. | |
5026 | ||
d233b485 CR |
5027 | 'progcomp_alias' |
5028 | If set, and programmable completion is enabled, Bash treats a | |
5029 | command name that doesn't have any completions as a possible | |
5030 | alias and attempts alias expansion. If it has an alias, Bash | |
5031 | attempts programmable completion using the command word | |
5032 | resulting from the expanded alias. | |
5033 | ||
a0c0a00f CR |
5034 | 'promptvars' |
5035 | If set, prompt strings undergo parameter expansion, command | |
5036 | substitution, arithmetic expansion, and quote removal after | |
5037 | being expanded as described below (*note Controlling the | |
5038 | Prompt::). This option is enabled by default. | |
5039 | ||
5040 | 'restricted_shell' | |
5041 | The shell sets this option if it is started in restricted mode | |
5042 | (*note The Restricted Shell::). The value may not be changed. | |
5043 | This is not reset when the startup files are executed, | |
5044 | allowing the startup files to discover whether or not a shell | |
5045 | is restricted. | |
5046 | ||
5047 | 'shift_verbose' | |
5048 | If this is set, the 'shift' builtin prints an error message | |
5049 | when the shift count exceeds the number of positional | |
5050 | parameters. | |
5051 | ||
5052 | 'sourcepath' | |
74091dd4 CR |
5053 | If set, the '.' ('source') builtin uses the value of 'PATH' to |
5054 | find the directory containing the file supplied as an | |
5055 | argument. This option is enabled by default. | |
5056 | ||
5057 | 'varredir_close' | |
5058 | If set, the shell automatically closes file descriptors | |
5059 | assigned using the '{varname}' redirection syntax (*note | |
5060 | Redirections::) instead of leaving them open when the command | |
5061 | completes. | |
a0c0a00f CR |
5062 | |
5063 | 'xpg_echo' | |
5064 | If set, the 'echo' builtin expands backslash-escape sequences | |
5065 | by default. | |
5066 | ||
a0c0a00f CR |
5067 | \1f |
5068 | File: bash.info, Node: Special Builtins, Prev: Modifying Shell Behavior, Up: Shell Builtin Commands | |
5069 | ||
5070 | 4.4 Special Builtins | |
5071 | ==================== | |
5072 | ||
5073 | For historical reasons, the POSIX standard has classified several | |
5074 | builtin commands as _special_. When Bash is executing in POSIX mode, | |
5075 | the special builtins differ from other builtin commands in three | |
5076 | respects: | |
5077 | ||
5078 | 1. Special builtins are found before shell functions during command | |
5079 | lookup. | |
5080 | ||
5081 | 2. If a special builtin returns an error status, a non-interactive | |
5082 | shell exits. | |
5083 | ||
5084 | 3. Assignment statements preceding the command stay in effect in the | |
5085 | shell environment after the command completes. | |
5086 | ||
5087 | When Bash is not executing in POSIX mode, these builtins behave no | |
5088 | differently than the rest of the Bash builtin commands. The Bash POSIX | |
5089 | mode is described in *note Bash POSIX Mode::. | |
5090 | ||
5091 | These are the POSIX special builtins: | |
5092 | break : . continue eval exec exit export readonly return set | |
5093 | shift trap unset | |
5094 | ||
5095 | \1f | |
5096 | File: bash.info, Node: Shell Variables, Next: Bash Features, Prev: Shell Builtin Commands, Up: Top | |
5097 | ||
5098 | 5 Shell Variables | |
5099 | ***************** | |
5100 | ||
5101 | * Menu: | |
5102 | ||
5103 | * Bourne Shell Variables:: Variables which Bash uses in the same way | |
5104 | as the Bourne Shell. | |
5105 | * Bash Variables:: List of variables that exist in Bash. | |
5106 | ||
5107 | This chapter describes the shell variables that Bash uses. Bash | |
5108 | automatically assigns default values to a number of variables. | |
5109 | ||
5110 | \1f | |
5111 | File: bash.info, Node: Bourne Shell Variables, Next: Bash Variables, Up: Shell Variables | |
5112 | ||
5113 | 5.1 Bourne Shell Variables | |
5114 | ========================== | |
5115 | ||
5116 | Bash uses certain shell variables in the same way as the Bourne shell. | |
5117 | In some cases, Bash assigns a default value to the variable. | |
5118 | ||
5119 | 'CDPATH' | |
5120 | A colon-separated list of directories used as a search path for the | |
5121 | 'cd' builtin command. | |
5122 | ||
5123 | 'HOME' | |
5124 | The current user's home directory; the default for the 'cd' builtin | |
5125 | command. The value of this variable is also used by tilde | |
5126 | expansion (*note Tilde Expansion::). | |
5127 | ||
5128 | 'IFS' | |
5129 | A list of characters that separate fields; used when the shell | |
5130 | splits words as part of expansion. | |
5131 | ||
5132 | 'MAIL' | |
5133 | If this parameter is set to a filename or directory name and the | |
5134 | 'MAILPATH' variable is not set, Bash informs the user of the | |
5135 | arrival of mail in the specified file or Maildir-format directory. | |
5136 | ||
5137 | 'MAILPATH' | |
5138 | A colon-separated list of filenames which the shell periodically | |
5139 | checks for new mail. Each list entry can specify the message that | |
5140 | is printed when new mail arrives in the mail file by separating the | |
5141 | filename from the message with a '?'. When used in the text of the | |
5142 | message, '$_' expands to the name of the current mail file. | |
5143 | ||
5144 | 'OPTARG' | |
5145 | The value of the last option argument processed by the 'getopts' | |
5146 | builtin. | |
5147 | ||
5148 | 'OPTIND' | |
5149 | The index of the last option argument processed by the 'getopts' | |
5150 | builtin. | |
5151 | ||
5152 | 'PATH' | |
5153 | A colon-separated list of directories in which the shell looks for | |
5154 | commands. A zero-length (null) directory name in the value of | |
5155 | 'PATH' indicates the current directory. A null directory name may | |
5156 | appear as two adjacent colons, or as an initial or trailing colon. | |
5157 | ||
5158 | 'PS1' | |
5159 | The primary prompt string. The default value is '\s-\v\$ '. *Note | |
5160 | Controlling the Prompt::, for the complete list of escape sequences | |
5161 | that are expanded before 'PS1' is displayed. | |
5162 | ||
5163 | 'PS2' | |
d233b485 CR |
5164 | The secondary prompt string. The default value is '> '. 'PS2' is |
5165 | expanded in the same way as 'PS1' before being displayed. | |
a0c0a00f CR |
5166 | |
5167 | \1f | |
5168 | File: bash.info, Node: Bash Variables, Prev: Bourne Shell Variables, Up: Shell Variables | |
5169 | ||
5170 | 5.2 Bash Variables | |
5171 | ================== | |
5172 | ||
5173 | These variables are set or used by Bash, but other shells do not | |
5174 | normally treat them specially. | |
5175 | ||
5176 | A few variables used by Bash are described in different chapters: | |
5177 | variables for controlling the job control facilities (*note Job Control | |
5178 | Variables::). | |
5179 | ||
8868edaf CR |
5180 | '_' |
5181 | ($_, an underscore.) At shell startup, set to the pathname used to | |
5182 | invoke the shell or shell script being executed as passed in the | |
5183 | environment or argument list. Subsequently, expands to the last | |
5184 | argument to the previous simple command executed in the foreground, | |
5185 | after expansion. Also set to the full pathname used to invoke each | |
5186 | command executed and placed in the environment exported to that | |
5187 | command. When checking mail, this parameter holds the name of the | |
5188 | mail file. | |
5189 | ||
a0c0a00f CR |
5190 | 'BASH' |
5191 | The full pathname used to execute the current instance of Bash. | |
5192 | ||
5193 | 'BASHOPTS' | |
5194 | A colon-separated list of enabled shell options. Each word in the | |
5195 | list is a valid argument for the '-s' option to the 'shopt' builtin | |
5196 | command (*note The Shopt Builtin::). The options appearing in | |
5197 | 'BASHOPTS' are those reported as 'on' by 'shopt'. If this variable | |
5198 | is in the environment when Bash starts up, each shell option in the | |
5199 | list will be enabled before reading any startup files. This | |
5200 | variable is readonly. | |
5201 | ||
5202 | 'BASHPID' | |
5203 | Expands to the process ID of the current Bash process. This | |
5204 | differs from '$$' under certain circumstances, such as subshells | |
d233b485 CR |
5205 | that do not require Bash to be re-initialized. Assignments to |
5206 | 'BASHPID' have no effect. If 'BASHPID' is unset, it loses its | |
5207 | special properties, even if it is subsequently reset. | |
a0c0a00f CR |
5208 | |
5209 | 'BASH_ALIASES' | |
5210 | An associative array variable whose members correspond to the | |
5211 | internal list of aliases as maintained by the 'alias' builtin. | |
5212 | (*note Bourne Shell Builtins::). Elements added to this array | |
5213 | appear in the alias list; however, unsetting array elements | |
5214 | currently does not cause aliases to be removed from the alias list. | |
5215 | If 'BASH_ALIASES' is unset, it loses its special properties, even | |
5216 | if it is subsequently reset. | |
5217 | ||
5218 | 'BASH_ARGC' | |
5219 | An array variable whose values are the number of parameters in each | |
5220 | frame of the current bash execution call stack. The number of | |
5221 | parameters to the current subroutine (shell function or script | |
5222 | executed with '.' or 'source') is at the top of the stack. When a | |
5223 | subroutine is executed, the number of parameters passed is pushed | |
5224 | onto 'BASH_ARGC'. The shell sets 'BASH_ARGC' only when in extended | |
5225 | debugging mode (see *note The Shopt Builtin:: for a description of | |
d233b485 CR |
5226 | the 'extdebug' option to the 'shopt' builtin). Setting 'extdebug' |
5227 | after the shell has started to execute a script, or referencing | |
5228 | this variable when 'extdebug' is not set, may result in | |
5229 | inconsistent values. | |
a0c0a00f CR |
5230 | |
5231 | 'BASH_ARGV' | |
5232 | An array variable containing all of the parameters in the current | |
5233 | bash execution call stack. The final parameter of the last | |
5234 | subroutine call is at the top of the stack; the first parameter of | |
5235 | the initial call is at the bottom. When a subroutine is executed, | |
5236 | the parameters supplied are pushed onto 'BASH_ARGV'. The shell | |
5237 | sets 'BASH_ARGV' only when in extended debugging mode (see *note | |
5238 | The Shopt Builtin:: for a description of the 'extdebug' option to | |
d233b485 CR |
5239 | the 'shopt' builtin). Setting 'extdebug' after the shell has |
5240 | started to execute a script, or referencing this variable when | |
5241 | 'extdebug' is not set, may result in inconsistent values. | |
5242 | ||
5243 | 'BASH_ARGV0' | |
5244 | When referenced, this variable expands to the name of the shell or | |
5245 | shell script (identical to '$0'; *Note Special Parameters::, for | |
5246 | the description of special parameter 0). Assignment to | |
5247 | 'BASH_ARGV0' causes the value assigned to also be assigned to '$0'. | |
5248 | If 'BASH_ARGV0' is unset, it loses its special properties, even if | |
5249 | it is subsequently reset. | |
a0c0a00f CR |
5250 | |
5251 | 'BASH_CMDS' | |
5252 | An associative array variable whose members correspond to the | |
5253 | internal hash table of commands as maintained by the 'hash' builtin | |
5254 | (*note Bourne Shell Builtins::). Elements added to this array | |
5255 | appear in the hash table; however, unsetting array elements | |
5256 | currently does not cause command names to be removed from the hash | |
5257 | table. If 'BASH_CMDS' is unset, it loses its special properties, | |
5258 | even if it is subsequently reset. | |
5259 | ||
5260 | 'BASH_COMMAND' | |
5261 | The command currently being executed or about to be executed, | |
5262 | unless the shell is executing a command as the result of a trap, in | |
8868edaf CR |
5263 | which case it is the command executing at the time of the trap. If |
5264 | 'BASH_COMMAND' is unset, it loses its special properties, even if | |
5265 | it is subsequently reset. | |
a0c0a00f CR |
5266 | |
5267 | 'BASH_COMPAT' | |
5268 | The value is used to set the shell's compatibility level. *Note | |
8868edaf CR |
5269 | Shell Compatibility Mode::, for a description of the various |
5270 | compatibility levels and their effects. The value may be a decimal | |
5271 | number (e.g., 4.2) or an integer (e.g., 42) corresponding to the | |
5272 | desired compatibility level. If 'BASH_COMPAT' is unset or set to | |
5273 | the empty string, the compatibility level is set to the default for | |
5274 | the current version. If 'BASH_COMPAT' is set to a value that is | |
5275 | not one of the valid compatibility levels, the shell prints an | |
5276 | error message and sets the compatibility level to the default for | |
5277 | the current version. The valid values correspond to the | |
5278 | compatibility levels described below (*note Shell Compatibility | |
5279 | Mode::). For example, 4.2 and 42 are valid values that correspond | |
5280 | to the 'compat42' 'shopt' option and set the compatibility level to | |
5281 | 42. The current version is also a valid value. | |
a0c0a00f CR |
5282 | |
5283 | 'BASH_ENV' | |
5284 | If this variable is set when Bash is invoked to execute a shell | |
5285 | script, its value is expanded and used as the name of a startup | |
5286 | file to read before executing the script. *Note Bash Startup | |
5287 | Files::. | |
5288 | ||
5289 | 'BASH_EXECUTION_STRING' | |
5290 | The command argument to the '-c' invocation option. | |
5291 | ||
5292 | 'BASH_LINENO' | |
5293 | An array variable whose members are the line numbers in source | |
74091dd4 | 5294 | files where each corresponding member of 'FUNCNAME' was invoked. |
a0c0a00f CR |
5295 | '${BASH_LINENO[$i]}' is the line number in the source file |
5296 | ('${BASH_SOURCE[$i+1]}') where '${FUNCNAME[$i]}' was called (or | |
5297 | '${BASH_LINENO[$i-1]}' if referenced within another shell | |
5298 | function). Use 'LINENO' to obtain the current line number. | |
5299 | ||
5300 | 'BASH_LOADABLES_PATH' | |
5301 | A colon-separated list of directories in which the shell looks for | |
5302 | dynamically loadable builtins specified by the 'enable' command. | |
5303 | ||
5304 | 'BASH_REMATCH' | |
5305 | An array variable whose members are assigned by the '=~' binary | |
5306 | operator to the '[[' conditional command (*note Conditional | |
5307 | Constructs::). The element with index 0 is the portion of the | |
5308 | string matching the entire regular expression. The element with | |
5309 | index N is the portion of the string matching the Nth parenthesized | |
8868edaf | 5310 | subexpression. |
a0c0a00f CR |
5311 | |
5312 | 'BASH_SOURCE' | |
5313 | An array variable whose members are the source filenames where the | |
5314 | corresponding shell function names in the 'FUNCNAME' array variable | |
5315 | are defined. The shell function '${FUNCNAME[$i]}' is defined in | |
5316 | the file '${BASH_SOURCE[$i]}' and called from | |
5317 | '${BASH_SOURCE[$i+1]}' | |
5318 | ||
5319 | 'BASH_SUBSHELL' | |
5320 | Incremented by one within each subshell or subshell environment | |
5321 | when the shell begins executing in that environment. The initial | |
8868edaf CR |
5322 | value is 0. If 'BASH_SUBSHELL' is unset, it loses its special |
5323 | properties, even if it is subsequently reset. | |
a0c0a00f CR |
5324 | |
5325 | 'BASH_VERSINFO' | |
5326 | A readonly array variable (*note Arrays::) whose members hold | |
5327 | version information for this instance of Bash. The values assigned | |
5328 | to the array members are as follows: | |
5329 | ||
5330 | 'BASH_VERSINFO[0]' | |
74091dd4 | 5331 | The major version number (the "release"). |
a0c0a00f CR |
5332 | |
5333 | 'BASH_VERSINFO[1]' | |
74091dd4 | 5334 | The minor version number (the "version"). |
a0c0a00f CR |
5335 | |
5336 | 'BASH_VERSINFO[2]' | |
5337 | The patch level. | |
5338 | ||
5339 | 'BASH_VERSINFO[3]' | |
5340 | The build version. | |
5341 | ||
5342 | 'BASH_VERSINFO[4]' | |
74091dd4 | 5343 | The release status (e.g., 'beta1'). |
a0c0a00f CR |
5344 | |
5345 | 'BASH_VERSINFO[5]' | |
5346 | The value of 'MACHTYPE'. | |
5347 | ||
5348 | 'BASH_VERSION' | |
5349 | The version number of the current instance of Bash. | |
5350 | ||
5351 | 'BASH_XTRACEFD' | |
5352 | If set to an integer corresponding to a valid file descriptor, Bash | |
5353 | will write the trace output generated when 'set -x' is enabled to | |
5354 | that file descriptor. This allows tracing output to be separated | |
5355 | from diagnostic and error messages. The file descriptor is closed | |
5356 | when 'BASH_XTRACEFD' is unset or assigned a new value. Unsetting | |
5357 | 'BASH_XTRACEFD' or assigning it the empty string causes the trace | |
5358 | output to be sent to the standard error. Note that setting | |
5359 | 'BASH_XTRACEFD' to 2 (the standard error file descriptor) and then | |
5360 | unsetting it will result in the standard error being closed. | |
5361 | ||
5362 | 'CHILD_MAX' | |
5363 | Set the number of exited child status values for the shell to | |
5364 | remember. Bash will not allow this value to be decreased below a | |
5365 | POSIX-mandated minimum, and there is a maximum value (currently | |
5366 | 8192) that this may not exceed. The minimum value is | |
5367 | system-dependent. | |
5368 | ||
5369 | 'COLUMNS' | |
5370 | Used by the 'select' command to determine the terminal width when | |
5371 | printing selection lists. Automatically set if the 'checkwinsize' | |
5372 | option is enabled (*note The Shopt Builtin::), or in an interactive | |
5373 | shell upon receipt of a 'SIGWINCH'. | |
5374 | ||
5375 | 'COMP_CWORD' | |
5376 | An index into '${COMP_WORDS}' of the word containing the current | |
5377 | cursor position. This variable is available only in shell | |
5378 | functions invoked by the programmable completion facilities (*note | |
5379 | Programmable Completion::). | |
5380 | ||
5381 | 'COMP_LINE' | |
5382 | The current command line. This variable is available only in shell | |
5383 | functions and external commands invoked by the programmable | |
5384 | completion facilities (*note Programmable Completion::). | |
5385 | ||
5386 | 'COMP_POINT' | |
5387 | The index of the current cursor position relative to the beginning | |
5388 | of the current command. If the current cursor position is at the | |
5389 | end of the current command, the value of this variable is equal to | |
5390 | '${#COMP_LINE}'. This variable is available only in shell | |
5391 | functions and external commands invoked by the programmable | |
5392 | completion facilities (*note Programmable Completion::). | |
5393 | ||
5394 | 'COMP_TYPE' | |
5395 | Set to an integer value corresponding to the type of completion | |
74091dd4 CR |
5396 | attempted that caused a completion function to be called: <TAB>, |
5397 | for normal completion, '?', for listing completions after | |
5398 | successive tabs, '!', for listing alternatives on partial word | |
5399 | completion, '@', to list completions if the word is not unmodified, | |
5400 | or '%', for menu completion. This variable is available only in | |
5401 | shell functions and external commands invoked by the programmable | |
a0c0a00f CR |
5402 | completion facilities (*note Programmable Completion::). |
5403 | ||
5404 | 'COMP_KEY' | |
5405 | The key (or final key of a key sequence) used to invoke the current | |
5406 | completion function. | |
5407 | ||
5408 | 'COMP_WORDBREAKS' | |
5409 | The set of characters that the Readline library treats as word | |
5410 | separators when performing word completion. If 'COMP_WORDBREAKS' | |
5411 | is unset, it loses its special properties, even if it is | |
5412 | subsequently reset. | |
5413 | ||
5414 | 'COMP_WORDS' | |
5415 | An array variable consisting of the individual words in the current | |
5416 | command line. The line is split into words as Readline would split | |
5417 | it, using 'COMP_WORDBREAKS' as described above. This variable is | |
5418 | available only in shell functions invoked by the programmable | |
5419 | completion facilities (*note Programmable Completion::). | |
5420 | ||
5421 | 'COMPREPLY' | |
5422 | An array variable from which Bash reads the possible completions | |
5423 | generated by a shell function invoked by the programmable | |
5424 | completion facility (*note Programmable Completion::). Each array | |
5425 | element contains one possible completion. | |
5426 | ||
5427 | 'COPROC' | |
5428 | An array variable created to hold the file descriptors for output | |
5429 | from and input to an unnamed coprocess (*note Coprocesses::). | |
5430 | ||
5431 | 'DIRSTACK' | |
5432 | An array variable containing the current contents of the directory | |
5433 | stack. Directories appear in the stack in the order they are | |
5434 | displayed by the 'dirs' builtin. Assigning to members of this | |
5435 | array variable may be used to modify directories already in the | |
5436 | stack, but the 'pushd' and 'popd' builtins must be used to add and | |
5437 | remove directories. Assignment to this variable will not change | |
5438 | the current directory. If 'DIRSTACK' is unset, it loses its | |
5439 | special properties, even if it is subsequently reset. | |
5440 | ||
5441 | 'EMACS' | |
5442 | If Bash finds this variable in the environment when the shell | |
5443 | starts with value 't', it assumes that the shell is running in an | |
5444 | Emacs shell buffer and disables line editing. | |
5445 | ||
5446 | 'ENV' | |
74091dd4 | 5447 | Expanded and executed similarly to 'BASH_ENV' (*note Bash Startup |
8868edaf CR |
5448 | Files::) when an interactive shell is invoked in POSIX Mode (*note |
5449 | Bash POSIX Mode::). | |
a0c0a00f | 5450 | |
d233b485 CR |
5451 | 'EPOCHREALTIME' |
5452 | Each time this parameter is referenced, it expands to the number of | |
5453 | seconds since the Unix Epoch as a floating point value with | |
5454 | micro-second granularity (see the documentation for the C library | |
74091dd4 | 5455 | function 'time' for the definition of Epoch). Assignments to |
d233b485 CR |
5456 | 'EPOCHREALTIME' are ignored. If 'EPOCHREALTIME' is unset, it loses |
5457 | its special properties, even if it is subsequently reset. | |
5458 | ||
5459 | 'EPOCHSECONDS' | |
5460 | Each time this parameter is referenced, it expands to the number of | |
5461 | seconds since the Unix Epoch (see the documentation for the C | |
74091dd4 CR |
5462 | library function 'time' for the definition of Epoch). Assignments |
5463 | to 'EPOCHSECONDS' are ignored. If 'EPOCHSECONDS' is unset, it | |
5464 | loses its special properties, even if it is subsequently reset. | |
d233b485 | 5465 | |
a0c0a00f CR |
5466 | 'EUID' |
5467 | The numeric effective user id of the current user. This variable | |
5468 | is readonly. | |
5469 | ||
5470 | 'EXECIGNORE' | |
5471 | A colon-separated list of shell patterns (*note Pattern Matching::) | |
5472 | defining the list of filenames to be ignored by command search | |
5473 | using 'PATH'. Files whose full pathnames match one of these | |
5474 | patterns are not considered executable files for the purposes of | |
5475 | completion and command execution via 'PATH' lookup. This does not | |
5476 | affect the behavior of the '[', 'test', and '[[' commands. Full | |
5477 | pathnames in the command hash table are not subject to | |
5478 | 'EXECIGNORE'. Use this variable to ignore shared library files | |
5479 | that have the executable bit set, but are not executable files. | |
5480 | The pattern matching honors the setting of the 'extglob' shell | |
5481 | option. | |
5482 | ||
5483 | 'FCEDIT' | |
5484 | The editor used as a default by the '-e' option to the 'fc' builtin | |
5485 | command. | |
5486 | ||
5487 | 'FIGNORE' | |
5488 | A colon-separated list of suffixes to ignore when performing | |
5489 | filename completion. A filename whose suffix matches one of the | |
5490 | entries in 'FIGNORE' is excluded from the list of matched | |
5491 | filenames. A sample value is '.o:~' | |
5492 | ||
5493 | 'FUNCNAME' | |
5494 | An array variable containing the names of all shell functions | |
5495 | currently in the execution call stack. The element with index 0 is | |
5496 | the name of any currently-executing shell function. The | |
5497 | bottom-most element (the one with the highest index) is '"main"'. | |
5498 | This variable exists only when a shell function is executing. | |
5499 | Assignments to 'FUNCNAME' have no effect. If 'FUNCNAME' is unset, | |
5500 | it loses its special properties, even if it is subsequently reset. | |
5501 | ||
5502 | This variable can be used with 'BASH_LINENO' and 'BASH_SOURCE'. | |
5503 | Each element of 'FUNCNAME' has corresponding elements in | |
5504 | 'BASH_LINENO' and 'BASH_SOURCE' to describe the call stack. For | |
5505 | instance, '${FUNCNAME[$i]}' was called from the file | |
5506 | '${BASH_SOURCE[$i+1]}' at line number '${BASH_LINENO[$i]}'. The | |
5507 | 'caller' builtin displays the current call stack using this | |
5508 | information. | |
5509 | ||
5510 | 'FUNCNEST' | |
5511 | If set to a numeric value greater than 0, defines a maximum | |
5512 | function nesting level. Function invocations that exceed this | |
5513 | nesting level will cause the current command to abort. | |
5514 | ||
5515 | 'GLOBIGNORE' | |
d233b485 CR |
5516 | A colon-separated list of patterns defining the set of file names |
5517 | to be ignored by filename expansion. If a file name matched by a | |
a0c0a00f CR |
5518 | filename expansion pattern also matches one of the patterns in |
5519 | 'GLOBIGNORE', it is removed from the list of matches. The pattern | |
5520 | matching honors the setting of the 'extglob' shell option. | |
5521 | ||
5522 | 'GROUPS' | |
5523 | An array variable containing the list of groups of which the | |
5524 | current user is a member. Assignments to 'GROUPS' have no effect. | |
5525 | If 'GROUPS' is unset, it loses its special properties, even if it | |
5526 | is subsequently reset. | |
5527 | ||
5528 | 'histchars' | |
5529 | Up to three characters which control history expansion, quick | |
5530 | substitution, and tokenization (*note History Interaction::). The | |
74091dd4 | 5531 | first character is the "history expansion" character, that is, the |
a0c0a00f CR |
5532 | character which signifies the start of a history expansion, |
5533 | normally '!'. The second character is the character which | |
5534 | signifies 'quick substitution' when seen as the first character on | |
5535 | a line, normally '^'. The optional third character is the | |
5536 | character which indicates that the remainder of the line is a | |
5537 | comment when found as the first character of a word, usually '#'. | |
5538 | The history comment character causes history substitution to be | |
5539 | skipped for the remaining words on the line. It does not | |
5540 | necessarily cause the shell parser to treat the rest of the line as | |
5541 | a comment. | |
5542 | ||
5543 | 'HISTCMD' | |
5544 | The history number, or index in the history list, of the current | |
8868edaf CR |
5545 | command. Assignments to 'HISTCMD' are ignored. If 'HISTCMD' is |
5546 | unset, it loses its special properties, even if it is subsequently | |
5547 | reset. | |
a0c0a00f CR |
5548 | |
5549 | 'HISTCONTROL' | |
5550 | A colon-separated list of values controlling how commands are saved | |
5551 | on the history list. If the list of values includes 'ignorespace', | |
5552 | lines which begin with a space character are not saved in the | |
5553 | history list. A value of 'ignoredups' causes lines which match the | |
5554 | previous history entry to not be saved. A value of 'ignoreboth' is | |
5555 | shorthand for 'ignorespace' and 'ignoredups'. A value of | |
5556 | 'erasedups' causes all previous lines matching the current line to | |
5557 | be removed from the history list before that line is saved. Any | |
5558 | value not in the above list is ignored. If 'HISTCONTROL' is unset, | |
5559 | or does not include a valid value, all lines read by the shell | |
5560 | parser are saved on the history list, subject to the value of | |
5561 | 'HISTIGNORE'. The second and subsequent lines of a multi-line | |
5562 | compound command are not tested, and are added to the history | |
5563 | regardless of the value of 'HISTCONTROL'. | |
5564 | ||
5565 | 'HISTFILE' | |
5566 | The name of the file to which the command history is saved. The | |
5567 | default value is '~/.bash_history'. | |
5568 | ||
5569 | 'HISTFILESIZE' | |
5570 | The maximum number of lines contained in the history file. When | |
5571 | this variable is assigned a value, the history file is truncated, | |
5572 | if necessary, to contain no more than that number of lines by | |
5573 | removing the oldest entries. The history file is also truncated to | |
5574 | this size after writing it when a shell exits. If the value is 0, | |
5575 | the history file is truncated to zero size. Non-numeric values and | |
5576 | numeric values less than zero inhibit truncation. The shell sets | |
5577 | the default value to the value of 'HISTSIZE' after reading any | |
5578 | startup files. | |
5579 | ||
5580 | 'HISTIGNORE' | |
5581 | A colon-separated list of patterns used to decide which command | |
5582 | lines should be saved on the history list. Each pattern is | |
5583 | anchored at the beginning of the line and must match the complete | |
5584 | line (no implicit '*' is appended). Each pattern is tested against | |
5585 | the line after the checks specified by 'HISTCONTROL' are applied. | |
5586 | In addition to the normal shell pattern matching characters, '&' | |
5587 | matches the previous history line. '&' may be escaped using a | |
5588 | backslash; the backslash is removed before attempting a match. The | |
5589 | second and subsequent lines of a multi-line compound command are | |
5590 | not tested, and are added to the history regardless of the value of | |
5591 | 'HISTIGNORE'. The pattern matching honors the setting of the | |
5592 | 'extglob' shell option. | |
5593 | ||
5594 | 'HISTIGNORE' subsumes the function of 'HISTCONTROL'. A pattern of | |
5595 | '&' is identical to 'ignoredups', and a pattern of '[ ]*' is | |
5596 | identical to 'ignorespace'. Combining these two patterns, | |
5597 | separating them with a colon, provides the functionality of | |
5598 | 'ignoreboth'. | |
5599 | ||
5600 | 'HISTSIZE' | |
5601 | The maximum number of commands to remember on the history list. If | |
5602 | the value is 0, commands are not saved in the history list. | |
5603 | Numeric values less than zero result in every command being saved | |
5604 | on the history list (there is no limit). The shell sets the | |
5605 | default value to 500 after reading any startup files. | |
5606 | ||
5607 | 'HISTTIMEFORMAT' | |
5608 | If this variable is set and not null, its value is used as a format | |
74091dd4 | 5609 | string for 'strftime' to print the time stamp associated with each |
a0c0a00f CR |
5610 | history entry displayed by the 'history' builtin. If this variable |
5611 | is set, time stamps are written to the history file so they may be | |
5612 | preserved across shell sessions. This uses the history comment | |
5613 | character to distinguish timestamps from other history lines. | |
5614 | ||
5615 | 'HOSTFILE' | |
5616 | Contains the name of a file in the same format as '/etc/hosts' that | |
5617 | should be read when the shell needs to complete a hostname. The | |
5618 | list of possible hostname completions may be changed while the | |
5619 | shell is running; the next time hostname completion is attempted | |
5620 | after the value is changed, Bash adds the contents of the new file | |
5621 | to the existing list. If 'HOSTFILE' is set, but has no value, or | |
5622 | does not name a readable file, Bash attempts to read '/etc/hosts' | |
5623 | to obtain the list of possible hostname completions. When | |
5624 | 'HOSTFILE' is unset, the hostname list is cleared. | |
5625 | ||
5626 | 'HOSTNAME' | |
5627 | The name of the current host. | |
5628 | ||
5629 | 'HOSTTYPE' | |
5630 | A string describing the machine Bash is running on. | |
5631 | ||
5632 | 'IGNOREEOF' | |
5633 | Controls the action of the shell on receipt of an 'EOF' character | |
5634 | as the sole input. If set, the value denotes the number of | |
5635 | consecutive 'EOF' characters that can be read as the first | |
5636 | character on an input line before the shell will exit. If the | |
d233b485 | 5637 | variable exists but does not have a numeric value, or has no value, |
a0c0a00f CR |
5638 | then the default is 10. If the variable does not exist, then 'EOF' |
5639 | signifies the end of input to the shell. This is only in effect | |
5640 | for interactive shells. | |
5641 | ||
5642 | 'INPUTRC' | |
5643 | The name of the Readline initialization file, overriding the | |
5644 | default of '~/.inputrc'. | |
5645 | ||
d233b485 CR |
5646 | 'INSIDE_EMACS' |
5647 | If Bash finds this variable in the environment when the shell | |
5648 | starts, it assumes that the shell is running in an Emacs shell | |
5649 | buffer and may disable line editing depending on the value of | |
5650 | 'TERM'. | |
5651 | ||
a0c0a00f CR |
5652 | 'LANG' |
5653 | Used to determine the locale category for any category not | |
5654 | specifically selected with a variable starting with 'LC_'. | |
5655 | ||
5656 | 'LC_ALL' | |
5657 | This variable overrides the value of 'LANG' and any other 'LC_' | |
5658 | variable specifying a locale category. | |
5659 | ||
5660 | 'LC_COLLATE' | |
5661 | This variable determines the collation order used when sorting the | |
5662 | results of filename expansion, and determines the behavior of range | |
5663 | expressions, equivalence classes, and collating sequences within | |
5664 | filename expansion and pattern matching (*note Filename | |
5665 | Expansion::). | |
5666 | ||
5667 | 'LC_CTYPE' | |
5668 | This variable determines the interpretation of characters and the | |
5669 | behavior of character classes within filename expansion and pattern | |
5670 | matching (*note Filename Expansion::). | |
5671 | ||
5672 | 'LC_MESSAGES' | |
5673 | This variable determines the locale used to translate double-quoted | |
5674 | strings preceded by a '$' (*note Locale Translation::). | |
5675 | ||
5676 | 'LC_NUMERIC' | |
5677 | This variable determines the locale category used for number | |
5678 | formatting. | |
5679 | ||
5680 | 'LC_TIME' | |
5681 | This variable determines the locale category used for data and time | |
5682 | formatting. | |
5683 | ||
5684 | 'LINENO' | |
5685 | The line number in the script or shell function currently | |
8868edaf CR |
5686 | executing. If 'LINENO' is unset, it loses its special properties, |
5687 | even if it is subsequently reset. | |
a0c0a00f CR |
5688 | |
5689 | 'LINES' | |
5690 | Used by the 'select' command to determine the column length for | |
5691 | printing selection lists. Automatically set if the 'checkwinsize' | |
5692 | option is enabled (*note The Shopt Builtin::), or in an interactive | |
5693 | shell upon receipt of a 'SIGWINCH'. | |
5694 | ||
5695 | 'MACHTYPE' | |
5696 | A string that fully describes the system type on which Bash is | |
5697 | executing, in the standard GNU CPU-COMPANY-SYSTEM format. | |
5698 | ||
5699 | 'MAILCHECK' | |
5700 | How often (in seconds) that the shell should check for mail in the | |
5701 | files specified in the 'MAILPATH' or 'MAIL' variables. The default | |
5702 | is 60 seconds. When it is time to check for mail, the shell does | |
5703 | so before displaying the primary prompt. If this variable is | |
5704 | unset, or set to a value that is not a number greater than or equal | |
5705 | to zero, the shell disables mail checking. | |
5706 | ||
5707 | 'MAPFILE' | |
5708 | An array variable created to hold the text read by the 'mapfile' | |
5709 | builtin when no variable name is supplied. | |
5710 | ||
5711 | 'OLDPWD' | |
5712 | The previous working directory as set by the 'cd' builtin. | |
5713 | ||
5714 | 'OPTERR' | |
5715 | If set to the value 1, Bash displays error messages generated by | |
5716 | the 'getopts' builtin command. | |
5717 | ||
5718 | 'OSTYPE' | |
5719 | A string describing the operating system Bash is running on. | |
5720 | ||
5721 | 'PIPESTATUS' | |
5722 | An array variable (*note Arrays::) containing a list of exit status | |
5723 | values from the processes in the most-recently-executed foreground | |
5724 | pipeline (which may contain only a single command). | |
5725 | ||
5726 | 'POSIXLY_CORRECT' | |
5727 | If this variable is in the environment when Bash starts, the shell | |
5728 | enters POSIX mode (*note Bash POSIX Mode::) before reading the | |
5729 | startup files, as if the '--posix' invocation option had been | |
5730 | supplied. If it is set while the shell is running, Bash enables | |
5731 | POSIX mode, as if the command | |
5732 | set -o posix | |
d233b485 CR |
5733 | had been executed. When the shell enters POSIX mode, it sets this |
5734 | variable if it was not already set. | |
a0c0a00f CR |
5735 | |
5736 | 'PPID' | |
5737 | The process ID of the shell's parent process. This variable is | |
5738 | readonly. | |
5739 | ||
5740 | 'PROMPT_COMMAND' | |
8868edaf CR |
5741 | If this variable is set, and is an array, the value of each set |
5742 | element is interpreted as a command to execute before printing the | |
5743 | primary prompt ('$PS1'). If this is set but not an array variable, | |
5744 | its value is used as a command to execute instead. | |
a0c0a00f CR |
5745 | |
5746 | 'PROMPT_DIRTRIM' | |
5747 | If set to a number greater than zero, the value is used as the | |
5748 | number of trailing directory components to retain when expanding | |
5749 | the '\w' and '\W' prompt string escapes (*note Controlling the | |
5750 | Prompt::). Characters removed are replaced with an ellipsis. | |
5751 | ||
5752 | 'PS0' | |
8868edaf | 5753 | The value of this parameter is expanded like 'PS1' and displayed by |
a0c0a00f CR |
5754 | interactive shells after reading a command and before the command |
5755 | is executed. | |
5756 | ||
5757 | 'PS3' | |
5758 | The value of this variable is used as the prompt for the 'select' | |
5759 | command. If this variable is not set, the 'select' command prompts | |
5760 | with '#? ' | |
5761 | ||
5762 | 'PS4' | |
74091dd4 | 5763 | The value of this parameter is expanded like 'PS1' and the expanded |
d233b485 CR |
5764 | value is the prompt printed before the command line is echoed when |
5765 | the '-x' option is set (*note The Set Builtin::). The first | |
5766 | character of the expanded value is replicated multiple times, as | |
5767 | necessary, to indicate multiple levels of indirection. The default | |
5768 | is '+ '. | |
a0c0a00f CR |
5769 | |
5770 | 'PWD' | |
5771 | The current working directory as set by the 'cd' builtin. | |
5772 | ||
5773 | 'RANDOM' | |
8868edaf CR |
5774 | Each time this parameter is referenced, it expands to a random |
5775 | integer between 0 and 32767. Assigning a value to this variable | |
5776 | seeds the random number generator. If 'RANDOM' is unset, it loses | |
5777 | its special properties, even if it is subsequently reset. | |
a0c0a00f | 5778 | |
74091dd4 CR |
5779 | 'READLINE_ARGUMENT' |
5780 | Any numeric argument given to a Readline command that was defined | |
5781 | using 'bind -x' (*note Bash Builtins:: when it was invoked. | |
5782 | ||
a0c0a00f CR |
5783 | 'READLINE_LINE' |
5784 | The contents of the Readline line buffer, for use with 'bind -x' | |
5785 | (*note Bash Builtins::). | |
5786 | ||
8868edaf | 5787 | 'READLINE_MARK' |
74091dd4 | 5788 | The position of the "mark" (saved insertion point) in the Readline |
8868edaf CR |
5789 | line buffer, for use with 'bind -x' (*note Bash Builtins::). The |
5790 | characters between the insertion point and the mark are often | |
74091dd4 | 5791 | called the "region". |
8868edaf | 5792 | |
a0c0a00f CR |
5793 | 'READLINE_POINT' |
5794 | The position of the insertion point in the Readline line buffer, | |
5795 | for use with 'bind -x' (*note Bash Builtins::). | |
5796 | ||
5797 | 'REPLY' | |
5798 | The default variable for the 'read' builtin. | |
5799 | ||
5800 | 'SECONDS' | |
5801 | This variable expands to the number of seconds since the shell was | |
5802 | started. Assignment to this variable resets the count to the value | |
5803 | assigned, and the expanded value becomes the value assigned plus | |
8868edaf | 5804 | the number of seconds since the assignment. The number of seconds |
74091dd4 | 5805 | at shell invocation and the current time are always determined by |
8868edaf CR |
5806 | querying the system clock. If 'SECONDS' is unset, it loses its |
5807 | special properties, even if it is subsequently reset. | |
a0c0a00f CR |
5808 | |
5809 | 'SHELL' | |
8868edaf CR |
5810 | This environment variable expands to the full pathname to the |
5811 | shell. If it is not set when the shell starts, Bash assigns to it | |
5812 | the full pathname of the current user's login shell. | |
a0c0a00f CR |
5813 | |
5814 | 'SHELLOPTS' | |
5815 | A colon-separated list of enabled shell options. Each word in the | |
5816 | list is a valid argument for the '-o' option to the 'set' builtin | |
5817 | command (*note The Set Builtin::). The options appearing in | |
5818 | 'SHELLOPTS' are those reported as 'on' by 'set -o'. If this | |
5819 | variable is in the environment when Bash starts up, each shell | |
5820 | option in the list will be enabled before reading any startup | |
5821 | files. This variable is readonly. | |
5822 | ||
5823 | 'SHLVL' | |
5824 | Incremented by one each time a new instance of Bash is started. | |
5825 | This is intended to be a count of how deeply your Bash shells are | |
5826 | nested. | |
5827 | ||
8868edaf CR |
5828 | 'SRANDOM' |
5829 | This variable expands to a 32-bit pseudo-random number each time it | |
5830 | is referenced. The random number generator is not linear on | |
5831 | systems that support '/dev/urandom' or 'arc4random', so each | |
5832 | returned number has no relationship to the numbers preceding it. | |
5833 | The random number generator cannot be seeded, so assignments to | |
5834 | this variable have no effect. If 'SRANDOM' is unset, it loses its | |
5835 | special properties, even if it is subsequently reset. | |
5836 | ||
a0c0a00f CR |
5837 | 'TIMEFORMAT' |
5838 | The value of this parameter is used as a format string specifying | |
5839 | how the timing information for pipelines prefixed with the 'time' | |
5840 | reserved word should be displayed. The '%' character introduces an | |
5841 | escape sequence that is expanded to a time value or other | |
5842 | information. The escape sequences and their meanings are as | |
5843 | follows; the braces denote optional portions. | |
5844 | ||
5845 | '%%' | |
5846 | A literal '%'. | |
5847 | ||
5848 | '%[P][l]R' | |
5849 | The elapsed time in seconds. | |
5850 | ||
5851 | '%[P][l]U' | |
5852 | The number of CPU seconds spent in user mode. | |
5853 | ||
5854 | '%[P][l]S' | |
5855 | The number of CPU seconds spent in system mode. | |
5856 | ||
5857 | '%P' | |
5858 | The CPU percentage, computed as (%U + %S) / %R. | |
5859 | ||
5860 | The optional P is a digit specifying the precision, the number of | |
5861 | fractional digits after a decimal point. A value of 0 causes no | |
5862 | decimal point or fraction to be output. At most three places after | |
5863 | the decimal point may be specified; values of P greater than 3 are | |
5864 | changed to 3. If P is not specified, the value 3 is used. | |
5865 | ||
5866 | The optional 'l' specifies a longer format, including minutes, of | |
5867 | the form MMmSS.FFs. The value of P determines whether or not the | |
5868 | fraction is included. | |
5869 | ||
5870 | If this variable is not set, Bash acts as if it had the value | |
5871 | $'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS' | |
5872 | If the value is null, no timing information is displayed. A | |
5873 | trailing newline is added when the format string is displayed. | |
5874 | ||
5875 | 'TMOUT' | |
5876 | If set to a value greater than zero, 'TMOUT' is treated as the | |
5877 | default timeout for the 'read' builtin (*note Bash Builtins::). | |
5878 | The 'select' command (*note Conditional Constructs::) terminates if | |
5879 | input does not arrive after 'TMOUT' seconds when input is coming | |
5880 | from a terminal. | |
5881 | ||
5882 | In an interactive shell, the value is interpreted as the number of | |
5883 | seconds to wait for a line of input after issuing the primary | |
5884 | prompt. Bash terminates after waiting for that number of seconds | |
5885 | if a complete line of input does not arrive. | |
5886 | ||
5887 | 'TMPDIR' | |
5888 | If set, Bash uses its value as the name of a directory in which | |
5889 | Bash creates temporary files for the shell's use. | |
5890 | ||
5891 | 'UID' | |
5892 | The numeric real user id of the current user. This variable is | |
5893 | readonly. | |
5894 | ||
5895 | \1f | |
5896 | File: bash.info, Node: Bash Features, Next: Job Control, Prev: Shell Variables, Up: Top | |
5897 | ||
5898 | 6 Bash Features | |
5899 | *************** | |
5900 | ||
5901 | This chapter describes features unique to Bash. | |
5902 | ||
5903 | * Menu: | |
5904 | ||
5905 | * Invoking Bash:: Command line options that you can give | |
5906 | to Bash. | |
5907 | * Bash Startup Files:: When and how Bash executes scripts. | |
5908 | * Interactive Shells:: What an interactive shell is. | |
5909 | * Bash Conditional Expressions:: Primitives used in composing expressions for | |
5910 | the 'test' builtin. | |
5911 | * Shell Arithmetic:: Arithmetic on shell variables. | |
5912 | * Aliases:: Substituting one command for another. | |
5913 | * Arrays:: Array Variables. | |
5914 | * The Directory Stack:: History of visited directories. | |
5915 | * Controlling the Prompt:: Customizing the various prompt strings. | |
5916 | * The Restricted Shell:: A more controlled mode of shell execution. | |
5917 | * Bash POSIX Mode:: Making Bash behave more closely to what | |
5918 | the POSIX standard specifies. | |
8868edaf CR |
5919 | * Shell Compatibility Mode:: How Bash supports behavior that was present |
5920 | in earlier versions and has changed. | |
a0c0a00f CR |
5921 | |
5922 | \1f | |
5923 | File: bash.info, Node: Invoking Bash, Next: Bash Startup Files, Up: Bash Features | |
5924 | ||
5925 | 6.1 Invoking Bash | |
5926 | ================= | |
5927 | ||
d233b485 CR |
5928 | bash [long-opt] [-ir] [-abefhkmnptuvxdBCDHP] [-o OPTION] |
5929 | [-O SHOPT_OPTION] [ARGUMENT ...] | |
5930 | bash [long-opt] [-abefhkmnptuvxdBCDHP] [-o OPTION] | |
5931 | [-O SHOPT_OPTION] -c STRING [ARGUMENT ...] | |
5932 | bash [long-opt] -s [-abefhkmnptuvxdBCDHP] [-o OPTION] | |
5933 | [-O SHOPT_OPTION] [ARGUMENT ...] | |
a0c0a00f CR |
5934 | |
5935 | All of the single-character options used with the 'set' builtin | |
5936 | (*note The Set Builtin::) can be used as options when the shell is | |
5937 | invoked. In addition, there are several multi-character options that | |
5938 | you can use. These options must appear on the command line before the | |
5939 | single-character options to be recognized. | |
5940 | ||
5941 | '--debugger' | |
5942 | Arrange for the debugger profile to be executed before the shell | |
5943 | starts. Turns on extended debugging mode (see *note The Shopt | |
5944 | Builtin:: for a description of the 'extdebug' option to the 'shopt' | |
5945 | builtin). | |
5946 | ||
5947 | '--dump-po-strings' | |
5948 | A list of all double-quoted strings preceded by '$' is printed on | |
5949 | the standard output in the GNU 'gettext' PO (portable object) file | |
5950 | format. Equivalent to '-D' except for the output format. | |
5951 | ||
5952 | '--dump-strings' | |
5953 | Equivalent to '-D'. | |
5954 | ||
5955 | '--help' | |
5956 | Display a usage message on standard output and exit successfully. | |
5957 | ||
5958 | '--init-file FILENAME' | |
5959 | '--rcfile FILENAME' | |
5960 | Execute commands from FILENAME (instead of '~/.bashrc') in an | |
5961 | interactive shell. | |
5962 | ||
5963 | '--login' | |
5964 | Equivalent to '-l'. | |
5965 | ||
5966 | '--noediting' | |
5967 | Do not use the GNU Readline library (*note Command Line Editing::) | |
5968 | to read command lines when the shell is interactive. | |
5969 | ||
5970 | '--noprofile' | |
5971 | Don't load the system-wide startup file '/etc/profile' or any of | |
5972 | the personal initialization files '~/.bash_profile', | |
5973 | '~/.bash_login', or '~/.profile' when Bash is invoked as a login | |
5974 | shell. | |
5975 | ||
5976 | '--norc' | |
5977 | Don't read the '~/.bashrc' initialization file in an interactive | |
5978 | shell. This is on by default if the shell is invoked as 'sh'. | |
5979 | ||
5980 | '--posix' | |
5981 | Change the behavior of Bash where the default operation differs | |
5982 | from the POSIX standard to match the standard. This is intended to | |
5983 | make Bash behave as a strict superset of that standard. *Note Bash | |
5984 | POSIX Mode::, for a description of the Bash POSIX mode. | |
5985 | ||
5986 | '--restricted' | |
5987 | Make the shell a restricted shell (*note The Restricted Shell::). | |
5988 | ||
5989 | '--verbose' | |
5990 | Equivalent to '-v'. Print shell input lines as they're read. | |
5991 | ||
5992 | '--version' | |
5993 | Show version information for this instance of Bash on the standard | |
5994 | output and exit successfully. | |
5995 | ||
5996 | There are several single-character options that may be supplied at | |
5997 | invocation which are not available with the 'set' builtin. | |
5998 | ||
5999 | '-c' | |
6000 | Read and execute commands from the first non-option argument | |
6001 | COMMAND_STRING, then exit. If there are arguments after the | |
6002 | COMMAND_STRING, the first argument is assigned to '$0' and any | |
6003 | remaining arguments are assigned to the positional parameters. The | |
6004 | assignment to '$0' sets the name of the shell, which is used in | |
6005 | warning and error messages. | |
6006 | ||
6007 | '-i' | |
6008 | Force the shell to run interactively. Interactive shells are | |
6009 | described in *note Interactive Shells::. | |
6010 | ||
6011 | '-l' | |
6012 | Make this shell act as if it had been directly invoked by login. | |
6013 | When the shell is interactive, this is equivalent to starting a | |
6014 | login shell with 'exec -l bash'. When the shell is not | |
6015 | interactive, the login shell startup files will be executed. 'exec | |
6016 | bash -l' or 'exec bash --login' will replace the current shell with | |
6017 | a Bash login shell. *Note Bash Startup Files::, for a description | |
6018 | of the special behavior of a login shell. | |
6019 | ||
6020 | '-r' | |
6021 | Make the shell a restricted shell (*note The Restricted Shell::). | |
6022 | ||
6023 | '-s' | |
6024 | If this option is present, or if no arguments remain after option | |
6025 | processing, then commands are read from the standard input. This | |
6026 | option allows the positional parameters to be set when invoking an | |
d233b485 | 6027 | interactive shell or when reading input through a pipe. |
a0c0a00f CR |
6028 | |
6029 | '-D' | |
6030 | A list of all double-quoted strings preceded by '$' is printed on | |
6031 | the standard output. These are the strings that are subject to | |
6032 | language translation when the current locale is not 'C' or 'POSIX' | |
6033 | (*note Locale Translation::). This implies the '-n' option; no | |
6034 | commands will be executed. | |
6035 | ||
6036 | '[-+]O [SHOPT_OPTION]' | |
6037 | SHOPT_OPTION is one of the shell options accepted by the 'shopt' | |
6038 | builtin (*note The Shopt Builtin::). If SHOPT_OPTION is present, | |
6039 | '-O' sets the value of that option; '+O' unsets it. If | |
6040 | SHOPT_OPTION is not supplied, the names and values of the shell | |
6041 | options accepted by 'shopt' are printed on the standard output. If | |
6042 | the invocation option is '+O', the output is displayed in a format | |
6043 | that may be reused as input. | |
6044 | ||
6045 | '--' | |
6046 | A '--' signals the end of options and disables further option | |
6047 | processing. Any arguments after the '--' are treated as filenames | |
6048 | and arguments. | |
6049 | ||
6050 | A _login_ shell is one whose first character of argument zero is '-', | |
6051 | or one invoked with the '--login' option. | |
6052 | ||
6053 | An _interactive_ shell is one started without non-option arguments, | |
6054 | unless '-s' is specified, without specifying the '-c' option, and whose | |
6055 | input and output are both connected to terminals (as determined by | |
6056 | 'isatty(3)'), or one started with the '-i' option. *Note Interactive | |
6057 | Shells::, for more information. | |
6058 | ||
6059 | If arguments remain after option processing, and neither the '-c' nor | |
6060 | the '-s' option has been supplied, the first argument is assumed to be | |
6061 | the name of a file containing shell commands (*note Shell Scripts::). | |
6062 | When Bash is invoked in this fashion, '$0' is set to the name of the | |
6063 | file, and the positional parameters are set to the remaining arguments. | |
6064 | Bash reads and executes commands from this file, then exits. Bash's | |
6065 | exit status is the exit status of the last command executed in the | |
6066 | script. If no commands are executed, the exit status is 0. | |
6067 | ||
6068 | \1f | |
6069 | File: bash.info, Node: Bash Startup Files, Next: Interactive Shells, Prev: Invoking Bash, Up: Bash Features | |
6070 | ||
6071 | 6.2 Bash Startup Files | |
6072 | ====================== | |
6073 | ||
6074 | This section describes how Bash executes its startup files. If any of | |
6075 | the files exist but cannot be read, Bash reports an error. Tildes are | |
6076 | expanded in filenames as described above under Tilde Expansion (*note | |
6077 | Tilde Expansion::). | |
6078 | ||
6079 | Interactive shells are described in *note Interactive Shells::. | |
6080 | ||
6081 | Invoked as an interactive login shell, or with '--login' | |
6082 | ........................................................ | |
6083 | ||
6084 | When Bash is invoked as an interactive login shell, or as a | |
6085 | non-interactive shell with the '--login' option, it first reads and | |
6086 | executes commands from the file '/etc/profile', if that file exists. | |
6087 | After reading that file, it looks for '~/.bash_profile', | |
6088 | '~/.bash_login', and '~/.profile', in that order, and reads and executes | |
6089 | commands from the first one that exists and is readable. The | |
6090 | '--noprofile' option may be used when the shell is started to inhibit | |
6091 | this behavior. | |
6092 | ||
6093 | When an interactive login shell exits, or a non-interactive login | |
6094 | shell executes the 'exit' builtin command, Bash reads and executes | |
6095 | commands from the file '~/.bash_logout', if it exists. | |
6096 | ||
6097 | Invoked as an interactive non-login shell | |
6098 | ......................................... | |
6099 | ||
6100 | When an interactive shell that is not a login shell is started, Bash | |
6101 | reads and executes commands from '~/.bashrc', if that file exists. This | |
6102 | may be inhibited by using the '--norc' option. The '--rcfile FILE' | |
6103 | option will force Bash to read and execute commands from FILE instead of | |
6104 | '~/.bashrc'. | |
6105 | ||
6106 | So, typically, your '~/.bash_profile' contains the line | |
6107 | if [ -f ~/.bashrc ]; then . ~/.bashrc; fi | |
6108 | after (or before) any login-specific initializations. | |
6109 | ||
6110 | Invoked non-interactively | |
6111 | ......................... | |
6112 | ||
6113 | When Bash is started non-interactively, to run a shell script, for | |
6114 | example, it looks for the variable 'BASH_ENV' in the environment, | |
6115 | expands its value if it appears there, and uses the expanded value as | |
6116 | the name of a file to read and execute. Bash behaves as if the | |
6117 | following command were executed: | |
6118 | if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi | |
6119 | but the value of the 'PATH' variable is not used to search for the | |
6120 | filename. | |
6121 | ||
6122 | As noted above, if a non-interactive shell is invoked with the | |
6123 | '--login' option, Bash attempts to read and execute commands from the | |
6124 | login shell startup files. | |
6125 | ||
6126 | Invoked with name 'sh' | |
6127 | ...................... | |
6128 | ||
6129 | If Bash is invoked with the name 'sh', it tries to mimic the startup | |
6130 | behavior of historical versions of 'sh' as closely as possible, while | |
6131 | conforming to the POSIX standard as well. | |
6132 | ||
6133 | When invoked as an interactive login shell, or as a non-interactive | |
6134 | shell with the '--login' option, it first attempts to read and execute | |
6135 | commands from '/etc/profile' and '~/.profile', in that order. The | |
6136 | '--noprofile' option may be used to inhibit this behavior. When invoked | |
6137 | as an interactive shell with the name 'sh', Bash looks for the variable | |
6138 | 'ENV', expands its value if it is defined, and uses the expanded value | |
6139 | as the name of a file to read and execute. Since a shell invoked as | |
6140 | 'sh' does not attempt to read and execute commands from any other | |
6141 | startup files, the '--rcfile' option has no effect. A non-interactive | |
6142 | shell invoked with the name 'sh' does not attempt to read any other | |
6143 | startup files. | |
6144 | ||
6145 | When invoked as 'sh', Bash enters POSIX mode after the startup files | |
6146 | are read. | |
6147 | ||
6148 | Invoked in POSIX mode | |
6149 | ..................... | |
6150 | ||
6151 | When Bash is started in POSIX mode, as with the '--posix' command line | |
6152 | option, it follows the POSIX standard for startup files. In this mode, | |
6153 | interactive shells expand the 'ENV' variable and commands are read and | |
6154 | executed from the file whose name is the expanded value. No other | |
6155 | startup files are read. | |
6156 | ||
6157 | Invoked by remote shell daemon | |
6158 | .............................. | |
6159 | ||
6160 | Bash attempts to determine when it is being run with its standard input | |
74091dd4 CR |
6161 | connected to a network connection, as when executed by the historical |
6162 | remote shell daemon, usually 'rshd', or the secure shell daemon 'sshd'. | |
6163 | If Bash determines it is being run non-interactively in this fashion, it | |
6164 | reads and executes commands from '~/.bashrc', if that file exists and is | |
6165 | readable. It will not do this if invoked as 'sh'. The '--norc' option | |
6166 | may be used to inhibit this behavior, and the '--rcfile' option may be | |
6167 | used to force another file to be read, but neither 'rshd' nor 'sshd' | |
6168 | generally invoke the shell with those options or allow them to be | |
6169 | specified. | |
a0c0a00f CR |
6170 | |
6171 | Invoked with unequal effective and real UID/GIDs | |
6172 | ................................................ | |
6173 | ||
6174 | If Bash is started with the effective user (group) id not equal to the | |
6175 | real user (group) id, and the '-p' option is not supplied, no startup | |
6176 | files are read, shell functions are not inherited from the environment, | |
6177 | the 'SHELLOPTS', 'BASHOPTS', 'CDPATH', and 'GLOBIGNORE' variables, if | |
6178 | they appear in the environment, are ignored, and the effective user id | |
6179 | is set to the real user id. If the '-p' option is supplied at | |
6180 | invocation, the startup behavior is the same, but the effective user id | |
6181 | is not reset. | |
6182 | ||
6183 | \1f | |
6184 | File: bash.info, Node: Interactive Shells, Next: Bash Conditional Expressions, Prev: Bash Startup Files, Up: Bash Features | |
6185 | ||
6186 | 6.3 Interactive Shells | |
6187 | ====================== | |
6188 | ||
6189 | * Menu: | |
6190 | ||
6191 | * What is an Interactive Shell?:: What determines whether a shell is Interactive. | |
6192 | * Is this Shell Interactive?:: How to tell if a shell is interactive. | |
74091dd4 | 6193 | * Interactive Shell Behavior:: What changes in an interactive shell? |
a0c0a00f CR |
6194 | |
6195 | \1f | |
6196 | File: bash.info, Node: What is an Interactive Shell?, Next: Is this Shell Interactive?, Up: Interactive Shells | |
6197 | ||
6198 | 6.3.1 What is an Interactive Shell? | |
6199 | ----------------------------------- | |
6200 | ||
74091dd4 CR |
6201 | An interactive shell is one started without non-option arguments (unless |
6202 | '-s' is specified) and without specifying the '-c' option, whose input | |
a0c0a00f CR |
6203 | and error output are both connected to terminals (as determined by |
6204 | 'isatty(3)'), or one started with the '-i' option. | |
6205 | ||
6206 | An interactive shell generally reads from and writes to a user's | |
6207 | terminal. | |
6208 | ||
6209 | The '-s' invocation option may be used to set the positional | |
6210 | parameters when an interactive shell is started. | |
6211 | ||
6212 | \1f | |
6213 | File: bash.info, Node: Is this Shell Interactive?, Next: Interactive Shell Behavior, Prev: What is an Interactive Shell?, Up: Interactive Shells | |
6214 | ||
6215 | 6.3.2 Is this Shell Interactive? | |
6216 | -------------------------------- | |
6217 | ||
6218 | To determine within a startup script whether or not Bash is running | |
6219 | interactively, test the value of the '-' special parameter. It contains | |
6220 | 'i' when the shell is interactive. For example: | |
6221 | ||
6222 | case "$-" in | |
6223 | *i*) echo This shell is interactive ;; | |
6224 | *) echo This shell is not interactive ;; | |
6225 | esac | |
6226 | ||
6227 | Alternatively, startup scripts may examine the variable 'PS1'; it is | |
6228 | unset in non-interactive shells, and set in interactive shells. Thus: | |
6229 | ||
6230 | if [ -z "$PS1" ]; then | |
6231 | echo This shell is not interactive | |
6232 | else | |
6233 | echo This shell is interactive | |
6234 | fi | |
6235 | ||
6236 | \1f | |
6237 | File: bash.info, Node: Interactive Shell Behavior, Prev: Is this Shell Interactive?, Up: Interactive Shells | |
6238 | ||
6239 | 6.3.3 Interactive Shell Behavior | |
6240 | -------------------------------- | |
6241 | ||
6242 | When the shell is running interactively, it changes its behavior in | |
6243 | several ways. | |
6244 | ||
6245 | 1. Startup files are read and executed as described in *note Bash | |
6246 | Startup Files::. | |
6247 | ||
6248 | 2. Job Control (*note Job Control::) is enabled by default. When job | |
6249 | control is in effect, Bash ignores the keyboard-generated job | |
6250 | control signals 'SIGTTIN', 'SIGTTOU', and 'SIGTSTP'. | |
6251 | ||
6252 | 3. Bash expands and displays 'PS1' before reading the first line of a | |
6253 | command, and expands and displays 'PS2' before reading the second | |
d233b485 CR |
6254 | and subsequent lines of a multi-line command. Bash expands and |
6255 | displays 'PS0' after it reads a command but before executing it. | |
6256 | See *note Controlling the Prompt::, for a complete list of prompt | |
6257 | string escape sequences. | |
a0c0a00f | 6258 | |
8868edaf | 6259 | 4. Bash executes the values of the set elements of the |
74091dd4 | 6260 | 'PROMPT_COMMAND' array variable as commands before printing the |
8868edaf | 6261 | primary prompt, '$PS1' (*note Bash Variables::). |
a0c0a00f CR |
6262 | |
6263 | 5. Readline (*note Command Line Editing::) is used to read commands | |
6264 | from the user's terminal. | |
6265 | ||
6266 | 6. Bash inspects the value of the 'ignoreeof' option to 'set -o' | |
6267 | instead of exiting immediately when it receives an 'EOF' on its | |
6268 | standard input when reading a command (*note The Set Builtin::). | |
6269 | ||
6270 | 7. Command history (*note Bash History Facilities::) and history | |
6271 | expansion (*note History Interaction::) are enabled by default. | |
6272 | Bash will save the command history to the file named by '$HISTFILE' | |
6273 | when a shell with history enabled exits. | |
6274 | ||
6275 | 8. Alias expansion (*note Aliases::) is performed by default. | |
6276 | ||
6277 | 9. In the absence of any traps, Bash ignores 'SIGTERM' (*note | |
6278 | Signals::). | |
6279 | ||
d233b485 CR |
6280 | 10. In the absence of any traps, 'SIGINT' is caught and handled (*note |
6281 | Signals::). 'SIGINT' will interrupt some shell builtins. | |
a0c0a00f CR |
6282 | |
6283 | 11. An interactive login shell sends a 'SIGHUP' to all jobs on exit if | |
6284 | the 'huponexit' shell option has been enabled (*note Signals::). | |
6285 | ||
6286 | 12. The '-n' invocation option is ignored, and 'set -n' has no effect | |
6287 | (*note The Set Builtin::). | |
6288 | ||
6289 | 13. Bash will check for mail periodically, depending on the values of | |
6290 | the 'MAIL', 'MAILPATH', and 'MAILCHECK' shell variables (*note Bash | |
6291 | Variables::). | |
6292 | ||
6293 | 14. Expansion errors due to references to unbound shell variables | |
6294 | after 'set -u' has been enabled will not cause the shell to exit | |
6295 | (*note The Set Builtin::). | |
6296 | ||
6297 | 15. The shell will not exit on expansion errors caused by VAR being | |
6298 | unset or null in '${VAR:?WORD}' expansions (*note Shell Parameter | |
6299 | Expansion::). | |
6300 | ||
6301 | 16. Redirection errors encountered by shell builtins will not cause | |
6302 | the shell to exit. | |
6303 | ||
6304 | 17. When running in POSIX mode, a special builtin returning an error | |
6305 | status will not cause the shell to exit (*note Bash POSIX Mode::). | |
6306 | ||
6307 | 18. A failed 'exec' will not cause the shell to exit (*note Bourne | |
6308 | Shell Builtins::). | |
6309 | ||
6310 | 19. Parser syntax errors will not cause the shell to exit. | |
6311 | ||
74091dd4 CR |
6312 | 20. If the 'cdspell' shell option is enabled, the shell will attempt |
6313 | simple spelling correction for directory arguments to the 'cd' | |
6314 | builtin (see the description of the 'cdspell' option to the 'shopt' | |
6315 | builtin in *note The Shopt Builtin::). The 'cdspell' option is | |
6316 | only effective in interactive shells. | |
a0c0a00f CR |
6317 | |
6318 | 21. The shell will check the value of the 'TMOUT' variable and exit if | |
6319 | a command is not read within the specified number of seconds after | |
6320 | printing '$PS1' (*note Bash Variables::). | |
6321 | ||
6322 | \1f | |
6323 | File: bash.info, Node: Bash Conditional Expressions, Next: Shell Arithmetic, Prev: Interactive Shells, Up: Bash Features | |
6324 | ||
6325 | 6.4 Bash Conditional Expressions | |
6326 | ================================ | |
6327 | ||
74091dd4 CR |
6328 | Conditional expressions are used by the '[[' compound command (*note |
6329 | Conditional Constructs::) and the 'test' and '[' builtin commands (*note | |
6330 | Bourne Shell Builtins::). The 'test' and '[' commands determine their | |
6331 | behavior based on the number of arguments; see the descriptions of those | |
6332 | commands for any other command-specific actions. | |
d233b485 CR |
6333 | |
6334 | Expressions may be unary or binary, and are formed from the following | |
6335 | primaries. Unary expressions are often used to examine the status of a | |
6336 | file. There are string operators and numeric comparison operators as | |
6337 | well. Bash handles several filenames specially when they are used in | |
6338 | expressions. If the operating system on which Bash is running provides | |
6339 | these special files, Bash will use them; otherwise it will emulate them | |
6340 | internally with this behavior: If the FILE argument to one of the | |
6341 | primaries is of the form '/dev/fd/N', then file descriptor N is checked. | |
6342 | If the FILE argument to one of the primaries is one of '/dev/stdin', | |
6343 | '/dev/stdout', or '/dev/stderr', file descriptor 0, 1, or 2, | |
6344 | respectively, is checked. | |
a0c0a00f CR |
6345 | |
6346 | When used with '[[', the '<' and '>' operators sort lexicographically | |
6347 | using the current locale. The 'test' command uses ASCII ordering. | |
6348 | ||
6349 | Unless otherwise specified, primaries that operate on files follow | |
6350 | symbolic links and operate on the target of the link, rather than the | |
6351 | link itself. | |
6352 | ||
6353 | '-a FILE' | |
6354 | True if FILE exists. | |
6355 | ||
6356 | '-b FILE' | |
6357 | True if FILE exists and is a block special file. | |
6358 | ||
6359 | '-c FILE' | |
6360 | True if FILE exists and is a character special file. | |
6361 | ||
6362 | '-d FILE' | |
6363 | True if FILE exists and is a directory. | |
6364 | ||
6365 | '-e FILE' | |
6366 | True if FILE exists. | |
6367 | ||
6368 | '-f FILE' | |
6369 | True if FILE exists and is a regular file. | |
6370 | ||
6371 | '-g FILE' | |
6372 | True if FILE exists and its set-group-id bit is set. | |
6373 | ||
6374 | '-h FILE' | |
6375 | True if FILE exists and is a symbolic link. | |
6376 | ||
6377 | '-k FILE' | |
6378 | True if FILE exists and its "sticky" bit is set. | |
6379 | ||
6380 | '-p FILE' | |
6381 | True if FILE exists and is a named pipe (FIFO). | |
6382 | ||
6383 | '-r FILE' | |
6384 | True if FILE exists and is readable. | |
6385 | ||
6386 | '-s FILE' | |
6387 | True if FILE exists and has a size greater than zero. | |
6388 | ||
6389 | '-t FD' | |
6390 | True if file descriptor FD is open and refers to a terminal. | |
6391 | ||
6392 | '-u FILE' | |
6393 | True if FILE exists and its set-user-id bit is set. | |
6394 | ||
6395 | '-w FILE' | |
6396 | True if FILE exists and is writable. | |
6397 | ||
6398 | '-x FILE' | |
6399 | True if FILE exists and is executable. | |
6400 | ||
6401 | '-G FILE' | |
6402 | True if FILE exists and is owned by the effective group id. | |
6403 | ||
6404 | '-L FILE' | |
6405 | True if FILE exists and is a symbolic link. | |
6406 | ||
6407 | '-N FILE' | |
6408 | True if FILE exists and has been modified since it was last read. | |
6409 | ||
6410 | '-O FILE' | |
6411 | True if FILE exists and is owned by the effective user id. | |
6412 | ||
6413 | '-S FILE' | |
6414 | True if FILE exists and is a socket. | |
6415 | ||
6416 | 'FILE1 -ef FILE2' | |
6417 | True if FILE1 and FILE2 refer to the same device and inode numbers. | |
6418 | ||
6419 | 'FILE1 -nt FILE2' | |
6420 | True if FILE1 is newer (according to modification date) than FILE2, | |
6421 | or if FILE1 exists and FILE2 does not. | |
6422 | ||
6423 | 'FILE1 -ot FILE2' | |
6424 | True if FILE1 is older than FILE2, or if FILE2 exists and FILE1 | |
6425 | does not. | |
6426 | ||
6427 | '-o OPTNAME' | |
6428 | True if the shell option OPTNAME is enabled. The list of options | |
6429 | appears in the description of the '-o' option to the 'set' builtin | |
6430 | (*note The Set Builtin::). | |
6431 | ||
6432 | '-v VARNAME' | |
6433 | True if the shell variable VARNAME is set (has been assigned a | |
6434 | value). | |
6435 | ||
6436 | '-R VARNAME' | |
6437 | True if the shell variable VARNAME is set and is a name reference. | |
6438 | ||
6439 | '-z STRING' | |
6440 | True if the length of STRING is zero. | |
6441 | ||
6442 | '-n STRING' | |
6443 | 'STRING' | |
6444 | True if the length of STRING is non-zero. | |
6445 | ||
6446 | 'STRING1 == STRING2' | |
6447 | 'STRING1 = STRING2' | |
6448 | True if the strings are equal. When used with the '[[' command, | |
6449 | this performs pattern matching as described above (*note | |
6450 | Conditional Constructs::). | |
6451 | ||
6452 | '=' should be used with the 'test' command for POSIX conformance. | |
6453 | ||
6454 | 'STRING1 != STRING2' | |
6455 | True if the strings are not equal. | |
6456 | ||
6457 | 'STRING1 < STRING2' | |
6458 | True if STRING1 sorts before STRING2 lexicographically. | |
6459 | ||
6460 | 'STRING1 > STRING2' | |
6461 | True if STRING1 sorts after STRING2 lexicographically. | |
6462 | ||
6463 | 'ARG1 OP ARG2' | |
6464 | 'OP' is one of '-eq', '-ne', '-lt', '-le', '-gt', or '-ge'. These | |
6465 | arithmetic binary operators return true if ARG1 is equal to, not | |
6466 | equal to, less than, less than or equal to, greater than, or | |
6467 | greater than or equal to ARG2, respectively. ARG1 and ARG2 may be | |
d233b485 CR |
6468 | positive or negative integers. When used with the '[[' command, |
6469 | ARG1 and ARG2 are evaluated as arithmetic expressions (*note Shell | |
6470 | Arithmetic::). | |
a0c0a00f CR |
6471 | |
6472 | \1f | |
6473 | File: bash.info, Node: Shell Arithmetic, Next: Aliases, Prev: Bash Conditional Expressions, Up: Bash Features | |
6474 | ||
6475 | 6.5 Shell Arithmetic | |
6476 | ==================== | |
6477 | ||
6478 | The shell allows arithmetic expressions to be evaluated, as one of the | |
6479 | shell expansions or by using the '((' compound command, the 'let' | |
6480 | builtin, or the '-i' option to the 'declare' builtin. | |
6481 | ||
6482 | Evaluation is done in fixed-width integers with no check for | |
6483 | overflow, though division by 0 is trapped and flagged as an error. The | |
6484 | operators and their precedence, associativity, and values are the same | |
6485 | as in the C language. The following list of operators is grouped into | |
6486 | levels of equal-precedence operators. The levels are listed in order of | |
6487 | decreasing precedence. | |
6488 | ||
6489 | 'ID++ ID--' | |
6490 | variable post-increment and post-decrement | |
6491 | ||
6492 | '++ID --ID' | |
6493 | variable pre-increment and pre-decrement | |
6494 | ||
6495 | '- +' | |
6496 | unary minus and plus | |
6497 | ||
6498 | '! ~' | |
6499 | logical and bitwise negation | |
6500 | ||
6501 | '**' | |
6502 | exponentiation | |
6503 | ||
6504 | '* / %' | |
6505 | multiplication, division, remainder | |
6506 | ||
6507 | '+ -' | |
6508 | addition, subtraction | |
6509 | ||
6510 | '<< >>' | |
6511 | left and right bitwise shifts | |
6512 | ||
6513 | '<= >= < >' | |
6514 | comparison | |
6515 | ||
6516 | '== !=' | |
6517 | equality and inequality | |
6518 | ||
6519 | '&' | |
6520 | bitwise AND | |
6521 | ||
6522 | '^' | |
6523 | bitwise exclusive OR | |
6524 | ||
6525 | '|' | |
6526 | bitwise OR | |
6527 | ||
6528 | '&&' | |
6529 | logical AND | |
6530 | ||
6531 | '||' | |
6532 | logical OR | |
6533 | ||
6534 | 'expr ? expr : expr' | |
6535 | conditional operator | |
6536 | ||
6537 | '= *= /= %= += -= <<= >>= &= ^= |=' | |
6538 | assignment | |
6539 | ||
6540 | 'expr1 , expr2' | |
6541 | comma | |
6542 | ||
6543 | Shell variables are allowed as operands; parameter expansion is | |
6544 | performed before the expression is evaluated. Within an expression, | |
6545 | shell variables may also be referenced by name without using the | |
6546 | parameter expansion syntax. A shell variable that is null or unset | |
6547 | evaluates to 0 when referenced by name without using the parameter | |
6548 | expansion syntax. The value of a variable is evaluated as an arithmetic | |
6549 | expression when it is referenced, or when a variable which has been | |
74091dd4 CR |
6550 | given the 'integer' attribute using 'declare -i' is assigned a value. A |
6551 | null value evaluates to 0. A shell variable need not have its 'integer' | |
a0c0a00f CR |
6552 | attribute turned on to be used in an expression. |
6553 | ||
8868edaf CR |
6554 | Integer constants follow the C language definition, without suffixes |
6555 | or character constants. Constants with a leading 0 are interpreted as | |
6556 | octal numbers. A leading '0x' or '0X' denotes hexadecimal. Otherwise, | |
6557 | numbers take the form [BASE'#']N, where the optional BASE is a decimal | |
6558 | number between 2 and 64 representing the arithmetic base, and N is a | |
6559 | number in that base. If BASE'#' is omitted, then base 10 is used. When | |
6560 | specifying N, if a non-digit is required, the digits greater than 9 are | |
6561 | represented by the lowercase letters, the uppercase letters, '@', and | |
6562 | '_', in that order. If BASE is less than or equal to 36, lowercase and | |
6563 | uppercase letters may be used interchangeably to represent numbers | |
6564 | between 10 and 35. | |
a0c0a00f CR |
6565 | |
6566 | Operators are evaluated in order of precedence. Sub-expressions in | |
6567 | parentheses are evaluated first and may override the precedence rules | |
6568 | above. | |
6569 | ||
6570 | \1f | |
6571 | File: bash.info, Node: Aliases, Next: Arrays, Prev: Shell Arithmetic, Up: Bash Features | |
6572 | ||
6573 | 6.6 Aliases | |
6574 | =========== | |
6575 | ||
74091dd4 | 6576 | "Aliases" allow a string to be substituted for a word when it is used as |
a0c0a00f CR |
6577 | the first word of a simple command. The shell maintains a list of |
6578 | aliases that may be set and unset with the 'alias' and 'unalias' builtin | |
6579 | commands. | |
6580 | ||
6581 | The first word of each simple command, if unquoted, is checked to see | |
6582 | if it has an alias. If so, that word is replaced by the text of the | |
6583 | alias. The characters '/', '$', '`', '=' and any of the shell | |
6584 | metacharacters or quoting characters listed above may not appear in an | |
6585 | alias name. The replacement text may contain any valid shell input, | |
6586 | including shell metacharacters. The first word of the replacement text | |
6587 | is tested for aliases, but a word that is identical to an alias being | |
6588 | expanded is not expanded a second time. This means that one may alias | |
6589 | 'ls' to '"ls -F"', for instance, and Bash does not try to recursively | |
6590 | expand the replacement text. If the last character of the alias value | |
74091dd4 | 6591 | is a 'blank', then the next command word following the alias is also |
a0c0a00f CR |
6592 | checked for alias expansion. |
6593 | ||
6594 | Aliases are created and listed with the 'alias' command, and removed | |
6595 | with the 'unalias' command. | |
6596 | ||
6597 | There is no mechanism for using arguments in the replacement text, as | |
74091dd4 CR |
6598 | in 'csh'. If arguments are needed, use a shell function (*note Shell |
6599 | Functions::). | |
a0c0a00f CR |
6600 | |
6601 | Aliases are not expanded when the shell is not interactive, unless | |
6602 | the 'expand_aliases' shell option is set using 'shopt' (*note The Shopt | |
6603 | Builtin::). | |
6604 | ||
6605 | The rules concerning the definition and use of aliases are somewhat | |
d233b485 CR |
6606 | confusing. Bash always reads at least one complete line of input, and |
6607 | all lines that make up a compound command, before executing any of the | |
6608 | commands on that line or the compound command. Aliases are expanded | |
6609 | when a command is read, not when it is executed. Therefore, an alias | |
a0c0a00f CR |
6610 | definition appearing on the same line as another command does not take |
6611 | effect until the next line of input is read. The commands following the | |
6612 | alias definition on that line are not affected by the new alias. This | |
6613 | behavior is also an issue when functions are executed. Aliases are | |
6614 | expanded when a function definition is read, not when the function is | |
6615 | executed, because a function definition is itself a command. As a | |
6616 | consequence, aliases defined in a function are not available until after | |
6617 | that function is executed. To be safe, always put alias definitions on | |
6618 | a separate line, and do not use 'alias' in compound commands. | |
6619 | ||
6620 | For almost every purpose, shell functions are preferred over aliases. | |
6621 | ||
6622 | \1f | |
6623 | File: bash.info, Node: Arrays, Next: The Directory Stack, Prev: Aliases, Up: Bash Features | |
6624 | ||
6625 | 6.7 Arrays | |
6626 | ========== | |
6627 | ||
6628 | Bash provides one-dimensional indexed and associative array variables. | |
6629 | Any variable may be used as an indexed array; the 'declare' builtin will | |
6630 | explicitly declare an array. There is no maximum limit on the size of | |
6631 | an array, nor any requirement that members be indexed or assigned | |
6632 | contiguously. Indexed arrays are referenced using integers (including | |
6633 | arithmetic expressions (*note Shell Arithmetic::)) and are zero-based; | |
6634 | associative arrays use arbitrary strings. Unless otherwise noted, | |
6635 | indexed array indices must be non-negative integers. | |
6636 | ||
6637 | An indexed array is created automatically if any variable is assigned | |
6638 | to using the syntax | |
6639 | NAME[SUBSCRIPT]=VALUE | |
6640 | ||
6641 | The SUBSCRIPT is treated as an arithmetic expression that must evaluate | |
6642 | to a number. To explicitly declare an array, use | |
6643 | declare -a NAME | |
6644 | The syntax | |
6645 | declare -a NAME[SUBSCRIPT] | |
6646 | is also accepted; the SUBSCRIPT is ignored. | |
6647 | ||
6648 | Associative arrays are created using | |
8868edaf | 6649 | declare -A NAME |
a0c0a00f CR |
6650 | |
6651 | Attributes may be specified for an array variable using the 'declare' | |
6652 | and 'readonly' builtins. Each attribute applies to all members of an | |
6653 | array. | |
6654 | ||
6655 | Arrays are assigned to using compound assignments of the form | |
6656 | NAME=(VALUE1 VALUE2 ... ) | |
8868edaf | 6657 | where each VALUE may be of the form '[SUBSCRIPT]='STRING. Indexed array |
a0c0a00f CR |
6658 | assignments do not require anything but STRING. When assigning to |
6659 | indexed arrays, if the optional subscript is supplied, that index is | |
6660 | assigned to; otherwise the index of the element assigned is the last | |
6661 | index assigned to by the statement plus one. Indexing starts at zero. | |
6662 | ||
8868edaf CR |
6663 | Each VALUE in the list undergoes all the shell expansions described |
6664 | above (*note Shell Expansions::). | |
6665 | ||
6666 | When assigning to an associative array, the words in a compound | |
6667 | assignment may be either assignment statements, for which the subscript | |
6668 | is required, or a list of words that is interpreted as a sequence of | |
6669 | alternating keys and values: NAME=(KEY1 VALUE1 KEY2 VALUE2 ... ). These | |
6670 | are treated identically to NAME=( [KEY1]=VALUE1 [KEY2]=VALUE2 ... ). | |
6671 | The first word in the list determines how the remaining words are | |
6672 | interpreted; all assignments in a list must be of the same type. When | |
6673 | using key/value pairs, the keys may not be missing or empty; a final | |
6674 | missing value is treated like the empty string. | |
a0c0a00f CR |
6675 | |
6676 | This syntax is also accepted by the 'declare' builtin. Individual | |
6677 | array elements may be assigned to using the 'NAME[SUBSCRIPT]=VALUE' | |
6678 | syntax introduced above. | |
6679 | ||
6680 | When assigning to an indexed array, if NAME is subscripted by a | |
6681 | negative number, that number is interpreted as relative to one greater | |
6682 | than the maximum index of NAME, so negative indices count back from the | |
6683 | end of the array, and an index of -1 references the last element. | |
6684 | ||
74091dd4 CR |
6685 | The '+=' operator will append to an array variable when assigning |
6686 | using the compound assignment syntax; see *note Shell Parameters:: | |
6687 | above. | |
6688 | ||
a0c0a00f CR |
6689 | Any element of an array may be referenced using '${NAME[SUBSCRIPT]}'. |
6690 | The braces are required to avoid conflicts with the shell's filename | |
6691 | expansion operators. If the SUBSCRIPT is '@' or '*', the word expands | |
6692 | to all members of the array NAME. These subscripts differ only when the | |
6693 | word appears within double quotes. If the word is double-quoted, | |
6694 | '${NAME[*]}' expands to a single word with the value of each array | |
6695 | member separated by the first character of the 'IFS' variable, and | |
6696 | '${NAME[@]}' expands each element of NAME to a separate word. When | |
6697 | there are no array members, '${NAME[@]}' expands to nothing. If the | |
6698 | double-quoted expansion occurs within a word, the expansion of the first | |
6699 | parameter is joined with the beginning part of the original word, and | |
6700 | the expansion of the last parameter is joined with the last part of the | |
6701 | original word. This is analogous to the expansion of the special | |
6702 | parameters '@' and '*'. '${#NAME[SUBSCRIPT]}' expands to the length of | |
6703 | '${NAME[SUBSCRIPT]}'. If SUBSCRIPT is '@' or '*', the expansion is the | |
6704 | number of elements in the array. If the SUBSCRIPT used to reference an | |
6705 | element of an indexed array evaluates to a number less than zero, it is | |
6706 | interpreted as relative to one greater than the maximum index of the | |
6707 | array, so negative indices count back from the end of the array, and an | |
6708 | index of -1 refers to the last element. | |
6709 | ||
6710 | Referencing an array variable without a subscript is equivalent to | |
6711 | referencing with a subscript of 0. Any reference to a variable using a | |
6712 | valid subscript is legal, and 'bash' will create an array if necessary. | |
6713 | ||
6714 | An array variable is considered set if a subscript has been assigned | |
6715 | a value. The null string is a valid value. | |
6716 | ||
6717 | It is possible to obtain the keys (indices) of an array as well as | |
6718 | the values. ${!NAME[@]} and ${!NAME[*]} expand to the indices assigned | |
6719 | in array variable NAME. The treatment when in double quotes is similar | |
6720 | to the expansion of the special parameters '@' and '*' within double | |
6721 | quotes. | |
6722 | ||
6723 | The 'unset' builtin is used to destroy arrays. 'unset | |
6724 | NAME[SUBSCRIPT]' destroys the array element at index SUBSCRIPT. | |
6725 | Negative subscripts to indexed arrays are interpreted as described | |
d233b485 CR |
6726 | above. Unsetting the last element of an array variable does not unset |
6727 | the variable. 'unset NAME', where NAME is an array, removes the entire | |
74091dd4 CR |
6728 | array. 'unset NAME[SUBSCRIPT]' behaves differently depending on the |
6729 | array type when given a subscript of '*' or '@'. When NAME is an | |
6730 | associative array, it removes the element with key '*' or '@'. If NAME | |
6731 | is an indexed array, 'unset' removes all of the elements, but does not | |
6732 | remove the array itself. | |
d233b485 CR |
6733 | |
6734 | When using a variable name with a subscript as an argument to a | |
6735 | command, such as with 'unset', without using the word expansion syntax | |
6736 | described above, the argument is subject to the shell's filename | |
6737 | expansion. If filename expansion is not desired, the argument should be | |
6738 | quoted. | |
a0c0a00f CR |
6739 | |
6740 | The 'declare', 'local', and 'readonly' builtins each accept a '-a' | |
6741 | option to specify an indexed array and a '-A' option to specify an | |
6742 | associative array. If both options are supplied, '-A' takes precedence. | |
6743 | The 'read' builtin accepts a '-a' option to assign a list of words read | |
6744 | from the standard input to an array, and can read values from the | |
6745 | standard input into individual array elements. The 'set' and 'declare' | |
6746 | builtins display array values in a way that allows them to be reused as | |
6747 | input. | |
6748 | ||
6749 | \1f | |
6750 | File: bash.info, Node: The Directory Stack, Next: Controlling the Prompt, Prev: Arrays, Up: Bash Features | |
6751 | ||
6752 | 6.8 The Directory Stack | |
6753 | ======================= | |
6754 | ||
6755 | * Menu: | |
6756 | ||
6757 | * Directory Stack Builtins:: Bash builtin commands to manipulate | |
6758 | the directory stack. | |
6759 | ||
6760 | The directory stack is a list of recently-visited directories. The | |
6761 | 'pushd' builtin adds directories to the stack as it changes the current | |
6762 | directory, and the 'popd' builtin removes specified directories from the | |
6763 | stack and changes the current directory to the directory removed. The | |
6764 | 'dirs' builtin displays the contents of the directory stack. The | |
6765 | current directory is always the "top" of the directory stack. | |
6766 | ||
6767 | The contents of the directory stack are also visible as the value of | |
6768 | the 'DIRSTACK' shell variable. | |
6769 | ||
6770 | \1f | |
6771 | File: bash.info, Node: Directory Stack Builtins, Up: The Directory Stack | |
6772 | ||
6773 | 6.8.1 Directory Stack Builtins | |
6774 | ------------------------------ | |
6775 | ||
6776 | 'dirs' | |
6777 | dirs [-clpv] [+N | -N] | |
6778 | ||
6779 | Display the list of currently remembered directories. Directories | |
6780 | are added to the list with the 'pushd' command; the 'popd' command | |
6781 | removes directories from the list. The current directory is always | |
6782 | the first directory in the stack. | |
6783 | ||
6784 | '-c' | |
6785 | Clears the directory stack by deleting all of the elements. | |
6786 | '-l' | |
6787 | Produces a listing using full pathnames; the default listing | |
6788 | format uses a tilde to denote the home directory. | |
6789 | '-p' | |
6790 | Causes 'dirs' to print the directory stack with one entry per | |
6791 | line. | |
6792 | '-v' | |
6793 | Causes 'dirs' to print the directory stack with one entry per | |
6794 | line, prefixing each entry with its index in the stack. | |
6795 | '+N' | |
6796 | Displays the Nth directory (counting from the left of the list | |
6797 | printed by 'dirs' when invoked without options), starting with | |
6798 | zero. | |
6799 | '-N' | |
6800 | Displays the Nth directory (counting from the right of the | |
6801 | list printed by 'dirs' when invoked without options), starting | |
6802 | with zero. | |
6803 | ||
6804 | 'popd' | |
6805 | popd [-n] [+N | -N] | |
6806 | ||
74091dd4 CR |
6807 | Removes elements from the directory stack. The elements are |
6808 | numbered from 0 starting at the first directory listed by 'dirs'; | |
6809 | that is, 'popd' is equivalent to 'popd +0'. | |
6810 | ||
a0c0a00f | 6811 | When no arguments are given, 'popd' removes the top directory from |
74091dd4 CR |
6812 | the stack and changes to the new top directory. |
6813 | ||
6814 | Arguments, if supplied, have the following meanings: | |
a0c0a00f CR |
6815 | |
6816 | '-n' | |
6817 | Suppresses the normal change of directory when removing | |
6818 | directories from the stack, so that only the stack is | |
6819 | manipulated. | |
6820 | '+N' | |
6821 | Removes the Nth directory (counting from the left of the list | |
74091dd4 | 6822 | printed by 'dirs'), starting with zero, from the stack. |
a0c0a00f CR |
6823 | '-N' |
6824 | Removes the Nth directory (counting from the right of the list | |
74091dd4 CR |
6825 | printed by 'dirs'), starting with zero, from the stack. |
6826 | ||
6827 | If the top element of the directory stack is modified, and the '-n' | |
6828 | option was not supplied, 'popd' uses the 'cd' builtin to change to | |
6829 | the directory at the top of the stack. If the 'cd' fails, 'popd' | |
6830 | returns a non-zero value. | |
6831 | ||
6832 | Otherwise, 'popd' returns an unsuccessful status if an invalid | |
6833 | option is encountered, the directory stack is empty, or a | |
6834 | non-existent directory stack entry is specified. | |
6835 | ||
6836 | If the 'popd' command is successful, Bash runs 'dirs' to show the | |
6837 | final contents of the directory stack, and the return status is 0. | |
a0c0a00f CR |
6838 | |
6839 | 'pushd' | |
6840 | pushd [-n] [+N | -N | DIR] | |
6841 | ||
74091dd4 CR |
6842 | Adds a directory to the top of the directory stack, or rotates the |
6843 | stack, making the new top of the stack the current working | |
6844 | directory. With no arguments, 'pushd' exchanges the top two | |
6845 | elements of the directory stack. | |
6846 | ||
6847 | Arguments, if supplied, have the following meanings: | |
a0c0a00f CR |
6848 | |
6849 | '-n' | |
6850 | Suppresses the normal change of directory when rotating or | |
6851 | adding directories to the stack, so that only the stack is | |
6852 | manipulated. | |
6853 | '+N' | |
6854 | Brings the Nth directory (counting from the left of the list | |
6855 | printed by 'dirs', starting with zero) to the top of the list | |
6856 | by rotating the stack. | |
6857 | '-N' | |
6858 | Brings the Nth directory (counting from the right of the list | |
6859 | printed by 'dirs', starting with zero) to the top of the list | |
6860 | by rotating the stack. | |
6861 | 'DIR' | |
74091dd4 CR |
6862 | Makes DIR be the top of the stack. |
6863 | ||
6864 | After the stack has been modified, if the '-n' option was not | |
6865 | supplied, 'pushd' uses the 'cd' builtin to change to the directory | |
6866 | at the top of the stack. If the 'cd' fails, 'pushd' returns a | |
6867 | non-zero value. | |
6868 | ||
6869 | Otherwise, if no arguments are supplied, 'pushd' returns 0 unless | |
6870 | the directory stack is empty. When rotating the directory stack, | |
6871 | 'pushd' returns 0 unless the directory stack is empty or a | |
6872 | non-existent directory stack element is specified. | |
6873 | ||
6874 | If the 'pushd' command is successful, Bash runs 'dirs' to show the | |
6875 | final contents of the directory stack. | |
a0c0a00f CR |
6876 | |
6877 | \1f | |
6878 | File: bash.info, Node: Controlling the Prompt, Next: The Restricted Shell, Prev: The Directory Stack, Up: Bash Features | |
6879 | ||
6880 | 6.9 Controlling the Prompt | |
6881 | ========================== | |
6882 | ||
74091dd4 | 6883 | Bash examines the value of the array variable 'PROMPT_COMMAND' just |
8868edaf | 6884 | before printing each primary prompt. If any elements in |
74091dd4 | 6885 | 'PROMPT_COMMAND' are set and non-null, Bash executes each value, in |
8868edaf | 6886 | numeric order, just as if it had been typed on the command line. |
a0c0a00f CR |
6887 | |
6888 | In addition, the following table describes the special characters | |
d233b485 | 6889 | which can appear in the prompt variables 'PS0', 'PS1', 'PS2', and 'PS4': |
a0c0a00f CR |
6890 | |
6891 | '\a' | |
6892 | A bell character. | |
6893 | '\d' | |
6894 | The date, in "Weekday Month Date" format (e.g., "Tue May 26"). | |
6895 | '\D{FORMAT}' | |
6896 | The FORMAT is passed to 'strftime'(3) and the result is inserted | |
6897 | into the prompt string; an empty FORMAT results in a | |
6898 | locale-specific time representation. The braces are required. | |
6899 | '\e' | |
6900 | An escape character. | |
6901 | '\h' | |
6902 | The hostname, up to the first '.'. | |
6903 | '\H' | |
6904 | The hostname. | |
6905 | '\j' | |
6906 | The number of jobs currently managed by the shell. | |
6907 | '\l' | |
6908 | The basename of the shell's terminal device name. | |
6909 | '\n' | |
6910 | A newline. | |
6911 | '\r' | |
6912 | A carriage return. | |
6913 | '\s' | |
6914 | The name of the shell, the basename of '$0' (the portion following | |
6915 | the final slash). | |
6916 | '\t' | |
6917 | The time, in 24-hour HH:MM:SS format. | |
6918 | '\T' | |
6919 | The time, in 12-hour HH:MM:SS format. | |
6920 | '\@' | |
6921 | The time, in 12-hour am/pm format. | |
6922 | '\A' | |
6923 | The time, in 24-hour HH:MM format. | |
6924 | '\u' | |
6925 | The username of the current user. | |
6926 | '\v' | |
6927 | The version of Bash (e.g., 2.00) | |
6928 | '\V' | |
6929 | The release of Bash, version + patchlevel (e.g., 2.00.0) | |
6930 | '\w' | |
74091dd4 CR |
6931 | The value of the 'PWD' shell variable ('$PWD'), with '$HOME' |
6932 | abbreviated with a tilde (uses the '$PROMPT_DIRTRIM' variable). | |
a0c0a00f CR |
6933 | '\W' |
6934 | The basename of '$PWD', with '$HOME' abbreviated with a tilde. | |
6935 | '\!' | |
6936 | The history number of this command. | |
6937 | '\#' | |
6938 | The command number of this command. | |
6939 | '\$' | |
6940 | If the effective uid is 0, '#', otherwise '$'. | |
6941 | '\NNN' | |
6942 | The character whose ASCII code is the octal value NNN. | |
6943 | '\\' | |
6944 | A backslash. | |
6945 | '\[' | |
6946 | Begin a sequence of non-printing characters. This could be used to | |
6947 | embed a terminal control sequence into the prompt. | |
6948 | '\]' | |
6949 | End a sequence of non-printing characters. | |
6950 | ||
6951 | The command number and the history number are usually different: the | |
6952 | history number of a command is its position in the history list, which | |
6953 | may include commands restored from the history file (*note Bash History | |
6954 | Facilities::), while the command number is the position in the sequence | |
6955 | of commands executed during the current shell session. | |
6956 | ||
6957 | After the string is decoded, it is expanded via parameter expansion, | |
6958 | command substitution, arithmetic expansion, and quote removal, subject | |
d233b485 | 6959 | to the value of the 'promptvars' shell option (*note The Shopt |
8868edaf CR |
6960 | Builtin::). This can have unwanted side effects if escaped portions of |
6961 | the string appear within command substitution or contain characters | |
6962 | special to word expansion. | |
a0c0a00f CR |
6963 | |
6964 | \1f | |
6965 | File: bash.info, Node: The Restricted Shell, Next: Bash POSIX Mode, Prev: Controlling the Prompt, Up: Bash Features | |
6966 | ||
6967 | 6.10 The Restricted Shell | |
6968 | ========================= | |
6969 | ||
6970 | If Bash is started with the name 'rbash', or the '--restricted' or '-r' | |
6971 | option is supplied at invocation, the shell becomes restricted. A | |
6972 | restricted shell is used to set up an environment more controlled than | |
6973 | the standard shell. A restricted shell behaves identically to 'bash' | |
6974 | with the exception that the following are disallowed or not performed: | |
6975 | ||
6976 | * Changing directories with the 'cd' builtin. | |
8868edaf CR |
6977 | * Setting or unsetting the values of the 'SHELL', 'PATH', 'HISTFILE', |
6978 | 'ENV', or 'BASH_ENV' variables. | |
a0c0a00f CR |
6979 | * Specifying command names containing slashes. |
6980 | * Specifying a filename containing a slash as an argument to the '.' | |
6981 | builtin command. | |
8868edaf CR |
6982 | * Specifying a filename containing a slash as an argument to the |
6983 | 'history' builtin command. | |
a0c0a00f CR |
6984 | * Specifying a filename containing a slash as an argument to the '-p' |
6985 | option to the 'hash' builtin command. | |
6986 | * Importing function definitions from the shell environment at | |
6987 | startup. | |
6988 | * Parsing the value of 'SHELLOPTS' from the shell environment at | |
6989 | startup. | |
6990 | * Redirecting output using the '>', '>|', '<>', '>&', '&>', and '>>' | |
6991 | redirection operators. | |
6992 | * Using the 'exec' builtin to replace the shell with another command. | |
6993 | * Adding or deleting builtin commands with the '-f' and '-d' options | |
6994 | to the 'enable' builtin. | |
6995 | * Using the 'enable' builtin command to enable disabled shell | |
6996 | builtins. | |
6997 | * Specifying the '-p' option to the 'command' builtin. | |
74091dd4 CR |
6998 | * Turning off restricted mode with 'set +r' or 'shopt -u |
6999 | restricted_shell'. | |
a0c0a00f CR |
7000 | |
7001 | These restrictions are enforced after any startup files are read. | |
7002 | ||
7003 | When a command that is found to be a shell script is executed (*note | |
7004 | Shell Scripts::), 'rbash' turns off any restrictions in the shell | |
7005 | spawned to execute the script. | |
7006 | ||
8868edaf CR |
7007 | The restricted shell mode is only one component of a useful |
7008 | restricted environment. It should be accompanied by setting 'PATH' to a | |
7009 | value that allows execution of only a few verified commands (commands | |
74091dd4 CR |
7010 | that allow shell escapes are particularly vulnerable), changing the |
7011 | current directory to a non-writable directory other than '$HOME' after | |
7012 | login, not allowing the restricted shell to execute shell scripts, and | |
7013 | cleaning the environment of variables that cause some commands to modify | |
7014 | their behavior (e.g., 'VISUAL' or 'PAGER'). | |
8868edaf CR |
7015 | |
7016 | Modern systems provide more secure ways to implement a restricted | |
7017 | environment, such as 'jails', 'zones', or 'containers'. | |
7018 | ||
a0c0a00f | 7019 | \1f |
8868edaf | 7020 | File: bash.info, Node: Bash POSIX Mode, Next: Shell Compatibility Mode, Prev: The Restricted Shell, Up: Bash Features |
a0c0a00f CR |
7021 | |
7022 | 6.11 Bash POSIX Mode | |
7023 | ==================== | |
7024 | ||
7025 | Starting Bash with the '--posix' command-line option or executing 'set | |
7026 | -o posix' while Bash is running will cause Bash to conform more closely | |
7027 | to the POSIX standard by changing the behavior to match that specified | |
7028 | by POSIX in areas where the Bash default differs. | |
7029 | ||
7030 | When invoked as 'sh', Bash enters POSIX mode after reading the | |
7031 | startup files. | |
7032 | ||
7033 | The following list is what's changed when 'POSIX mode' is in effect: | |
7034 | ||
d233b485 CR |
7035 | 1. Bash ensures that the 'POSIXLY_CORRECT' variable is set. |
7036 | ||
7037 | 2. When a command in the hash table no longer exists, Bash will | |
a0c0a00f CR |
7038 | re-search '$PATH' to find the new location. This is also available |
7039 | with 'shopt -s checkhash'. | |
7040 | ||
8868edaf CR |
7041 | 3. Bash will not insert a command without the execute bit set into the |
7042 | command hash table, even if it returns it as a (last-ditch) result | |
7043 | from a '$PATH' search. | |
a0c0a00f | 7044 | |
d233b485 | 7045 | 4. The message printed by the job control code and builtins when a job |
8868edaf CR |
7046 | exits with a non-zero status is 'Done(status)'. |
7047 | ||
7048 | 5. The message printed by the job control code and builtins when a job | |
a0c0a00f CR |
7049 | is stopped is 'Stopped(SIGNAME)', where SIGNAME is, for example, |
7050 | 'SIGTSTP'. | |
7051 | ||
8868edaf | 7052 | 6. Alias expansion is always enabled, even in non-interactive shells. |
a0c0a00f | 7053 | |
8868edaf | 7054 | 7. Reserved words appearing in a context where reserved words are |
a0c0a00f CR |
7055 | recognized do not undergo alias expansion. |
7056 | ||
74091dd4 CR |
7057 | 8. Alias expansion is performed when initially parsing a command |
7058 | substitution. The default mode generally defers it, when enabled, | |
7059 | until the command substitution is executed. This means that | |
7060 | command substitution will not expand aliases that are defined after | |
7061 | the command substitution is initially parsed (e.g., as part of a | |
7062 | function definition). | |
7063 | ||
7064 | 9. The POSIX 'PS1' and 'PS2' expansions of '!' to the history number | |
a0c0a00f CR |
7065 | and '!!' to '!' are enabled, and parameter expansion is performed |
7066 | on the values of 'PS1' and 'PS2' regardless of the setting of the | |
7067 | 'promptvars' option. | |
7068 | ||
74091dd4 | 7069 | 10. The POSIX startup files are executed ('$ENV') rather than the |
a0c0a00f CR |
7070 | normal Bash files. |
7071 | ||
74091dd4 | 7072 | 11. Tilde expansion is only performed on assignments preceding a |
a0c0a00f CR |
7073 | command name, rather than on all assignment statements on the line. |
7074 | ||
74091dd4 | 7075 | 12. The default history file is '~/.sh_history' (this is the default |
a0c0a00f CR |
7076 | value of '$HISTFILE'). |
7077 | ||
74091dd4 | 7078 | 13. Redirection operators do not perform filename expansion on the |
a0c0a00f CR |
7079 | word in the redirection unless the shell is interactive. |
7080 | ||
74091dd4 | 7081 | 14. Redirection operators do not perform word splitting on the word in |
a0c0a00f CR |
7082 | the redirection. |
7083 | ||
74091dd4 | 7084 | 15. Function names must be valid shell 'name's. That is, they may not |
a0c0a00f CR |
7085 | contain characters other than letters, digits, and underscores, and |
7086 | may not start with a digit. Declaring a function with an invalid | |
7087 | name causes a fatal syntax error in non-interactive shells. | |
7088 | ||
74091dd4 | 7089 | 16. Function names may not be the same as one of the POSIX special |
a0c0a00f CR |
7090 | builtins. |
7091 | ||
74091dd4 | 7092 | 17. POSIX special builtins are found before shell functions during |
a0c0a00f CR |
7093 | command lookup. |
7094 | ||
74091dd4 | 7095 | 18. When printing shell function definitions (e.g., by 'type'), Bash |
a0c0a00f CR |
7096 | does not print the 'function' keyword. |
7097 | ||
74091dd4 | 7098 | 19. Literal tildes that appear as the first character in elements of |
a0c0a00f CR |
7099 | the 'PATH' variable are not expanded as described above under *note |
7100 | Tilde Expansion::. | |
7101 | ||
74091dd4 | 7102 | 20. The 'time' reserved word may be used by itself as a command. When |
a0c0a00f CR |
7103 | used in this way, it displays timing statistics for the shell and |
7104 | its completed children. The 'TIMEFORMAT' variable controls the | |
7105 | format of the timing information. | |
7106 | ||
74091dd4 | 7107 | 21. When parsing and expanding a ${...} expansion that appears within |
a0c0a00f CR |
7108 | double quotes, single quotes are no longer special and cannot be |
7109 | used to quote a closing brace or other special character, unless | |
7110 | the operator is one of those defined to perform pattern removal. | |
7111 | In this case, they do not have to appear as matched pairs. | |
7112 | ||
74091dd4 | 7113 | 22. The parser does not recognize 'time' as a reserved word if the |
a0c0a00f CR |
7114 | next token begins with a '-'. |
7115 | ||
74091dd4 | 7116 | 23. The '!' character does not introduce history expansion within a |
a0c0a00f CR |
7117 | double-quoted string, even if the 'histexpand' option is enabled. |
7118 | ||
74091dd4 | 7119 | 24. If a POSIX special builtin returns an error status, a |
a0c0a00f CR |
7120 | non-interactive shell exits. The fatal errors are those listed in |
7121 | the POSIX standard, and include things like passing incorrect | |
7122 | options, redirection errors, variable assignment errors for | |
7123 | assignments preceding the command name, and so on. | |
7124 | ||
74091dd4 | 7125 | 25. A non-interactive shell exits with an error status if a variable |
a0c0a00f CR |
7126 | assignment error occurs when no command name follows the assignment |
7127 | statements. A variable assignment error occurs, for example, when | |
7128 | trying to assign a value to a readonly variable. | |
7129 | ||
74091dd4 | 7130 | 26. A non-interactive shell exits with an error status if a variable |
a0c0a00f | 7131 | assignment error occurs in an assignment statement preceding a |
74091dd4 CR |
7132 | special builtin, but not with any other simple command. For any |
7133 | other simple command, the shell aborts execution of that command, | |
7134 | and execution continues at the top level ("the shell shall not | |
7135 | perform any further processing of the command in which the error | |
7136 | occurred"). | |
a0c0a00f | 7137 | |
74091dd4 | 7138 | 27. A non-interactive shell exits with an error status if the |
a0c0a00f CR |
7139 | iteration variable in a 'for' statement or the selection variable |
7140 | in a 'select' statement is a readonly variable. | |
7141 | ||
74091dd4 | 7142 | 28. Non-interactive shells exit if FILENAME in '.' FILENAME is not |
a0c0a00f CR |
7143 | found. |
7144 | ||
74091dd4 | 7145 | 29. Non-interactive shells exit if a syntax error in an arithmetic |
a0c0a00f CR |
7146 | expansion results in an invalid expression. |
7147 | ||
74091dd4 | 7148 | 30. Non-interactive shells exit if a parameter expansion error occurs. |
a0c0a00f | 7149 | |
74091dd4 | 7150 | 31. Non-interactive shells exit if there is a syntax error in a script |
a0c0a00f CR |
7151 | read with the '.' or 'source' builtins, or in a string processed by |
7152 | the 'eval' builtin. | |
7153 | ||
74091dd4 | 7154 | 32. While variable indirection is available, it may not be applied to |
a0c0a00f CR |
7155 | the '#' and '?' special parameters. |
7156 | ||
74091dd4 CR |
7157 | 33. Expanding the '*' special parameter in a pattern context where the |
7158 | expansion is double-quoted does not treat the '$*' as if it were | |
7159 | double-quoted. | |
a0c0a00f | 7160 | |
74091dd4 | 7161 | 34. Assignment statements preceding POSIX special builtins persist in |
a0c0a00f CR |
7162 | the shell environment after the builtin completes. |
7163 | ||
74091dd4 | 7164 | 35. The 'command' builtin does not prevent builtins that take |
a0c0a00f CR |
7165 | assignment statements as arguments from expanding them as |
7166 | assignment statements; when not in POSIX mode, assignment builtins | |
7167 | lose their assignment statement expansion properties when preceded | |
7168 | by 'command'. | |
7169 | ||
74091dd4 | 7170 | 36. The 'bg' builtin uses the required format to describe each job |
a0c0a00f CR |
7171 | placed in the background, which does not include an indication of |
7172 | whether the job is the current or previous job. | |
7173 | ||
74091dd4 | 7174 | 37. The output of 'kill -l' prints all the signal names on a single |
a0c0a00f CR |
7175 | line, separated by spaces, without the 'SIG' prefix. |
7176 | ||
74091dd4 | 7177 | 38. The 'kill' builtin does not accept signal names with a 'SIG' |
a0c0a00f CR |
7178 | prefix. |
7179 | ||
74091dd4 | 7180 | 39. The 'export' and 'readonly' builtin commands display their output |
a0c0a00f CR |
7181 | in the format required by POSIX. |
7182 | ||
74091dd4 | 7183 | 40. The 'trap' builtin displays signal names without the leading |
a0c0a00f CR |
7184 | 'SIG'. |
7185 | ||
74091dd4 | 7186 | 41. The 'trap' builtin doesn't check the first argument for a possible |
a0c0a00f CR |
7187 | signal specification and revert the signal handling to the original |
7188 | disposition if it is, unless that argument consists solely of | |
7189 | digits and is a valid signal number. If users want to reset the | |
7190 | handler for a given signal to the original disposition, they should | |
7191 | use '-' as the first argument. | |
7192 | ||
74091dd4 | 7193 | 42. 'trap -p' displays signals whose dispositions are set to SIG_DFL |
8868edaf CR |
7194 | and those that were ignored when the shell started. |
7195 | ||
74091dd4 | 7196 | 43. The '.' and 'source' builtins do not search the current directory |
a0c0a00f CR |
7197 | for the filename argument if it is not found by searching 'PATH'. |
7198 | ||
74091dd4 | 7199 | 44. Enabling POSIX mode has the effect of setting the |
a0c0a00f CR |
7200 | 'inherit_errexit' option, so subshells spawned to execute command |
7201 | substitutions inherit the value of the '-e' option from the parent | |
7202 | shell. When the 'inherit_errexit' option is not enabled, Bash | |
7203 | clears the '-e' option in such subshells. | |
7204 | ||
74091dd4 | 7205 | 45. Enabling POSIX mode has the effect of setting the 'shift_verbose' |
d233b485 CR |
7206 | option, so numeric arguments to 'shift' that exceed the number of |
7207 | positional parameters will result in an error message. | |
7208 | ||
74091dd4 | 7209 | 46. When the 'alias' builtin displays alias definitions, it does not |
a0c0a00f CR |
7210 | display them with a leading 'alias ' unless the '-p' option is |
7211 | supplied. | |
7212 | ||
74091dd4 | 7213 | 47. When the 'set' builtin is invoked without options, it does not |
a0c0a00f CR |
7214 | display shell function names and definitions. |
7215 | ||
74091dd4 | 7216 | 48. When the 'set' builtin is invoked without options, it displays |
a0c0a00f CR |
7217 | variable values without quotes, unless they contain shell |
7218 | metacharacters, even if the result contains nonprinting characters. | |
7219 | ||
74091dd4 | 7220 | 49. When the 'cd' builtin is invoked in logical mode, and the pathname |
a0c0a00f CR |
7221 | constructed from '$PWD' and the directory name supplied as an |
7222 | argument does not refer to an existing directory, 'cd' will fail | |
74091dd4 | 7223 | instead of falling back to physical mode. |
a0c0a00f | 7224 | |
74091dd4 | 7225 | 50. When the 'cd' builtin cannot change a directory because the length |
d233b485 | 7226 | of the pathname constructed from '$PWD' and the directory name |
74091dd4 | 7227 | supplied as an argument exceeds 'PATH_MAX' when all symbolic links |
d233b485 CR |
7228 | are expanded, 'cd' will fail instead of attempting to use only the |
7229 | supplied directory name. | |
7230 | ||
74091dd4 | 7231 | 51. The 'pwd' builtin verifies that the value it prints is the same as |
a0c0a00f CR |
7232 | the current directory, even if it is not asked to check the file |
7233 | system with the '-P' option. | |
7234 | ||
74091dd4 | 7235 | 52. When listing the history, the 'fc' builtin does not include an |
a0c0a00f CR |
7236 | indication of whether or not a history entry has been modified. |
7237 | ||
74091dd4 | 7238 | 53. The default editor used by 'fc' is 'ed'. |
a0c0a00f | 7239 | |
74091dd4 | 7240 | 54. The 'type' and 'command' builtins will not report a non-executable |
a0c0a00f CR |
7241 | file as having been found, though the shell will attempt to execute |
7242 | such a file if it is the only so-named file found in '$PATH'. | |
7243 | ||
74091dd4 | 7244 | 55. The 'vi' editing mode will invoke the 'vi' editor directly when |
a0c0a00f CR |
7245 | the 'v' command is run, instead of checking '$VISUAL' and |
7246 | '$EDITOR'. | |
7247 | ||
74091dd4 | 7248 | 56. When the 'xpg_echo' option is enabled, Bash does not attempt to |
a0c0a00f CR |
7249 | interpret any arguments to 'echo' as options. Each argument is |
7250 | displayed, after escape characters are converted. | |
7251 | ||
74091dd4 | 7252 | 57. The 'ulimit' builtin uses a block size of 512 bytes for the '-c' |
a0c0a00f CR |
7253 | and '-f' options. |
7254 | ||
74091dd4 | 7255 | 58. The arrival of 'SIGCHLD' when a trap is set on 'SIGCHLD' does not |
a0c0a00f CR |
7256 | interrupt the 'wait' builtin and cause it to return immediately. |
7257 | The trap command is run once for each child that exits. | |
7258 | ||
74091dd4 | 7259 | 59. The 'read' builtin may be interrupted by a signal for which a trap |
a0c0a00f CR |
7260 | has been set. If Bash receives a trapped signal while executing |
7261 | 'read', the trap handler executes and 'read' returns an exit status | |
7262 | greater than 128. | |
7263 | ||
74091dd4 CR |
7264 | 60. The 'printf' builtin uses 'double' (via 'strtod') to convert |
7265 | arguments corresponding to floating point conversion specifiers, | |
7266 | instead of 'long double' if it's available. The 'L' length | |
7267 | modifier forces 'printf' to use 'long double' if it's available. | |
7268 | ||
7269 | 61. Bash removes an exited background process's status from the list | |
a0c0a00f CR |
7270 | of such statuses after the 'wait' builtin is used to obtain it. |
7271 | ||
7272 | There is other POSIX behavior that Bash does not implement by default | |
7273 | even when in POSIX mode. Specifically: | |
7274 | ||
7275 | 1. The 'fc' builtin checks '$EDITOR' as a program to edit history | |
7276 | entries if 'FCEDIT' is unset, rather than defaulting directly to | |
7277 | 'ed'. 'fc' uses 'ed' if 'EDITOR' is unset. | |
7278 | ||
7279 | 2. As noted above, Bash requires the 'xpg_echo' option to be enabled | |
7280 | for the 'echo' builtin to be fully conformant. | |
7281 | ||
7282 | Bash can be configured to be POSIX-conformant by default, by | |
7283 | specifying the '--enable-strict-posix-default' to 'configure' when | |
7284 | building (*note Optional Features::). | |
7285 | ||
8868edaf CR |
7286 | \1f |
7287 | File: bash.info, Node: Shell Compatibility Mode, Prev: Bash POSIX Mode, Up: Bash Features | |
7288 | ||
7289 | 6.12 Shell Compatibility Mode | |
7290 | ============================= | |
7291 | ||
74091dd4 | 7292 | Bash-4.0 introduced the concept of a "shell compatibility level", |
8868edaf CR |
7293 | specified as a set of options to the shopt builtin ('compat31', |
7294 | 'compat32', 'compat40', 'compat41', and so on). There is only one | |
7295 | current compatibility level - each option is mutually exclusive. The | |
7296 | compatibility level is intended to allow users to select behavior from | |
7297 | previous versions that is incompatible with newer versions while they | |
7298 | migrate scripts to use current features and behavior. It's intended to | |
7299 | be a temporary solution. | |
7300 | ||
7301 | This section does not mention behavior that is standard for a | |
7302 | particular version (e.g., setting 'compat32' means that quoting the rhs | |
7303 | of the regexp matching operator quotes special regexp characters in the | |
74091dd4 | 7304 | word, which is default behavior in bash-3.2 and subsequent versions). |
8868edaf CR |
7305 | |
7306 | If a user enables, say, 'compat32', it may affect the behavior of | |
7307 | other compatibility levels up to and including the current compatibility | |
7308 | level. The idea is that each compatibility level controls behavior that | |
7309 | changed in that version of Bash, but that behavior may have been present | |
7310 | in earlier versions. For instance, the change to use locale-based | |
7311 | comparisons with the '[[' command came in bash-4.1, and earlier versions | |
7312 | used ASCII-based comparisons, so enabling 'compat32' will enable | |
7313 | ASCII-based comparisons as well. That granularity may not be sufficient | |
7314 | for all uses, and as a result users should employ compatibility levels | |
7315 | carefully. Read the documentation for a particular feature to find out | |
7316 | the current behavior. | |
7317 | ||
7318 | Bash-4.3 introduced a new shell variable: 'BASH_COMPAT'. The value | |
7319 | assigned to this variable (a decimal version number like 4.2, or an | |
7320 | integer corresponding to the 'compat'NN option, like 42) determines the | |
7321 | compatibility level. | |
7322 | ||
7323 | Starting with bash-4.4, Bash has begun deprecating older | |
7324 | compatibility levels. Eventually, the options will be removed in favor | |
7325 | of 'BASH_COMPAT'. | |
7326 | ||
7327 | Bash-5.0 is the final version for which there will be an individual | |
7328 | shopt option for the previous version. Users should use 'BASH_COMPAT' | |
7329 | on bash-5.0 and later versions. | |
7330 | ||
7331 | The following table describes the behavior changes controlled by each | |
7332 | compatibility level setting. The 'compat'NN tag is used as shorthand | |
7333 | for setting the compatibility level to NN using one of the following | |
7334 | mechanisms. For versions prior to bash-5.0, the compatibility level may | |
7335 | be set using the corresponding 'compat'NN shopt option. For bash-4.3 | |
7336 | and later versions, the 'BASH_COMPAT' variable is preferred, and it is | |
7337 | required for bash-5.1 and later versions. | |
7338 | ||
7339 | 'compat31' | |
7340 | * quoting the rhs of the '[[' command's regexp matching operator | |
7341 | (=~) has no special effect | |
7342 | ||
7343 | 'compat32' | |
7344 | * interrupting a command list such as "a ; b ; c" causes the | |
7345 | execution of the next command in the list (in bash-4.0 and | |
7346 | later versions, the shell acts as if it received the | |
7347 | interrupt, so interrupting one command in a list aborts the | |
7348 | execution of the entire list) | |
7349 | ||
7350 | 'compat40' | |
7351 | * the '<' and '>' operators to the '[[' command do not consider | |
7352 | the current locale when comparing strings; they use ASCII | |
7353 | ordering. Bash versions prior to bash-4.1 use ASCII collation | |
7354 | and strcmp(3); bash-4.1 and later use the current locale's | |
7355 | collation sequence and strcoll(3). | |
7356 | ||
7357 | 'compat41' | |
7358 | * in posix mode, 'time' may be followed by options and still be | |
7359 | recognized as a reserved word (this is POSIX interpretation | |
7360 | 267) | |
7361 | * in posix mode, the parser requires that an even number of | |
7362 | single quotes occur in the WORD portion of a double-quoted | |
7363 | ${...} parameter expansion and treats them specially, so that | |
7364 | characters within the single quotes are considered quoted | |
7365 | (this is POSIX interpretation 221) | |
7366 | ||
7367 | 'compat42' | |
7368 | * the replacement string in double-quoted pattern substitution | |
7369 | does not undergo quote removal, as it does in versions after | |
7370 | bash-4.2 | |
7371 | * in posix mode, single quotes are considered special when | |
7372 | expanding the WORD portion of a double-quoted ${...} parameter | |
7373 | expansion and can be used to quote a closing brace or other | |
7374 | special character (this is part of POSIX interpretation 221); | |
7375 | in later versions, single quotes are not special within | |
7376 | double-quoted word expansions | |
7377 | ||
7378 | 'compat43' | |
7379 | * the shell does not print a warning message if an attempt is | |
7380 | made to use a quoted compound assignment as an argument to | |
74091dd4 CR |
7381 | declare (e.g., declare -a foo='(1 2)'). Later versions warn |
7382 | that this usage is deprecated | |
8868edaf CR |
7383 | * word expansion errors are considered non-fatal errors that |
7384 | cause the current command to fail, even in posix mode (the | |
7385 | default behavior is to make them fatal errors that cause the | |
7386 | shell to exit) | |
7387 | * when executing a shell function, the loop state | |
7388 | (while/until/etc.) is not reset, so 'break' or 'continue' in | |
7389 | that function will break or continue loops in the calling | |
7390 | context. Bash-4.4 and later reset the loop state to prevent | |
7391 | this | |
7392 | ||
7393 | 'compat44' | |
7394 | * the shell sets up the values used by 'BASH_ARGV' and | |
7395 | 'BASH_ARGC' so they can expand to the shell's positional | |
7396 | parameters even if extended debugging mode is not enabled | |
7397 | * a subshell inherits loops from its parent context, so 'break' | |
7398 | or 'continue' will cause the subshell to exit. Bash-5.0 and | |
7399 | later reset the loop state to prevent the exit | |
7400 | * variable assignments preceding builtins like 'export' and | |
7401 | 'readonly' that set attributes continue to affect variables | |
7402 | with the same name in the calling environment even if the | |
7403 | shell is not in posix mode | |
7404 | ||
7405 | 'compat50 (set using BASH_COMPAT)' | |
7406 | * Bash-5.1 changed the way '$RANDOM' is generated to introduce | |
7407 | slightly more randomness. If the shell compatibility level is | |
7408 | set to 50 or lower, it reverts to the method from bash-5.0 and | |
7409 | previous versions, so seeding the random number generator by | |
7410 | assigning a value to 'RANDOM' will produce the same sequence | |
7411 | as in bash-5.0 | |
7412 | * If the command hash table is empty, Bash versions prior to | |
7413 | bash-5.1 printed an informational message to that effect, even | |
7414 | when producing output that can be reused as input. Bash-5.1 | |
7415 | suppresses that message when the '-l' option is supplied. | |
7416 | ||
74091dd4 CR |
7417 | 'compat51 (set using BASH_COMPAT)' |
7418 | * The 'unset' builtin will unset the array 'a' given an argument | |
7419 | like 'a[@]'. Bash-5.2 will unset an element with key '@' | |
7420 | (associative arrays) or remove all the elements without | |
7421 | unsetting the array (indexed arrays) | |
7422 | * arithmetic commands ( ((...)) ) and the expressions in an | |
7423 | arithmetic for statement can be expanded more than once | |
7424 | * expressions used as arguments to arithmetic operators in the | |
7425 | '[[' conditional command can be expanded more than once | |
7426 | * the expressions in substring parameter brace expansion can be | |
7427 | expanded more than once | |
7428 | * the expressions in the $(( ... )) word expansion can be | |
7429 | expanded more than once | |
7430 | * arithmetic expressions used as indexed array subscripts can be | |
7431 | expanded more than once | |
7432 | * 'test -v', when given an argument of 'A[@]', where A is an | |
7433 | existing associative array, will return true if the array has | |
7434 | any set elements. Bash-5.2 will look for and report on a key | |
7435 | named '@' | |
7436 | * the ${PARAMETER[:]=VALUE} word expansion will return VALUE, | |
7437 | before any variable-specific transformations have been | |
7438 | performed (e.g., converting to lowercase). Bash-5.2 will | |
7439 | return the final value assigned to the variable. | |
7440 | * Parsing command substitutions will behave as if extended glob | |
7441 | (*note The Shopt Builtin::) is enabled, so that parsing a | |
7442 | command substitution containing an extglob pattern (say, as | |
7443 | part of a shell function) will not fail. This assumes the | |
7444 | intent is to enable extglob before the command is executed and | |
7445 | word expansions are performed. It will fail at word expansion | |
7446 | time if extglob hasn't been enabled by the time the command is | |
7447 | executed. | |
7448 | ||
a0c0a00f CR |
7449 | \1f |
7450 | File: bash.info, Node: Job Control, Next: Command Line Editing, Prev: Bash Features, Up: Top | |
7451 | ||
7452 | 7 Job Control | |
7453 | ************* | |
7454 | ||
7455 | This chapter discusses what job control is, how it works, and how Bash | |
7456 | allows you to access its facilities. | |
7457 | ||
7458 | * Menu: | |
7459 | ||
7460 | * Job Control Basics:: How job control works. | |
7461 | * Job Control Builtins:: Bash builtin commands used to interact | |
7462 | with job control. | |
7463 | * Job Control Variables:: Variables Bash uses to customize job | |
7464 | control. | |
7465 | ||
7466 | \1f | |
7467 | File: bash.info, Node: Job Control Basics, Next: Job Control Builtins, Up: Job Control | |
7468 | ||
7469 | 7.1 Job Control Basics | |
7470 | ====================== | |
7471 | ||
7472 | Job control refers to the ability to selectively stop (suspend) the | |
7473 | execution of processes and continue (resume) their execution at a later | |
7474 | point. A user typically employs this facility via an interactive | |
7475 | interface supplied jointly by the operating system kernel's terminal | |
7476 | driver and Bash. | |
7477 | ||
7478 | The shell associates a JOB with each pipeline. It keeps a table of | |
7479 | currently executing jobs, which may be listed with the 'jobs' command. | |
7480 | When Bash starts a job asynchronously, it prints a line that looks like: | |
7481 | [1] 25647 | |
7482 | indicating that this job is job number 1 and that the process ID of the | |
7483 | last process in the pipeline associated with this job is 25647. All of | |
7484 | the processes in a single pipeline are members of the same job. Bash | |
7485 | uses the JOB abstraction as the basis for job control. | |
7486 | ||
7487 | To facilitate the implementation of the user interface to job | |
7488 | control, the operating system maintains the notion of a current terminal | |
7489 | process group ID. Members of this process group (processes whose | |
7490 | process group ID is equal to the current terminal process group ID) | |
7491 | receive keyboard-generated signals such as 'SIGINT'. These processes | |
7492 | are said to be in the foreground. Background processes are those whose | |
7493 | process group ID differs from the terminal's; such processes are immune | |
7494 | to keyboard-generated signals. Only foreground processes are allowed to | |
7495 | read from or, if the user so specifies with 'stty tostop', write to the | |
7496 | terminal. Background processes which attempt to read from (write to | |
7497 | when 'stty tostop' is in effect) the terminal are sent a 'SIGTTIN' | |
7498 | ('SIGTTOU') signal by the kernel's terminal driver, which, unless | |
7499 | caught, suspends the process. | |
7500 | ||
7501 | If the operating system on which Bash is running supports job | |
74091dd4 | 7502 | control, Bash contains facilities to use it. Typing the "suspend" |
a0c0a00f CR |
7503 | character (typically '^Z', Control-Z) while a process is running causes |
7504 | that process to be stopped and returns control to Bash. Typing the | |
74091dd4 CR |
7505 | "delayed suspend" character (typically '^Y', Control-Y) causes the |
7506 | process to be stopped when it attempts to read input from the terminal, | |
7507 | and control to be returned to Bash. The user then manipulates the state | |
7508 | of this job, using the 'bg' command to continue it in the background, | |
7509 | the 'fg' command to continue it in the foreground, or the 'kill' command | |
7510 | to kill it. A '^Z' takes effect immediately, and has the additional | |
7511 | side effect of causing pending output and typeahead to be discarded. | |
a0c0a00f CR |
7512 | |
7513 | There are a number of ways to refer to a job in the shell. The | |
74091dd4 | 7514 | character '%' introduces a job specification ("jobspec"). |
a0c0a00f CR |
7515 | |
7516 | Job number 'n' may be referred to as '%n'. The symbols '%%' and '%+' | |
7517 | refer to the shell's notion of the current job, which is the last job | |
7518 | stopped while it was in the foreground or started in the background. A | |
7519 | single '%' (with no accompanying job specification) also refers to the | |
7520 | current job. The previous job may be referenced using '%-'. If there | |
7521 | is only a single job, '%+' and '%-' can both be used to refer to that | |
7522 | job. In output pertaining to jobs (e.g., the output of the 'jobs' | |
7523 | command), the current job is always flagged with a '+', and the previous | |
7524 | job with a '-'. | |
7525 | ||
7526 | A job may also be referred to using a prefix of the name used to | |
7527 | start it, or using a substring that appears in its command line. For | |
8868edaf CR |
7528 | example, '%ce' refers to a stopped job whose command name begins with |
7529 | 'ce'. Using '%?ce', on the other hand, refers to any job containing the | |
7530 | string 'ce' in its command line. If the prefix or substring matches | |
7531 | more than one job, Bash reports an error. | |
a0c0a00f CR |
7532 | |
7533 | Simply naming a job can be used to bring it into the foreground: '%1' | |
7534 | is a synonym for 'fg %1', bringing job 1 from the background into the | |
7535 | foreground. Similarly, '%1 &' resumes job 1 in the background, | |
7536 | equivalent to 'bg %1' | |
7537 | ||
7538 | The shell learns immediately whenever a job changes state. Normally, | |
7539 | Bash waits until it is about to print a prompt before reporting changes | |
7540 | in a job's status so as to not interrupt any other output. If the '-b' | |
7541 | option to the 'set' builtin is enabled, Bash reports such changes | |
7542 | immediately (*note The Set Builtin::). Any trap on 'SIGCHLD' is | |
7543 | executed for each child process that exits. | |
7544 | ||
7545 | If an attempt to exit Bash is made while jobs are stopped, (or | |
7546 | running, if the 'checkjobs' option is enabled - see *note The Shopt | |
7547 | Builtin::), the shell prints a warning message, and if the 'checkjobs' | |
7548 | option is enabled, lists the jobs and their statuses. The 'jobs' | |
7549 | command may then be used to inspect their status. If a second attempt | |
7550 | to exit is made without an intervening command, Bash does not print | |
7551 | another warning, and any stopped jobs are terminated. | |
7552 | ||
d233b485 CR |
7553 | When the shell is waiting for a job or process using the 'wait' |
7554 | builtin, and job control is enabled, 'wait' will return when the job | |
8868edaf CR |
7555 | changes state. The '-f' option causes 'wait' to wait until the job or |
7556 | process terminates before returning. | |
d233b485 | 7557 | |
a0c0a00f CR |
7558 | \1f |
7559 | File: bash.info, Node: Job Control Builtins, Next: Job Control Variables, Prev: Job Control Basics, Up: Job Control | |
7560 | ||
7561 | 7.2 Job Control Builtins | |
7562 | ======================== | |
7563 | ||
7564 | 'bg' | |
7565 | bg [JOBSPEC ...] | |
7566 | ||
7567 | Resume each suspended job JOBSPEC in the background, as if it had | |
7568 | been started with '&'. If JOBSPEC is not supplied, the current job | |
7569 | is used. The return status is zero unless it is run when job | |
7570 | control is not enabled, or, when run with job control enabled, any | |
7571 | JOBSPEC was not found or specifies a job that was started without | |
7572 | job control. | |
7573 | ||
7574 | 'fg' | |
7575 | fg [JOBSPEC] | |
7576 | ||
7577 | Resume the job JOBSPEC in the foreground and make it the current | |
7578 | job. If JOBSPEC is not supplied, the current job is used. The | |
7579 | return status is that of the command placed into the foreground, or | |
7580 | non-zero if run when job control is disabled or, when run with job | |
7581 | control enabled, JOBSPEC does not specify a valid job or JOBSPEC | |
7582 | specifies a job that was started without job control. | |
7583 | ||
7584 | 'jobs' | |
7585 | jobs [-lnprs] [JOBSPEC] | |
7586 | jobs -x COMMAND [ARGUMENTS] | |
7587 | ||
7588 | The first form lists the active jobs. The options have the | |
7589 | following meanings: | |
7590 | ||
7591 | '-l' | |
7592 | List process IDs in addition to the normal information. | |
7593 | ||
7594 | '-n' | |
7595 | Display information only about jobs that have changed status | |
7596 | since the user was last notified of their status. | |
7597 | ||
7598 | '-p' | |
7599 | List only the process ID of the job's process group leader. | |
7600 | ||
7601 | '-r' | |
7602 | Display only running jobs. | |
7603 | ||
7604 | '-s' | |
7605 | Display only stopped jobs. | |
7606 | ||
7607 | If JOBSPEC is given, output is restricted to information about that | |
7608 | job. If JOBSPEC is not supplied, the status of all jobs is listed. | |
7609 | ||
7610 | If the '-x' option is supplied, 'jobs' replaces any JOBSPEC found | |
7611 | in COMMAND or ARGUMENTS with the corresponding process group ID, | |
7612 | and executes COMMAND, passing it ARGUMENTs, returning its exit | |
7613 | status. | |
7614 | ||
7615 | 'kill' | |
7616 | kill [-s SIGSPEC] [-n SIGNUM] [-SIGSPEC] JOBSPEC or PID | |
7617 | kill -l|-L [EXIT_STATUS] | |
7618 | ||
7619 | Send a signal specified by SIGSPEC or SIGNUM to the process named | |
7620 | by job specification JOBSPEC or process ID PID. SIGSPEC is either | |
7621 | a case-insensitive signal name such as 'SIGINT' (with or without | |
7622 | the 'SIG' prefix) or a signal number; SIGNUM is a signal number. | |
7623 | If SIGSPEC and SIGNUM are not present, 'SIGTERM' is used. The '-l' | |
7624 | option lists the signal names. If any arguments are supplied when | |
7625 | '-l' is given, the names of the signals corresponding to the | |
7626 | arguments are listed, and the return status is zero. EXIT_STATUS | |
7627 | is a number specifying a signal number or the exit status of a | |
7628 | process terminated by a signal. The '-L' option is equivalent to | |
7629 | '-l'. The return status is zero if at least one signal was | |
7630 | successfully sent, or non-zero if an error occurs or an invalid | |
7631 | option is encountered. | |
7632 | ||
7633 | 'wait' | |
8868edaf | 7634 | wait [-fn] [-p VARNAME] [JOBSPEC or PID ...] |
a0c0a00f CR |
7635 | |
7636 | Wait until the child process specified by each process ID PID or | |
7637 | job specification JOBSPEC exits and return the exit status of the | |
7638 | last command waited for. If a job spec is given, all processes in | |
8868edaf CR |
7639 | the job are waited for. If no arguments are given, 'wait' waits |
7640 | for all running background jobs and the last-executed process | |
7641 | substitution, if its process id is the same as $!, and the return | |
7642 | status is zero. If the '-n' option is supplied, 'wait' waits for a | |
74091dd4 | 7643 | single job from the list of PIDs or JOBSPECs or, if no arguments |
8868edaf CR |
7644 | are supplied, any job, to complete and returns its exit status. If |
7645 | none of the supplied arguments is a child of the shell, or if no | |
7646 | arguments are supplied and the shell has no unwaited-for children, | |
7647 | the exit status is 127. If the '-p' option is supplied, the | |
7648 | process or job identifier of the job for which the exit status is | |
7649 | returned is assigned to the variable VARNAME named by the option | |
7650 | argument. The variable will be unset initially, before any | |
7651 | assignment. This is useful only when the '-n' option is supplied. | |
7652 | Supplying the '-f' option, when job control is enabled, forces | |
7653 | 'wait' to wait for each PID or JOBSPEC to terminate before | |
74091dd4 | 7654 | returning its status, instead of returning when it changes status. |
8868edaf | 7655 | If neither JOBSPEC nor PID specifies an active child process of the |
74091dd4 CR |
7656 | shell, the return status is 127. If 'wait' is interrupted by a |
7657 | signal, the return status will be greater than 128, as described | |
7658 | above (*note Signals::). Otherwise, the return status is the exit | |
7659 | status of the last process or job waited for. | |
a0c0a00f CR |
7660 | |
7661 | 'disown' | |
7662 | disown [-ar] [-h] [JOBSPEC ... | PID ... ] | |
7663 | ||
7664 | Without options, remove each JOBSPEC from the table of active jobs. | |
7665 | If the '-h' option is given, the job is not removed from the table, | |
7666 | but is marked so that 'SIGHUP' is not sent to the job if the shell | |
7667 | receives a 'SIGHUP'. If JOBSPEC is not present, and neither the | |
7668 | '-a' nor the '-r' option is supplied, the current job is used. If | |
7669 | no JOBSPEC is supplied, the '-a' option means to remove or mark all | |
7670 | jobs; the '-r' option without a JOBSPEC argument restricts | |
7671 | operation to running jobs. | |
7672 | ||
7673 | 'suspend' | |
7674 | suspend [-f] | |
7675 | ||
7676 | Suspend the execution of this shell until it receives a 'SIGCONT' | |
74091dd4 CR |
7677 | signal. A login shell, or a shell without job control enabled, |
7678 | cannot be suspended; the '-f' option can be used to override this | |
7679 | and force the suspension. The return status is 0 unless the shell | |
7680 | is a login shell or job control is not enabled and '-f' is not | |
7681 | supplied. | |
a0c0a00f CR |
7682 | |
7683 | When job control is not active, the 'kill' and 'wait' builtins do not | |
7684 | accept JOBSPEC arguments. They must be supplied process IDs. | |
7685 | ||
7686 | \1f | |
7687 | File: bash.info, Node: Job Control Variables, Prev: Job Control Builtins, Up: Job Control | |
7688 | ||
7689 | 7.3 Job Control Variables | |
7690 | ========================= | |
7691 | ||
7692 | 'auto_resume' | |
7693 | This variable controls how the shell interacts with the user and | |
7694 | job control. If this variable exists then single word simple | |
7695 | commands without redirections are treated as candidates for | |
7696 | resumption of an existing job. There is no ambiguity allowed; if | |
7697 | there is more than one job beginning with the string typed, then | |
7698 | the most recently accessed job will be selected. The name of a | |
7699 | stopped job, in this context, is the command line used to start it. | |
7700 | If this variable is set to the value 'exact', the string supplied | |
7701 | must match the name of a stopped job exactly; if set to | |
7702 | 'substring', the string supplied needs to match a substring of the | |
7703 | name of a stopped job. The 'substring' value provides | |
7704 | functionality analogous to the '%?' job ID (*note Job Control | |
7705 | Basics::). If set to any other value, the supplied string must be | |
7706 | a prefix of a stopped job's name; this provides functionality | |
7707 | analogous to the '%' job ID. | |
7708 | ||
7709 | \1f | |
7710 | File: bash.info, Node: Command Line Editing, Next: Using History Interactively, Prev: Job Control, Up: Top | |
7711 | ||
7712 | 8 Command Line Editing | |
7713 | ********************** | |
7714 | ||
7715 | This chapter describes the basic features of the GNU command line | |
7716 | editing interface. Command line editing is provided by the Readline | |
7717 | library, which is used by several different programs, including Bash. | |
7718 | Command line editing is enabled by default when using an interactive | |
7719 | shell, unless the '--noediting' option is supplied at shell invocation. | |
7720 | Line editing is also used when using the '-e' option to the 'read' | |
7721 | builtin command (*note Bash Builtins::). By default, the line editing | |
7722 | commands are similar to those of Emacs. A vi-style line editing | |
7723 | interface is also available. Line editing can be enabled at any time | |
7724 | using the '-o emacs' or '-o vi' options to the 'set' builtin command | |
7725 | (*note The Set Builtin::), or disabled using the '+o emacs' or '+o vi' | |
7726 | options to 'set'. | |
7727 | ||
7728 | * Menu: | |
7729 | ||
7730 | * Introduction and Notation:: Notation used in this text. | |
7731 | * Readline Interaction:: The minimum set of commands for editing a line. | |
7732 | * Readline Init File:: Customizing Readline from a user's view. | |
7733 | * Bindable Readline Commands:: A description of most of the Readline commands | |
7734 | available for binding | |
7735 | * Readline vi Mode:: A short description of how to make Readline | |
7736 | behave like the vi editor. | |
7737 | * Programmable Completion:: How to specify the possible completions for | |
7738 | a specific command. | |
7739 | * Programmable Completion Builtins:: Builtin commands to specify how to | |
7740 | complete arguments for a particular command. | |
7741 | * A Programmable Completion Example:: An example shell function for | |
7742 | generating possible completions. | |
7743 | ||
7744 | \1f | |
7745 | File: bash.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing | |
7746 | ||
7747 | 8.1 Introduction to Line Editing | |
7748 | ================================ | |
7749 | ||
7750 | The following paragraphs describe the notation used to represent | |
7751 | keystrokes. | |
7752 | ||
7753 | The text 'C-k' is read as 'Control-K' and describes the character | |
7754 | produced when the <k> key is pressed while the Control key is depressed. | |
7755 | ||
7756 | The text 'M-k' is read as 'Meta-K' and describes the character | |
7757 | produced when the Meta key (if you have one) is depressed, and the <k> | |
7758 | key is pressed. The Meta key is labeled <ALT> on many keyboards. On | |
7759 | keyboards with two keys labeled <ALT> (usually to either side of the | |
7760 | space bar), the <ALT> on the left side is generally set to work as a | |
7761 | Meta key. The <ALT> key on the right may also be configured to work as | |
7762 | a Meta key or may be configured as some other modifier, such as a | |
7763 | Compose key for typing accented characters. | |
7764 | ||
7765 | If you do not have a Meta or <ALT> key, or another key working as a | |
7766 | Meta key, the identical keystroke can be generated by typing <ESC> | |
7767 | _first_, and then typing <k>. Either process is known as "metafying" | |
7768 | the <k> key. | |
7769 | ||
7770 | The text 'M-C-k' is read as 'Meta-Control-k' and describes the | |
7771 | character produced by "metafying" 'C-k'. | |
7772 | ||
7773 | In addition, several keys have their own names. Specifically, <DEL>, | |
7774 | <ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves when seen | |
7775 | in this text, or in an init file (*note Readline Init File::). If your | |
7776 | keyboard lacks a <LFD> key, typing <C-j> will produce the desired | |
7777 | character. The <RET> key may be labeled <Return> or <Enter> on some | |
7778 | keyboards. | |
7779 | ||
7780 | \1f | |
7781 | File: bash.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing | |
7782 | ||
7783 | 8.2 Readline Interaction | |
7784 | ======================== | |
7785 | ||
7786 | Often during an interactive session you type in a long line of text, | |
7787 | only to notice that the first word on the line is misspelled. The | |
7788 | Readline library gives you a set of commands for manipulating the text | |
7789 | as you type it in, allowing you to just fix your typo, and not forcing | |
7790 | you to retype the majority of the line. Using these editing commands, | |
7791 | you move the cursor to the place that needs correction, and delete or | |
7792 | insert the text of the corrections. Then, when you are satisfied with | |
7793 | the line, you simply press <RET>. You do not have to be at the end of | |
7794 | the line to press <RET>; the entire line is accepted regardless of the | |
7795 | location of the cursor within the line. | |
7796 | ||
7797 | * Menu: | |
7798 | ||
7799 | * Readline Bare Essentials:: The least you need to know about Readline. | |
7800 | * Readline Movement Commands:: Moving about the input line. | |
7801 | * Readline Killing Commands:: How to delete text, and how to get it back! | |
7802 | * Readline Arguments:: Giving numeric arguments to commands. | |
7803 | * Searching:: Searching through previous lines. | |
7804 | ||
7805 | \1f | |
7806 | File: bash.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction | |
7807 | ||
7808 | 8.2.1 Readline Bare Essentials | |
7809 | ------------------------------ | |
7810 | ||
7811 | In order to enter characters into the line, simply type them. The typed | |
7812 | character appears where the cursor was, and then the cursor moves one | |
7813 | space to the right. If you mistype a character, you can use your erase | |
7814 | character to back up and delete the mistyped character. | |
7815 | ||
7816 | Sometimes you may mistype a character, and not notice the error until | |
7817 | you have typed several other characters. In that case, you can type | |
7818 | 'C-b' to move the cursor to the left, and then correct your mistake. | |
7819 | Afterwards, you can move the cursor to the right with 'C-f'. | |
7820 | ||
7821 | When you add text in the middle of a line, you will notice that | |
7822 | characters to the right of the cursor are 'pushed over' to make room for | |
7823 | the text that you have inserted. Likewise, when you delete text behind | |
7824 | the cursor, characters to the right of the cursor are 'pulled back' to | |
7825 | fill in the blank space created by the removal of the text. A list of | |
7826 | the bare essentials for editing the text of an input line follows. | |
7827 | ||
7828 | 'C-b' | |
7829 | Move back one character. | |
7830 | 'C-f' | |
7831 | Move forward one character. | |
7832 | <DEL> or <Backspace> | |
7833 | Delete the character to the left of the cursor. | |
7834 | 'C-d' | |
7835 | Delete the character underneath the cursor. | |
7836 | Printing characters | |
7837 | Insert the character into the line at the cursor. | |
7838 | 'C-_' or 'C-x C-u' | |
7839 | Undo the last editing command. You can undo all the way back to an | |
7840 | empty line. | |
7841 | ||
74091dd4 CR |
7842 | (Depending on your configuration, the <Backspace> key might be set to |
7843 | delete the character to the left of the cursor and the <DEL> key set to | |
7844 | delete the character underneath the cursor, like 'C-d', rather than the | |
a0c0a00f CR |
7845 | character to the left of the cursor.) |
7846 | ||
7847 | \1f | |
7848 | File: bash.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction | |
7849 | ||
7850 | 8.2.2 Readline Movement Commands | |
7851 | -------------------------------- | |
7852 | ||
7853 | The above table describes the most basic keystrokes that you need in | |
7854 | order to do editing of the input line. For your convenience, many other | |
7855 | commands have been added in addition to 'C-b', 'C-f', 'C-d', and <DEL>. | |
7856 | Here are some commands for moving more rapidly about the line. | |
7857 | ||
7858 | 'C-a' | |
7859 | Move to the start of the line. | |
7860 | 'C-e' | |
7861 | Move to the end of the line. | |
7862 | 'M-f' | |
7863 | Move forward a word, where a word is composed of letters and | |
7864 | digits. | |
7865 | 'M-b' | |
7866 | Move backward a word. | |
7867 | 'C-l' | |
7868 | Clear the screen, reprinting the current line at the top. | |
7869 | ||
7870 | Notice how 'C-f' moves forward a character, while 'M-f' moves forward | |
7871 | a word. It is a loose convention that control keystrokes operate on | |
7872 | characters while meta keystrokes operate on words. | |
7873 | ||
7874 | \1f | |
7875 | File: bash.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction | |
7876 | ||
7877 | 8.2.3 Readline Killing Commands | |
7878 | ------------------------------- | |
7879 | ||
7880 | "Killing" text means to delete the text from the line, but to save it | |
7881 | away for later use, usually by "yanking" (re-inserting) it back into the | |
7882 | line. ('Cut' and 'paste' are more recent jargon for 'kill' and 'yank'.) | |
7883 | ||
7884 | If the description for a command says that it 'kills' text, then you | |
7885 | can be sure that you can get the text back in a different (or the same) | |
7886 | place later. | |
7887 | ||
7888 | When you use a kill command, the text is saved in a "kill-ring". Any | |
7889 | number of consecutive kills save all of the killed text together, so | |
7890 | that when you yank it back, you get it all. The kill ring is not line | |
7891 | specific; the text that you killed on a previously typed line is | |
7892 | available to be yanked back later, when you are typing another line. | |
7893 | ||
7894 | Here is the list of commands for killing text. | |
7895 | ||
7896 | 'C-k' | |
7897 | Kill the text from the current cursor position to the end of the | |
7898 | line. | |
7899 | ||
7900 | 'M-d' | |
7901 | Kill from the cursor to the end of the current word, or, if between | |
7902 | words, to the end of the next word. Word boundaries are the same | |
7903 | as those used by 'M-f'. | |
7904 | ||
7905 | 'M-<DEL>' | |
74091dd4 CR |
7906 | Kill from the cursor to the start of the current word, or, if |
7907 | between words, to the start of the previous word. Word boundaries | |
7908 | are the same as those used by 'M-b'. | |
a0c0a00f CR |
7909 | |
7910 | 'C-w' | |
7911 | Kill from the cursor to the previous whitespace. This is different | |
7912 | than 'M-<DEL>' because the word boundaries differ. | |
7913 | ||
7914 | Here is how to "yank" the text back into the line. Yanking means to | |
7915 | copy the most-recently-killed text from the kill buffer. | |
7916 | ||
7917 | 'C-y' | |
7918 | Yank the most recently killed text back into the buffer at the | |
7919 | cursor. | |
7920 | ||
7921 | 'M-y' | |
7922 | Rotate the kill-ring, and yank the new top. You can only do this | |
7923 | if the prior command is 'C-y' or 'M-y'. | |
7924 | ||
7925 | \1f | |
7926 | File: bash.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction | |
7927 | ||
7928 | 8.2.4 Readline Arguments | |
7929 | ------------------------ | |
7930 | ||
7931 | You can pass numeric arguments to Readline commands. Sometimes the | |
7932 | argument acts as a repeat count, other times it is the sign of the | |
7933 | argument that is significant. If you pass a negative argument to a | |
7934 | command which normally acts in a forward direction, that command will | |
7935 | act in a backward direction. For example, to kill text back to the | |
7936 | start of the line, you might type 'M-- C-k'. | |
7937 | ||
7938 | The general way to pass numeric arguments to a command is to type | |
7939 | meta digits before the command. If the first 'digit' typed is a minus | |
7940 | sign ('-'), then the sign of the argument will be negative. Once you | |
7941 | have typed one meta digit to get the argument started, you can type the | |
7942 | remainder of the digits, and then the command. For example, to give the | |
7943 | 'C-d' command an argument of 10, you could type 'M-1 0 C-d', which will | |
7944 | delete the next ten characters on the input line. | |
7945 | ||
7946 | \1f | |
7947 | File: bash.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction | |
7948 | ||
7949 | 8.2.5 Searching for Commands in the History | |
7950 | ------------------------------------------- | |
7951 | ||
7952 | Readline provides commands for searching through the command history | |
7953 | (*note Bash History Facilities::) for lines containing a specified | |
7954 | string. There are two search modes: "incremental" and | |
7955 | "non-incremental". | |
7956 | ||
7957 | Incremental searches begin before the user has finished typing the | |
7958 | search string. As each character of the search string is typed, | |
7959 | Readline displays the next entry from the history matching the string | |
7960 | typed so far. An incremental search requires only as many characters as | |
7961 | needed to find the desired history entry. To search backward in the | |
7962 | history for a particular string, type 'C-r'. Typing 'C-s' searches | |
7963 | forward through the history. The characters present in the value of the | |
7964 | 'isearch-terminators' variable are used to terminate an incremental | |
7965 | search. If that variable has not been assigned a value, the <ESC> and | |
7966 | 'C-J' characters will terminate an incremental search. 'C-g' will abort | |
7967 | an incremental search and restore the original line. When the search is | |
7968 | terminated, the history entry containing the search string becomes the | |
7969 | current line. | |
7970 | ||
7971 | To find other matching entries in the history list, type 'C-r' or | |
7972 | 'C-s' as appropriate. This will search backward or forward in the | |
7973 | history for the next entry matching the search string typed so far. Any | |
7974 | other key sequence bound to a Readline command will terminate the search | |
7975 | and execute that command. For instance, a <RET> will terminate the | |
7976 | search and accept the line, thereby executing the command from the | |
7977 | history list. A movement command will terminate the search, make the | |
7978 | last line found the current line, and begin editing. | |
7979 | ||
7980 | Readline remembers the last incremental search string. If two 'C-r's | |
7981 | are typed without any intervening characters defining a new search | |
7982 | string, any remembered search string is used. | |
7983 | ||
7984 | Non-incremental searches read the entire search string before | |
7985 | starting to search for matching history lines. The search string may be | |
7986 | typed by the user or be part of the contents of the current line. | |
7987 | ||
7988 | \1f | |
7989 | File: bash.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing | |
7990 | ||
7991 | 8.3 Readline Init File | |
7992 | ====================== | |
7993 | ||
7994 | Although the Readline library comes with a set of Emacs-like keybindings | |
7995 | installed by default, it is possible to use a different set of | |
7996 | keybindings. Any user can customize programs that use Readline by | |
74091dd4 | 7997 | putting commands in an "inputrc" file, conventionally in their home |
a0c0a00f CR |
7998 | directory. The name of this file is taken from the value of the shell |
7999 | variable 'INPUTRC'. If that variable is unset, the default is | |
8000 | '~/.inputrc'. If that file does not exist or cannot be read, the | |
8868edaf CR |
8001 | ultimate default is '/etc/inputrc'. The 'bind' builtin command can also |
8002 | be used to set Readline keybindings and variables. *Note Bash | |
8003 | Builtins::. | |
a0c0a00f CR |
8004 | |
8005 | When a program which uses the Readline library starts up, the init | |
8006 | file is read, and the key bindings are set. | |
8007 | ||
8008 | In addition, the 'C-x C-r' command re-reads this init file, thus | |
8009 | incorporating any changes that you might have made to it. | |
8010 | ||
8011 | * Menu: | |
8012 | ||
8013 | * Readline Init File Syntax:: Syntax for the commands in the inputrc file. | |
8014 | ||
8015 | * Conditional Init Constructs:: Conditional key bindings in the inputrc file. | |
8016 | ||
8017 | * Sample Init File:: An example inputrc file. | |
8018 | ||
8019 | \1f | |
8020 | File: bash.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File | |
8021 | ||
8022 | 8.3.1 Readline Init File Syntax | |
8023 | ------------------------------- | |
8024 | ||
8025 | There are only a few basic constructs allowed in the Readline init file. | |
8026 | Blank lines are ignored. Lines beginning with a '#' are comments. | |
8027 | Lines beginning with a '$' indicate conditional constructs (*note | |
8028 | Conditional Init Constructs::). Other lines denote variable settings | |
8029 | and key bindings. | |
8030 | ||
8031 | Variable Settings | |
8032 | You can modify the run-time behavior of Readline by altering the | |
8033 | values of variables in Readline using the 'set' command within the | |
8034 | init file. The syntax is simple: | |
8035 | ||
8036 | set VARIABLE VALUE | |
8037 | ||
8038 | Here, for example, is how to change from the default Emacs-like key | |
8039 | binding to use 'vi' line editing commands: | |
8040 | ||
8041 | set editing-mode vi | |
8042 | ||
8043 | Variable names and values, where appropriate, are recognized | |
8044 | without regard to case. Unrecognized variable names are ignored. | |
8045 | ||
8046 | Boolean variables (those that can be set to on or off) are set to | |
8047 | on if the value is null or empty, ON (case-insensitive), or 1. Any | |
8048 | other value results in the variable being set to off. | |
8049 | ||
8050 | The 'bind -V' command lists the current Readline variable names and | |
8051 | values. *Note Bash Builtins::. | |
8052 | ||
8053 | A great deal of run-time behavior is changeable with the following | |
8054 | variables. | |
8055 | ||
74091dd4 CR |
8056 | 'active-region-start-color' |
8057 | A string variable that controls the text color and background | |
8058 | when displaying the text in the active region (see the | |
8059 | description of 'enable-active-region' below). This string | |
8060 | must not take up any physical character positions on the | |
8061 | display, so it should consist only of terminal escape | |
8062 | sequences. It is output to the terminal before displaying the | |
8063 | text in the active region. This variable is reset to the | |
8064 | default value whenever the terminal type changes. The default | |
8065 | value is the string that puts the terminal in standout mode, | |
8066 | as obtained from the terminal's terminfo description. A | |
8067 | sample value might be '\e[01;33m'. | |
8068 | ||
8069 | 'active-region-end-color' | |
8070 | A string variable that "undoes" the effects of | |
8071 | 'active-region-start-color' and restores "normal" terminal | |
8072 | display appearance after displaying text in the active region. | |
8073 | This string must not take up any physical character positions | |
8074 | on the display, so it should consist only of terminal escape | |
8075 | sequences. It is output to the terminal after displaying the | |
8076 | text in the active region. This variable is reset to the | |
8077 | default value whenever the terminal type changes. The default | |
8078 | value is the string that restores the terminal from standout | |
8079 | mode, as obtained from the terminal's terminfo description. A | |
8080 | sample value might be '\e[0m'. | |
8081 | ||
a0c0a00f CR |
8082 | 'bell-style' |
8083 | Controls what happens when Readline wants to ring the terminal | |
8084 | bell. If set to 'none', Readline never rings the bell. If | |
8085 | set to 'visible', Readline uses a visible bell if one is | |
8086 | available. If set to 'audible' (the default), Readline | |
8087 | attempts to ring the terminal's bell. | |
8088 | ||
8089 | 'bind-tty-special-chars' | |
8090 | If set to 'on' (the default), Readline attempts to bind the | |
8091 | control characters treated specially by the kernel's terminal | |
8092 | driver to their Readline equivalents. | |
8093 | ||
8094 | 'blink-matching-paren' | |
8095 | If set to 'on', Readline attempts to briefly move the cursor | |
8096 | to an opening parenthesis when a closing parenthesis is | |
8097 | inserted. The default is 'off'. | |
8098 | ||
8099 | 'colored-completion-prefix' | |
8100 | If set to 'on', when listing completions, Readline displays | |
8101 | the common prefix of the set of possible completions using a | |
8102 | different color. The color definitions are taken from the | |
74091dd4 CR |
8103 | value of the 'LS_COLORS' environment variable. If there is a |
8104 | color definition in 'LS_COLORS' for the custom suffix | |
8105 | 'readline-colored-completion-prefix', Readline uses this color | |
8106 | for the common prefix instead of its default. The default is | |
a0c0a00f CR |
8107 | 'off'. |
8108 | ||
8109 | 'colored-stats' | |
8110 | If set to 'on', Readline displays possible completions using | |
8111 | different colors to indicate their file type. The color | |
8112 | definitions are taken from the value of the 'LS_COLORS' | |
8113 | environment variable. The default is 'off'. | |
8114 | ||
8115 | 'comment-begin' | |
8116 | The string to insert at the beginning of the line when the | |
8117 | 'insert-comment' command is executed. The default value is | |
8118 | '"#"'. | |
8119 | ||
8120 | 'completion-display-width' | |
8121 | The number of screen columns used to display possible matches | |
8122 | when performing completion. The value is ignored if it is | |
8123 | less than 0 or greater than the terminal screen width. A | |
8124 | value of 0 will cause matches to be displayed one per line. | |
8125 | The default value is -1. | |
8126 | ||
8127 | 'completion-ignore-case' | |
8128 | If set to 'on', Readline performs filename matching and | |
8129 | completion in a case-insensitive fashion. The default value | |
8130 | is 'off'. | |
8131 | ||
8132 | 'completion-map-case' | |
8133 | If set to 'on', and COMPLETION-IGNORE-CASE is enabled, | |
8134 | Readline treats hyphens ('-') and underscores ('_') as | |
8135 | equivalent when performing case-insensitive filename matching | |
d233b485 | 8136 | and completion. The default value is 'off'. |
a0c0a00f CR |
8137 | |
8138 | 'completion-prefix-display-length' | |
8139 | The length in characters of the common prefix of a list of | |
8140 | possible completions that is displayed without modification. | |
8141 | When set to a value greater than zero, common prefixes longer | |
8142 | than this value are replaced with an ellipsis when displaying | |
8143 | possible completions. | |
8144 | ||
8145 | 'completion-query-items' | |
8146 | The number of possible completions that determines when the | |
8147 | user is asked whether the list of possibilities should be | |
8148 | displayed. If the number of possible completions is greater | |
8868edaf CR |
8149 | than or equal to this value, Readline will ask whether or not |
8150 | the user wishes to view them; otherwise, they are simply | |
8151 | listed. This variable must be set to an integer value greater | |
74091dd4 CR |
8152 | than or equal to zero. A zero value means Readline should |
8153 | never ask; negative values are treated as zero. The default | |
8154 | limit is '100'. | |
a0c0a00f CR |
8155 | |
8156 | 'convert-meta' | |
8157 | If set to 'on', Readline will convert characters with the | |
8158 | eighth bit set to an ASCII key sequence by stripping the | |
8159 | eighth bit and prefixing an <ESC> character, converting them | |
8160 | to a meta-prefixed key sequence. The default value is 'on', | |
8161 | but will be set to 'off' if the locale is one that contains | |
74091dd4 CR |
8162 | eight-bit characters. This variable is dependent on the |
8163 | 'LC_CTYPE' locale category, and may change if the locale is | |
8164 | changed. | |
a0c0a00f CR |
8165 | |
8166 | 'disable-completion' | |
8167 | If set to 'On', Readline will inhibit word completion. | |
8168 | Completion characters will be inserted into the line as if | |
8169 | they had been mapped to 'self-insert'. The default is 'off'. | |
8170 | ||
8171 | 'echo-control-characters' | |
8172 | When set to 'on', on operating systems that indicate they | |
74091dd4 | 8173 | support it, Readline echoes a character corresponding to a |
a0c0a00f CR |
8174 | signal generated from the keyboard. The default is 'on'. |
8175 | ||
8176 | 'editing-mode' | |
8177 | The 'editing-mode' variable controls which default set of key | |
8178 | bindings is used. By default, Readline starts up in Emacs | |
8179 | editing mode, where the keystrokes are most similar to Emacs. | |
8180 | This variable can be set to either 'emacs' or 'vi'. | |
8181 | ||
8182 | 'emacs-mode-string' | |
d233b485 CR |
8183 | If the SHOW-MODE-IN-PROMPT variable is enabled, this string is |
8184 | displayed immediately before the last line of the primary | |
8185 | prompt when emacs editing mode is active. The value is | |
8186 | expanded like a key binding, so the standard set of meta- and | |
8187 | control prefixes and backslash escape sequences is available. | |
8188 | Use the '\1' and '\2' escapes to begin and end sequences of | |
8189 | non-printing characters, which can be used to embed a terminal | |
8190 | control sequence into the mode string. The default is '@'. | |
a0c0a00f | 8191 | |
74091dd4 CR |
8192 | 'enable-active-region' |
8193 | The "point" is the current cursor position, and "mark" refers | |
8194 | to a saved cursor position (*note Commands For Moving::). The | |
8195 | text between the point and mark is referred to as the | |
8196 | "region". When this variable is set to 'On', Readline allows | |
8197 | certain commands to designate the region as "active". When | |
8198 | the region is active, Readline highlights the text in the | |
8199 | region using the value of the 'active-region-start-color', | |
8200 | which defaults to the string that enables the terminal's | |
8201 | standout mode. The active region shows the text inserted by | |
8202 | bracketed-paste and any matching text found by incremental and | |
8203 | non-incremental history searches. The default is 'On'. | |
8204 | ||
a0c0a00f | 8205 | 'enable-bracketed-paste' |
74091dd4 CR |
8206 | When set to 'On', Readline configures the terminal to insert |
8207 | each paste into the editing buffer as a single string of | |
8208 | characters, instead of treating each character as if it had | |
8209 | been read from the keyboard. This is called putting the | |
8210 | terminal into "bracketed paste mode"; it prevents Readline | |
8211 | from executing any editing commands bound to key sequences | |
8212 | appearing in the pasted text. The default is 'On'. | |
a0c0a00f CR |
8213 | |
8214 | 'enable-keypad' | |
8215 | When set to 'on', Readline will try to enable the application | |
8216 | keypad when it is called. Some systems need this to enable | |
8217 | the arrow keys. The default is 'off'. | |
8218 | ||
8219 | 'enable-meta-key' | |
8220 | When set to 'on', Readline will try to enable any meta | |
8221 | modifier key the terminal claims to support when it is called. | |
8222 | On many terminals, the meta key is used to send eight-bit | |
8223 | characters. The default is 'on'. | |
8224 | ||
8225 | 'expand-tilde' | |
8226 | If set to 'on', tilde expansion is performed when Readline | |
8227 | attempts word completion. The default is 'off'. | |
8228 | ||
8229 | 'history-preserve-point' | |
8230 | If set to 'on', the history code attempts to place the point | |
8231 | (the current cursor position) at the same location on each | |
8232 | history line retrieved with 'previous-history' or | |
8233 | 'next-history'. The default is 'off'. | |
8234 | ||
8235 | 'history-size' | |
8236 | Set the maximum number of history entries saved in the history | |
8237 | list. If set to zero, any existing history entries are | |
8238 | deleted and no new entries are saved. If set to a value less | |
8239 | than zero, the number of history entries is not limited. By | |
8240 | default, the number of history entries is not limited. If an | |
8241 | attempt is made to set HISTORY-SIZE to a non-numeric value, | |
8242 | the maximum number of history entries will be set to 500. | |
8243 | ||
8244 | 'horizontal-scroll-mode' | |
8245 | This variable can be set to either 'on' or 'off'. Setting it | |
8246 | to 'on' means that the text of the lines being edited will | |
8247 | scroll horizontally on a single screen line when they are | |
8248 | longer than the width of the screen, instead of wrapping onto | |
8868edaf CR |
8249 | a new screen line. This variable is automatically set to 'on' |
8250 | for terminals of height 1. By default, this variable is set | |
8251 | to 'off'. | |
a0c0a00f CR |
8252 | |
8253 | 'input-meta' | |
8254 | If set to 'on', Readline will enable eight-bit input (it will | |
8255 | not clear the eighth bit in the characters it reads), | |
8256 | regardless of what the terminal claims it can support. The | |
8257 | default value is 'off', but Readline will set it to 'on' if | |
8258 | the locale contains eight-bit characters. The name | |
74091dd4 CR |
8259 | 'meta-flag' is a synonym for this variable. This variable is |
8260 | dependent on the 'LC_CTYPE' locale category, and may change if | |
8261 | the locale is changed. | |
a0c0a00f CR |
8262 | |
8263 | 'isearch-terminators' | |
8264 | The string of characters that should terminate an incremental | |
8265 | search without subsequently executing the character as a | |
8266 | command (*note Searching::). If this variable has not been | |
8267 | given a value, the characters <ESC> and 'C-J' will terminate | |
8268 | an incremental search. | |
8269 | ||
8270 | 'keymap' | |
8271 | Sets Readline's idea of the current keymap for key binding | |
d233b485 | 8272 | commands. Built-in 'keymap' names are 'emacs', |
a0c0a00f CR |
8273 | 'emacs-standard', 'emacs-meta', 'emacs-ctlx', 'vi', 'vi-move', |
8274 | 'vi-command', and 'vi-insert'. 'vi' is equivalent to | |
8275 | 'vi-command' ('vi-move' is also a synonym); 'emacs' is | |
d233b485 CR |
8276 | equivalent to 'emacs-standard'. Applications may add |
8277 | additional names. The default value is 'emacs'. The value of | |
8278 | the 'editing-mode' variable also affects the default keymap. | |
a0c0a00f CR |
8279 | |
8280 | 'keyseq-timeout' | |
8281 | Specifies the duration Readline will wait for a character when | |
8282 | reading an ambiguous key sequence (one that can form a | |
8283 | complete key sequence using the input read so far, or can take | |
8284 | additional input to complete a longer key sequence). If no | |
8285 | input is received within the timeout, Readline will use the | |
8286 | shorter but complete key sequence. Readline uses this value | |
8287 | to determine whether or not input is available on the current | |
8288 | input source ('rl_instream' by default). The value is | |
8289 | specified in milliseconds, so a value of 1000 means that | |
8290 | Readline will wait one second for additional input. If this | |
8291 | variable is set to a value less than or equal to zero, or to a | |
8292 | non-numeric value, Readline will wait until another key is | |
8293 | pressed to decide which key sequence to complete. The default | |
8294 | value is '500'. | |
8295 | ||
8296 | 'mark-directories' | |
8297 | If set to 'on', completed directory names have a slash | |
8298 | appended. The default is 'on'. | |
8299 | ||
8300 | 'mark-modified-lines' | |
8301 | This variable, when set to 'on', causes Readline to display an | |
8302 | asterisk ('*') at the start of history lines which have been | |
8303 | modified. This variable is 'off' by default. | |
8304 | ||
8305 | 'mark-symlinked-directories' | |
8306 | If set to 'on', completed names which are symbolic links to | |
8307 | directories have a slash appended (subject to the value of | |
8308 | 'mark-directories'). The default is 'off'. | |
8309 | ||
8310 | 'match-hidden-files' | |
8311 | This variable, when set to 'on', causes Readline to match | |
8312 | files whose names begin with a '.' (hidden files) when | |
8313 | performing filename completion. If set to 'off', the leading | |
8314 | '.' must be supplied by the user in the filename to be | |
8315 | completed. This variable is 'on' by default. | |
8316 | ||
8317 | 'menu-complete-display-prefix' | |
8318 | If set to 'on', menu completion displays the common prefix of | |
8319 | the list of possible completions (which may be empty) before | |
8320 | cycling through the list. The default is 'off'. | |
8321 | ||
8322 | 'output-meta' | |
8323 | If set to 'on', Readline will display characters with the | |
8324 | eighth bit set directly rather than as a meta-prefixed escape | |
8325 | sequence. The default is 'off', but Readline will set it to | |
74091dd4 CR |
8326 | 'on' if the locale contains eight-bit characters. This |
8327 | variable is dependent on the 'LC_CTYPE' locale category, and | |
8328 | may change if the locale is changed. | |
a0c0a00f CR |
8329 | |
8330 | 'page-completions' | |
8331 | If set to 'on', Readline uses an internal 'more'-like pager to | |
8332 | display a screenful of possible completions at a time. This | |
8333 | variable is 'on' by default. | |
8334 | ||
8335 | 'print-completions-horizontally' | |
8336 | If set to 'on', Readline will display completions with matches | |
8337 | sorted horizontally in alphabetical order, rather than down | |
8338 | the screen. The default is 'off'. | |
8339 | ||
8340 | 'revert-all-at-newline' | |
8341 | If set to 'on', Readline will undo all changes to history | |
8342 | lines before returning when 'accept-line' is executed. By | |
8343 | default, history lines may be modified and retain individual | |
74091dd4 CR |
8344 | undo lists across calls to 'readline()'. The default is |
8345 | 'off'. | |
a0c0a00f CR |
8346 | |
8347 | 'show-all-if-ambiguous' | |
8348 | This alters the default behavior of the completion functions. | |
8349 | If set to 'on', words which have more than one possible | |
8350 | completion cause the matches to be listed immediately instead | |
8351 | of ringing the bell. The default value is 'off'. | |
8352 | ||
8353 | 'show-all-if-unmodified' | |
8354 | This alters the default behavior of the completion functions | |
8355 | in a fashion similar to SHOW-ALL-IF-AMBIGUOUS. If set to | |
8356 | 'on', words which have more than one possible completion | |
8357 | without any possible partial completion (the possible | |
8358 | completions don't share a common prefix) cause the matches to | |
8359 | be listed immediately instead of ringing the bell. The | |
8360 | default value is 'off'. | |
8361 | ||
8362 | 'show-mode-in-prompt' | |
d233b485 | 8363 | If set to 'on', add a string to the beginning of the prompt |
a0c0a00f | 8364 | indicating the editing mode: emacs, vi command, or vi |
d233b485 CR |
8365 | insertion. The mode strings are user-settable (e.g., |
8366 | EMACS-MODE-STRING). The default value is 'off'. | |
a0c0a00f CR |
8367 | |
8368 | 'skip-completed-text' | |
8369 | If set to 'on', this alters the default completion behavior | |
8370 | when inserting a single match into the line. It's only active | |
8371 | when performing completion in the middle of a word. If | |
74091dd4 | 8372 | enabled, Readline does not insert characters from the |
a0c0a00f CR |
8373 | completion that match characters after point in the word being |
8374 | completed, so portions of the word following the cursor are | |
8375 | not duplicated. For instance, if this is enabled, attempting | |
8376 | completion when the cursor is after the 'e' in 'Makefile' will | |
8377 | result in 'Makefile' rather than 'Makefilefile', assuming | |
8378 | there is a single possible completion. The default value is | |
8379 | 'off'. | |
8380 | ||
8381 | 'vi-cmd-mode-string' | |
d233b485 CR |
8382 | If the SHOW-MODE-IN-PROMPT variable is enabled, this string is |
8383 | displayed immediately before the last line of the primary | |
8384 | prompt when vi editing mode is active and in command mode. | |
8385 | The value is expanded like a key binding, so the standard set | |
8386 | of meta- and control prefixes and backslash escape sequences | |
8387 | is available. Use the '\1' and '\2' escapes to begin and end | |
8388 | sequences of non-printing characters, which can be used to | |
8389 | embed a terminal control sequence into the mode string. The | |
8390 | default is '(cmd)'. | |
a0c0a00f CR |
8391 | |
8392 | 'vi-ins-mode-string' | |
d233b485 CR |
8393 | If the SHOW-MODE-IN-PROMPT variable is enabled, this string is |
8394 | displayed immediately before the last line of the primary | |
8395 | prompt when vi editing mode is active and in insertion mode. | |
8396 | The value is expanded like a key binding, so the standard set | |
8397 | of meta- and control prefixes and backslash escape sequences | |
8398 | is available. Use the '\1' and '\2' escapes to begin and end | |
8399 | sequences of non-printing characters, which can be used to | |
8400 | embed a terminal control sequence into the mode string. The | |
8401 | default is '(ins)'. | |
a0c0a00f CR |
8402 | |
8403 | 'visible-stats' | |
8404 | If set to 'on', a character denoting a file's type is appended | |
8405 | to the filename when listing possible completions. The | |
8406 | default is 'off'. | |
8407 | ||
8408 | Key Bindings | |
8409 | The syntax for controlling key bindings in the init file is simple. | |
8410 | First you need to find the name of the command that you want to | |
8411 | change. The following sections contain tables of the command name, | |
8412 | the default keybinding, if any, and a short description of what the | |
8413 | command does. | |
8414 | ||
8415 | Once you know the name of the command, simply place on a line in | |
8416 | the init file the name of the key you wish to bind the command to, | |
8417 | a colon, and then the name of the command. There can be no space | |
8418 | between the key name and the colon - that will be interpreted as | |
8419 | part of the key name. The name of the key can be expressed in | |
8420 | different ways, depending on what you find most comfortable. | |
8421 | ||
74091dd4 | 8422 | In addition to command names, Readline allows keys to be bound to a |
a0c0a00f CR |
8423 | string that is inserted when the key is pressed (a MACRO). |
8424 | ||
8425 | The 'bind -p' command displays Readline function names and bindings | |
74091dd4 | 8426 | in a format that can be put directly into an initialization file. |
a0c0a00f CR |
8427 | *Note Bash Builtins::. |
8428 | ||
8429 | KEYNAME: FUNCTION-NAME or MACRO | |
8430 | KEYNAME is the name of a key spelled out in English. For | |
8431 | example: | |
8432 | Control-u: universal-argument | |
8433 | Meta-Rubout: backward-kill-word | |
8434 | Control-o: "> output" | |
8435 | ||
d233b485 | 8436 | In the example above, 'C-u' is bound to the function |
a0c0a00f CR |
8437 | 'universal-argument', 'M-DEL' is bound to the function |
8438 | 'backward-kill-word', and 'C-o' is bound to run the macro | |
8439 | expressed on the right hand side (that is, to insert the text | |
8440 | '> output' into the line). | |
8441 | ||
8442 | A number of symbolic character names are recognized while | |
8443 | processing this key binding syntax: DEL, ESC, ESCAPE, LFD, | |
8444 | NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB. | |
8445 | ||
8446 | "KEYSEQ": FUNCTION-NAME or MACRO | |
8447 | KEYSEQ differs from KEYNAME above in that strings denoting an | |
8448 | entire key sequence can be specified, by placing the key | |
8449 | sequence in double quotes. Some GNU Emacs style key escapes | |
8450 | can be used, as in the following example, but the special | |
8451 | character names are not recognized. | |
8452 | ||
8453 | "\C-u": universal-argument | |
8454 | "\C-x\C-r": re-read-init-file | |
8455 | "\e[11~": "Function Key 1" | |
8456 | ||
8457 | In the above example, 'C-u' is again bound to the function | |
8458 | 'universal-argument' (just as it was in the first example), | |
8459 | ''C-x' 'C-r'' is bound to the function 're-read-init-file', | |
8460 | and '<ESC> <[> <1> <1> <~>' is bound to insert the text | |
8461 | 'Function Key 1'. | |
8462 | ||
8463 | The following GNU Emacs style escape sequences are available when | |
8464 | specifying key sequences: | |
8465 | ||
8466 | '\C-' | |
8467 | control prefix | |
8468 | '\M-' | |
8469 | meta prefix | |
8470 | '\e' | |
8471 | an escape character | |
8472 | '\\' | |
8473 | backslash | |
8474 | '\"' | |
8475 | <">, a double quotation mark | |
8476 | '\'' | |
8477 | <'>, a single quote or apostrophe | |
8478 | ||
8479 | In addition to the GNU Emacs style escape sequences, a second set | |
8480 | of backslash escapes is available: | |
8481 | ||
8482 | '\a' | |
8483 | alert (bell) | |
8484 | '\b' | |
8485 | backspace | |
8486 | '\d' | |
8487 | delete | |
8488 | '\f' | |
8489 | form feed | |
8490 | '\n' | |
8491 | newline | |
8492 | '\r' | |
8493 | carriage return | |
8494 | '\t' | |
8495 | horizontal tab | |
8496 | '\v' | |
8497 | vertical tab | |
8498 | '\NNN' | |
8499 | the eight-bit character whose value is the octal value NNN | |
8500 | (one to three digits) | |
8501 | '\xHH' | |
8502 | the eight-bit character whose value is the hexadecimal value | |
8503 | HH (one or two hex digits) | |
8504 | ||
8505 | When entering the text of a macro, single or double quotes must be | |
8506 | used to indicate a macro definition. Unquoted text is assumed to | |
8507 | be a function name. In the macro body, the backslash escapes | |
8508 | described above are expanded. Backslash will quote any other | |
8509 | character in the macro text, including '"' and '''. For example, | |
8510 | the following binding will make ''C-x' \' insert a single '\' into | |
8511 | the line: | |
8512 | "\C-x\\": "\\" | |
8513 | ||
8514 | \1f | |
8515 | File: bash.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File | |
8516 | ||
8517 | 8.3.2 Conditional Init Constructs | |
8518 | --------------------------------- | |
8519 | ||
8520 | Readline implements a facility similar in spirit to the conditional | |
8521 | compilation features of the C preprocessor which allows key bindings and | |
8522 | variable settings to be performed as the result of tests. There are | |
8523 | four parser directives used. | |
8524 | ||
8525 | '$if' | |
8526 | The '$if' construct allows bindings to be made based on the editing | |
8527 | mode, the terminal being used, or the application using Readline. | |
d233b485 CR |
8528 | The text of the test, after any comparison operator, extends to the |
8529 | end of the line; unless otherwise noted, no characters are required | |
8530 | to isolate it. | |
a0c0a00f CR |
8531 | |
8532 | 'mode' | |
8533 | The 'mode=' form of the '$if' directive is used to test | |
8534 | whether Readline is in 'emacs' or 'vi' mode. This may be used | |
8535 | in conjunction with the 'set keymap' command, for instance, to | |
8536 | set bindings in the 'emacs-standard' and 'emacs-ctlx' keymaps | |
8537 | only if Readline is starting out in 'emacs' mode. | |
8538 | ||
8539 | 'term' | |
8540 | The 'term=' form may be used to include terminal-specific key | |
8541 | bindings, perhaps to bind the key sequences output by the | |
8542 | terminal's function keys. The word on the right side of the | |
8543 | '=' is tested against both the full name of the terminal and | |
8544 | the portion of the terminal name before the first '-'. This | |
8545 | allows 'sun' to match both 'sun' and 'sun-cmd', for instance. | |
8546 | ||
d233b485 CR |
8547 | 'version' |
8548 | The 'version' test may be used to perform comparisons against | |
8549 | specific Readline versions. The 'version' expands to the | |
8550 | current Readline version. The set of comparison operators | |
8551 | includes '=' (and '=='), '!=', '<=', '>=', '<', and '>'. The | |
8552 | version number supplied on the right side of the operator | |
8553 | consists of a major version number, an optional decimal point, | |
8554 | and an optional minor version (e.g., '7.1'). If the minor | |
8555 | version is omitted, it is assumed to be '0'. The operator may | |
8556 | be separated from the string 'version' and from the version | |
8557 | number argument by whitespace. The following example sets a | |
8558 | variable if the Readline version being used is 7.0 or newer: | |
8559 | $if version >= 7.0 | |
8560 | set show-mode-in-prompt on | |
8561 | $endif | |
8562 | ||
a0c0a00f CR |
8563 | 'application' |
8564 | The APPLICATION construct is used to include | |
8565 | application-specific settings. Each program using the | |
8566 | Readline library sets the APPLICATION NAME, and you can test | |
8567 | for a particular value. This could be used to bind key | |
8568 | sequences to functions useful for a specific program. For | |
8569 | instance, the following command adds a key sequence that | |
8570 | quotes the current or previous word in Bash: | |
8571 | $if Bash | |
8572 | # Quote the current or previous word | |
8573 | "\C-xq": "\eb\"\ef\"" | |
8574 | $endif | |
8575 | ||
d233b485 CR |
8576 | 'variable' |
8577 | The VARIABLE construct provides simple equality tests for | |
8578 | Readline variables and values. The permitted comparison | |
8579 | operators are '=', '==', and '!='. The variable name must be | |
8580 | separated from the comparison operator by whitespace; the | |
8581 | operator may be separated from the value on the right hand | |
8582 | side by whitespace. Both string and boolean variables may be | |
8583 | tested. Boolean variables must be tested against the values | |
8584 | ON and OFF. The following example is equivalent to the | |
8585 | 'mode=emacs' test described above: | |
8586 | $if editing-mode == emacs | |
8587 | set show-mode-in-prompt on | |
8588 | $endif | |
8589 | ||
a0c0a00f CR |
8590 | '$endif' |
8591 | This command, as seen in the previous example, terminates an '$if' | |
8592 | command. | |
8593 | ||
8594 | '$else' | |
8595 | Commands in this branch of the '$if' directive are executed if the | |
8596 | test fails. | |
8597 | ||
8598 | '$include' | |
8599 | This directive takes a single filename as an argument and reads | |
8600 | commands and bindings from that file. For example, the following | |
8601 | directive reads from '/etc/inputrc': | |
8602 | $include /etc/inputrc | |
8603 | ||
8604 | \1f | |
8605 | File: bash.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File | |
8606 | ||
8607 | 8.3.3 Sample Init File | |
8608 | ---------------------- | |
8609 | ||
8610 | Here is an example of an INPUTRC file. This illustrates key binding, | |
8611 | variable assignment, and conditional syntax. | |
8612 | ||
8613 | # This file controls the behaviour of line input editing for | |
8614 | # programs that use the GNU Readline library. Existing | |
8615 | # programs include FTP, Bash, and GDB. | |
8616 | # | |
8617 | # You can re-read the inputrc file with C-x C-r. | |
8618 | # Lines beginning with '#' are comments. | |
8619 | # | |
8620 | # First, include any system-wide bindings and variable | |
8621 | # assignments from /etc/Inputrc | |
8622 | $include /etc/Inputrc | |
8623 | ||
8624 | # | |
8625 | # Set various bindings for emacs mode. | |
8626 | ||
8627 | set editing-mode emacs | |
8628 | ||
8629 | $if mode=emacs | |
8630 | ||
8631 | Meta-Control-h: backward-kill-word Text after the function name is ignored | |
8632 | ||
8633 | # | |
8634 | # Arrow keys in keypad mode | |
8635 | # | |
8636 | #"\M-OD": backward-char | |
8637 | #"\M-OC": forward-char | |
8638 | #"\M-OA": previous-history | |
8639 | #"\M-OB": next-history | |
8640 | # | |
8641 | # Arrow keys in ANSI mode | |
8642 | # | |
8643 | "\M-[D": backward-char | |
8644 | "\M-[C": forward-char | |
8645 | "\M-[A": previous-history | |
8646 | "\M-[B": next-history | |
8647 | # | |
8648 | # Arrow keys in 8 bit keypad mode | |
8649 | # | |
8650 | #"\M-\C-OD": backward-char | |
8651 | #"\M-\C-OC": forward-char | |
8652 | #"\M-\C-OA": previous-history | |
8653 | #"\M-\C-OB": next-history | |
8654 | # | |
8655 | # Arrow keys in 8 bit ANSI mode | |
8656 | # | |
8657 | #"\M-\C-[D": backward-char | |
8658 | #"\M-\C-[C": forward-char | |
8659 | #"\M-\C-[A": previous-history | |
8660 | #"\M-\C-[B": next-history | |
8661 | ||
8662 | C-q: quoted-insert | |
8663 | ||
8664 | $endif | |
8665 | ||
8666 | # An old-style binding. This happens to be the default. | |
8667 | TAB: complete | |
8668 | ||
8669 | # Macros that are convenient for shell interaction | |
8670 | $if Bash | |
8671 | # edit the path | |
8672 | "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f" | |
8673 | # prepare to type a quoted word -- | |
8674 | # insert open and close double quotes | |
8675 | # and move to just after the open quote | |
8676 | "\C-x\"": "\"\"\C-b" | |
8677 | # insert a backslash (testing backslash escapes | |
8678 | # in sequences and macros) | |
8679 | "\C-x\\": "\\" | |
8680 | # Quote the current or previous word | |
8681 | "\C-xq": "\eb\"\ef\"" | |
8682 | # Add a binding to refresh the line, which is unbound | |
8683 | "\C-xr": redraw-current-line | |
8684 | # Edit variable on current line. | |
8685 | "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y=" | |
8686 | $endif | |
8687 | ||
8688 | # use a visible bell if one is available | |
8689 | set bell-style visible | |
8690 | ||
8691 | # don't strip characters to 7 bits when reading | |
8692 | set input-meta on | |
8693 | ||
8694 | # allow iso-latin1 characters to be inserted rather | |
8695 | # than converted to prefix-meta sequences | |
8696 | set convert-meta off | |
8697 | ||
8698 | # display characters with the eighth bit set directly | |
8699 | # rather than as meta-prefixed characters | |
8700 | set output-meta on | |
8701 | ||
8868edaf CR |
8702 | # if there are 150 or more possible completions for a word, |
8703 | # ask whether or not the user wants to see all of them | |
a0c0a00f CR |
8704 | set completion-query-items 150 |
8705 | ||
8706 | # For FTP | |
8707 | $if Ftp | |
8708 | "\C-xg": "get \M-?" | |
8709 | "\C-xt": "put \M-?" | |
8710 | "\M-.": yank-last-arg | |
8711 | $endif | |
8712 | ||
8713 | \1f | |
8714 | File: bash.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing | |
8715 | ||
8716 | 8.4 Bindable Readline Commands | |
8717 | ============================== | |
8718 | ||
8719 | * Menu: | |
8720 | ||
8721 | * Commands For Moving:: Moving about the line. | |
8722 | * Commands For History:: Getting at previous lines. | |
8723 | * Commands For Text:: Commands for changing text. | |
8724 | * Commands For Killing:: Commands for killing and yanking. | |
8725 | * Numeric Arguments:: Specifying numeric arguments, repeat counts. | |
8726 | * Commands For Completion:: Getting Readline to do the typing for you. | |
8727 | * Keyboard Macros:: Saving and re-executing typed characters | |
8728 | * Miscellaneous Commands:: Other miscellaneous commands. | |
8729 | ||
8730 | This section describes Readline commands that may be bound to key | |
8731 | sequences. You can list your key bindings by executing 'bind -P' or, | |
8732 | for a more terse format, suitable for an INPUTRC file, 'bind -p'. | |
8733 | (*Note Bash Builtins::.) Command names without an accompanying key | |
8734 | sequence are unbound by default. | |
8735 | ||
8736 | In the following descriptions, "point" refers to the current cursor | |
8737 | position, and "mark" refers to a cursor position saved by the 'set-mark' | |
8738 | command. The text between the point and mark is referred to as the | |
8739 | "region". | |
8740 | ||
8741 | \1f | |
8742 | File: bash.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands | |
8743 | ||
8744 | 8.4.1 Commands For Moving | |
8745 | ------------------------- | |
8746 | ||
8747 | 'beginning-of-line (C-a)' | |
8748 | Move to the start of the current line. | |
8749 | ||
8750 | 'end-of-line (C-e)' | |
8751 | Move to the end of the line. | |
8752 | ||
8753 | 'forward-char (C-f)' | |
8754 | Move forward a character. | |
8755 | ||
8756 | 'backward-char (C-b)' | |
8757 | Move back a character. | |
8758 | ||
8759 | 'forward-word (M-f)' | |
8760 | Move forward to the end of the next word. Words are composed of | |
8761 | letters and digits. | |
8762 | ||
8763 | 'backward-word (M-b)' | |
8764 | Move back to the start of the current or previous word. Words are | |
8765 | composed of letters and digits. | |
8766 | ||
8868edaf | 8767 | 'shell-forward-word (M-C-f)' |
a0c0a00f CR |
8768 | Move forward to the end of the next word. Words are delimited by |
8769 | non-quoted shell metacharacters. | |
8770 | ||
8868edaf | 8771 | 'shell-backward-word (M-C-b)' |
a0c0a00f CR |
8772 | Move back to the start of the current or previous word. Words are |
8773 | delimited by non-quoted shell metacharacters. | |
8774 | ||
d233b485 CR |
8775 | 'previous-screen-line ()' |
8776 | Attempt to move point to the same physical screen column on the | |
8777 | previous physical screen line. This will not have the desired | |
8778 | effect if the current Readline line does not take up more than one | |
8779 | physical line or if point is not greater than the length of the | |
8780 | prompt plus the screen width. | |
8781 | ||
8782 | 'next-screen-line ()' | |
8783 | Attempt to move point to the same physical screen column on the | |
8784 | next physical screen line. This will not have the desired effect | |
8785 | if the current Readline line does not take up more than one | |
8786 | physical line or if the length of the current Readline line is not | |
8787 | greater than the length of the prompt plus the screen width. | |
8788 | ||
8868edaf CR |
8789 | 'clear-display (M-C-l)' |
8790 | Clear the screen and, if possible, the terminal's scrollback | |
8791 | buffer, then redraw the current line, leaving the current line at | |
8792 | the top of the screen. | |
8793 | ||
a0c0a00f | 8794 | 'clear-screen (C-l)' |
8868edaf | 8795 | Clear the screen, then redraw the current line, leaving the current |
a0c0a00f CR |
8796 | line at the top of the screen. |
8797 | ||
8798 | 'redraw-current-line ()' | |
8799 | Refresh the current line. By default, this is unbound. | |
8800 | ||
8801 | \1f | |
8802 | File: bash.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands | |
8803 | ||
8804 | 8.4.2 Commands For Manipulating The History | |
8805 | ------------------------------------------- | |
8806 | ||
8807 | 'accept-line (Newline or Return)' | |
8808 | Accept the line regardless of where the cursor is. If this line is | |
8809 | non-empty, add it to the history list according to the setting of | |
8810 | the 'HISTCONTROL' and 'HISTIGNORE' variables. If this line is a | |
8811 | modified history line, then restore the history line to its | |
8812 | original state. | |
8813 | ||
8814 | 'previous-history (C-p)' | |
8815 | Move 'back' through the history list, fetching the previous | |
8816 | command. | |
8817 | ||
8818 | 'next-history (C-n)' | |
8819 | Move 'forward' through the history list, fetching the next command. | |
8820 | ||
8821 | 'beginning-of-history (M-<)' | |
8822 | Move to the first line in the history. | |
8823 | ||
8824 | 'end-of-history (M->)' | |
8825 | Move to the end of the input history, i.e., the line currently | |
8826 | being entered. | |
8827 | ||
8828 | 'reverse-search-history (C-r)' | |
8829 | Search backward starting at the current line and moving 'up' | |
8830 | through the history as necessary. This is an incremental search. | |
8868edaf CR |
8831 | This command sets the region to the matched text and activates the |
8832 | mark. | |
a0c0a00f CR |
8833 | |
8834 | 'forward-search-history (C-s)' | |
8835 | Search forward starting at the current line and moving 'down' | |
8836 | through the history as necessary. This is an incremental search. | |
8868edaf CR |
8837 | This command sets the region to the matched text and activates the |
8838 | mark. | |
a0c0a00f CR |
8839 | |
8840 | 'non-incremental-reverse-search-history (M-p)' | |
8841 | Search backward starting at the current line and moving 'up' | |
8842 | through the history as necessary using a non-incremental search for | |
8843 | a string supplied by the user. The search string may match | |
8844 | anywhere in a history line. | |
8845 | ||
8846 | 'non-incremental-forward-search-history (M-n)' | |
8847 | Search forward starting at the current line and moving 'down' | |
8848 | through the history as necessary using a non-incremental search for | |
8849 | a string supplied by the user. The search string may match | |
8850 | anywhere in a history line. | |
8851 | ||
8852 | 'history-search-forward ()' | |
8853 | Search forward through the history for the string of characters | |
8854 | between the start of the current line and the point. The search | |
8855 | string must match at the beginning of a history line. This is a | |
8856 | non-incremental search. By default, this command is unbound. | |
8857 | ||
8858 | 'history-search-backward ()' | |
8859 | Search backward through the history for the string of characters | |
8860 | between the start of the current line and the point. The search | |
8861 | string must match at the beginning of a history line. This is a | |
8862 | non-incremental search. By default, this command is unbound. | |
8863 | ||
d233b485 | 8864 | 'history-substring-search-forward ()' |
a0c0a00f CR |
8865 | Search forward through the history for the string of characters |
8866 | between the start of the current line and the point. The search | |
8867 | string may match anywhere in a history line. This is a | |
8868 | non-incremental search. By default, this command is unbound. | |
8869 | ||
d233b485 | 8870 | 'history-substring-search-backward ()' |
a0c0a00f CR |
8871 | Search backward through the history for the string of characters |
8872 | between the start of the current line and the point. The search | |
8873 | string may match anywhere in a history line. This is a | |
8874 | non-incremental search. By default, this command is unbound. | |
8875 | ||
8876 | 'yank-nth-arg (M-C-y)' | |
8877 | Insert the first argument to the previous command (usually the | |
8878 | second word on the previous line) at point. With an argument N, | |
8879 | insert the Nth word from the previous command (the words in the | |
8880 | previous command begin with word 0). A negative argument inserts | |
8881 | the Nth word from the end of the previous command. Once the | |
8882 | argument N is computed, the argument is extracted as if the '!N' | |
8883 | history expansion had been specified. | |
8884 | ||
8885 | 'yank-last-arg (M-. or M-_)' | |
8886 | Insert last argument to the previous command (the last word of the | |
8887 | previous history entry). With a numeric argument, behave exactly | |
8888 | like 'yank-nth-arg'. Successive calls to 'yank-last-arg' move back | |
8889 | through the history list, inserting the last word (or the word | |
8890 | specified by the argument to the first call) of each line in turn. | |
8891 | Any numeric argument supplied to these successive calls determines | |
8892 | the direction to move through the history. A negative argument | |
8893 | switches the direction through the history (back or forward). The | |
8894 | history expansion facilities are used to extract the last argument, | |
8895 | as if the '!$' history expansion had been specified. | |
8896 | ||
8868edaf CR |
8897 | 'operate-and-get-next (C-o)' |
8898 | Accept the current line for return to the calling application as if | |
8899 | a newline had been entered, and fetch the next line relative to the | |
8900 | current line from the history for editing. A numeric argument, if | |
8901 | supplied, specifies the history entry to use instead of the current | |
8902 | line. | |
8903 | ||
74091dd4 CR |
8904 | 'fetch-history ()' |
8905 | With a numeric argument, fetch that entry from the history list and | |
8906 | make it the current line. Without an argument, move back to the | |
8907 | first entry in the history list. | |
8908 | ||
a0c0a00f CR |
8909 | \1f |
8910 | File: bash.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands | |
8911 | ||
8912 | 8.4.3 Commands For Changing Text | |
8913 | -------------------------------- | |
8914 | ||
8915 | 'end-of-file (usually C-d)' | |
8916 | The character indicating end-of-file as set, for example, by | |
8917 | 'stty'. If this character is read when there are no characters on | |
8918 | the line, and point is at the beginning of the line, Readline | |
8919 | interprets it as the end of input and returns EOF. | |
8920 | ||
8921 | 'delete-char (C-d)' | |
8922 | Delete the character at point. If this function is bound to the | |
8923 | same character as the tty EOF character, as 'C-d' commonly is, see | |
8924 | above for the effects. | |
8925 | ||
8926 | 'backward-delete-char (Rubout)' | |
8927 | Delete the character behind the cursor. A numeric argument means | |
8928 | to kill the characters instead of deleting them. | |
8929 | ||
8930 | 'forward-backward-delete-char ()' | |
8931 | Delete the character under the cursor, unless the cursor is at the | |
8932 | end of the line, in which case the character behind the cursor is | |
8933 | deleted. By default, this is not bound to a key. | |
8934 | ||
8935 | 'quoted-insert (C-q or C-v)' | |
8936 | Add the next character typed to the line verbatim. This is how to | |
8937 | insert key sequences like 'C-q', for example. | |
8938 | ||
8939 | 'self-insert (a, b, A, 1, !, ...)' | |
8940 | Insert yourself. | |
8941 | ||
8942 | 'bracketed-paste-begin ()' | |
8943 | This function is intended to be bound to the "bracketed paste" | |
8944 | escape sequence sent by some terminals, and such a binding is | |
8945 | assigned by default. It allows Readline to insert the pasted text | |
8946 | as a single unit without treating each character as if it had been | |
8947 | read from the keyboard. The characters are inserted as if each one | |
d233b485 | 8948 | was bound to 'self-insert' instead of executing any editing |
a0c0a00f CR |
8949 | commands. |
8950 | ||
8868edaf CR |
8951 | Bracketed paste sets the region (the characters between point and |
8952 | the mark) to the inserted text. It uses the concept of an _active | |
8953 | mark_: when the mark is active, Readline redisplay uses the | |
8954 | terminal's standout mode to denote the region. | |
8955 | ||
a0c0a00f CR |
8956 | 'transpose-chars (C-t)' |
8957 | Drag the character before the cursor forward over the character at | |
8958 | the cursor, moving the cursor forward as well. If the insertion | |
8959 | point is at the end of the line, then this transposes the last two | |
8960 | characters of the line. Negative arguments have no effect. | |
8961 | ||
8962 | 'transpose-words (M-t)' | |
8963 | Drag the word before point past the word after point, moving point | |
8964 | past that word as well. If the insertion point is at the end of | |
8965 | the line, this transposes the last two words on the line. | |
8966 | ||
8967 | 'upcase-word (M-u)' | |
8968 | Uppercase the current (or following) word. With a negative | |
8969 | argument, uppercase the previous word, but do not move the cursor. | |
8970 | ||
8971 | 'downcase-word (M-l)' | |
8972 | Lowercase the current (or following) word. With a negative | |
8973 | argument, lowercase the previous word, but do not move the cursor. | |
8974 | ||
8975 | 'capitalize-word (M-c)' | |
8976 | Capitalize the current (or following) word. With a negative | |
8977 | argument, capitalize the previous word, but do not move the cursor. | |
8978 | ||
8979 | 'overwrite-mode ()' | |
8980 | Toggle overwrite mode. With an explicit positive numeric argument, | |
8981 | switches to overwrite mode. With an explicit non-positive numeric | |
8982 | argument, switches to insert mode. This command affects only | |
8983 | 'emacs' mode; 'vi' mode does overwrite differently. Each call to | |
8984 | 'readline()' starts in insert mode. | |
8985 | ||
8986 | In overwrite mode, characters bound to 'self-insert' replace the | |
8987 | text at point rather than pushing the text to the right. | |
8988 | Characters bound to 'backward-delete-char' replace the character | |
8989 | before point with a space. | |
8990 | ||
8991 | By default, this command is unbound. | |
8992 | ||
8993 | \1f | |
8994 | File: bash.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands | |
8995 | ||
8996 | 8.4.4 Killing And Yanking | |
8997 | ------------------------- | |
8998 | ||
8999 | 'kill-line (C-k)' | |
8868edaf CR |
9000 | Kill the text from point to the end of the line. With a negative |
9001 | numeric argument, kill backward from the cursor to the beginning of | |
9002 | the current line. | |
a0c0a00f CR |
9003 | |
9004 | 'backward-kill-line (C-x Rubout)' | |
9005 | Kill backward from the cursor to the beginning of the current line. | |
8868edaf CR |
9006 | With a negative numeric argument, kill forward from the cursor to |
9007 | the end of the current line. | |
a0c0a00f CR |
9008 | |
9009 | 'unix-line-discard (C-u)' | |
9010 | Kill backward from the cursor to the beginning of the current line. | |
9011 | ||
9012 | 'kill-whole-line ()' | |
9013 | Kill all characters on the current line, no matter where point is. | |
9014 | By default, this is unbound. | |
9015 | ||
9016 | 'kill-word (M-d)' | |
9017 | Kill from point to the end of the current word, or if between | |
9018 | words, to the end of the next word. Word boundaries are the same | |
9019 | as 'forward-word'. | |
9020 | ||
9021 | 'backward-kill-word (M-<DEL>)' | |
9022 | Kill the word behind point. Word boundaries are the same as | |
9023 | 'backward-word'. | |
9024 | ||
8868edaf | 9025 | 'shell-kill-word (M-C-d)' |
a0c0a00f CR |
9026 | Kill from point to the end of the current word, or if between |
9027 | words, to the end of the next word. Word boundaries are the same | |
9028 | as 'shell-forward-word'. | |
9029 | ||
9030 | 'shell-backward-kill-word ()' | |
9031 | Kill the word behind point. Word boundaries are the same as | |
9032 | 'shell-backward-word'. | |
9033 | ||
8868edaf CR |
9034 | 'shell-transpose-words (M-C-t)' |
9035 | Drag the word before point past the word after point, moving point | |
9036 | past that word as well. If the insertion point is at the end of | |
9037 | the line, this transposes the last two words on the line. Word | |
9038 | boundaries are the same as 'shell-forward-word' and | |
9039 | 'shell-backward-word'. | |
9040 | ||
a0c0a00f CR |
9041 | 'unix-word-rubout (C-w)' |
9042 | Kill the word behind point, using white space as a word boundary. | |
9043 | The killed text is saved on the kill-ring. | |
9044 | ||
9045 | 'unix-filename-rubout ()' | |
9046 | Kill the word behind point, using white space and the slash | |
9047 | character as the word boundaries. The killed text is saved on the | |
9048 | kill-ring. | |
9049 | ||
9050 | 'delete-horizontal-space ()' | |
9051 | Delete all spaces and tabs around point. By default, this is | |
9052 | unbound. | |
9053 | ||
9054 | 'kill-region ()' | |
9055 | Kill the text in the current region. By default, this command is | |
9056 | unbound. | |
9057 | ||
9058 | 'copy-region-as-kill ()' | |
9059 | Copy the text in the region to the kill buffer, so it can be yanked | |
9060 | right away. By default, this command is unbound. | |
9061 | ||
9062 | 'copy-backward-word ()' | |
9063 | Copy the word before point to the kill buffer. The word boundaries | |
9064 | are the same as 'backward-word'. By default, this command is | |
9065 | unbound. | |
9066 | ||
9067 | 'copy-forward-word ()' | |
9068 | Copy the word following point to the kill buffer. The word | |
9069 | boundaries are the same as 'forward-word'. By default, this | |
9070 | command is unbound. | |
9071 | ||
9072 | 'yank (C-y)' | |
9073 | Yank the top of the kill ring into the buffer at point. | |
9074 | ||
9075 | 'yank-pop (M-y)' | |
9076 | Rotate the kill-ring, and yank the new top. You can only do this | |
9077 | if the prior command is 'yank' or 'yank-pop'. | |
9078 | ||
9079 | \1f | |
9080 | File: bash.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands | |
9081 | ||
9082 | 8.4.5 Specifying Numeric Arguments | |
9083 | ---------------------------------- | |
9084 | ||
9085 | 'digit-argument (M-0, M-1, ... M--)' | |
9086 | Add this digit to the argument already accumulating, or start a new | |
9087 | argument. 'M--' starts a negative argument. | |
9088 | ||
9089 | 'universal-argument ()' | |
9090 | This is another way to specify an argument. If this command is | |
9091 | followed by one or more digits, optionally with a leading minus | |
9092 | sign, those digits define the argument. If the command is followed | |
9093 | by digits, executing 'universal-argument' again ends the numeric | |
9094 | argument, but is otherwise ignored. As a special case, if this | |
9095 | command is immediately followed by a character that is neither a | |
9096 | digit nor minus sign, the argument count for the next command is | |
9097 | multiplied by four. The argument count is initially one, so | |
9098 | executing this function the first time makes the argument count | |
9099 | four, a second time makes the argument count sixteen, and so on. | |
9100 | By default, this is not bound to a key. | |
9101 | ||
9102 | \1f | |
9103 | File: bash.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands | |
9104 | ||
9105 | 8.4.6 Letting Readline Type For You | |
9106 | ----------------------------------- | |
9107 | ||
9108 | 'complete (<TAB>)' | |
9109 | Attempt to perform completion on the text before point. The actual | |
9110 | completion performed is application-specific. Bash attempts | |
9111 | completion treating the text as a variable (if the text begins with | |
9112 | '$'), username (if the text begins with '~'), hostname (if the text | |
9113 | begins with '@'), or command (including aliases and functions) in | |
9114 | turn. If none of these produces a match, filename completion is | |
9115 | attempted. | |
9116 | ||
9117 | 'possible-completions (M-?)' | |
9118 | List the possible completions of the text before point. When | |
9119 | displaying completions, Readline sets the number of columns used | |
9120 | for display to the value of 'completion-display-width', the value | |
9121 | of the environment variable 'COLUMNS', or the screen width, in that | |
9122 | order. | |
9123 | ||
9124 | 'insert-completions (M-*)' | |
9125 | Insert all completions of the text before point that would have | |
9126 | been generated by 'possible-completions'. | |
9127 | ||
9128 | 'menu-complete ()' | |
9129 | Similar to 'complete', but replaces the word to be completed with a | |
9130 | single match from the list of possible completions. Repeated | |
9131 | execution of 'menu-complete' steps through the list of possible | |
9132 | completions, inserting each match in turn. At the end of the list | |
9133 | of completions, the bell is rung (subject to the setting of | |
9134 | 'bell-style') and the original text is restored. An argument of N | |
9135 | moves N positions forward in the list of matches; a negative | |
9136 | argument may be used to move backward through the list. This | |
9137 | command is intended to be bound to <TAB>, but is unbound by | |
9138 | default. | |
9139 | ||
9140 | 'menu-complete-backward ()' | |
9141 | Identical to 'menu-complete', but moves backward through the list | |
9142 | of possible completions, as if 'menu-complete' had been given a | |
9143 | negative argument. | |
9144 | ||
9145 | 'delete-char-or-list ()' | |
9146 | Deletes the character under the cursor if not at the beginning or | |
9147 | end of the line (like 'delete-char'). If at the end of the line, | |
9148 | behaves identically to 'possible-completions'. This command is | |
9149 | unbound by default. | |
9150 | ||
9151 | 'complete-filename (M-/)' | |
9152 | Attempt filename completion on the text before point. | |
9153 | ||
9154 | 'possible-filename-completions (C-x /)' | |
9155 | List the possible completions of the text before point, treating it | |
9156 | as a filename. | |
9157 | ||
9158 | 'complete-username (M-~)' | |
9159 | Attempt completion on the text before point, treating it as a | |
9160 | username. | |
9161 | ||
9162 | 'possible-username-completions (C-x ~)' | |
9163 | List the possible completions of the text before point, treating it | |
9164 | as a username. | |
9165 | ||
9166 | 'complete-variable (M-$)' | |
9167 | Attempt completion on the text before point, treating it as a shell | |
9168 | variable. | |
9169 | ||
9170 | 'possible-variable-completions (C-x $)' | |
9171 | List the possible completions of the text before point, treating it | |
9172 | as a shell variable. | |
9173 | ||
9174 | 'complete-hostname (M-@)' | |
9175 | Attempt completion on the text before point, treating it as a | |
9176 | hostname. | |
9177 | ||
9178 | 'possible-hostname-completions (C-x @)' | |
9179 | List the possible completions of the text before point, treating it | |
9180 | as a hostname. | |
9181 | ||
9182 | 'complete-command (M-!)' | |
9183 | Attempt completion on the text before point, treating it as a | |
9184 | command name. Command completion attempts to match the text | |
9185 | against aliases, reserved words, shell functions, shell builtins, | |
9186 | and finally executable filenames, in that order. | |
9187 | ||
9188 | 'possible-command-completions (C-x !)' | |
9189 | List the possible completions of the text before point, treating it | |
9190 | as a command name. | |
9191 | ||
9192 | 'dynamic-complete-history (M-<TAB>)' | |
9193 | Attempt completion on the text before point, comparing the text | |
9194 | against lines from the history list for possible completion | |
9195 | matches. | |
9196 | ||
9197 | 'dabbrev-expand ()' | |
9198 | Attempt menu completion on the text before point, comparing the | |
9199 | text against lines from the history list for possible completion | |
9200 | matches. | |
9201 | ||
9202 | 'complete-into-braces (M-{)' | |
9203 | Perform filename completion and insert the list of possible | |
9204 | completions enclosed within braces so the list is available to the | |
9205 | shell (*note Brace Expansion::). | |
9206 | ||
9207 | \1f | |
9208 | File: bash.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands | |
9209 | ||
9210 | 8.4.7 Keyboard Macros | |
9211 | --------------------- | |
9212 | ||
9213 | 'start-kbd-macro (C-x ()' | |
9214 | Begin saving the characters typed into the current keyboard macro. | |
9215 | ||
9216 | 'end-kbd-macro (C-x ))' | |
9217 | Stop saving the characters typed into the current keyboard macro | |
9218 | and save the definition. | |
9219 | ||
9220 | 'call-last-kbd-macro (C-x e)' | |
9221 | Re-execute the last keyboard macro defined, by making the | |
9222 | characters in the macro appear as if typed at the keyboard. | |
9223 | ||
9224 | 'print-last-kbd-macro ()' | |
74091dd4 | 9225 | Print the last keyboard macro defined in a format suitable for the |
a0c0a00f CR |
9226 | INPUTRC file. |
9227 | ||
9228 | \1f | |
9229 | File: bash.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands | |
9230 | ||
9231 | 8.4.8 Some Miscellaneous Commands | |
9232 | --------------------------------- | |
9233 | ||
9234 | 're-read-init-file (C-x C-r)' | |
9235 | Read in the contents of the INPUTRC file, and incorporate any | |
9236 | bindings or variable assignments found there. | |
9237 | ||
9238 | 'abort (C-g)' | |
9239 | Abort the current editing command and ring the terminal's bell | |
9240 | (subject to the setting of 'bell-style'). | |
9241 | ||
d233b485 CR |
9242 | 'do-lowercase-version (M-A, M-B, M-X, ...)' |
9243 | If the metafied character X is upper case, run the command that is | |
9244 | bound to the corresponding metafied lower case character. The | |
9245 | behavior is undefined if X is already lower case. | |
a0c0a00f CR |
9246 | |
9247 | 'prefix-meta (<ESC>)' | |
9248 | Metafy the next character typed. This is for keyboards without a | |
9249 | meta key. Typing '<ESC> f' is equivalent to typing 'M-f'. | |
9250 | ||
9251 | 'undo (C-_ or C-x C-u)' | |
9252 | Incremental undo, separately remembered for each line. | |
9253 | ||
9254 | 'revert-line (M-r)' | |
9255 | Undo all changes made to this line. This is like executing the | |
9256 | 'undo' command enough times to get back to the beginning. | |
9257 | ||
9258 | 'tilde-expand (M-&)' | |
9259 | Perform tilde expansion on the current word. | |
9260 | ||
9261 | 'set-mark (C-@)' | |
9262 | Set the mark to the point. If a numeric argument is supplied, the | |
9263 | mark is set to that position. | |
9264 | ||
9265 | 'exchange-point-and-mark (C-x C-x)' | |
9266 | Swap the point with the mark. The current cursor position is set | |
9267 | to the saved position, and the old cursor position is saved as the | |
9268 | mark. | |
9269 | ||
9270 | 'character-search (C-])' | |
9271 | A character is read and point is moved to the next occurrence of | |
74091dd4 | 9272 | that character. A negative argument searches for previous |
a0c0a00f CR |
9273 | occurrences. |
9274 | ||
9275 | 'character-search-backward (M-C-])' | |
9276 | A character is read and point is moved to the previous occurrence | |
74091dd4 | 9277 | of that character. A negative argument searches for subsequent |
a0c0a00f CR |
9278 | occurrences. |
9279 | ||
9280 | 'skip-csi-sequence ()' | |
9281 | Read enough characters to consume a multi-key sequence such as | |
9282 | those defined for keys like Home and End. Such sequences begin | |
9283 | with a Control Sequence Indicator (CSI), usually ESC-[. If this | |
9284 | sequence is bound to "\e[", keys producing such sequences will have | |
74091dd4 | 9285 | no effect unless explicitly bound to a Readline command, instead of |
a0c0a00f CR |
9286 | inserting stray characters into the editing buffer. This is |
9287 | unbound by default, but usually bound to ESC-[. | |
9288 | ||
9289 | 'insert-comment (M-#)' | |
9290 | Without a numeric argument, the value of the 'comment-begin' | |
9291 | variable is inserted at the beginning of the current line. If a | |
9292 | numeric argument is supplied, this command acts as a toggle: if the | |
9293 | characters at the beginning of the line do not match the value of | |
9294 | 'comment-begin', the value is inserted, otherwise the characters in | |
9295 | 'comment-begin' are deleted from the beginning of the line. In | |
9296 | either case, the line is accepted as if a newline had been typed. | |
9297 | The default value of 'comment-begin' causes this command to make | |
9298 | the current line a shell comment. If a numeric argument causes the | |
9299 | comment character to be removed, the line will be executed by the | |
9300 | shell. | |
9301 | ||
9302 | 'dump-functions ()' | |
9303 | Print all of the functions and their key bindings to the Readline | |
9304 | output stream. If a numeric argument is supplied, the output is | |
9305 | formatted in such a way that it can be made part of an INPUTRC | |
9306 | file. This command is unbound by default. | |
9307 | ||
9308 | 'dump-variables ()' | |
9309 | Print all of the settable variables and their values to the | |
9310 | Readline output stream. If a numeric argument is supplied, the | |
9311 | output is formatted in such a way that it can be made part of an | |
9312 | INPUTRC file. This command is unbound by default. | |
9313 | ||
9314 | 'dump-macros ()' | |
9315 | Print all of the Readline key sequences bound to macros and the | |
9316 | strings they output. If a numeric argument is supplied, the output | |
9317 | is formatted in such a way that it can be made part of an INPUTRC | |
9318 | file. This command is unbound by default. | |
9319 | ||
74091dd4 CR |
9320 | 'spell-correct-word (C-x s)' |
9321 | Perform spelling correction on the current word, treating it as a | |
9322 | directory or filename, in the same way as the 'cdspell' shell | |
9323 | option. Word boundaries are the same as those used by | |
9324 | 'shell-forward-word'. | |
9325 | ||
a0c0a00f CR |
9326 | 'glob-complete-word (M-g)' |
9327 | The word before point is treated as a pattern for pathname | |
9328 | expansion, with an asterisk implicitly appended. This pattern is | |
9329 | used to generate a list of matching file names for possible | |
9330 | completions. | |
9331 | ||
9332 | 'glob-expand-word (C-x *)' | |
9333 | The word before point is treated as a pattern for pathname | |
9334 | expansion, and the list of matching file names is inserted, | |
9335 | replacing the word. If a numeric argument is supplied, a '*' is | |
9336 | appended before pathname expansion. | |
9337 | ||
9338 | 'glob-list-expansions (C-x g)' | |
9339 | The list of expansions that would have been generated by | |
9340 | 'glob-expand-word' is displayed, and the line is redrawn. If a | |
9341 | numeric argument is supplied, a '*' is appended before pathname | |
9342 | expansion. | |
9343 | ||
9344 | 'display-shell-version (C-x C-v)' | |
9345 | Display version information about the current instance of Bash. | |
9346 | ||
9347 | 'shell-expand-line (M-C-e)' | |
9348 | Expand the line as the shell does. This performs alias and history | |
9349 | expansion as well as all of the shell word expansions (*note Shell | |
9350 | Expansions::). | |
9351 | ||
9352 | 'history-expand-line (M-^)' | |
9353 | Perform history expansion on the current line. | |
9354 | ||
9355 | 'magic-space ()' | |
9356 | Perform history expansion on the current line and insert a space | |
9357 | (*note History Interaction::). | |
9358 | ||
9359 | 'alias-expand-line ()' | |
9360 | Perform alias expansion on the current line (*note Aliases::). | |
9361 | ||
9362 | 'history-and-alias-expand-line ()' | |
9363 | Perform history and alias expansion on the current line. | |
9364 | ||
9365 | 'insert-last-argument (M-. or M-_)' | |
9366 | A synonym for 'yank-last-arg'. | |
9367 | ||
d233b485 | 9368 | 'edit-and-execute-command (C-x C-e)' |
a0c0a00f CR |
9369 | Invoke an editor on the current command line, and execute the |
9370 | result as shell commands. Bash attempts to invoke '$VISUAL', | |
9371 | '$EDITOR', and 'emacs' as the editor, in that order. | |
9372 | ||
9373 | \1f | |
9374 | File: bash.info, Node: Readline vi Mode, Next: Programmable Completion, Prev: Bindable Readline Commands, Up: Command Line Editing | |
9375 | ||
9376 | 8.5 Readline vi Mode | |
9377 | ==================== | |
9378 | ||
9379 | While the Readline library does not have a full set of 'vi' editing | |
9380 | functions, it does contain enough to allow simple editing of the line. | |
9381 | The Readline 'vi' mode behaves as specified in the POSIX standard. | |
9382 | ||
9383 | In order to switch interactively between 'emacs' and 'vi' editing | |
9384 | modes, use the 'set -o emacs' and 'set -o vi' commands (*note The Set | |
9385 | Builtin::). The Readline default is 'emacs' mode. | |
9386 | ||
9387 | When you enter a line in 'vi' mode, you are already placed in | |
9388 | 'insertion' mode, as if you had typed an 'i'. Pressing <ESC> switches | |
9389 | you into 'command' mode, where you can edit the text of the line with | |
9390 | the standard 'vi' movement keys, move to previous history lines with 'k' | |
9391 | and subsequent lines with 'j', and so forth. | |
9392 | ||
9393 | \1f | |
9394 | File: bash.info, Node: Programmable Completion, Next: Programmable Completion Builtins, Prev: Readline vi Mode, Up: Command Line Editing | |
9395 | ||
9396 | 8.6 Programmable Completion | |
9397 | =========================== | |
9398 | ||
9399 | When word completion is attempted for an argument to a command for which | |
9400 | a completion specification (a COMPSPEC) has been defined using the | |
9401 | 'complete' builtin (*note Programmable Completion Builtins::), the | |
9402 | programmable completion facilities are invoked. | |
9403 | ||
9404 | First, the command name is identified. If a compspec has been | |
9405 | defined for that command, the compspec is used to generate the list of | |
9406 | possible completions for the word. If the command word is the empty | |
9407 | string (completion attempted at the beginning of an empty line), any | |
9408 | compspec defined with the '-E' option to 'complete' is used. If the | |
9409 | command word is a full pathname, a compspec for the full pathname is | |
9410 | searched for first. If no compspec is found for the full pathname, an | |
9411 | attempt is made to find a compspec for the portion following the final | |
9412 | slash. If those searches do not result in a compspec, any compspec | |
d233b485 CR |
9413 | defined with the '-D' option to 'complete' is used as the default. If |
9414 | there is no default compspec, Bash attempts alias expansion on the | |
9415 | command word as a final resort, and attempts to find a compspec for the | |
9416 | command word from any successful expansion | |
a0c0a00f CR |
9417 | |
9418 | Once a compspec has been found, it is used to generate the list of | |
9419 | matching words. If a compspec is not found, the default Bash completion | |
9420 | described above (*note Commands For Completion::) is performed. | |
9421 | ||
9422 | First, the actions specified by the compspec are used. Only matches | |
9423 | which are prefixed by the word being completed are returned. When the | |
9424 | '-f' or '-d' option is used for filename or directory name completion, | |
9425 | the shell variable 'FIGNORE' is used to filter the matches. *Note Bash | |
9426 | Variables::, for a description of 'FIGNORE'. | |
9427 | ||
9428 | Any completions specified by a filename expansion pattern to the '-G' | |
9429 | option are generated next. The words generated by the pattern need not | |
9430 | match the word being completed. The 'GLOBIGNORE' shell variable is not | |
9431 | used to filter the matches, but the 'FIGNORE' shell variable is used. | |
9432 | ||
9433 | Next, the string specified as the argument to the '-W' option is | |
9434 | considered. The string is first split using the characters in the 'IFS' | |
d233b485 CR |
9435 | special variable as delimiters. Shell quoting is honored within the |
9436 | string, in order to provide a mechanism for the words to contain shell | |
9437 | metacharacters or characters in the value of 'IFS'. Each word is then | |
9438 | expanded using brace expansion, tilde expansion, parameter and variable | |
9439 | expansion, command substitution, and arithmetic expansion, as described | |
9440 | above (*note Shell Expansions::). The results are split using the rules | |
9441 | described above (*note Word Splitting::). The results of the expansion | |
9442 | are prefix-matched against the word being completed, and the matching | |
9443 | words become the possible completions. | |
a0c0a00f CR |
9444 | |
9445 | After these matches have been generated, any shell function or | |
9446 | command specified with the '-F' and '-C' options is invoked. When the | |
9447 | command or function is invoked, the 'COMP_LINE', 'COMP_POINT', | |
9448 | 'COMP_KEY', and 'COMP_TYPE' variables are assigned values as described | |
9449 | above (*note Bash Variables::). If a shell function is being invoked, | |
9450 | the 'COMP_WORDS' and 'COMP_CWORD' variables are also set. When the | |
9451 | function or command is invoked, the first argument ($1) is the name of | |
9452 | the command whose arguments are being completed, the second argument | |
9453 | ($2) is the word being completed, and the third argument ($3) is the | |
9454 | word preceding the word being completed on the current command line. No | |
9455 | filtering of the generated completions against the word being completed | |
9456 | is performed; the function or command has complete freedom in generating | |
9457 | the matches. | |
9458 | ||
9459 | Any function specified with '-F' is invoked first. The function may | |
9460 | use any of the shell facilities, including the 'compgen' and 'compopt' | |
9461 | builtins described below (*note Programmable Completion Builtins::), to | |
9462 | generate the matches. It must put the possible completions in the | |
9463 | 'COMPREPLY' array variable, one per array element. | |
9464 | ||
9465 | Next, any command specified with the '-C' option is invoked in an | |
9466 | environment equivalent to command substitution. It should print a list | |
9467 | of completions, one per line, to the standard output. Backslash may be | |
9468 | used to escape a newline, if necessary. | |
9469 | ||
9470 | After all of the possible completions are generated, any filter | |
9471 | specified with the '-X' option is applied to the list. The filter is a | |
9472 | pattern as used for pathname expansion; a '&' in the pattern is replaced | |
9473 | with the text of the word being completed. A literal '&' may be escaped | |
9474 | with a backslash; the backslash is removed before attempting a match. | |
9475 | Any completion that matches the pattern will be removed from the list. | |
9476 | A leading '!' negates the pattern; in this case any completion not | |
9477 | matching the pattern will be removed. If the 'nocasematch' shell option | |
9478 | (see the description of 'shopt' in *note The Shopt Builtin::) is | |
9479 | enabled, the match is performed without regard to the case of alphabetic | |
9480 | characters. | |
9481 | ||
9482 | Finally, any prefix and suffix specified with the '-P' and '-S' | |
9483 | options are added to each member of the completion list, and the result | |
9484 | is returned to the Readline completion code as the list of possible | |
9485 | completions. | |
9486 | ||
9487 | If the previously-applied actions do not generate any matches, and | |
9488 | the '-o dirnames' option was supplied to 'complete' when the compspec | |
9489 | was defined, directory name completion is attempted. | |
9490 | ||
9491 | If the '-o plusdirs' option was supplied to 'complete' when the | |
9492 | compspec was defined, directory name completion is attempted and any | |
9493 | matches are added to the results of the other actions. | |
9494 | ||
9495 | By default, if a compspec is found, whatever it generates is returned | |
9496 | to the completion code as the full set of possible completions. The | |
9497 | default Bash completions are not attempted, and the Readline default of | |
9498 | filename completion is disabled. If the '-o bashdefault' option was | |
9499 | supplied to 'complete' when the compspec was defined, the default Bash | |
9500 | completions are attempted if the compspec generates no matches. If the | |
9501 | '-o default' option was supplied to 'complete' when the compspec was | |
9502 | defined, Readline's default completion will be performed if the compspec | |
9503 | (and, if attempted, the default Bash completions) generate no matches. | |
9504 | ||
9505 | When a compspec indicates that directory name completion is desired, | |
9506 | the programmable completion functions force Readline to append a slash | |
9507 | to completed names which are symbolic links to directories, subject to | |
9508 | the value of the MARK-DIRECTORIES Readline variable, regardless of the | |
9509 | setting of the MARK-SYMLINKED-DIRECTORIES Readline variable. | |
9510 | ||
9511 | There is some support for dynamically modifying completions. This is | |
9512 | most useful when used in combination with a default completion specified | |
9513 | with '-D'. It's possible for shell functions executed as completion | |
9514 | handlers to indicate that completion should be retried by returning an | |
9515 | exit status of 124. If a shell function returns 124, and changes the | |
9516 | compspec associated with the command on which completion is being | |
9517 | attempted (supplied as the first argument when the function is | |
9518 | executed), programmable completion restarts from the beginning, with an | |
9519 | attempt to find a new compspec for that command. This allows a set of | |
9520 | completions to be built dynamically as completion is attempted, rather | |
9521 | than being loaded all at once. | |
9522 | ||
9523 | For instance, assuming that there is a library of compspecs, each | |
9524 | kept in a file corresponding to the name of the command, the following | |
9525 | default completion function would load completions dynamically: | |
9526 | ||
9527 | _completion_loader() | |
9528 | { | |
9529 | . "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124 | |
9530 | } | |
9531 | complete -D -F _completion_loader -o bashdefault -o default | |
9532 | ||
9533 | \1f | |
9534 | File: bash.info, Node: Programmable Completion Builtins, Next: A Programmable Completion Example, Prev: Programmable Completion, Up: Command Line Editing | |
9535 | ||
9536 | 8.7 Programmable Completion Builtins | |
9537 | ==================================== | |
9538 | ||
9539 | Three builtin commands are available to manipulate the programmable | |
9540 | completion facilities: one to specify how the arguments to a particular | |
9541 | command are to be completed, and two to modify the completion as it is | |
9542 | happening. | |
9543 | ||
9544 | 'compgen' | |
9545 | compgen [OPTION] [WORD] | |
9546 | ||
9547 | Generate possible completion matches for WORD according to the | |
9548 | OPTIONs, which may be any option accepted by the 'complete' builtin | |
9549 | with the exception of '-p' and '-r', and write the matches to the | |
9550 | standard output. When using the '-F' or '-C' options, the various | |
9551 | shell variables set by the programmable completion facilities, | |
9552 | while available, will not have useful values. | |
9553 | ||
9554 | The matches will be generated in the same way as if the | |
9555 | programmable completion code had generated them directly from a | |
9556 | completion specification with the same flags. If WORD is | |
9557 | specified, only those completions matching WORD will be displayed. | |
9558 | ||
9559 | The return value is true unless an invalid option is supplied, or | |
9560 | no matches were generated. | |
9561 | ||
9562 | 'complete' | |
d233b485 CR |
9563 | complete [-abcdefgjksuv] [-o COMP-OPTION] [-DEI] [-A ACTION] [-G GLOBPAT] |
9564 | [-W WORDLIST] [-F FUNCTION] [-C COMMAND] [-X FILTERPAT] | |
a0c0a00f | 9565 | [-P PREFIX] [-S SUFFIX] NAME [NAME ...] |
d233b485 | 9566 | complete -pr [-DEI] [NAME ...] |
a0c0a00f CR |
9567 | |
9568 | Specify how arguments to each NAME should be completed. If the | |
9569 | '-p' option is supplied, or if no options are supplied, existing | |
9570 | completion specifications are printed in a way that allows them to | |
9571 | be reused as input. The '-r' option removes a completion | |
9572 | specification for each NAME, or, if no NAMEs are supplied, all | |
d233b485 CR |
9573 | completion specifications. The '-D' option indicates that other |
9574 | supplied options and actions should apply to the "default" command | |
a0c0a00f CR |
9575 | completion; that is, completion attempted on a command for which no |
9576 | completion has previously been defined. The '-E' option indicates | |
d233b485 | 9577 | that other supplied options and actions should apply to "empty" |
a0c0a00f | 9578 | command completion; that is, completion attempted on a blank line. |
d233b485 | 9579 | The '-I' option indicates that other supplied options and actions |
8868edaf CR |
9580 | should apply to completion on the initial non-assignment word on |
9581 | the line, or after a command delimiter such as ';' or '|', which is | |
d233b485 CR |
9582 | usually command name completion. If multiple options are supplied, |
9583 | the '-D' option takes precedence over '-E', and both take | |
9584 | precedence over '-I'. If any of '-D', '-E', or '-I' are supplied, | |
9585 | any other NAME arguments are ignored; these completions only apply | |
9586 | to the case specified by the option. | |
a0c0a00f CR |
9587 | |
9588 | The process of applying these completion specifications when word | |
9589 | completion is attempted is described above (*note Programmable | |
d233b485 | 9590 | Completion::). |
a0c0a00f CR |
9591 | |
9592 | Other options, if specified, have the following meanings. The | |
9593 | arguments to the '-G', '-W', and '-X' options (and, if necessary, | |
9594 | the '-P' and '-S' options) should be quoted to protect them from | |
9595 | expansion before the 'complete' builtin is invoked. | |
9596 | ||
9597 | '-o COMP-OPTION' | |
9598 | The COMP-OPTION controls several aspects of the compspec's | |
9599 | behavior beyond the simple generation of completions. | |
9600 | COMP-OPTION may be one of: | |
9601 | ||
9602 | 'bashdefault' | |
9603 | Perform the rest of the default Bash completions if the | |
9604 | compspec generates no matches. | |
9605 | ||
9606 | 'default' | |
9607 | Use Readline's default filename completion if the | |
9608 | compspec generates no matches. | |
9609 | ||
9610 | 'dirnames' | |
9611 | Perform directory name completion if the compspec | |
9612 | generates no matches. | |
9613 | ||
9614 | 'filenames' | |
9615 | Tell Readline that the compspec generates filenames, so | |
9616 | it can perform any filename-specific processing (like | |
d233b485 | 9617 | adding a slash to directory names, quoting special |
a0c0a00f CR |
9618 | characters, or suppressing trailing spaces). This option |
9619 | is intended to be used with shell functions specified | |
9620 | with '-F'. | |
9621 | ||
9622 | 'noquote' | |
9623 | Tell Readline not to quote the completed words if they | |
9624 | are filenames (quoting filenames is the default). | |
9625 | ||
9626 | 'nosort' | |
9627 | Tell Readline not to sort the list of possible | |
9628 | completions alphabetically. | |
9629 | ||
9630 | 'nospace' | |
9631 | Tell Readline not to append a space (the default) to | |
9632 | words completed at the end of the line. | |
9633 | ||
9634 | 'plusdirs' | |
9635 | After any matches defined by the compspec are generated, | |
9636 | directory name completion is attempted and any matches | |
9637 | are added to the results of the other actions. | |
9638 | ||
9639 | '-A ACTION' | |
9640 | The ACTION may be one of the following to generate a list of | |
9641 | possible completions: | |
9642 | ||
9643 | 'alias' | |
9644 | Alias names. May also be specified as '-a'. | |
9645 | ||
9646 | 'arrayvar' | |
9647 | Array variable names. | |
9648 | ||
9649 | 'binding' | |
9650 | Readline key binding names (*note Bindable Readline | |
9651 | Commands::). | |
9652 | ||
9653 | 'builtin' | |
9654 | Names of shell builtin commands. May also be specified | |
9655 | as '-b'. | |
9656 | ||
9657 | 'command' | |
9658 | Command names. May also be specified as '-c'. | |
9659 | ||
9660 | 'directory' | |
9661 | Directory names. May also be specified as '-d'. | |
9662 | ||
9663 | 'disabled' | |
9664 | Names of disabled shell builtins. | |
9665 | ||
9666 | 'enabled' | |
9667 | Names of enabled shell builtins. | |
9668 | ||
9669 | 'export' | |
9670 | Names of exported shell variables. May also be specified | |
9671 | as '-e'. | |
9672 | ||
9673 | 'file' | |
9674 | File names. May also be specified as '-f'. | |
9675 | ||
9676 | 'function' | |
9677 | Names of shell functions. | |
9678 | ||
9679 | 'group' | |
9680 | Group names. May also be specified as '-g'. | |
9681 | ||
9682 | 'helptopic' | |
9683 | Help topics as accepted by the 'help' builtin (*note Bash | |
9684 | Builtins::). | |
9685 | ||
9686 | 'hostname' | |
9687 | Hostnames, as taken from the file specified by the | |
9688 | 'HOSTFILE' shell variable (*note Bash Variables::). | |
9689 | ||
9690 | 'job' | |
9691 | Job names, if job control is active. May also be | |
9692 | specified as '-j'. | |
9693 | ||
9694 | 'keyword' | |
9695 | Shell reserved words. May also be specified as '-k'. | |
9696 | ||
9697 | 'running' | |
9698 | Names of running jobs, if job control is active. | |
9699 | ||
9700 | 'service' | |
9701 | Service names. May also be specified as '-s'. | |
9702 | ||
9703 | 'setopt' | |
9704 | Valid arguments for the '-o' option to the 'set' builtin | |
9705 | (*note The Set Builtin::). | |
9706 | ||
9707 | 'shopt' | |
9708 | Shell option names as accepted by the 'shopt' builtin | |
9709 | (*note Bash Builtins::). | |
9710 | ||
9711 | 'signal' | |
9712 | Signal names. | |
9713 | ||
9714 | 'stopped' | |
9715 | Names of stopped jobs, if job control is active. | |
9716 | ||
9717 | 'user' | |
9718 | User names. May also be specified as '-u'. | |
9719 | ||
9720 | 'variable' | |
9721 | Names of all shell variables. May also be specified as | |
9722 | '-v'. | |
9723 | ||
9724 | '-C COMMAND' | |
9725 | COMMAND is executed in a subshell environment, and its output | |
74091dd4 CR |
9726 | is used as the possible completions. Arguments are passed as |
9727 | with the '-F' option. | |
a0c0a00f CR |
9728 | |
9729 | '-F FUNCTION' | |
9730 | The shell function FUNCTION is executed in the current shell | |
9731 | environment. When it is executed, $1 is the name of the | |
9732 | command whose arguments are being completed, $2 is the word | |
9733 | being completed, and $3 is the word preceding the word being | |
9734 | completed, as described above (*note Programmable | |
9735 | Completion::). When it finishes, the possible completions are | |
9736 | retrieved from the value of the 'COMPREPLY' array variable. | |
9737 | ||
9738 | '-G GLOBPAT' | |
9739 | The filename expansion pattern GLOBPAT is expanded to generate | |
9740 | the possible completions. | |
9741 | ||
9742 | '-P PREFIX' | |
9743 | PREFIX is added at the beginning of each possible completion | |
9744 | after all other options have been applied. | |
9745 | ||
9746 | '-S SUFFIX' | |
9747 | SUFFIX is appended to each possible completion after all other | |
9748 | options have been applied. | |
9749 | ||
9750 | '-W WORDLIST' | |
9751 | The WORDLIST is split using the characters in the 'IFS' | |
9752 | special variable as delimiters, and each resultant word is | |
9753 | expanded. The possible completions are the members of the | |
9754 | resultant list which match the word being completed. | |
9755 | ||
9756 | '-X FILTERPAT' | |
9757 | FILTERPAT is a pattern as used for filename expansion. It is | |
9758 | applied to the list of possible completions generated by the | |
9759 | preceding options and arguments, and each completion matching | |
9760 | FILTERPAT is removed from the list. A leading '!' in | |
9761 | FILTERPAT negates the pattern; in this case, any completion | |
9762 | not matching FILTERPAT is removed. | |
9763 | ||
9764 | The return value is true unless an invalid option is supplied, an | |
9765 | option other than '-p' or '-r' is supplied without a NAME argument, | |
9766 | an attempt is made to remove a completion specification for a NAME | |
9767 | for which no specification exists, or an error occurs adding a | |
9768 | completion specification. | |
9769 | ||
9770 | 'compopt' | |
d233b485 | 9771 | compopt [-o OPTION] [-DEI] [+o OPTION] [NAME] |
a0c0a00f CR |
9772 | Modify completion options for each NAME according to the OPTIONs, |
9773 | or for the currently-executing completion if no NAMEs are supplied. | |
9774 | If no OPTIONs are given, display the completion options for each | |
9775 | NAME or the current completion. The possible values of OPTION are | |
9776 | those valid for the 'complete' builtin described above. The '-D' | |
d233b485 | 9777 | option indicates that other supplied options should apply to the |
a0c0a00f CR |
9778 | "default" command completion; that is, completion attempted on a |
9779 | command for which no completion has previously been defined. The | |
d233b485 | 9780 | '-E' option indicates that other supplied options should apply to |
a0c0a00f | 9781 | "empty" command completion; that is, completion attempted on a |
d233b485 | 9782 | blank line. The '-I' option indicates that other supplied options |
8868edaf CR |
9783 | should apply to completion on the initial non-assignment word on |
9784 | the line, or after a command delimiter such as ';' or '|', which is | |
d233b485 | 9785 | usually command name completion. |
a0c0a00f | 9786 | |
d233b485 CR |
9787 | If multiple options are supplied, the '-D' option takes precedence |
9788 | over '-E', and both take precedence over '-I' | |
a0c0a00f CR |
9789 | |
9790 | The return value is true unless an invalid option is supplied, an | |
9791 | attempt is made to modify the options for a NAME for which no | |
9792 | completion specification exists, or an output error occurs. | |
9793 | ||
9794 | \1f | |
9795 | File: bash.info, Node: A Programmable Completion Example, Prev: Programmable Completion Builtins, Up: Command Line Editing | |
9796 | ||
9797 | 8.8 A Programmable Completion Example | |
9798 | ===================================== | |
9799 | ||
9800 | The most common way to obtain additional completion functionality beyond | |
9801 | the default actions 'complete' and 'compgen' provide is to use a shell | |
9802 | function and bind it to a particular command using 'complete -F'. | |
9803 | ||
9804 | The following function provides completions for the 'cd' builtin. It | |
9805 | is a reasonably good example of what shell functions must do when used | |
d233b485 CR |
9806 | for completion. This function uses the word passed as '$2' to determine |
9807 | the directory name to complete. You can also use the 'COMP_WORDS' array | |
9808 | variable; the current word is indexed by the 'COMP_CWORD' variable. | |
a0c0a00f CR |
9809 | |
9810 | The function relies on the 'complete' and 'compgen' builtins to do | |
9811 | much of the work, adding only the things that the Bash 'cd' does beyond | |
9812 | accepting basic directory names: tilde expansion (*note Tilde | |
9813 | Expansion::), searching directories in $CDPATH, which is described above | |
9814 | (*note Bourne Shell Builtins::), and basic support for the 'cdable_vars' | |
9815 | shell option (*note The Shopt Builtin::). '_comp_cd' modifies the value | |
9816 | of IFS so that it contains only a newline to accommodate file names | |
9817 | containing spaces and tabs - 'compgen' prints the possible completions | |
9818 | it generates one per line. | |
9819 | ||
9820 | Possible completions go into the COMPREPLY array variable, one | |
9821 | completion per array element. The programmable completion system | |
9822 | retrieves the completions from there when the function returns. | |
9823 | ||
9824 | # A completion function for the cd builtin | |
9825 | # based on the cd completion function from the bash_completion package | |
9826 | _comp_cd() | |
9827 | { | |
9828 | local IFS=$' \t\n' # normalize IFS | |
9829 | local cur _skipdot _cdpath | |
9830 | local i j k | |
9831 | ||
d233b485 | 9832 | # Tilde expansion, which also expands tilde to full pathname |
a0c0a00f CR |
9833 | case "$2" in |
9834 | \~*) eval cur="$2" ;; | |
9835 | *) cur=$2 ;; | |
9836 | esac | |
9837 | ||
9838 | # no cdpath or absolute pathname -- straight directory completion | |
9839 | if [[ -z "${CDPATH:-}" ]] || [[ "$cur" == @(./*|../*|/*) ]]; then | |
9840 | # compgen prints paths one per line; could also use while loop | |
9841 | IFS=$'\n' | |
9842 | COMPREPLY=( $(compgen -d -- "$cur") ) | |
9843 | IFS=$' \t\n' | |
9844 | # CDPATH+directories in the current directory if not in CDPATH | |
9845 | else | |
9846 | IFS=$'\n' | |
9847 | _skipdot=false | |
9848 | # preprocess CDPATH to convert null directory names to . | |
9849 | _cdpath=${CDPATH/#:/.:} | |
9850 | _cdpath=${_cdpath//::/:.:} | |
9851 | _cdpath=${_cdpath/%:/:.} | |
9852 | for i in ${_cdpath//:/$'\n'}; do | |
9853 | if [[ $i -ef . ]]; then _skipdot=true; fi | |
9854 | k="${#COMPREPLY[@]}" | |
9855 | for j in $( compgen -d -- "$i/$cur" ); do | |
9856 | COMPREPLY[k++]=${j#$i/} # cut off directory | |
9857 | done | |
9858 | done | |
9859 | $_skipdot || COMPREPLY+=( $(compgen -d -- "$cur") ) | |
9860 | IFS=$' \t\n' | |
9861 | fi | |
9862 | ||
9863 | # variable names if appropriate shell option set and no completions | |
9864 | if shopt -q cdable_vars && [[ ${#COMPREPLY[@]} -eq 0 ]]; then | |
9865 | COMPREPLY=( $(compgen -v -- "$cur") ) | |
9866 | fi | |
9867 | ||
9868 | return 0 | |
9869 | } | |
9870 | ||
9871 | We install the completion function using the '-F' option to | |
9872 | 'complete': | |
9873 | ||
9874 | # Tell readline to quote appropriate and append slashes to directories; | |
9875 | # use the bash default completion for other arguments | |
9876 | complete -o filenames -o nospace -o bashdefault -F _comp_cd cd | |
9877 | ||
9878 | Since we'd like Bash and Readline to take care of some of the other | |
9879 | details for us, we use several other options to tell Bash and Readline | |
9880 | what to do. The '-o filenames' option tells Readline that the possible | |
9881 | completions should be treated as filenames, and quoted appropriately. | |
9882 | That option will also cause Readline to append a slash to filenames it | |
9883 | can determine are directories (which is why we might want to extend | |
9884 | '_comp_cd' to append a slash if we're using directories found via | |
9885 | CDPATH: Readline can't tell those completions are directories). The '-o | |
9886 | nospace' option tells Readline to not append a space character to the | |
9887 | directory name, in case we want to append to it. The '-o bashdefault' | |
9888 | option brings in the rest of the "Bash default" completions - possible | |
74091dd4 | 9889 | completions that Bash adds to the default Readline set. These include |
a0c0a00f | 9890 | things like command name completion, variable completion for words |
8868edaf CR |
9891 | beginning with '$' or '${', completions containing pathname expansion |
9892 | patterns (*note Filename Expansion::), and so on. | |
a0c0a00f CR |
9893 | |
9894 | Once installed using 'complete', '_comp_cd' will be called every time | |
9895 | we attempt word completion for a 'cd' command. | |
9896 | ||
9897 | Many more examples - an extensive collection of completions for most | |
9898 | of the common GNU, Unix, and Linux commands - are available as part of | |
9899 | the bash_completion project. This is installed by default on many | |
9900 | GNU/Linux distributions. Originally written by Ian Macdonald, the | |
8868edaf | 9901 | project now lives at <https://github.com/scop/bash-completion/>. There |
a0c0a00f CR |
9902 | are ports for other systems such as Solaris and Mac OS X. |
9903 | ||
9904 | An older version of the bash_completion package is distributed with | |
9905 | bash in the 'examples/complete' subdirectory. | |
9906 | ||
9907 | \1f | |
9908 | File: bash.info, Node: Using History Interactively, Next: Installing Bash, Prev: Command Line Editing, Up: Top | |
9909 | ||
9910 | 9 Using History Interactively | |
9911 | ***************************** | |
9912 | ||
9913 | This chapter describes how to use the GNU History Library interactively, | |
9914 | from a user's standpoint. It should be considered a user's guide. For | |
9915 | information on using the GNU History Library in other programs, see the | |
9916 | GNU Readline Library Manual. | |
9917 | ||
9918 | * Menu: | |
9919 | ||
9920 | * Bash History Facilities:: How Bash lets you manipulate your command | |
9921 | history. | |
9922 | * Bash History Builtins:: The Bash builtin commands that manipulate | |
9923 | the command history. | |
9924 | * History Interaction:: What it feels like using History as a user. | |
9925 | ||
9926 | \1f | |
9927 | File: bash.info, Node: Bash History Facilities, Next: Bash History Builtins, Up: Using History Interactively | |
9928 | ||
9929 | 9.1 Bash History Facilities | |
9930 | =========================== | |
9931 | ||
9932 | When the '-o history' option to the 'set' builtin is enabled (*note The | |
9933 | Set Builtin::), the shell provides access to the "command history", the | |
9934 | list of commands previously typed. The value of the 'HISTSIZE' shell | |
9935 | variable is used as the number of commands to save in a history list. | |
9936 | The text of the last '$HISTSIZE' commands (default 500) is saved. The | |
9937 | shell stores each command in the history list prior to parameter and | |
9938 | variable expansion but after history expansion is performed, subject to | |
9939 | the values of the shell variables 'HISTIGNORE' and 'HISTCONTROL'. | |
9940 | ||
9941 | When the shell starts up, the history is initialized from the file | |
9942 | named by the 'HISTFILE' variable (default '~/.bash_history'). The file | |
9943 | named by the value of 'HISTFILE' is truncated, if necessary, to contain | |
9944 | no more than the number of lines specified by the value of the | |
9945 | 'HISTFILESIZE' variable. When a shell with history enabled exits, the | |
9946 | last '$HISTSIZE' lines are copied from the history list to the file | |
9947 | named by '$HISTFILE'. If the 'histappend' shell option is set (*note | |
9948 | Bash Builtins::), the lines are appended to the history file, otherwise | |
9949 | the history file is overwritten. If 'HISTFILE' is unset, or if the | |
9950 | history file is unwritable, the history is not saved. After saving the | |
9951 | history, the history file is truncated to contain no more than | |
9952 | '$HISTFILESIZE' lines. If 'HISTFILESIZE' is unset, or set to null, a | |
9953 | non-numeric value, or a numeric value less than zero, the history file | |
9954 | is not truncated. | |
9955 | ||
9956 | If the 'HISTTIMEFORMAT' is set, the time stamp information associated | |
9957 | with each history entry is written to the history file, marked with the | |
9958 | history comment character. When the history file is read, lines | |
9959 | beginning with the history comment character followed immediately by a | |
9960 | digit are interpreted as timestamps for the following history entry. | |
9961 | ||
9962 | The builtin command 'fc' may be used to list or edit and re-execute a | |
9963 | portion of the history list. The 'history' builtin may be used to | |
9964 | display or modify the history list and manipulate the history file. | |
9965 | When using command-line editing, search commands are available in each | |
9966 | editing mode that provide access to the history list (*note Commands For | |
9967 | History::). | |
9968 | ||
9969 | The shell allows control over which commands are saved on the history | |
9970 | list. The 'HISTCONTROL' and 'HISTIGNORE' variables may be set to cause | |
9971 | the shell to save only a subset of the commands entered. The 'cmdhist' | |
9972 | shell option, if enabled, causes the shell to attempt to save each line | |
9973 | of a multi-line command in the same history entry, adding semicolons | |
9974 | where necessary to preserve syntactic correctness. The 'lithist' shell | |
9975 | option causes the shell to save the command with embedded newlines | |
9976 | instead of semicolons. The 'shopt' builtin is used to set these | |
d233b485 | 9977 | options. *Note The Shopt Builtin::, for a description of 'shopt'. |
a0c0a00f CR |
9978 | |
9979 | \1f | |
9980 | File: bash.info, Node: Bash History Builtins, Next: History Interaction, Prev: Bash History Facilities, Up: Using History Interactively | |
9981 | ||
9982 | 9.2 Bash History Builtins | |
9983 | ========================= | |
9984 | ||
9985 | Bash provides two builtin commands which manipulate the history list and | |
9986 | history file. | |
9987 | ||
9988 | 'fc' | |
9989 | fc [-e ENAME] [-lnr] [FIRST] [LAST] | |
9990 | fc -s [PAT=REP] [COMMAND] | |
9991 | ||
9992 | The first form selects a range of commands from FIRST to LAST from | |
9993 | the history list and displays or edits and re-executes them. Both | |
9994 | FIRST and LAST may be specified as a string (to locate the most | |
9995 | recent command beginning with that string) or as a number (an index | |
9996 | into the history list, where a negative number is used as an offset | |
8868edaf CR |
9997 | from the current command number). |
9998 | ||
9999 | When listing, a FIRST or LAST of 0 is equivalent to -1 and -0 is | |
10000 | equivalent to the current command (usually the 'fc' command); | |
10001 | otherwise 0 is equivalent to -1 and -0 is invalid. | |
10002 | ||
10003 | If LAST is not specified, it is set to FIRST. If FIRST is not | |
10004 | specified, it is set to the previous command for editing and -16 | |
10005 | for listing. If the '-l' flag is given, the commands are listed on | |
10006 | standard output. The '-n' flag suppresses the command numbers when | |
10007 | listing. The '-r' flag reverses the order of the listing. | |
10008 | Otherwise, the editor given by ENAME is invoked on a file | |
10009 | containing those commands. If ENAME is not given, the value of the | |
10010 | following variable expansion is used: '${FCEDIT:-${EDITOR:-vi}}'. | |
10011 | This says to use the value of the 'FCEDIT' variable if set, or the | |
10012 | value of the 'EDITOR' variable if that is set, or 'vi' if neither | |
10013 | is set. When editing is complete, the edited commands are echoed | |
10014 | and executed. | |
a0c0a00f CR |
10015 | |
10016 | In the second form, COMMAND is re-executed after each instance of | |
10017 | PAT in the selected command is replaced by REP. COMMAND is | |
8868edaf | 10018 | interpreted the same as FIRST above. |
a0c0a00f CR |
10019 | |
10020 | A useful alias to use with the 'fc' command is 'r='fc -s'', so that | |
10021 | typing 'r cc' runs the last command beginning with 'cc' and typing | |
10022 | 'r' re-executes the last command (*note Aliases::). | |
10023 | ||
10024 | 'history' | |
10025 | history [N] | |
10026 | history -c | |
10027 | history -d OFFSET | |
d233b485 | 10028 | history -d START-END |
a0c0a00f CR |
10029 | history [-anrw] [FILENAME] |
10030 | history -ps ARG | |
10031 | ||
10032 | With no options, display the history list with line numbers. Lines | |
10033 | prefixed with a '*' have been modified. An argument of N lists | |
10034 | only the last N lines. If the shell variable 'HISTTIMEFORMAT' is | |
10035 | set and not null, it is used as a format string for STRFTIME to | |
10036 | display the time stamp associated with each displayed history | |
10037 | entry. No intervening blank is printed between the formatted time | |
10038 | stamp and the history line. | |
10039 | ||
10040 | Options, if supplied, have the following meanings: | |
10041 | ||
10042 | '-c' | |
10043 | Clear the history list. This may be combined with the other | |
10044 | options to replace the history list completely. | |
10045 | ||
10046 | '-d OFFSET' | |
d233b485 CR |
10047 | Delete the history entry at position OFFSET. If OFFSET is |
10048 | positive, it should be specified as it appears when the | |
10049 | history is displayed. If OFFSET is negative, it is | |
10050 | interpreted as relative to one greater than the last history | |
10051 | position, so negative indices count back from the end of the | |
10052 | history, and an index of '-1' refers to the current 'history | |
10053 | -d' command. | |
10054 | ||
10055 | '-d START-END' | |
74091dd4 CR |
10056 | Delete the range of history entries between positions START |
10057 | and END, inclusive. Positive and negative values for START | |
10058 | and END are interpreted as described above. | |
a0c0a00f CR |
10059 | |
10060 | '-a' | |
10061 | Append the new history lines to the history file. These are | |
10062 | history lines entered since the beginning of the current Bash | |
10063 | session, but not already appended to the history file. | |
10064 | ||
10065 | '-n' | |
10066 | Append the history lines not already read from the history | |
10067 | file to the current history list. These are lines appended to | |
10068 | the history file since the beginning of the current Bash | |
10069 | session. | |
10070 | ||
10071 | '-r' | |
10072 | Read the history file and append its contents to the history | |
10073 | list. | |
10074 | ||
10075 | '-w' | |
10076 | Write out the current history list to the history file. | |
10077 | ||
10078 | '-p' | |
10079 | Perform history substitution on the ARGs and display the | |
10080 | result on the standard output, without storing the results in | |
10081 | the history list. | |
10082 | ||
10083 | '-s' | |
10084 | The ARGs are added to the end of the history list as a single | |
10085 | entry. | |
10086 | ||
74091dd4 CR |
10087 | If a FILENAME argument is supplied when any of the '-w', '-r', |
10088 | '-a', or '-n' options is used, Bash uses FILENAME as the history | |
10089 | file. If not, then the value of the 'HISTFILE' variable is used. | |
10090 | ||
10091 | The return value is 0 unless an invalid option is encountered, an | |
10092 | error occurs while reading or writing the history file, an invalid | |
10093 | OFFSET or range is supplied as an argument to '-d', or the history | |
10094 | expansion supplied as an argument to '-p' fails. | |
a0c0a00f CR |
10095 | |
10096 | \1f | |
10097 | File: bash.info, Node: History Interaction, Prev: Bash History Builtins, Up: Using History Interactively | |
10098 | ||
10099 | 9.3 History Expansion | |
10100 | ===================== | |
10101 | ||
10102 | The History library provides a history expansion feature that is similar | |
10103 | to the history expansion provided by 'csh'. This section describes the | |
10104 | syntax used to manipulate the history information. | |
10105 | ||
10106 | History expansions introduce words from the history list into the | |
10107 | input stream, making it easy to repeat commands, insert the arguments to | |
10108 | a previous command into the current input line, or fix errors in | |
10109 | previous commands quickly. | |
10110 | ||
10111 | History expansion is performed immediately after a complete line is | |
d233b485 CR |
10112 | read, before the shell breaks it into words, and is performed on each |
10113 | line individually. Bash attempts to inform the history expansion | |
10114 | functions about quoting still in effect from previous lines. | |
a0c0a00f CR |
10115 | |
10116 | History expansion takes place in two parts. The first is to | |
10117 | determine which line from the history list should be used during | |
10118 | substitution. The second is to select portions of that line for | |
10119 | inclusion into the current one. The line selected from the history is | |
10120 | called the "event", and the portions of that line that are acted upon | |
10121 | are called "words". Various "modifiers" are available to manipulate the | |
10122 | selected words. The line is broken into words in the same fashion that | |
10123 | Bash does, so that several words surrounded by quotes are considered one | |
10124 | word. History expansions are introduced by the appearance of the | |
d233b485 CR |
10125 | history expansion character, which is '!' by default. |
10126 | ||
10127 | History expansion implements shell-like quoting conventions: a | |
10128 | backslash can be used to remove the special handling for the next | |
10129 | character; single quotes enclose verbatim sequences of characters, and | |
10130 | can be used to inhibit history expansion; and characters enclosed within | |
10131 | double quotes may be subject to history expansion, since backslash can | |
10132 | escape the history expansion character, but single quotes may not, since | |
10133 | they are not treated specially within double quotes. | |
10134 | ||
10135 | When using the shell, only '\' and ''' may be used to escape the | |
10136 | history expansion character, but the history expansion character is also | |
10137 | treated as quoted if it immediately precedes the closing double quote in | |
10138 | a double-quoted string. | |
10139 | ||
10140 | Several shell options settable with the 'shopt' builtin (*note The | |
10141 | Shopt Builtin::) may be used to tailor the behavior of history | |
10142 | expansion. If the 'histverify' shell option is enabled, and Readline is | |
10143 | being used, history substitutions are not immediately passed to the | |
10144 | shell parser. Instead, the expanded line is reloaded into the Readline | |
10145 | editing buffer for further modification. If Readline is being used, and | |
10146 | the 'histreedit' shell option is enabled, a failed history expansion | |
10147 | will be reloaded into the Readline editing buffer for correction. The | |
10148 | '-p' option to the 'history' builtin command may be used to see what a | |
a0c0a00f CR |
10149 | history expansion will do before using it. The '-s' option to the |
10150 | 'history' builtin may be used to add commands to the end of the history | |
10151 | list without actually executing them, so that they are available for | |
10152 | subsequent recall. This is most useful in conjunction with Readline. | |
10153 | ||
10154 | The shell allows control of the various characters used by the | |
10155 | history expansion mechanism with the 'histchars' variable, as explained | |
10156 | above (*note Bash Variables::). The shell uses the history comment | |
10157 | character to mark history timestamps when writing the history file. | |
10158 | ||
10159 | * Menu: | |
10160 | ||
10161 | * Event Designators:: How to specify which history line to use. | |
10162 | * Word Designators:: Specifying which words are of interest. | |
10163 | * Modifiers:: Modifying the results of substitution. | |
10164 | ||
10165 | \1f | |
10166 | File: bash.info, Node: Event Designators, Next: Word Designators, Up: History Interaction | |
10167 | ||
10168 | 9.3.1 Event Designators | |
10169 | ----------------------- | |
10170 | ||
10171 | An event designator is a reference to a command line entry in the | |
10172 | history list. Unless the reference is absolute, events are relative to | |
10173 | the current position in the history list. | |
10174 | ||
10175 | '!' | |
10176 | Start a history substitution, except when followed by a space, tab, | |
10177 | the end of the line, '=' or '(' (when the 'extglob' shell option is | |
10178 | enabled using the 'shopt' builtin). | |
10179 | ||
10180 | '!N' | |
10181 | Refer to command line N. | |
10182 | ||
10183 | '!-N' | |
10184 | Refer to the command N lines back. | |
10185 | ||
10186 | '!!' | |
10187 | Refer to the previous command. This is a synonym for '!-1'. | |
10188 | ||
10189 | '!STRING' | |
10190 | Refer to the most recent command preceding the current position in | |
10191 | the history list starting with STRING. | |
10192 | ||
10193 | '!?STRING[?]' | |
10194 | Refer to the most recent command preceding the current position in | |
10195 | the history list containing STRING. The trailing '?' may be | |
8868edaf CR |
10196 | omitted if the STRING is followed immediately by a newline. If |
10197 | STRING is missing, the string from the most recent search is used; | |
10198 | it is an error if there is no previous search string. | |
a0c0a00f CR |
10199 | |
10200 | '^STRING1^STRING2^' | |
10201 | Quick Substitution. Repeat the last command, replacing STRING1 | |
8868edaf | 10202 | with STRING2. Equivalent to '!!:s^STRING1^STRING2^'. |
a0c0a00f CR |
10203 | |
10204 | '!#' | |
10205 | The entire command line typed so far. | |
10206 | ||
10207 | \1f | |
10208 | File: bash.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction | |
10209 | ||
10210 | 9.3.2 Word Designators | |
10211 | ---------------------- | |
10212 | ||
10213 | Word designators are used to select desired words from the event. A ':' | |
10214 | separates the event specification from the word designator. It may be | |
10215 | omitted if the word designator begins with a '^', '$', '*', '-', or '%'. | |
10216 | Words are numbered from the beginning of the line, with the first word | |
10217 | being denoted by 0 (zero). Words are inserted into the current line | |
10218 | separated by single spaces. | |
10219 | ||
10220 | For example, | |
10221 | ||
10222 | '!!' | |
10223 | designates the preceding command. When you type this, the | |
10224 | preceding command is repeated in toto. | |
10225 | ||
10226 | '!!:$' | |
10227 | designates the last argument of the preceding command. This may be | |
10228 | shortened to '!$'. | |
10229 | ||
10230 | '!fi:2' | |
10231 | designates the second argument of the most recent command starting | |
10232 | with the letters 'fi'. | |
10233 | ||
10234 | Here are the word designators: | |
10235 | ||
10236 | '0 (zero)' | |
10237 | The '0'th word. For many applications, this is the command word. | |
10238 | ||
10239 | 'N' | |
10240 | The Nth word. | |
10241 | ||
10242 | '^' | |
10243 | The first argument; that is, word 1. | |
10244 | ||
10245 | '$' | |
10246 | The last argument. | |
10247 | ||
10248 | '%' | |
8868edaf CR |
10249 | The first word matched by the most recent '?STRING?' search, if the |
10250 | search string begins with a character that is part of a word. | |
a0c0a00f CR |
10251 | |
10252 | 'X-Y' | |
10253 | A range of words; '-Y' abbreviates '0-Y'. | |
10254 | ||
10255 | '*' | |
10256 | All of the words, except the '0'th. This is a synonym for '1-$'. | |
10257 | It is not an error to use '*' if there is just one word in the | |
10258 | event; the empty string is returned in that case. | |
10259 | ||
10260 | 'X*' | |
10261 | Abbreviates 'X-$' | |
10262 | ||
10263 | 'X-' | |
8868edaf CR |
10264 | Abbreviates 'X-$' like 'X*', but omits the last word. If 'x' is |
10265 | missing, it defaults to 0. | |
a0c0a00f CR |
10266 | |
10267 | If a word designator is supplied without an event specification, the | |
10268 | previous command is used as the event. | |
10269 | ||
10270 | \1f | |
10271 | File: bash.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction | |
10272 | ||
10273 | 9.3.3 Modifiers | |
10274 | --------------- | |
10275 | ||
10276 | After the optional word designator, you can add a sequence of one or | |
8868edaf CR |
10277 | more of the following modifiers, each preceded by a ':'. These modify, |
10278 | or edit, the word or words selected from the history event. | |
a0c0a00f CR |
10279 | |
10280 | 'h' | |
10281 | Remove a trailing pathname component, leaving only the head. | |
10282 | ||
10283 | 't' | |
10284 | Remove all leading pathname components, leaving the tail. | |
10285 | ||
10286 | 'r' | |
10287 | Remove a trailing suffix of the form '.SUFFIX', leaving the | |
10288 | basename. | |
10289 | ||
10290 | 'e' | |
10291 | Remove all but the trailing suffix. | |
10292 | ||
10293 | 'p' | |
10294 | Print the new command but do not execute it. | |
10295 | ||
10296 | 'q' | |
10297 | Quote the substituted words, escaping further substitutions. | |
10298 | ||
10299 | 'x' | |
10300 | Quote the substituted words as with 'q', but break into words at | |
8868edaf CR |
10301 | spaces, tabs, and newlines. The 'q' and 'x' modifiers are mutually |
10302 | exclusive; the last one supplied is used. | |
a0c0a00f CR |
10303 | |
10304 | 's/OLD/NEW/' | |
10305 | Substitute NEW for the first occurrence of OLD in the event line. | |
8868edaf CR |
10306 | Any character may be used as the delimiter in place of '/'. The |
10307 | delimiter may be quoted in OLD and NEW with a single backslash. If | |
10308 | '&' appears in NEW, it is replaced by OLD. A single backslash will | |
10309 | quote the '&'. If OLD is null, it is set to the last OLD | |
10310 | substituted, or, if no previous history substitutions took place, | |
74091dd4 | 10311 | the last STRING in a !?STRING'[?]' search. If NEW is null, each |
8868edaf CR |
10312 | matching OLD is deleted. The final delimiter is optional if it is |
10313 | the last character on the input line. | |
a0c0a00f CR |
10314 | |
10315 | '&' | |
10316 | Repeat the previous substitution. | |
10317 | ||
10318 | 'g' | |
10319 | 'a' | |
10320 | Cause changes to be applied over the entire event line. Used in | |
10321 | conjunction with 's', as in 'gs/OLD/NEW/', or with '&'. | |
10322 | ||
10323 | 'G' | |
8868edaf CR |
10324 | Apply the following 's' or '&' modifier once to each word in the |
10325 | event. | |
a0c0a00f CR |
10326 | |
10327 | \1f | |
10328 | File: bash.info, Node: Installing Bash, Next: Reporting Bugs, Prev: Using History Interactively, Up: Top | |
10329 | ||
10330 | 10 Installing Bash | |
10331 | ****************** | |
10332 | ||
10333 | This chapter provides basic instructions for installing Bash on the | |
10334 | various supported platforms. The distribution supports the GNU | |
10335 | operating systems, nearly every version of Unix, and several non-Unix | |
10336 | systems such as BeOS and Interix. Other independent ports exist for | |
10337 | MS-DOS, OS/2, and Windows platforms. | |
10338 | ||
10339 | * Menu: | |
10340 | ||
10341 | * Basic Installation:: Installation instructions. | |
10342 | * Compilers and Options:: How to set special options for various | |
10343 | systems. | |
10344 | * Compiling For Multiple Architectures:: How to compile Bash for more | |
10345 | than one kind of system from | |
10346 | the same source tree. | |
10347 | * Installation Names:: How to set the various paths used by the installation. | |
10348 | * Specifying the System Type:: How to configure Bash for a particular system. | |
10349 | * Sharing Defaults:: How to share default configuration values among GNU | |
10350 | programs. | |
10351 | * Operation Controls:: Options recognized by the configuration program. | |
10352 | * Optional Features:: How to enable and disable optional features when | |
10353 | building Bash. | |
10354 | ||
10355 | \1f | |
10356 | File: bash.info, Node: Basic Installation, Next: Compilers and Options, Up: Installing Bash | |
10357 | ||
10358 | 10.1 Basic Installation | |
10359 | ======================= | |
10360 | ||
10361 | These are installation instructions for Bash. | |
10362 | ||
10363 | The simplest way to compile Bash is: | |
10364 | ||
10365 | 1. 'cd' to the directory containing the source code and type | |
10366 | './configure' to configure Bash for your system. If you're using | |
10367 | 'csh' on an old version of System V, you might need to type 'sh | |
10368 | ./configure' instead to prevent 'csh' from trying to execute | |
10369 | 'configure' itself. | |
10370 | ||
10371 | Running 'configure' takes some time. While running, it prints | |
10372 | messages telling which features it is checking for. | |
10373 | ||
10374 | 2. Type 'make' to compile Bash and build the 'bashbug' bug reporting | |
10375 | script. | |
10376 | ||
10377 | 3. Optionally, type 'make tests' to run the Bash test suite. | |
10378 | ||
10379 | 4. Type 'make install' to install 'bash' and 'bashbug'. This will | |
74091dd4 CR |
10380 | also install the manual pages and Info file, message translation |
10381 | files, some supplemental documentation, a number of example | |
10382 | loadable builtin commands, and a set of header files for developing | |
10383 | loadable builtins. You may need additional privileges to install | |
10384 | 'bash' to your desired destination, so 'sudo make install' might be | |
10385 | required. More information about controlling the locations where | |
10386 | 'bash' and other files are installed is below (*note Installation | |
10387 | Names::). | |
a0c0a00f CR |
10388 | |
10389 | The 'configure' shell script attempts to guess correct values for | |
10390 | various system-dependent variables used during compilation. It uses | |
10391 | those values to create a 'Makefile' in each directory of the package | |
74091dd4 CR |
10392 | (the top directory, the 'builtins', 'doc', 'po', and 'support' |
10393 | directories, each directory under 'lib', and several others). It also | |
10394 | creates a 'config.h' file containing system-dependent definitions. | |
10395 | Finally, it creates a shell script named 'config.status' that you can | |
10396 | run in the future to recreate the current configuration, a file | |
10397 | 'config.cache' that saves the results of its tests to speed up | |
10398 | reconfiguring, and a file 'config.log' containing compiler output | |
10399 | (useful mainly for debugging 'configure'). If at some point | |
10400 | 'config.cache' contains results you don't want to keep, you may remove | |
10401 | or edit it. | |
a0c0a00f CR |
10402 | |
10403 | To find out more about the options and arguments that the 'configure' | |
10404 | script understands, type | |
10405 | ||
d233b485 | 10406 | bash-4.2$ ./configure --help |
a0c0a00f CR |
10407 | |
10408 | at the Bash prompt in your Bash source directory. | |
10409 | ||
d233b485 CR |
10410 | If you want to build Bash in a directory separate from the source |
10411 | directory - to build for multiple architectures, for example - just use | |
10412 | the full path to the configure script. The following commands will | |
10413 | build bash in a directory under '/usr/local/build' from the source code | |
10414 | in '/usr/local/src/bash-4.4': | |
10415 | ||
10416 | mkdir /usr/local/build/bash-4.4 | |
10417 | cd /usr/local/build/bash-4.4 | |
10418 | bash /usr/local/src/bash-4.4/configure | |
10419 | make | |
10420 | ||
10421 | See *note Compiling For Multiple Architectures:: for more information | |
10422 | about building in a directory separate from the source. | |
10423 | ||
a0c0a00f CR |
10424 | If you need to do unusual things to compile Bash, please try to |
10425 | figure out how 'configure' could check whether or not to do them, and | |
10426 | mail diffs or instructions to <bash-maintainers@gnu.org> so they can be | |
10427 | considered for the next release. | |
10428 | ||
10429 | The file 'configure.ac' is used to create 'configure' by a program | |
10430 | called Autoconf. You only need 'configure.ac' if you want to change it | |
10431 | or regenerate 'configure' using a newer version of Autoconf. If you do | |
74091dd4 | 10432 | this, make sure you are using Autoconf version 2.69 or newer. |
a0c0a00f CR |
10433 | |
10434 | You can remove the program binaries and object files from the source | |
10435 | code directory by typing 'make clean'. To also remove the files that | |
10436 | 'configure' created (so you can compile Bash for a different kind of | |
10437 | computer), type 'make distclean'. | |
10438 | ||
10439 | \1f | |
10440 | File: bash.info, Node: Compilers and Options, Next: Compiling For Multiple Architectures, Prev: Basic Installation, Up: Installing Bash | |
10441 | ||
10442 | 10.2 Compilers and Options | |
10443 | ========================== | |
10444 | ||
10445 | Some systems require unusual options for compilation or linking that the | |
10446 | 'configure' script does not know about. You can give 'configure' | |
10447 | initial values for variables by setting them in the environment. Using | |
10448 | a Bourne-compatible shell, you can do that on the command line like | |
10449 | this: | |
10450 | ||
10451 | CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure | |
10452 | ||
10453 | On systems that have the 'env' program, you can do it like this: | |
10454 | ||
10455 | env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure | |
10456 | ||
10457 | The configuration process uses GCC to build Bash if it is available. | |
10458 | ||
10459 | \1f | |
10460 | File: bash.info, Node: Compiling For Multiple Architectures, Next: Installation Names, Prev: Compilers and Options, Up: Installing Bash | |
10461 | ||
10462 | 10.3 Compiling For Multiple Architectures | |
10463 | ========================================= | |
10464 | ||
10465 | You can compile Bash for more than one kind of computer at the same | |
10466 | time, by placing the object files for each architecture in their own | |
10467 | directory. To do this, you must use a version of 'make' that supports | |
10468 | the 'VPATH' variable, such as GNU 'make'. 'cd' to the directory where | |
10469 | you want the object files and executables to go and run the 'configure' | |
d233b485 CR |
10470 | script from the source directory (*note Basic Installation::). You may |
10471 | need to supply the '--srcdir=PATH' argument to tell 'configure' where | |
10472 | the source files are. 'configure' automatically checks for the source | |
10473 | code in the directory that 'configure' is in and in '..'. | |
a0c0a00f | 10474 | |
74091dd4 | 10475 | If you have to use a 'make' that does not support the 'VPATH' |
a0c0a00f CR |
10476 | variable, you can compile Bash for one architecture at a time in the |
10477 | source code directory. After you have installed Bash for one | |
10478 | architecture, use 'make distclean' before reconfiguring for another | |
10479 | architecture. | |
10480 | ||
10481 | Alternatively, if your system supports symbolic links, you can use | |
10482 | the 'support/mkclone' script to create a build tree which has symbolic | |
10483 | links back to each file in the source directory. Here's an example that | |
10484 | creates a build directory in the current directory from a source | |
10485 | directory '/usr/gnu/src/bash-2.0': | |
10486 | ||
10487 | bash /usr/gnu/src/bash-2.0/support/mkclone -s /usr/gnu/src/bash-2.0 . | |
10488 | ||
10489 | The 'mkclone' script requires Bash, so you must have already built Bash | |
10490 | for at least one architecture before you can create build directories | |
10491 | for other architectures. | |
10492 | ||
10493 | \1f | |
10494 | File: bash.info, Node: Installation Names, Next: Specifying the System Type, Prev: Compiling For Multiple Architectures, Up: Installing Bash | |
10495 | ||
10496 | 10.4 Installation Names | |
10497 | ======================= | |
10498 | ||
10499 | By default, 'make install' will install into '/usr/local/bin', | |
74091dd4 CR |
10500 | '/usr/local/man', etc.; that is, the "installation prefix" defaults to |
10501 | '/usr/local'. You can specify an installation prefix other than | |
10502 | '/usr/local' by giving 'configure' the option '--prefix=PATH', or by | |
10503 | specifying a value for the 'prefix' 'make' variable when running 'make | |
10504 | install' (e.g., 'make install prefix=PATH'). The 'prefix' variable | |
10505 | provides a default for 'exec_prefix' and other variables used when | |
10506 | installing bash. | |
a0c0a00f CR |
10507 | |
10508 | You can specify separate installation prefixes for | |
10509 | architecture-specific files and architecture-independent files. If you | |
10510 | give 'configure' the option '--exec-prefix=PATH', 'make install' will | |
10511 | use PATH as the prefix for installing programs and libraries. | |
10512 | Documentation and other data files will still use the regular prefix. | |
10513 | ||
74091dd4 CR |
10514 | If you would like to change the installation locations for a single |
10515 | run, you can specify these variables as arguments to 'make': 'make | |
10516 | install exec_prefix=/' will install 'bash' and 'bashbug' into '/bin' | |
10517 | instead of the default '/usr/local/bin'. | |
10518 | ||
10519 | If you want to see the files bash will install and where it will | |
10520 | install them without changing anything on your system, specify the | |
10521 | variable 'DESTDIR' as an argument to 'make'. Its value should be the | |
10522 | absolute directory path you'd like to use as the root of your sample | |
10523 | installation tree. For example, | |
10524 | ||
10525 | mkdir /fs1/bash-install | |
10526 | make install DESTDIR=/fs1/bash-install | |
10527 | ||
10528 | will install 'bash' into '/fs1/bash-install/usr/local/bin/bash', the | |
10529 | documentation into directories within | |
10530 | '/fs1/bash-install/usr/local/share', the example loadable builtins into | |
10531 | '/fs1/bash-install/usr/local/lib/bash', and so on. You can use the | |
10532 | usual 'exec_prefix' and 'prefix' variables to alter the directory paths | |
10533 | beneath the value of 'DESTDIR'. | |
10534 | ||
10535 | The GNU Makefile standards provide a more complete description of | |
10536 | these variables and their effects. | |
10537 | ||
a0c0a00f CR |
10538 | \1f |
10539 | File: bash.info, Node: Specifying the System Type, Next: Sharing Defaults, Prev: Installation Names, Up: Installing Bash | |
10540 | ||
10541 | 10.5 Specifying the System Type | |
10542 | =============================== | |
10543 | ||
10544 | There may be some features 'configure' can not figure out automatically, | |
74091dd4 | 10545 | but needs to determine by the type of host Bash will run on. Usually |
a0c0a00f CR |
10546 | 'configure' can figure that out, but if it prints a message saying it |
10547 | can not guess the host type, give it the '--host=TYPE' option. 'TYPE' | |
10548 | can either be a short name for the system type, such as 'sun4', or a | |
10549 | canonical name with three fields: 'CPU-COMPANY-SYSTEM' (e.g., | |
10550 | 'i386-unknown-freebsd4.2'). | |
10551 | ||
10552 | See the file 'support/config.sub' for the possible values of each | |
10553 | field. | |
10554 | ||
10555 | \1f | |
10556 | File: bash.info, Node: Sharing Defaults, Next: Operation Controls, Prev: Specifying the System Type, Up: Installing Bash | |
10557 | ||
10558 | 10.6 Sharing Defaults | |
10559 | ===================== | |
10560 | ||
10561 | If you want to set default values for 'configure' scripts to share, you | |
10562 | can create a site shell script called 'config.site' that gives default | |
10563 | values for variables like 'CC', 'cache_file', and 'prefix'. 'configure' | |
10564 | looks for 'PREFIX/share/config.site' if it exists, then | |
10565 | 'PREFIX/etc/config.site' if it exists. Or, you can set the | |
10566 | 'CONFIG_SITE' environment variable to the location of the site script. | |
10567 | A warning: the Bash 'configure' looks for a site script, but not all | |
10568 | 'configure' scripts do. | |
10569 | ||
10570 | \1f | |
10571 | File: bash.info, Node: Operation Controls, Next: Optional Features, Prev: Sharing Defaults, Up: Installing Bash | |
10572 | ||
10573 | 10.7 Operation Controls | |
10574 | ======================= | |
10575 | ||
10576 | 'configure' recognizes the following options to control how it operates. | |
10577 | ||
10578 | '--cache-file=FILE' | |
10579 | Use and save the results of the tests in FILE instead of | |
10580 | './config.cache'. Set FILE to '/dev/null' to disable caching, for | |
10581 | debugging 'configure'. | |
10582 | ||
10583 | '--help' | |
10584 | Print a summary of the options to 'configure', and exit. | |
10585 | ||
10586 | '--quiet' | |
10587 | '--silent' | |
10588 | '-q' | |
10589 | Do not print messages saying which checks are being made. | |
10590 | ||
10591 | '--srcdir=DIR' | |
10592 | Look for the Bash source code in directory DIR. Usually | |
10593 | 'configure' can determine that directory automatically. | |
10594 | ||
10595 | '--version' | |
10596 | Print the version of Autoconf used to generate the 'configure' | |
10597 | script, and exit. | |
10598 | ||
10599 | 'configure' also accepts some other, not widely used, boilerplate | |
10600 | options. 'configure --help' prints the complete list. | |
10601 | ||
10602 | \1f | |
10603 | File: bash.info, Node: Optional Features, Prev: Operation Controls, Up: Installing Bash | |
10604 | ||
10605 | 10.8 Optional Features | |
10606 | ====================== | |
10607 | ||
10608 | The Bash 'configure' has a number of '--enable-FEATURE' options, where | |
10609 | FEATURE indicates an optional part of Bash. There are also several | |
10610 | '--with-PACKAGE' options, where PACKAGE is something like 'bash-malloc' | |
10611 | or 'purify'. To turn off the default use of a package, use | |
10612 | '--without-PACKAGE'. To configure Bash without a feature that is | |
10613 | enabled by default, use '--disable-FEATURE'. | |
10614 | ||
10615 | Here is a complete list of the '--enable-' and '--with-' options that | |
10616 | the Bash 'configure' recognizes. | |
10617 | ||
10618 | '--with-afs' | |
10619 | Define if you are using the Andrew File System from Transarc. | |
10620 | ||
10621 | '--with-bash-malloc' | |
10622 | Use the Bash version of 'malloc' in the directory 'lib/malloc'. | |
10623 | This is not the same 'malloc' that appears in GNU libc, but an | |
10624 | older version originally derived from the 4.2 BSD 'malloc'. This | |
10625 | 'malloc' is very fast, but wastes some space on each allocation. | |
10626 | This option is enabled by default. The 'NOTES' file contains a | |
10627 | list of systems for which this should be turned off, and | |
10628 | 'configure' disables this option automatically for a number of | |
10629 | systems. | |
10630 | ||
10631 | '--with-curses' | |
10632 | Use the curses library instead of the termcap library. This should | |
10633 | be supplied if your system has an inadequate or incomplete termcap | |
10634 | database. | |
10635 | ||
10636 | '--with-gnu-malloc' | |
10637 | A synonym for '--with-bash-malloc'. | |
10638 | ||
10639 | '--with-installed-readline[=PREFIX]' | |
10640 | Define this to make Bash link with a locally-installed version of | |
10641 | Readline rather than the version in 'lib/readline'. This works | |
10642 | only with Readline 5.0 and later versions. If PREFIX is 'yes' or | |
10643 | not supplied, 'configure' uses the values of the make variables | |
10644 | 'includedir' and 'libdir', which are subdirectories of 'prefix' by | |
10645 | default, to find the installed version of Readline if it is not in | |
10646 | the standard system include and library directories. If PREFIX is | |
10647 | 'no', Bash links with the version in 'lib/readline'. If PREFIX is | |
10648 | set to any other value, 'configure' treats it as a directory | |
10649 | pathname and looks for the installed version of Readline in | |
10650 | subdirectories of that directory (include files in PREFIX/'include' | |
10651 | and the library in PREFIX/'lib'). | |
10652 | ||
74091dd4 CR |
10653 | '--with-libintl-prefix[=PREFIX]' |
10654 | Define this to make Bash link with a locally-installed version of | |
10655 | the libintl library instead of the version in 'lib/intl'. | |
10656 | ||
10657 | '--with-libiconv-prefix[=PREFIX]' | |
10658 | Define this to make Bash look for libiconv in PREFIX instead of the | |
10659 | standard system locations. There is no version included with Bash. | |
a0c0a00f CR |
10660 | |
10661 | '--enable-minimal-config' | |
10662 | This produces a shell with minimal features, close to the | |
10663 | historical Bourne shell. | |
10664 | ||
74091dd4 CR |
10665 | There are several '--enable-' options that alter how Bash is |
10666 | compiled, linked, and installed, rather than changing run-time features. | |
a0c0a00f CR |
10667 | |
10668 | '--enable-largefile' | |
10669 | Enable support for large files | |
d233b485 CR |
10670 | (http://www.unix.org/version2/whatsnew/lfs20mar.html) if the |
10671 | operating system requires special compiler options to build | |
a0c0a00f CR |
10672 | programs which can access large files. This is enabled by default, |
10673 | if the operating system provides large file support. | |
10674 | ||
10675 | '--enable-profiling' | |
10676 | This builds a Bash binary that produces profiling information to be | |
10677 | processed by 'gprof' each time it is executed. | |
10678 | ||
74091dd4 CR |
10679 | '--enable-separate-helpfiles' |
10680 | Use external files for the documentation displayed by the 'help' | |
10681 | builtin instead of storing the text internally. | |
10682 | ||
a0c0a00f CR |
10683 | '--enable-static-link' |
10684 | This causes Bash to be linked statically, if 'gcc' is being used. | |
10685 | This could be used to build a version to use as root's shell. | |
10686 | ||
10687 | The 'minimal-config' option can be used to disable all of the | |
10688 | following options, but it is processed first, so individual options may | |
10689 | be enabled using 'enable-FEATURE'. | |
10690 | ||
74091dd4 CR |
10691 | All of the following options except for 'alt-array-implementation', |
10692 | 'disabled-builtins', 'direxpand-default', 'strict-posix-default', and | |
10693 | 'xpg-echo-default' are enabled by default, unless the operating system | |
10694 | does not provide the necessary support. | |
a0c0a00f CR |
10695 | |
10696 | '--enable-alias' | |
10697 | Allow alias expansion and include the 'alias' and 'unalias' | |
10698 | builtins (*note Aliases::). | |
10699 | ||
74091dd4 CR |
10700 | '--enable-alt-array-implementation' |
10701 | This builds bash using an alternate implementation of arrays (*note | |
10702 | Arrays::) that provides faster access at the expense of using more | |
10703 | memory (sometimes many times more, depending on how sparse an array | |
10704 | is). | |
10705 | ||
a0c0a00f CR |
10706 | '--enable-arith-for-command' |
10707 | Include support for the alternate form of the 'for' command that | |
10708 | behaves like the C language 'for' statement (*note Looping | |
10709 | Constructs::). | |
10710 | ||
10711 | '--enable-array-variables' | |
10712 | Include support for one-dimensional array shell variables (*note | |
10713 | Arrays::). | |
10714 | ||
10715 | '--enable-bang-history' | |
10716 | Include support for 'csh'-like history substitution (*note History | |
10717 | Interaction::). | |
10718 | ||
10719 | '--enable-brace-expansion' | |
10720 | Include 'csh'-like brace expansion ( 'b{a,b}c' ==> 'bac bbc' ). | |
10721 | See *note Brace Expansion::, for a complete description. | |
10722 | ||
10723 | '--enable-casemod-attributes' | |
10724 | Include support for case-modifying attributes in the 'declare' | |
74091dd4 | 10725 | builtin and assignment statements. Variables with the 'uppercase' |
a0c0a00f CR |
10726 | attribute, for example, will have their values converted to |
10727 | uppercase upon assignment. | |
10728 | ||
10729 | '--enable-casemod-expansion' | |
10730 | Include support for case-modifying word expansions. | |
10731 | ||
10732 | '--enable-command-timing' | |
10733 | Include support for recognizing 'time' as a reserved word and for | |
10734 | displaying timing statistics for the pipeline following 'time' | |
10735 | (*note Pipelines::). This allows pipelines as well as shell | |
10736 | builtins and functions to be timed. | |
10737 | ||
10738 | '--enable-cond-command' | |
10739 | Include support for the '[[' conditional command. (*note | |
10740 | Conditional Constructs::). | |
10741 | ||
10742 | '--enable-cond-regexp' | |
10743 | Include support for matching POSIX regular expressions using the | |
10744 | '=~' binary operator in the '[[' conditional command. (*note | |
10745 | Conditional Constructs::). | |
10746 | ||
10747 | '--enable-coprocesses' | |
10748 | Include support for coprocesses and the 'coproc' reserved word | |
10749 | (*note Pipelines::). | |
10750 | ||
10751 | '--enable-debugger' | |
10752 | Include support for the bash debugger (distributed separately). | |
10753 | ||
d233b485 CR |
10754 | '--enable-dev-fd-stat-broken' |
10755 | If calling 'stat' on /dev/fd/N returns different results than | |
10756 | calling 'fstat' on file descriptor N, supply this option to enable | |
10757 | a workaround. This has implications for conditional commands that | |
10758 | test file attributes. | |
10759 | ||
a0c0a00f CR |
10760 | '--enable-direxpand-default' |
10761 | Cause the 'direxpand' shell option (*note The Shopt Builtin::) to | |
10762 | be enabled by default when the shell starts. It is normally | |
10763 | disabled by default. | |
10764 | ||
10765 | '--enable-directory-stack' | |
10766 | Include support for a 'csh'-like directory stack and the 'pushd', | |
10767 | 'popd', and 'dirs' builtins (*note The Directory Stack::). | |
10768 | ||
10769 | '--enable-disabled-builtins' | |
10770 | Allow builtin commands to be invoked via 'builtin xxx' even after | |
10771 | 'xxx' has been disabled using 'enable -n xxx'. See *note Bash | |
10772 | Builtins::, for details of the 'builtin' and 'enable' builtin | |
10773 | commands. | |
10774 | ||
10775 | '--enable-dparen-arithmetic' | |
10776 | Include support for the '((...))' command (*note Conditional | |
10777 | Constructs::). | |
10778 | ||
10779 | '--enable-extended-glob' | |
10780 | Include support for the extended pattern matching features | |
10781 | described above under *note Pattern Matching::. | |
10782 | ||
10783 | '--enable-extended-glob-default' | |
74091dd4 | 10784 | Set the default value of the 'extglob' shell option described above |
a0c0a00f CR |
10785 | under *note The Shopt Builtin:: to be enabled. |
10786 | ||
10787 | '--enable-function-import' | |
10788 | Include support for importing function definitions exported by | |
10789 | another instance of the shell from the environment. This option is | |
10790 | enabled by default. | |
10791 | ||
10792 | '--enable-glob-asciirange-default' | |
74091dd4 CR |
10793 | Set the default value of the 'globasciiranges' shell option |
10794 | described above under *note The Shopt Builtin:: to be enabled. | |
10795 | This controls the behavior of character ranges when used in pattern | |
10796 | matching bracket expressions. | |
a0c0a00f CR |
10797 | |
10798 | '--enable-help-builtin' | |
10799 | Include the 'help' builtin, which displays help on shell builtins | |
10800 | and variables (*note Bash Builtins::). | |
10801 | ||
10802 | '--enable-history' | |
10803 | Include command history and the 'fc' and 'history' builtin commands | |
10804 | (*note Bash History Facilities::). | |
10805 | ||
10806 | '--enable-job-control' | |
10807 | This enables the job control features (*note Job Control::), if the | |
10808 | operating system supports them. | |
10809 | ||
10810 | '--enable-multibyte' | |
10811 | This enables support for multibyte characters if the operating | |
10812 | system provides the necessary support. | |
10813 | ||
10814 | '--enable-net-redirections' | |
10815 | This enables the special handling of filenames of the form | |
10816 | '/dev/tcp/HOST/PORT' and '/dev/udp/HOST/PORT' when used in | |
10817 | redirections (*note Redirections::). | |
10818 | ||
10819 | '--enable-process-substitution' | |
10820 | This enables process substitution (*note Process Substitution::) if | |
10821 | the operating system provides the necessary support. | |
10822 | ||
10823 | '--enable-progcomp' | |
10824 | Enable the programmable completion facilities (*note Programmable | |
10825 | Completion::). If Readline is not enabled, this option has no | |
10826 | effect. | |
10827 | ||
10828 | '--enable-prompt-string-decoding' | |
10829 | Turn on the interpretation of a number of backslash-escaped | |
d233b485 | 10830 | characters in the '$PS0', '$PS1', '$PS2', and '$PS4' prompt |
a0c0a00f CR |
10831 | strings. See *note Controlling the Prompt::, for a complete list |
10832 | of prompt string escape sequences. | |
10833 | ||
10834 | '--enable-readline' | |
10835 | Include support for command-line editing and history with the Bash | |
10836 | version of the Readline library (*note Command Line Editing::). | |
10837 | ||
10838 | '--enable-restricted' | |
10839 | Include support for a "restricted shell". If this is enabled, | |
10840 | Bash, when called as 'rbash', enters a restricted mode. See *note | |
10841 | The Restricted Shell::, for a description of restricted mode. | |
10842 | ||
10843 | '--enable-select' | |
10844 | Include the 'select' compound command, which allows the generation | |
10845 | of simple menus (*note Conditional Constructs::). | |
10846 | ||
a0c0a00f CR |
10847 | '--enable-single-help-strings' |
10848 | Store the text displayed by the 'help' builtin as a single string | |
10849 | for each help topic. This aids in translating the text to | |
10850 | different languages. You may need to disable this if your compiler | |
10851 | cannot handle very long string literals. | |
10852 | ||
10853 | '--enable-strict-posix-default' | |
10854 | Make Bash POSIX-conformant by default (*note Bash POSIX Mode::). | |
10855 | ||
74091dd4 CR |
10856 | '--enable-translatable-strings' |
10857 | Enable support for '$"STRING"' translatable strings (*note Locale | |
10858 | Translation::). | |
10859 | ||
a0c0a00f CR |
10860 | '--enable-usg-echo-default' |
10861 | A synonym for '--enable-xpg-echo-default'. | |
10862 | ||
10863 | '--enable-xpg-echo-default' | |
10864 | Make the 'echo' builtin expand backslash-escaped characters by | |
10865 | default, without requiring the '-e' option. This sets the default | |
10866 | value of the 'xpg_echo' shell option to 'on', which makes the Bash | |
10867 | 'echo' behave more like the version specified in the Single Unix | |
10868 | Specification, version 3. *Note Bash Builtins::, for a description | |
10869 | of the escape sequences that 'echo' recognizes. | |
10870 | ||
10871 | The file 'config-top.h' contains C Preprocessor '#define' statements | |
10872 | for options which are not settable from 'configure'. Some of these are | |
10873 | not meant to be changed; beware of the consequences if you do. Read the | |
10874 | comments associated with each definition for more information about its | |
10875 | effect. | |
10876 | ||
10877 | \1f | |
10878 | File: bash.info, Node: Reporting Bugs, Next: Major Differences From The Bourne Shell, Prev: Installing Bash, Up: Top | |
10879 | ||
10880 | Appendix A Reporting Bugs | |
10881 | ************************* | |
10882 | ||
10883 | Please report all bugs you find in Bash. But first, you should make | |
10884 | sure that it really is a bug, and that it appears in the latest version | |
10885 | of Bash. The latest version of Bash is always available for FTP from | |
74091dd4 CR |
10886 | <ftp://ftp.gnu.org/pub/gnu/bash/> and from |
10887 | <http://git.savannah.gnu.org/cgit/bash.git/snapshot/bash-master.tar.gz>. | |
a0c0a00f CR |
10888 | |
10889 | Once you have determined that a bug actually exists, use the | |
10890 | 'bashbug' command to submit a bug report. If you have a fix, you are | |
10891 | encouraged to mail that as well! Suggestions and 'philosophical' bug | |
10892 | reports may be mailed to <bug-bash@gnu.org> or posted to the Usenet | |
10893 | newsgroup 'gnu.bash.bug'. | |
10894 | ||
10895 | All bug reports should include: | |
10896 | * The version number of Bash. | |
10897 | * The hardware and operating system. | |
10898 | * The compiler used to compile Bash. | |
10899 | * A description of the bug behaviour. | |
10900 | * A short script or 'recipe' which exercises the bug and may be used | |
10901 | to reproduce it. | |
10902 | ||
10903 | 'bashbug' inserts the first three items automatically into the template | |
10904 | it provides for filing a bug report. | |
10905 | ||
10906 | Please send all reports concerning this manual to <bug-bash@gnu.org>. | |
10907 | ||
10908 | \1f | |
10909 | File: bash.info, Node: Major Differences From The Bourne Shell, Next: GNU Free Documentation License, Prev: Reporting Bugs, Up: Top | |
10910 | ||
10911 | Appendix B Major Differences From The Bourne Shell | |
10912 | ************************************************** | |
10913 | ||
10914 | Bash implements essentially the same grammar, parameter and variable | |
10915 | expansion, redirection, and quoting as the Bourne Shell. Bash uses the | |
10916 | POSIX standard as the specification of how these features are to be | |
10917 | implemented. There are some differences between the traditional Bourne | |
10918 | shell and Bash; this section quickly details the differences of | |
10919 | significance. A number of these differences are explained in greater | |
10920 | depth in previous sections. This section uses the version of 'sh' | |
10921 | included in SVR4.2 (the last version of the historical Bourne shell) as | |
10922 | the baseline reference. | |
10923 | ||
10924 | * Bash is POSIX-conformant, even where the POSIX specification | |
10925 | differs from traditional 'sh' behavior (*note Bash POSIX Mode::). | |
10926 | ||
10927 | * Bash has multi-character invocation options (*note Invoking | |
10928 | Bash::). | |
10929 | ||
10930 | * Bash has command-line editing (*note Command Line Editing::) and | |
10931 | the 'bind' builtin. | |
10932 | ||
10933 | * Bash provides a programmable word completion mechanism (*note | |
10934 | Programmable Completion::), and builtin commands 'complete', | |
10935 | 'compgen', and 'compopt', to manipulate it. | |
10936 | ||
10937 | * Bash has command history (*note Bash History Facilities::) and the | |
10938 | 'history' and 'fc' builtins to manipulate it. The Bash history | |
10939 | list maintains timestamp information and uses the value of the | |
10940 | 'HISTTIMEFORMAT' variable to display it. | |
10941 | ||
10942 | * Bash implements 'csh'-like history expansion (*note History | |
10943 | Interaction::). | |
10944 | ||
10945 | * Bash has one-dimensional array variables (*note Arrays::), and the | |
10946 | appropriate variable expansions and assignment syntax to use them. | |
10947 | Several of the Bash builtins take options to act on arrays. Bash | |
10948 | provides a number of built-in array variables. | |
10949 | ||
10950 | * The '$'...'' quoting syntax, which expands ANSI-C backslash-escaped | |
10951 | characters in the text between the single quotes, is supported | |
10952 | (*note ANSI-C Quoting::). | |
10953 | ||
10954 | * Bash supports the '$"..."' quoting syntax to do locale-specific | |
10955 | translation of the characters between the double quotes. The '-D', | |
10956 | '--dump-strings', and '--dump-po-strings' invocation options list | |
10957 | the translatable strings found in a script (*note Locale | |
10958 | Translation::). | |
10959 | ||
10960 | * Bash implements the '!' keyword to negate the return value of a | |
10961 | pipeline (*note Pipelines::). Very useful when an 'if' statement | |
10962 | needs to act only if a test fails. The Bash '-o pipefail' option | |
10963 | to 'set' will cause a pipeline to return a failure status if any | |
10964 | command fails. | |
10965 | ||
10966 | * Bash has the 'time' reserved word and command timing (*note | |
10967 | Pipelines::). The display of the timing statistics may be | |
10968 | controlled with the 'TIMEFORMAT' variable. | |
10969 | ||
10970 | * Bash implements the 'for (( EXPR1 ; EXPR2 ; EXPR3 ))' arithmetic | |
10971 | for command, similar to the C language (*note Looping | |
10972 | Constructs::). | |
10973 | ||
10974 | * Bash includes the 'select' compound command, which allows the | |
10975 | generation of simple menus (*note Conditional Constructs::). | |
10976 | ||
10977 | * Bash includes the '[[' compound command, which makes conditional | |
10978 | testing part of the shell grammar (*note Conditional Constructs::), | |
10979 | including optional regular expression matching. | |
10980 | ||
10981 | * Bash provides optional case-insensitive matching for the 'case' and | |
10982 | '[[' constructs. | |
10983 | ||
10984 | * Bash includes brace expansion (*note Brace Expansion::) and tilde | |
10985 | expansion (*note Tilde Expansion::). | |
10986 | ||
10987 | * Bash implements command aliases and the 'alias' and 'unalias' | |
10988 | builtins (*note Aliases::). | |
10989 | ||
10990 | * Bash provides shell arithmetic, the '((' compound command (*note | |
10991 | Conditional Constructs::), and arithmetic expansion (*note Shell | |
10992 | Arithmetic::). | |
10993 | ||
10994 | * Variables present in the shell's initial environment are | |
10995 | automatically exported to child processes. The Bourne shell does | |
10996 | not normally do this unless the variables are explicitly marked | |
10997 | using the 'export' command. | |
10998 | ||
10999 | * Bash supports the '+=' assignment operator, which appends to the | |
11000 | value of the variable named on the left hand side. | |
11001 | ||
11002 | * Bash includes the POSIX pattern removal '%', '#', '%%' and '##' | |
11003 | expansions to remove leading or trailing substrings from variable | |
11004 | values (*note Shell Parameter Expansion::). | |
11005 | ||
11006 | * The expansion '${#xx}', which returns the length of '${xx}', is | |
11007 | supported (*note Shell Parameter Expansion::). | |
11008 | ||
11009 | * The expansion '${var:'OFFSET'[:'LENGTH']}', which expands to the | |
11010 | substring of 'var''s value of length LENGTH, beginning at OFFSET, | |
11011 | is present (*note Shell Parameter Expansion::). | |
11012 | ||
74091dd4 CR |
11013 | * The expansion '${VAR/[/]'PATTERN'[/'REPLACEMENT']}', which matches |
11014 | PATTERN and replaces it with REPLACEMENT in the value of VAR, is | |
a0c0a00f CR |
11015 | available (*note Shell Parameter Expansion::). |
11016 | ||
11017 | * The expansion '${!PREFIX*}' expansion, which expands to the names | |
11018 | of all shell variables whose names begin with PREFIX, is available | |
11019 | (*note Shell Parameter Expansion::). | |
11020 | ||
74091dd4 | 11021 | * Bash has indirect variable expansion using '${!word}' (*note Shell |
a0c0a00f CR |
11022 | Parameter Expansion::). |
11023 | ||
11024 | * Bash can expand positional parameters beyond '$9' using '${NUM}'. | |
11025 | ||
11026 | * The POSIX '$()' form of command substitution is implemented (*note | |
11027 | Command Substitution::), and preferred to the Bourne shell's '``' | |
11028 | (which is also implemented for backwards compatibility). | |
11029 | ||
11030 | * Bash has process substitution (*note Process Substitution::). | |
11031 | ||
11032 | * Bash automatically assigns variables that provide information about | |
11033 | the current user ('UID', 'EUID', and 'GROUPS'), the current host | |
11034 | ('HOSTTYPE', 'OSTYPE', 'MACHTYPE', and 'HOSTNAME'), and the | |
11035 | instance of Bash that is running ('BASH', 'BASH_VERSION', and | |
11036 | 'BASH_VERSINFO'). *Note Bash Variables::, for details. | |
11037 | ||
11038 | * The 'IFS' variable is used to split only the results of expansion, | |
11039 | not all words (*note Word Splitting::). This closes a longstanding | |
11040 | shell security hole. | |
11041 | ||
11042 | * The filename expansion bracket expression code uses '!' and '^' to | |
11043 | negate the set of characters between the brackets. The Bourne | |
11044 | shell uses only '!'. | |
11045 | ||
11046 | * Bash implements the full set of POSIX filename expansion operators, | |
74091dd4 CR |
11047 | including character classes, equivalence classes, and collating |
11048 | symbols (*note Filename Expansion::). | |
a0c0a00f CR |
11049 | |
11050 | * Bash implements extended pattern matching features when the | |
11051 | 'extglob' shell option is enabled (*note Pattern Matching::). | |
11052 | ||
11053 | * It is possible to have a variable and a function with the same | |
11054 | name; 'sh' does not separate the two name spaces. | |
11055 | ||
11056 | * Bash functions are permitted to have local variables using the | |
11057 | 'local' builtin, and thus useful recursive functions may be written | |
11058 | (*note Bash Builtins::). | |
11059 | ||
11060 | * Variable assignments preceding commands affect only that command, | |
11061 | even builtins and functions (*note Environment::). In 'sh', all | |
11062 | variable assignments preceding commands are global unless the | |
11063 | command is executed from the file system. | |
11064 | ||
11065 | * Bash performs filename expansion on filenames specified as operands | |
11066 | to input and output redirection operators (*note Redirections::). | |
11067 | ||
11068 | * Bash contains the '<>' redirection operator, allowing a file to be | |
11069 | opened for both reading and writing, and the '&>' redirection | |
11070 | operator, for directing standard output and standard error to the | |
11071 | same file (*note Redirections::). | |
11072 | ||
11073 | * Bash includes the '<<<' redirection operator, allowing a string to | |
11074 | be used as the standard input to a command. | |
11075 | ||
11076 | * Bash implements the '[n]<&WORD' and '[n]>&WORD' redirection | |
11077 | operators, which move one file descriptor to another. | |
11078 | ||
11079 | * Bash treats a number of filenames specially when they are used in | |
11080 | redirection operators (*note Redirections::). | |
11081 | ||
11082 | * Bash can open network connections to arbitrary machines and | |
11083 | services with the redirection operators (*note Redirections::). | |
11084 | ||
11085 | * The 'noclobber' option is available to avoid overwriting existing | |
11086 | files with output redirection (*note The Set Builtin::). The '>|' | |
11087 | redirection operator may be used to override 'noclobber'. | |
11088 | ||
11089 | * The Bash 'cd' and 'pwd' builtins (*note Bourne Shell Builtins::) | |
11090 | each take '-L' and '-P' options to switch between logical and | |
11091 | physical modes. | |
11092 | ||
11093 | * Bash allows a function to override a builtin with the same name, | |
11094 | and provides access to that builtin's functionality within the | |
11095 | function via the 'builtin' and 'command' builtins (*note Bash | |
11096 | Builtins::). | |
11097 | ||
11098 | * The 'command' builtin allows selective disabling of functions when | |
11099 | command lookup is performed (*note Bash Builtins::). | |
11100 | ||
11101 | * Individual builtins may be enabled or disabled using the 'enable' | |
11102 | builtin (*note Bash Builtins::). | |
11103 | ||
11104 | * The Bash 'exec' builtin takes additional options that allow users | |
11105 | to control the contents of the environment passed to the executed | |
11106 | command, and what the zeroth argument to the command is to be | |
11107 | (*note Bourne Shell Builtins::). | |
11108 | ||
11109 | * Shell functions may be exported to children via the environment | |
11110 | using 'export -f' (*note Shell Functions::). | |
11111 | ||
11112 | * The Bash 'export', 'readonly', and 'declare' builtins can take a | |
11113 | '-f' option to act on shell functions, a '-p' option to display | |
11114 | variables with various attributes set in a format that can be used | |
11115 | as shell input, a '-n' option to remove various variable | |
11116 | attributes, and 'name=value' arguments to set variable attributes | |
11117 | and values simultaneously. | |
11118 | ||
11119 | * The Bash 'hash' builtin allows a name to be associated with an | |
11120 | arbitrary filename, even when that filename cannot be found by | |
11121 | searching the '$PATH', using 'hash -p' (*note Bourne Shell | |
11122 | Builtins::). | |
11123 | ||
11124 | * Bash includes a 'help' builtin for quick reference to shell | |
11125 | facilities (*note Bash Builtins::). | |
11126 | ||
11127 | * The 'printf' builtin is available to display formatted output | |
11128 | (*note Bash Builtins::). | |
11129 | ||
11130 | * The Bash 'read' builtin (*note Bash Builtins::) will read a line | |
11131 | ending in '\' with the '-r' option, and will use the 'REPLY' | |
11132 | variable as a default if no non-option arguments are supplied. The | |
11133 | Bash 'read' builtin also accepts a prompt string with the '-p' | |
11134 | option and will use Readline to obtain the line when given the '-e' | |
11135 | option. The 'read' builtin also has additional options to control | |
11136 | input: the '-s' option will turn off echoing of input characters as | |
11137 | they are read, the '-t' option will allow 'read' to time out if | |
11138 | input does not arrive within a specified number of seconds, the | |
11139 | '-n' option will allow reading only a specified number of | |
11140 | characters rather than a full line, and the '-d' option will read | |
11141 | until a particular character rather than newline. | |
11142 | ||
11143 | * The 'return' builtin may be used to abort execution of scripts | |
11144 | executed with the '.' or 'source' builtins (*note Bourne Shell | |
11145 | Builtins::). | |
11146 | ||
11147 | * Bash includes the 'shopt' builtin, for finer control of shell | |
11148 | optional capabilities (*note The Shopt Builtin::), and allows these | |
11149 | options to be set and unset at shell invocation (*note Invoking | |
11150 | Bash::). | |
11151 | ||
11152 | * Bash has much more optional behavior controllable with the 'set' | |
11153 | builtin (*note The Set Builtin::). | |
11154 | ||
11155 | * The '-x' ('xtrace') option displays commands other than simple | |
11156 | commands when performing an execution trace (*note The Set | |
11157 | Builtin::). | |
11158 | ||
11159 | * The 'test' builtin (*note Bourne Shell Builtins::) is slightly | |
11160 | different, as it implements the POSIX algorithm, which specifies | |
11161 | the behavior based on the number of arguments. | |
11162 | ||
11163 | * Bash includes the 'caller' builtin, which displays the context of | |
11164 | any active subroutine call (a shell function or a script executed | |
74091dd4 | 11165 | with the '.' or 'source' builtins). This supports the Bash |
a0c0a00f CR |
11166 | debugger. |
11167 | ||
11168 | * The 'trap' builtin (*note Bourne Shell Builtins::) allows a 'DEBUG' | |
11169 | pseudo-signal specification, similar to 'EXIT'. Commands specified | |
11170 | with a 'DEBUG' trap are executed before every simple command, 'for' | |
11171 | command, 'case' command, 'select' command, every arithmetic 'for' | |
11172 | command, and before the first command executes in a shell function. | |
11173 | The 'DEBUG' trap is not inherited by shell functions unless the | |
11174 | function has been given the 'trace' attribute or the 'functrace' | |
11175 | option has been enabled using the 'shopt' builtin. The 'extdebug' | |
11176 | shell option has additional effects on the 'DEBUG' trap. | |
11177 | ||
11178 | The 'trap' builtin (*note Bourne Shell Builtins::) allows an 'ERR' | |
11179 | pseudo-signal specification, similar to 'EXIT' and 'DEBUG'. | |
11180 | Commands specified with an 'ERR' trap are executed after a simple | |
11181 | command fails, with a few exceptions. The 'ERR' trap is not | |
11182 | inherited by shell functions unless the '-o errtrace' option to the | |
11183 | 'set' builtin is enabled. | |
11184 | ||
11185 | The 'trap' builtin (*note Bourne Shell Builtins::) allows a | |
11186 | 'RETURN' pseudo-signal specification, similar to 'EXIT' and | |
74091dd4 | 11187 | 'DEBUG'. Commands specified with a 'RETURN' trap are executed |
a0c0a00f CR |
11188 | before execution resumes after a shell function or a shell script |
11189 | executed with '.' or 'source' returns. The 'RETURN' trap is not | |
11190 | inherited by shell functions unless the function has been given the | |
11191 | 'trace' attribute or the 'functrace' option has been enabled using | |
11192 | the 'shopt' builtin. | |
11193 | ||
11194 | * The Bash 'type' builtin is more extensive and gives more | |
11195 | information about the names it finds (*note Bash Builtins::). | |
11196 | ||
11197 | * The Bash 'umask' builtin permits a '-p' option to cause the output | |
11198 | to be displayed in the form of a 'umask' command that may be reused | |
11199 | as input (*note Bourne Shell Builtins::). | |
11200 | ||
11201 | * Bash implements a 'csh'-like directory stack, and provides the | |
11202 | 'pushd', 'popd', and 'dirs' builtins to manipulate it (*note The | |
11203 | Directory Stack::). Bash also makes the directory stack visible as | |
11204 | the value of the 'DIRSTACK' shell variable. | |
11205 | ||
11206 | * Bash interprets special backslash-escaped characters in the prompt | |
11207 | strings when interactive (*note Controlling the Prompt::). | |
11208 | ||
11209 | * The Bash restricted mode is more useful (*note The Restricted | |
11210 | Shell::); the SVR4.2 shell restricted mode is too limited. | |
11211 | ||
11212 | * The 'disown' builtin can remove a job from the internal shell job | |
11213 | table (*note Job Control Builtins::) or suppress the sending of | |
11214 | 'SIGHUP' to a job when the shell exits as the result of a 'SIGHUP'. | |
11215 | ||
11216 | * Bash includes a number of features to support a separate debugger | |
11217 | for shell scripts. | |
11218 | ||
11219 | * The SVR4.2 shell has two privilege-related builtins ('mldmode' and | |
11220 | 'priv') not present in Bash. | |
11221 | ||
11222 | * Bash does not have the 'stop' or 'newgrp' builtins. | |
11223 | ||
11224 | * Bash does not use the 'SHACCT' variable or perform shell | |
11225 | accounting. | |
11226 | ||
11227 | * The SVR4.2 'sh' uses a 'TIMEOUT' variable like Bash uses 'TMOUT'. | |
11228 | ||
11229 | More features unique to Bash may be found in *note Bash Features::. | |
11230 | ||
11231 | B.1 Implementation Differences From The SVR4.2 Shell | |
11232 | ==================================================== | |
11233 | ||
11234 | Since Bash is a completely new implementation, it does not suffer from | |
11235 | many of the limitations of the SVR4.2 shell. For instance: | |
11236 | ||
11237 | * Bash does not fork a subshell when redirecting into or out of a | |
11238 | shell control structure such as an 'if' or 'while' statement. | |
11239 | ||
11240 | * Bash does not allow unbalanced quotes. The SVR4.2 shell will | |
11241 | silently insert a needed closing quote at 'EOF' under certain | |
11242 | circumstances. This can be the cause of some hard-to-find errors. | |
11243 | ||
11244 | * The SVR4.2 shell uses a baroque memory management scheme based on | |
11245 | trapping 'SIGSEGV'. If the shell is started from a process with | |
11246 | 'SIGSEGV' blocked (e.g., by using the 'system()' C library function | |
11247 | call), it misbehaves badly. | |
11248 | ||
11249 | * In a questionable attempt at security, the SVR4.2 shell, when | |
11250 | invoked without the '-p' option, will alter its real and effective | |
11251 | UID and GID if they are less than some magic threshold value, | |
11252 | commonly 100. This can lead to unexpected results. | |
11253 | ||
11254 | * The SVR4.2 shell does not allow users to trap 'SIGSEGV', 'SIGALRM', | |
11255 | or 'SIGCHLD'. | |
11256 | ||
11257 | * The SVR4.2 shell does not allow the 'IFS', 'MAILCHECK', 'PATH', | |
11258 | 'PS1', or 'PS2' variables to be unset. | |
11259 | ||
11260 | * The SVR4.2 shell treats '^' as the undocumented equivalent of '|'. | |
11261 | ||
11262 | * Bash allows multiple option arguments when it is invoked ('-x -v'); | |
11263 | the SVR4.2 shell allows only one option argument ('-xv'). In fact, | |
11264 | some versions of the shell dump core if the second argument begins | |
11265 | with a '-'. | |
11266 | ||
11267 | * The SVR4.2 shell exits a script if any builtin fails; Bash exits a | |
11268 | script only if one of the POSIX special builtins fails, and only | |
11269 | for certain failures, as enumerated in the POSIX standard. | |
11270 | ||
11271 | * The SVR4.2 shell behaves differently when invoked as 'jsh' (it | |
11272 | turns on job control). | |
11273 | ||
11274 | \1f | |
11275 | File: bash.info, Node: GNU Free Documentation License, Next: Indexes, Prev: Major Differences From The Bourne Shell, Up: Top | |
11276 | ||
11277 | Appendix C GNU Free Documentation License | |
11278 | ***************************************** | |
11279 | ||
11280 | Version 1.3, 3 November 2008 | |
11281 | ||
11282 | Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. | |
11283 | <http://fsf.org/> | |
11284 | ||
11285 | Everyone is permitted to copy and distribute verbatim copies | |
11286 | of this license document, but changing it is not allowed. | |
11287 | ||
11288 | 0. PREAMBLE | |
11289 | ||
11290 | The purpose of this License is to make a manual, textbook, or other | |
11291 | functional and useful document "free" in the sense of freedom: to | |
11292 | assure everyone the effective freedom to copy and redistribute it, | |
11293 | with or without modifying it, either commercially or | |
11294 | noncommercially. Secondarily, this License preserves for the | |
11295 | author and publisher a way to get credit for their work, while not | |
11296 | being considered responsible for modifications made by others. | |
11297 | ||
11298 | This License is a kind of "copyleft", which means that derivative | |
11299 | works of the document must themselves be free in the same sense. | |
11300 | It complements the GNU General Public License, which is a copyleft | |
11301 | license designed for free software. | |
11302 | ||
11303 | We have designed this License in order to use it for manuals for | |
11304 | free software, because free software needs free documentation: a | |
11305 | free program should come with manuals providing the same freedoms | |
11306 | that the software does. But this License is not limited to | |
11307 | software manuals; it can be used for any textual work, regardless | |
11308 | of subject matter or whether it is published as a printed book. We | |
11309 | recommend this License principally for works whose purpose is | |
11310 | instruction or reference. | |
11311 | ||
11312 | 1. APPLICABILITY AND DEFINITIONS | |
11313 | ||
11314 | This License applies to any manual or other work, in any medium, | |
11315 | that contains a notice placed by the copyright holder saying it can | |
11316 | be distributed under the terms of this License. Such a notice | |
11317 | grants a world-wide, royalty-free license, unlimited in duration, | |
11318 | to use that work under the conditions stated herein. The | |
11319 | "Document", below, refers to any such manual or work. Any member | |
11320 | of the public is a licensee, and is addressed as "you". You accept | |
11321 | the license if you copy, modify or distribute the work in a way | |
11322 | requiring permission under copyright law. | |
11323 | ||
11324 | A "Modified Version" of the Document means any work containing the | |
11325 | Document or a portion of it, either copied verbatim, or with | |
11326 | modifications and/or translated into another language. | |
11327 | ||
11328 | A "Secondary Section" is a named appendix or a front-matter section | |
11329 | of the Document that deals exclusively with the relationship of the | |
11330 | publishers or authors of the Document to the Document's overall | |
11331 | subject (or to related matters) and contains nothing that could | |
11332 | fall directly within that overall subject. (Thus, if the Document | |
11333 | is in part a textbook of mathematics, a Secondary Section may not | |
11334 | explain any mathematics.) The relationship could be a matter of | |
11335 | historical connection with the subject or with related matters, or | |
11336 | of legal, commercial, philosophical, ethical or political position | |
11337 | regarding them. | |
11338 | ||
11339 | The "Invariant Sections" are certain Secondary Sections whose | |
11340 | titles are designated, as being those of Invariant Sections, in the | |
11341 | notice that says that the Document is released under this License. | |
11342 | If a section does not fit the above definition of Secondary then it | |
11343 | is not allowed to be designated as Invariant. The Document may | |
11344 | contain zero Invariant Sections. If the Document does not identify | |
11345 | any Invariant Sections then there are none. | |
11346 | ||
11347 | The "Cover Texts" are certain short passages of text that are | |
11348 | listed, as Front-Cover Texts or Back-Cover Texts, in the notice | |
11349 | that says that the Document is released under this License. A | |
11350 | Front-Cover Text may be at most 5 words, and a Back-Cover Text may | |
11351 | be at most 25 words. | |
11352 | ||
11353 | A "Transparent" copy of the Document means a machine-readable copy, | |
11354 | represented in a format whose specification is available to the | |
11355 | general public, that is suitable for revising the document | |
11356 | straightforwardly with generic text editors or (for images composed | |
11357 | of pixels) generic paint programs or (for drawings) some widely | |
11358 | available drawing editor, and that is suitable for input to text | |
11359 | formatters or for automatic translation to a variety of formats | |
11360 | suitable for input to text formatters. A copy made in an otherwise | |
11361 | Transparent file format whose markup, or absence of markup, has | |
11362 | been arranged to thwart or discourage subsequent modification by | |
11363 | readers is not Transparent. An image format is not Transparent if | |
11364 | used for any substantial amount of text. A copy that is not | |
11365 | "Transparent" is called "Opaque". | |
11366 | ||
11367 | Examples of suitable formats for Transparent copies include plain | |
11368 | ASCII without markup, Texinfo input format, LaTeX input format, | |
11369 | SGML or XML using a publicly available DTD, and standard-conforming | |
11370 | simple HTML, PostScript or PDF designed for human modification. | |
11371 | Examples of transparent image formats include PNG, XCF and JPG. | |
11372 | Opaque formats include proprietary formats that can be read and | |
11373 | edited only by proprietary word processors, SGML or XML for which | |
11374 | the DTD and/or processing tools are not generally available, and | |
11375 | the machine-generated HTML, PostScript or PDF produced by some word | |
11376 | processors for output purposes only. | |
11377 | ||
11378 | The "Title Page" means, for a printed book, the title page itself, | |
11379 | plus such following pages as are needed to hold, legibly, the | |
11380 | material this License requires to appear in the title page. For | |
11381 | works in formats which do not have any title page as such, "Title | |
11382 | Page" means the text near the most prominent appearance of the | |
11383 | work's title, preceding the beginning of the body of the text. | |
11384 | ||
11385 | The "publisher" means any person or entity that distributes copies | |
11386 | of the Document to the public. | |
11387 | ||
11388 | A section "Entitled XYZ" means a named subunit of the Document | |
11389 | whose title either is precisely XYZ or contains XYZ in parentheses | |
11390 | following text that translates XYZ in another language. (Here XYZ | |
11391 | stands for a specific section name mentioned below, such as | |
11392 | "Acknowledgements", "Dedications", "Endorsements", or "History".) | |
11393 | To "Preserve the Title" of such a section when you modify the | |
11394 | Document means that it remains a section "Entitled XYZ" according | |
11395 | to this definition. | |
11396 | ||
11397 | The Document may include Warranty Disclaimers next to the notice | |
11398 | which states that this License applies to the Document. These | |
11399 | Warranty Disclaimers are considered to be included by reference in | |
11400 | this License, but only as regards disclaiming warranties: any other | |
11401 | implication that these Warranty Disclaimers may have is void and | |
11402 | has no effect on the meaning of this License. | |
11403 | ||
11404 | 2. VERBATIM COPYING | |
11405 | ||
11406 | You may copy and distribute the Document in any medium, either | |
11407 | commercially or noncommercially, provided that this License, the | |
11408 | copyright notices, and the license notice saying this License | |
11409 | applies to the Document are reproduced in all copies, and that you | |
11410 | add no other conditions whatsoever to those of this License. You | |
11411 | may not use technical measures to obstruct or control the reading | |
11412 | or further copying of the copies you make or distribute. However, | |
11413 | you may accept compensation in exchange for copies. If you | |
11414 | distribute a large enough number of copies you must also follow the | |
11415 | conditions in section 3. | |
11416 | ||
11417 | You may also lend copies, under the same conditions stated above, | |
11418 | and you may publicly display copies. | |
11419 | ||
11420 | 3. COPYING IN QUANTITY | |
11421 | ||
11422 | If you publish printed copies (or copies in media that commonly | |
11423 | have printed covers) of the Document, numbering more than 100, and | |
11424 | the Document's license notice requires Cover Texts, you must | |
11425 | enclose the copies in covers that carry, clearly and legibly, all | |
11426 | these Cover Texts: Front-Cover Texts on the front cover, and | |
11427 | Back-Cover Texts on the back cover. Both covers must also clearly | |
11428 | and legibly identify you as the publisher of these copies. The | |
11429 | front cover must present the full title with all words of the title | |
11430 | equally prominent and visible. You may add other material on the | |
11431 | covers in addition. Copying with changes limited to the covers, as | |
11432 | long as they preserve the title of the Document and satisfy these | |
11433 | conditions, can be treated as verbatim copying in other respects. | |
11434 | ||
11435 | If the required texts for either cover are too voluminous to fit | |
11436 | legibly, you should put the first ones listed (as many as fit | |
11437 | reasonably) on the actual cover, and continue the rest onto | |
11438 | adjacent pages. | |
11439 | ||
11440 | If you publish or distribute Opaque copies of the Document | |
11441 | numbering more than 100, you must either include a machine-readable | |
11442 | Transparent copy along with each Opaque copy, or state in or with | |
11443 | each Opaque copy a computer-network location from which the general | |
11444 | network-using public has access to download using public-standard | |
11445 | network protocols a complete Transparent copy of the Document, free | |
11446 | of added material. If you use the latter option, you must take | |
11447 | reasonably prudent steps, when you begin distribution of Opaque | |
11448 | copies in quantity, to ensure that this Transparent copy will | |
11449 | remain thus accessible at the stated location until at least one | |
11450 | year after the last time you distribute an Opaque copy (directly or | |
11451 | through your agents or retailers) of that edition to the public. | |
11452 | ||
11453 | It is requested, but not required, that you contact the authors of | |
11454 | the Document well before redistributing any large number of copies, | |
11455 | to give them a chance to provide you with an updated version of the | |
11456 | Document. | |
11457 | ||
11458 | 4. MODIFICATIONS | |
11459 | ||
11460 | You may copy and distribute a Modified Version of the Document | |
11461 | under the conditions of sections 2 and 3 above, provided that you | |
11462 | release the Modified Version under precisely this License, with the | |
11463 | Modified Version filling the role of the Document, thus licensing | |
11464 | distribution and modification of the Modified Version to whoever | |
11465 | possesses a copy of it. In addition, you must do these things in | |
11466 | the Modified Version: | |
11467 | ||
11468 | A. Use in the Title Page (and on the covers, if any) a title | |
11469 | distinct from that of the Document, and from those of previous | |
11470 | versions (which should, if there were any, be listed in the | |
11471 | History section of the Document). You may use the same title | |
11472 | as a previous version if the original publisher of that | |
11473 | version gives permission. | |
11474 | ||
11475 | B. List on the Title Page, as authors, one or more persons or | |
11476 | entities responsible for authorship of the modifications in | |
11477 | the Modified Version, together with at least five of the | |
11478 | principal authors of the Document (all of its principal | |
11479 | authors, if it has fewer than five), unless they release you | |
11480 | from this requirement. | |
11481 | ||
11482 | C. State on the Title page the name of the publisher of the | |
11483 | Modified Version, as the publisher. | |
11484 | ||
11485 | D. Preserve all the copyright notices of the Document. | |
11486 | ||
11487 | E. Add an appropriate copyright notice for your modifications | |
11488 | adjacent to the other copyright notices. | |
11489 | ||
11490 | F. Include, immediately after the copyright notices, a license | |
11491 | notice giving the public permission to use the Modified | |
11492 | Version under the terms of this License, in the form shown in | |
11493 | the Addendum below. | |
11494 | ||
11495 | G. Preserve in that license notice the full lists of Invariant | |
11496 | Sections and required Cover Texts given in the Document's | |
11497 | license notice. | |
11498 | ||
11499 | H. Include an unaltered copy of this License. | |
11500 | ||
11501 | I. Preserve the section Entitled "History", Preserve its Title, | |
11502 | and add to it an item stating at least the title, year, new | |
11503 | authors, and publisher of the Modified Version as given on the | |
11504 | Title Page. If there is no section Entitled "History" in the | |
11505 | Document, create one stating the title, year, authors, and | |
11506 | publisher of the Document as given on its Title Page, then add | |
11507 | an item describing the Modified Version as stated in the | |
11508 | previous sentence. | |
11509 | ||
11510 | J. Preserve the network location, if any, given in the Document | |
11511 | for public access to a Transparent copy of the Document, and | |
11512 | likewise the network locations given in the Document for | |
11513 | previous versions it was based on. These may be placed in the | |
11514 | "History" section. You may omit a network location for a work | |
11515 | that was published at least four years before the Document | |
11516 | itself, or if the original publisher of the version it refers | |
11517 | to gives permission. | |
11518 | ||
11519 | K. For any section Entitled "Acknowledgements" or "Dedications", | |
11520 | Preserve the Title of the section, and preserve in the section | |
11521 | all the substance and tone of each of the contributor | |
11522 | acknowledgements and/or dedications given therein. | |
11523 | ||
11524 | L. Preserve all the Invariant Sections of the Document, unaltered | |
11525 | in their text and in their titles. Section numbers or the | |
11526 | equivalent are not considered part of the section titles. | |
11527 | ||
11528 | M. Delete any section Entitled "Endorsements". Such a section | |
11529 | may not be included in the Modified Version. | |
11530 | ||
11531 | N. Do not retitle any existing section to be Entitled | |
11532 | "Endorsements" or to conflict in title with any Invariant | |
11533 | Section. | |
11534 | ||
11535 | O. Preserve any Warranty Disclaimers. | |
11536 | ||
11537 | If the Modified Version includes new front-matter sections or | |
11538 | appendices that qualify as Secondary Sections and contain no | |
11539 | material copied from the Document, you may at your option designate | |
11540 | some or all of these sections as invariant. To do this, add their | |
11541 | titles to the list of Invariant Sections in the Modified Version's | |
11542 | license notice. These titles must be distinct from any other | |
11543 | section titles. | |
11544 | ||
11545 | You may add a section Entitled "Endorsements", provided it contains | |
11546 | nothing but endorsements of your Modified Version by various | |
11547 | parties--for example, statements of peer review or that the text | |
11548 | has been approved by an organization as the authoritative | |
11549 | definition of a standard. | |
11550 | ||
11551 | You may add a passage of up to five words as a Front-Cover Text, | |
11552 | and a passage of up to 25 words as a Back-Cover Text, to the end of | |
11553 | the list of Cover Texts in the Modified Version. Only one passage | |
11554 | of Front-Cover Text and one of Back-Cover Text may be added by (or | |
11555 | through arrangements made by) any one entity. If the Document | |
11556 | already includes a cover text for the same cover, previously added | |
11557 | by you or by arrangement made by the same entity you are acting on | |
11558 | behalf of, you may not add another; but you may replace the old | |
11559 | one, on explicit permission from the previous publisher that added | |
11560 | the old one. | |
11561 | ||
11562 | The author(s) and publisher(s) of the Document do not by this | |
11563 | License give permission to use their names for publicity for or to | |
11564 | assert or imply endorsement of any Modified Version. | |
11565 | ||
11566 | 5. COMBINING DOCUMENTS | |
11567 | ||
11568 | You may combine the Document with other documents released under | |
11569 | this License, under the terms defined in section 4 above for | |
11570 | modified versions, provided that you include in the combination all | |
11571 | of the Invariant Sections of all of the original documents, | |
11572 | unmodified, and list them all as Invariant Sections of your | |
11573 | combined work in its license notice, and that you preserve all | |
11574 | their Warranty Disclaimers. | |
11575 | ||
11576 | The combined work need only contain one copy of this License, and | |
11577 | multiple identical Invariant Sections may be replaced with a single | |
11578 | copy. If there are multiple Invariant Sections with the same name | |
11579 | but different contents, make the title of each such section unique | |
11580 | by adding at the end of it, in parentheses, the name of the | |
11581 | original author or publisher of that section if known, or else a | |
11582 | unique number. Make the same adjustment to the section titles in | |
11583 | the list of Invariant Sections in the license notice of the | |
11584 | combined work. | |
11585 | ||
11586 | In the combination, you must combine any sections Entitled | |
11587 | "History" in the various original documents, forming one section | |
11588 | Entitled "History"; likewise combine any sections Entitled | |
11589 | "Acknowledgements", and any sections Entitled "Dedications". You | |
11590 | must delete all sections Entitled "Endorsements." | |
11591 | ||
11592 | 6. COLLECTIONS OF DOCUMENTS | |
11593 | ||
11594 | You may make a collection consisting of the Document and other | |
11595 | documents released under this License, and replace the individual | |
11596 | copies of this License in the various documents with a single copy | |
11597 | that is included in the collection, provided that you follow the | |
11598 | rules of this License for verbatim copying of each of the documents | |
11599 | in all other respects. | |
11600 | ||
11601 | You may extract a single document from such a collection, and | |
11602 | distribute it individually under this License, provided you insert | |
11603 | a copy of this License into the extracted document, and follow this | |
11604 | License in all other respects regarding verbatim copying of that | |
11605 | document. | |
11606 | ||
11607 | 7. AGGREGATION WITH INDEPENDENT WORKS | |
11608 | ||
11609 | A compilation of the Document or its derivatives with other | |
11610 | separate and independent documents or works, in or on a volume of a | |
11611 | storage or distribution medium, is called an "aggregate" if the | |
11612 | copyright resulting from the compilation is not used to limit the | |
11613 | legal rights of the compilation's users beyond what the individual | |
11614 | works permit. When the Document is included in an aggregate, this | |
11615 | License does not apply to the other works in the aggregate which | |
11616 | are not themselves derivative works of the Document. | |
11617 | ||
11618 | If the Cover Text requirement of section 3 is applicable to these | |
11619 | copies of the Document, then if the Document is less than one half | |
11620 | of the entire aggregate, the Document's Cover Texts may be placed | |
11621 | on covers that bracket the Document within the aggregate, or the | |
11622 | electronic equivalent of covers if the Document is in electronic | |
11623 | form. Otherwise they must appear on printed covers that bracket | |
11624 | the whole aggregate. | |
11625 | ||
11626 | 8. TRANSLATION | |
11627 | ||
11628 | Translation is considered a kind of modification, so you may | |
11629 | distribute translations of the Document under the terms of section | |
11630 | 4. Replacing Invariant Sections with translations requires special | |
11631 | permission from their copyright holders, but you may include | |
11632 | translations of some or all Invariant Sections in addition to the | |
11633 | original versions of these Invariant Sections. You may include a | |
11634 | translation of this License, and all the license notices in the | |
11635 | Document, and any Warranty Disclaimers, provided that you also | |
11636 | include the original English version of this License and the | |
11637 | original versions of those notices and disclaimers. In case of a | |
11638 | disagreement between the translation and the original version of | |
11639 | this License or a notice or disclaimer, the original version will | |
11640 | prevail. | |
11641 | ||
11642 | If a section in the Document is Entitled "Acknowledgements", | |
11643 | "Dedications", or "History", the requirement (section 4) to | |
11644 | Preserve its Title (section 1) will typically require changing the | |
11645 | actual title. | |
11646 | ||
11647 | 9. TERMINATION | |
11648 | ||
11649 | You may not copy, modify, sublicense, or distribute the Document | |
11650 | except as expressly provided under this License. Any attempt | |
11651 | otherwise to copy, modify, sublicense, or distribute it is void, | |
11652 | and will automatically terminate your rights under this License. | |
11653 | ||
11654 | However, if you cease all violation of this License, then your | |
11655 | license from a particular copyright holder is reinstated (a) | |
11656 | provisionally, unless and until the copyright holder explicitly and | |
11657 | finally terminates your license, and (b) permanently, if the | |
11658 | copyright holder fails to notify you of the violation by some | |
11659 | reasonable means prior to 60 days after the cessation. | |
11660 | ||
11661 | Moreover, your license from a particular copyright holder is | |
11662 | reinstated permanently if the copyright holder notifies you of the | |
11663 | violation by some reasonable means, this is the first time you have | |
11664 | received notice of violation of this License (for any work) from | |
11665 | that copyright holder, and you cure the violation prior to 30 days | |
11666 | after your receipt of the notice. | |
11667 | ||
11668 | Termination of your rights under this section does not terminate | |
11669 | the licenses of parties who have received copies or rights from you | |
11670 | under this License. If your rights have been terminated and not | |
11671 | permanently reinstated, receipt of a copy of some or all of the | |
11672 | same material does not give you any rights to use it. | |
11673 | ||
11674 | 10. FUTURE REVISIONS OF THIS LICENSE | |
11675 | ||
11676 | The Free Software Foundation may publish new, revised versions of | |
11677 | the GNU Free Documentation License from time to time. Such new | |
11678 | versions will be similar in spirit to the present version, but may | |
11679 | differ in detail to address new problems or concerns. See | |
11680 | <http://www.gnu.org/copyleft/>. | |
11681 | ||
11682 | Each version of the License is given a distinguishing version | |
11683 | number. If the Document specifies that a particular numbered | |
11684 | version of this License "or any later version" applies to it, you | |
11685 | have the option of following the terms and conditions either of | |
11686 | that specified version or of any later version that has been | |
11687 | published (not as a draft) by the Free Software Foundation. If the | |
11688 | Document does not specify a version number of this License, you may | |
11689 | choose any version ever published (not as a draft) by the Free | |
11690 | Software Foundation. If the Document specifies that a proxy can | |
11691 | decide which future versions of this License can be used, that | |
11692 | proxy's public statement of acceptance of a version permanently | |
11693 | authorizes you to choose that version for the Document. | |
11694 | ||
11695 | 11. RELICENSING | |
11696 | ||
11697 | "Massive Multiauthor Collaboration Site" (or "MMC Site") means any | |
11698 | World Wide Web server that publishes copyrightable works and also | |
11699 | provides prominent facilities for anybody to edit those works. A | |
11700 | public wiki that anybody can edit is an example of such a server. | |
11701 | A "Massive Multiauthor Collaboration" (or "MMC") contained in the | |
11702 | site means any set of copyrightable works thus published on the MMC | |
11703 | site. | |
11704 | ||
11705 | "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 | |
11706 | license published by Creative Commons Corporation, a not-for-profit | |
11707 | corporation with a principal place of business in San Francisco, | |
11708 | California, as well as future copyleft versions of that license | |
11709 | published by that same organization. | |
11710 | ||
11711 | "Incorporate" means to publish or republish a Document, in whole or | |
11712 | in part, as part of another Document. | |
11713 | ||
11714 | An MMC is "eligible for relicensing" if it is licensed under this | |
11715 | License, and if all works that were first published under this | |
11716 | License somewhere other than this MMC, and subsequently | |
11717 | incorporated in whole or in part into the MMC, (1) had no cover | |
11718 | texts or invariant sections, and (2) were thus incorporated prior | |
11719 | to November 1, 2008. | |
11720 | ||
11721 | The operator of an MMC Site may republish an MMC contained in the | |
11722 | site under CC-BY-SA on the same site at any time before August 1, | |
11723 | 2009, provided the MMC is eligible for relicensing. | |
11724 | ||
11725 | ADDENDUM: How to use this License for your documents | |
11726 | ==================================================== | |
11727 | ||
11728 | To use this License in a document you have written, include a copy of | |
11729 | the License in the document and put the following copyright and license | |
11730 | notices just after the title page: | |
11731 | ||
11732 | Copyright (C) YEAR YOUR NAME. | |
11733 | Permission is granted to copy, distribute and/or modify this document | |
11734 | under the terms of the GNU Free Documentation License, Version 1.3 | |
11735 | or any later version published by the Free Software Foundation; | |
11736 | with no Invariant Sections, no Front-Cover Texts, and no Back-Cover | |
11737 | Texts. A copy of the license is included in the section entitled ``GNU | |
11738 | Free Documentation License''. | |
11739 | ||
11740 | If you have Invariant Sections, Front-Cover Texts and Back-Cover | |
11741 | Texts, replace the "with...Texts." line with this: | |
11742 | ||
11743 | with the Invariant Sections being LIST THEIR TITLES, with | |
11744 | the Front-Cover Texts being LIST, and with the Back-Cover Texts | |
11745 | being LIST. | |
11746 | ||
11747 | If you have Invariant Sections without Cover Texts, or some other | |
11748 | combination of the three, merge those two alternatives to suit the | |
11749 | situation. | |
11750 | ||
11751 | If your document contains nontrivial examples of program code, we | |
11752 | recommend releasing these examples in parallel under your choice of free | |
11753 | software license, such as the GNU General Public License, to permit | |
11754 | their use in free software. | |
11755 | ||
11756 | \1f | |
11757 | File: bash.info, Node: Indexes, Prev: GNU Free Documentation License, Up: Top | |
11758 | ||
11759 | Appendix D Indexes | |
11760 | ****************** | |
11761 | ||
11762 | * Menu: | |
11763 | ||
11764 | * Builtin Index:: Index of Bash builtin commands. | |
11765 | * Reserved Word Index:: Index of Bash reserved words. | |
11766 | * Variable Index:: Quick reference helps you find the | |
11767 | variable you want. | |
11768 | * Function Index:: Index of bindable Readline functions. | |
11769 | * Concept Index:: General index for concepts described in | |
11770 | this manual. | |
11771 | ||
11772 | \1f | |
11773 | File: bash.info, Node: Builtin Index, Next: Reserved Word Index, Up: Indexes | |
11774 | ||
11775 | D.1 Index of Shell Builtin Commands | |
11776 | =================================== | |
11777 | ||
11778 | \0\b[index\0\b] | |
11779 | * Menu: | |
11780 | ||
11781 | * .: Bourne Shell Builtins. | |
11782 | (line 17) | |
11783 | * :: Bourne Shell Builtins. | |
11784 | (line 11) | |
11785 | * [: Bourne Shell Builtins. | |
74091dd4 | 11786 | (line 275) |
a0c0a00f CR |
11787 | * alias: Bash Builtins. (line 11) |
11788 | * bg: Job Control Builtins. | |
11789 | (line 7) | |
11790 | * bind: Bash Builtins. (line 21) | |
11791 | * break: Bourne Shell Builtins. | |
74091dd4 CR |
11792 | (line 37) |
11793 | * builtin: Bash Builtins. (line 108) | |
11794 | * caller: Bash Builtins. (line 117) | |
a0c0a00f | 11795 | * cd: Bourne Shell Builtins. |
74091dd4 CR |
11796 | (line 45) |
11797 | * command: Bash Builtins. (line 134) | |
a0c0a00f CR |
11798 | * compgen: Programmable Completion Builtins. |
11799 | (line 12) | |
11800 | * complete: Programmable Completion Builtins. | |
11801 | (line 30) | |
11802 | * compopt: Programmable Completion Builtins. | |
74091dd4 | 11803 | (line 238) |
a0c0a00f | 11804 | * continue: Bourne Shell Builtins. |
74091dd4 CR |
11805 | (line 90) |
11806 | * declare: Bash Builtins. (line 154) | |
a0c0a00f CR |
11807 | * dirs: Directory Stack Builtins. |
11808 | (line 7) | |
11809 | * disown: Job Control Builtins. | |
74091dd4 CR |
11810 | (line 104) |
11811 | * echo: Bash Builtins. (line 257) | |
11812 | * enable: Bash Builtins. (line 306) | |
a0c0a00f | 11813 | * eval: Bourne Shell Builtins. |
74091dd4 | 11814 | (line 99) |
a0c0a00f | 11815 | * exec: Bourne Shell Builtins. |
74091dd4 | 11816 | (line 107) |
a0c0a00f | 11817 | * exit: Bourne Shell Builtins. |
74091dd4 | 11818 | (line 125) |
a0c0a00f | 11819 | * export: Bourne Shell Builtins. |
74091dd4 | 11820 | (line 132) |
a0c0a00f CR |
11821 | * fc: Bash History Builtins. |
11822 | (line 10) | |
11823 | * fg: Job Control Builtins. | |
11824 | (line 17) | |
11825 | * getopts: Bourne Shell Builtins. | |
74091dd4 | 11826 | (line 148) |
a0c0a00f | 11827 | * hash: Bourne Shell Builtins. |
74091dd4 CR |
11828 | (line 192) |
11829 | * help: Bash Builtins. (line 342) | |
a0c0a00f | 11830 | * history: Bash History Builtins. |
8868edaf | 11831 | (line 46) |
a0c0a00f CR |
11832 | * jobs: Job Control Builtins. |
11833 | (line 27) | |
11834 | * kill: Job Control Builtins. | |
11835 | (line 58) | |
74091dd4 CR |
11836 | * let: Bash Builtins. (line 361) |
11837 | * local: Bash Builtins. (line 369) | |
11838 | * logout: Bash Builtins. (line 385) | |
11839 | * mapfile: Bash Builtins. (line 390) | |
a0c0a00f CR |
11840 | * popd: Directory Stack Builtins. |
11841 | (line 35) | |
74091dd4 | 11842 | * printf: Bash Builtins. (line 436) |
a0c0a00f | 11843 | * pushd: Directory Stack Builtins. |
74091dd4 | 11844 | (line 69) |
a0c0a00f | 11845 | * pwd: Bourne Shell Builtins. |
74091dd4 CR |
11846 | (line 212) |
11847 | * read: Bash Builtins. (line 488) | |
11848 | * readarray: Bash Builtins. (line 585) | |
a0c0a00f | 11849 | * readonly: Bourne Shell Builtins. |
74091dd4 | 11850 | (line 222) |
a0c0a00f | 11851 | * return: Bourne Shell Builtins. |
74091dd4 | 11852 | (line 241) |
a0c0a00f CR |
11853 | * set: The Set Builtin. (line 11) |
11854 | * shift: Bourne Shell Builtins. | |
74091dd4 | 11855 | (line 262) |
a0c0a00f | 11856 | * shopt: The Shopt Builtin. (line 9) |
74091dd4 | 11857 | * source: Bash Builtins. (line 594) |
a0c0a00f | 11858 | * suspend: Job Control Builtins. |
74091dd4 | 11859 | (line 116) |
a0c0a00f | 11860 | * test: Bourne Shell Builtins. |
74091dd4 | 11861 | (line 275) |
a0c0a00f | 11862 | * times: Bourne Shell Builtins. |
74091dd4 | 11863 | (line 360) |
a0c0a00f | 11864 | * trap: Bourne Shell Builtins. |
74091dd4 CR |
11865 | (line 366) |
11866 | * type: Bash Builtins. (line 599) | |
11867 | * typeset: Bash Builtins. (line 631) | |
11868 | * ulimit: Bash Builtins. (line 637) | |
a0c0a00f | 11869 | * umask: Bourne Shell Builtins. |
74091dd4 CR |
11870 | (line 415) |
11871 | * unalias: Bash Builtins. (line 743) | |
a0c0a00f | 11872 | * unset: Bourne Shell Builtins. |
74091dd4 | 11873 | (line 433) |
a0c0a00f CR |
11874 | * wait: Job Control Builtins. |
11875 | (line 76) | |
11876 | ||
11877 | \1f | |
11878 | File: bash.info, Node: Reserved Word Index, Next: Variable Index, Prev: Builtin Index, Up: Indexes | |
11879 | ||
11880 | D.2 Index of Shell Reserved Words | |
11881 | ================================= | |
11882 | ||
11883 | \0\b[index\0\b] | |
11884 | * Menu: | |
11885 | ||
11886 | * !: Pipelines. (line 9) | |
11887 | * [[: Conditional Constructs. | |
74091dd4 | 11888 | (line 126) |
a0c0a00f | 11889 | * ]]: Conditional Constructs. |
74091dd4 | 11890 | (line 126) |
a0c0a00f CR |
11891 | * {: Command Grouping. (line 21) |
11892 | * }: Command Grouping. (line 21) | |
11893 | * case: Conditional Constructs. | |
11894 | (line 28) | |
11895 | * do: Looping Constructs. (line 12) | |
11896 | * done: Looping Constructs. (line 12) | |
11897 | * elif: Conditional Constructs. | |
11898 | (line 7) | |
11899 | * else: Conditional Constructs. | |
11900 | (line 7) | |
11901 | * esac: Conditional Constructs. | |
11902 | (line 28) | |
11903 | * fi: Conditional Constructs. | |
11904 | (line 7) | |
11905 | * for: Looping Constructs. (line 32) | |
11906 | * function: Shell Functions. (line 13) | |
11907 | * if: Conditional Constructs. | |
11908 | (line 7) | |
11909 | * in: Conditional Constructs. | |
11910 | (line 28) | |
11911 | * select: Conditional Constructs. | |
74091dd4 | 11912 | (line 84) |
a0c0a00f CR |
11913 | * then: Conditional Constructs. |
11914 | (line 7) | |
11915 | * time: Pipelines. (line 9) | |
11916 | * until: Looping Constructs. (line 12) | |
11917 | * while: Looping Constructs. (line 22) | |
11918 | ||
11919 | \1f | |
11920 | File: bash.info, Node: Variable Index, Next: Function Index, Prev: Reserved Word Index, Up: Indexes | |
11921 | ||
11922 | D.3 Parameter and Variable Index | |
11923 | ================================ | |
11924 | ||
11925 | \0\b[index\0\b] | |
11926 | * Menu: | |
11927 | ||
74091dd4 | 11928 | * !: Special Parameters. (line 55) |
d233b485 CR |
11929 | * #: Special Parameters. (line 39) |
11930 | * $: Special Parameters. (line 51) | |
74091dd4 | 11931 | * $!: Special Parameters. (line 56) |
d233b485 CR |
11932 | * $#: Special Parameters. (line 40) |
11933 | * $$: Special Parameters. (line 52) | |
a0c0a00f | 11934 | * $*: Special Parameters. (line 10) |
d233b485 | 11935 | * $-: Special Parameters. (line 47) |
74091dd4 | 11936 | * $0: Special Parameters. (line 61) |
d233b485 | 11937 | * $?: Special Parameters. (line 43) |
a0c0a00f | 11938 | * $@: Special Parameters. (line 23) |
8868edaf | 11939 | * $_: Bash Variables. (line 14) |
a0c0a00f | 11940 | * *: Special Parameters. (line 9) |
d233b485 | 11941 | * -: Special Parameters. (line 46) |
74091dd4 | 11942 | * 0: Special Parameters. (line 60) |
d233b485 | 11943 | * ?: Special Parameters. (line 42) |
a0c0a00f | 11944 | * @: Special Parameters. (line 22) |
8868edaf | 11945 | * _: Bash Variables. (line 13) |
74091dd4 CR |
11946 | * active-region-end-color: Readline Init File Syntax. |
11947 | (line 51) | |
11948 | * active-region-start-color: Readline Init File Syntax. | |
11949 | (line 38) | |
a0c0a00f CR |
11950 | * auto_resume: Job Control Variables. |
11951 | (line 6) | |
8868edaf CR |
11952 | * BASH: Bash Variables. (line 23) |
11953 | * BASHOPTS: Bash Variables. (line 26) | |
11954 | * BASHPID: Bash Variables. (line 35) | |
11955 | * BASH_ALIASES: Bash Variables. (line 42) | |
11956 | * BASH_ARGC: Bash Variables. (line 51) | |
11957 | * BASH_ARGV: Bash Variables. (line 64) | |
11958 | * BASH_ARGV0: Bash Variables. (line 76) | |
11959 | * BASH_CMDS: Bash Variables. (line 84) | |
11960 | * BASH_COMMAND: Bash Variables. (line 93) | |
11961 | * BASH_COMPAT: Bash Variables. (line 100) | |
11962 | * BASH_ENV: Bash Variables. (line 116) | |
11963 | * BASH_EXECUTION_STRING: Bash Variables. (line 122) | |
11964 | * BASH_LINENO: Bash Variables. (line 125) | |
11965 | * BASH_LOADABLES_PATH: Bash Variables. (line 133) | |
11966 | * BASH_REMATCH: Bash Variables. (line 137) | |
11967 | * BASH_SOURCE: Bash Variables. (line 145) | |
11968 | * BASH_SUBSHELL: Bash Variables. (line 152) | |
11969 | * BASH_VERSINFO: Bash Variables. (line 158) | |
11970 | * BASH_VERSION: Bash Variables. (line 181) | |
11971 | * BASH_XTRACEFD: Bash Variables. (line 184) | |
a0c0a00f | 11972 | * bell-style: Readline Init File Syntax. |
74091dd4 | 11973 | (line 64) |
a0c0a00f | 11974 | * bind-tty-special-chars: Readline Init File Syntax. |
74091dd4 | 11975 | (line 71) |
a0c0a00f | 11976 | * blink-matching-paren: Readline Init File Syntax. |
74091dd4 | 11977 | (line 76) |
a0c0a00f CR |
11978 | * CDPATH: Bourne Shell Variables. |
11979 | (line 9) | |
8868edaf | 11980 | * CHILD_MAX: Bash Variables. (line 195) |
a0c0a00f | 11981 | * colored-completion-prefix: Readline Init File Syntax. |
74091dd4 | 11982 | (line 81) |
a0c0a00f | 11983 | * colored-stats: Readline Init File Syntax. |
74091dd4 | 11984 | (line 91) |
8868edaf | 11985 | * COLUMNS: Bash Variables. (line 202) |
a0c0a00f | 11986 | * comment-begin: Readline Init File Syntax. |
74091dd4 | 11987 | (line 97) |
a0c0a00f | 11988 | * completion-display-width: Readline Init File Syntax. |
74091dd4 | 11989 | (line 102) |
a0c0a00f | 11990 | * completion-ignore-case: Readline Init File Syntax. |
74091dd4 | 11991 | (line 109) |
a0c0a00f | 11992 | * completion-map-case: Readline Init File Syntax. |
74091dd4 | 11993 | (line 114) |
a0c0a00f | 11994 | * completion-prefix-display-length: Readline Init File Syntax. |
74091dd4 | 11995 | (line 120) |
a0c0a00f | 11996 | * completion-query-items: Readline Init File Syntax. |
74091dd4 | 11997 | (line 127) |
8868edaf CR |
11998 | * COMPREPLY: Bash Variables. (line 254) |
11999 | * COMP_CWORD: Bash Variables. (line 208) | |
12000 | * COMP_KEY: Bash Variables. (line 237) | |
12001 | * COMP_LINE: Bash Variables. (line 214) | |
12002 | * COMP_POINT: Bash Variables. (line 219) | |
12003 | * COMP_TYPE: Bash Variables. (line 227) | |
12004 | * COMP_WORDBREAKS: Bash Variables. (line 241) | |
12005 | * COMP_WORDS: Bash Variables. (line 247) | |
a0c0a00f | 12006 | * convert-meta: Readline Init File Syntax. |
74091dd4 | 12007 | (line 138) |
8868edaf CR |
12008 | * COPROC: Bash Variables. (line 260) |
12009 | * DIRSTACK: Bash Variables. (line 264) | |
a0c0a00f | 12010 | * disable-completion: Readline Init File Syntax. |
74091dd4 | 12011 | (line 148) |
a0c0a00f | 12012 | * echo-control-characters: Readline Init File Syntax. |
74091dd4 | 12013 | (line 153) |
a0c0a00f | 12014 | * editing-mode: Readline Init File Syntax. |
74091dd4 | 12015 | (line 158) |
8868edaf | 12016 | * EMACS: Bash Variables. (line 274) |
a0c0a00f | 12017 | * emacs-mode-string: Readline Init File Syntax. |
74091dd4 CR |
12018 | (line 164) |
12019 | * enable-active-region: Readline Init File Syntax. | |
12020 | (line 174) | |
a0c0a00f | 12021 | * enable-bracketed-paste: Readline Init File Syntax. |
74091dd4 | 12022 | (line 187) |
a0c0a00f | 12023 | * enable-keypad: Readline Init File Syntax. |
74091dd4 | 12024 | (line 196) |
8868edaf CR |
12025 | * ENV: Bash Variables. (line 279) |
12026 | * EPOCHREALTIME: Bash Variables. (line 284) | |
12027 | * EPOCHSECONDS: Bash Variables. (line 292) | |
12028 | * EUID: Bash Variables. (line 299) | |
12029 | * EXECIGNORE: Bash Variables. (line 303) | |
a0c0a00f | 12030 | * expand-tilde: Readline Init File Syntax. |
74091dd4 | 12031 | (line 207) |
8868edaf CR |
12032 | * FCEDIT: Bash Variables. (line 316) |
12033 | * FIGNORE: Bash Variables. (line 320) | |
12034 | * FUNCNAME: Bash Variables. (line 326) | |
12035 | * FUNCNEST: Bash Variables. (line 343) | |
12036 | * GLOBIGNORE: Bash Variables. (line 348) | |
12037 | * GROUPS: Bash Variables. (line 355) | |
12038 | * histchars: Bash Variables. (line 361) | |
12039 | * HISTCMD: Bash Variables. (line 376) | |
12040 | * HISTCONTROL: Bash Variables. (line 382) | |
12041 | * HISTFILE: Bash Variables. (line 398) | |
12042 | * HISTFILESIZE: Bash Variables. (line 402) | |
12043 | * HISTIGNORE: Bash Variables. (line 413) | |
a0c0a00f | 12044 | * history-preserve-point: Readline Init File Syntax. |
74091dd4 | 12045 | (line 211) |
a0c0a00f | 12046 | * history-size: Readline Init File Syntax. |
74091dd4 | 12047 | (line 217) |
8868edaf CR |
12048 | * HISTSIZE: Bash Variables. (line 433) |
12049 | * HISTTIMEFORMAT: Bash Variables. (line 440) | |
a0c0a00f CR |
12050 | * HOME: Bourne Shell Variables. |
12051 | (line 13) | |
12052 | * horizontal-scroll-mode: Readline Init File Syntax. | |
74091dd4 | 12053 | (line 226) |
8868edaf CR |
12054 | * HOSTFILE: Bash Variables. (line 448) |
12055 | * HOSTNAME: Bash Variables. (line 459) | |
12056 | * HOSTTYPE: Bash Variables. (line 462) | |
a0c0a00f CR |
12057 | * IFS: Bourne Shell Variables. |
12058 | (line 18) | |
8868edaf | 12059 | * IGNOREEOF: Bash Variables. (line 465) |
a0c0a00f | 12060 | * input-meta: Readline Init File Syntax. |
74091dd4 | 12061 | (line 235) |
8868edaf CR |
12062 | * INPUTRC: Bash Variables. (line 475) |
12063 | * INSIDE_EMACS: Bash Variables. (line 479) | |
a0c0a00f | 12064 | * isearch-terminators: Readline Init File Syntax. |
74091dd4 | 12065 | (line 245) |
a0c0a00f | 12066 | * keymap: Readline Init File Syntax. |
74091dd4 CR |
12067 | (line 252) |
12068 | * LANG: Creating Internationalized Scripts. | |
12069 | (line 51) | |
12070 | * LANG <1>: Bash Variables. (line 485) | |
8868edaf CR |
12071 | * LC_ALL: Bash Variables. (line 489) |
12072 | * LC_COLLATE: Bash Variables. (line 493) | |
12073 | * LC_CTYPE: Bash Variables. (line 500) | |
74091dd4 CR |
12074 | * LC_MESSAGES: Creating Internationalized Scripts. |
12075 | (line 51) | |
8868edaf CR |
12076 | * LC_MESSAGES <1>: Bash Variables. (line 505) |
12077 | * LC_NUMERIC: Bash Variables. (line 509) | |
12078 | * LC_TIME: Bash Variables. (line 513) | |
12079 | * LINENO: Bash Variables. (line 517) | |
12080 | * LINES: Bash Variables. (line 522) | |
12081 | * MACHTYPE: Bash Variables. (line 528) | |
a0c0a00f CR |
12082 | * MAIL: Bourne Shell Variables. |
12083 | (line 22) | |
8868edaf | 12084 | * MAILCHECK: Bash Variables. (line 532) |
a0c0a00f CR |
12085 | * MAILPATH: Bourne Shell Variables. |
12086 | (line 27) | |
8868edaf | 12087 | * MAPFILE: Bash Variables. (line 540) |
a0c0a00f | 12088 | * mark-modified-lines: Readline Init File Syntax. |
74091dd4 | 12089 | (line 282) |
a0c0a00f | 12090 | * mark-symlinked-directories: Readline Init File Syntax. |
74091dd4 | 12091 | (line 287) |
a0c0a00f | 12092 | * match-hidden-files: Readline Init File Syntax. |
74091dd4 | 12093 | (line 292) |
a0c0a00f | 12094 | * menu-complete-display-prefix: Readline Init File Syntax. |
74091dd4 | 12095 | (line 299) |
a0c0a00f | 12096 | * meta-flag: Readline Init File Syntax. |
74091dd4 | 12097 | (line 235) |
8868edaf | 12098 | * OLDPWD: Bash Variables. (line 544) |
a0c0a00f CR |
12099 | * OPTARG: Bourne Shell Variables. |
12100 | (line 34) | |
8868edaf | 12101 | * OPTERR: Bash Variables. (line 547) |
a0c0a00f CR |
12102 | * OPTIND: Bourne Shell Variables. |
12103 | (line 38) | |
8868edaf | 12104 | * OSTYPE: Bash Variables. (line 551) |
a0c0a00f | 12105 | * output-meta: Readline Init File Syntax. |
74091dd4 | 12106 | (line 304) |
a0c0a00f | 12107 | * page-completions: Readline Init File Syntax. |
74091dd4 | 12108 | (line 312) |
a0c0a00f CR |
12109 | * PATH: Bourne Shell Variables. |
12110 | (line 42) | |
8868edaf CR |
12111 | * PIPESTATUS: Bash Variables. (line 554) |
12112 | * POSIXLY_CORRECT: Bash Variables. (line 559) | |
12113 | * PPID: Bash Variables. (line 569) | |
12114 | * PROMPT_COMMAND: Bash Variables. (line 573) | |
12115 | * PROMPT_DIRTRIM: Bash Variables. (line 579) | |
12116 | * PS0: Bash Variables. (line 585) | |
a0c0a00f CR |
12117 | * PS1: Bourne Shell Variables. |
12118 | (line 48) | |
12119 | * PS2: Bourne Shell Variables. | |
12120 | (line 53) | |
8868edaf CR |
12121 | * PS3: Bash Variables. (line 590) |
12122 | * PS4: Bash Variables. (line 595) | |
12123 | * PWD: Bash Variables. (line 603) | |
12124 | * RANDOM: Bash Variables. (line 606) | |
74091dd4 CR |
12125 | * READLINE_ARGUMENT: Bash Variables. (line 612) |
12126 | * READLINE_LINE: Bash Variables. (line 616) | |
12127 | * READLINE_MARK: Bash Variables. (line 620) | |
12128 | * READLINE_POINT: Bash Variables. (line 626) | |
12129 | * REPLY: Bash Variables. (line 630) | |
a0c0a00f | 12130 | * revert-all-at-newline: Readline Init File Syntax. |
74091dd4 CR |
12131 | (line 322) |
12132 | * SECONDS: Bash Variables. (line 633) | |
12133 | * SHELL: Bash Variables. (line 642) | |
12134 | * SHELLOPTS: Bash Variables. (line 647) | |
12135 | * SHLVL: Bash Variables. (line 656) | |
a0c0a00f | 12136 | * show-all-if-ambiguous: Readline Init File Syntax. |
74091dd4 | 12137 | (line 329) |
a0c0a00f | 12138 | * show-all-if-unmodified: Readline Init File Syntax. |
74091dd4 | 12139 | (line 335) |
a0c0a00f | 12140 | * show-mode-in-prompt: Readline Init File Syntax. |
74091dd4 | 12141 | (line 344) |
a0c0a00f | 12142 | * skip-completed-text: Readline Init File Syntax. |
74091dd4 CR |
12143 | (line 350) |
12144 | * SRANDOM: Bash Variables. (line 661) | |
12145 | * TEXTDOMAIN: Creating Internationalized Scripts. | |
12146 | (line 51) | |
12147 | * TEXTDOMAINDIR: Creating Internationalized Scripts. | |
12148 | (line 51) | |
12149 | * TIMEFORMAT: Bash Variables. (line 670) | |
12150 | * TMOUT: Bash Variables. (line 708) | |
12151 | * TMPDIR: Bash Variables. (line 720) | |
12152 | * UID: Bash Variables. (line 724) | |
a0c0a00f | 12153 | * vi-cmd-mode-string: Readline Init File Syntax. |
74091dd4 | 12154 | (line 363) |
a0c0a00f | 12155 | * vi-ins-mode-string: Readline Init File Syntax. |
74091dd4 | 12156 | (line 374) |
a0c0a00f | 12157 | * visible-stats: Readline Init File Syntax. |
74091dd4 | 12158 | (line 385) |
a0c0a00f CR |
12159 | |
12160 | \1f | |
12161 | File: bash.info, Node: Function Index, Next: Concept Index, Prev: Variable Index, Up: Indexes | |
12162 | ||
12163 | D.4 Function Index | |
12164 | ================== | |
12165 | ||
12166 | \0\b[index\0\b] | |
12167 | * Menu: | |
12168 | ||
12169 | * abort (C-g): Miscellaneous Commands. | |
12170 | (line 10) | |
12171 | * accept-line (Newline or Return): Commands For History. | |
12172 | (line 6) | |
12173 | * alias-expand-line (): Miscellaneous Commands. | |
74091dd4 | 12174 | (line 131) |
a0c0a00f CR |
12175 | * backward-char (C-b): Commands For Moving. (line 15) |
12176 | * backward-delete-char (Rubout): Commands For Text. (line 17) | |
12177 | * backward-kill-line (C-x Rubout): Commands For Killing. | |
8868edaf | 12178 | (line 11) |
a0c0a00f | 12179 | * backward-kill-word (M-<DEL>): Commands For Killing. |
8868edaf | 12180 | (line 28) |
a0c0a00f CR |
12181 | * backward-word (M-b): Commands For Moving. (line 22) |
12182 | * beginning-of-history (M-<): Commands For History. | |
12183 | (line 20) | |
12184 | * beginning-of-line (C-a): Commands For Moving. (line 6) | |
12185 | * bracketed-paste-begin (): Commands For Text. (line 33) | |
12186 | * call-last-kbd-macro (C-x e): Keyboard Macros. (line 13) | |
8868edaf | 12187 | * capitalize-word (M-c): Commands For Text. (line 66) |
a0c0a00f | 12188 | * character-search (C-]): Miscellaneous Commands. |
d233b485 | 12189 | (line 42) |
a0c0a00f | 12190 | * character-search-backward (M-C-]): Miscellaneous Commands. |
d233b485 | 12191 | (line 47) |
8868edaf CR |
12192 | * clear-display (M-C-l): Commands For Moving. (line 48) |
12193 | * clear-screen (C-l): Commands For Moving. (line 53) | |
a0c0a00f CR |
12194 | * complete (<TAB>): Commands For Completion. |
12195 | (line 6) | |
12196 | * complete-command (M-!): Commands For Completion. | |
12197 | (line 80) | |
12198 | * complete-filename (M-/): Commands For Completion. | |
12199 | (line 49) | |
12200 | * complete-hostname (M-@): Commands For Completion. | |
12201 | (line 72) | |
12202 | * complete-into-braces (M-{): Commands For Completion. | |
12203 | (line 100) | |
12204 | * complete-username (M-~): Commands For Completion. | |
12205 | (line 56) | |
12206 | * complete-variable (M-$): Commands For Completion. | |
12207 | (line 64) | |
12208 | * copy-backward-word (): Commands For Killing. | |
8868edaf | 12209 | (line 69) |
a0c0a00f | 12210 | * copy-forward-word (): Commands For Killing. |
8868edaf | 12211 | (line 74) |
a0c0a00f | 12212 | * copy-region-as-kill (): Commands For Killing. |
8868edaf | 12213 | (line 65) |
a0c0a00f CR |
12214 | * dabbrev-expand (): Commands For Completion. |
12215 | (line 95) | |
12216 | * delete-char (C-d): Commands For Text. (line 12) | |
12217 | * delete-char-or-list (): Commands For Completion. | |
12218 | (line 43) | |
12219 | * delete-horizontal-space (): Commands For Killing. | |
8868edaf | 12220 | (line 57) |
a0c0a00f CR |
12221 | * digit-argument (M-0, M-1, ... M--): Numeric Arguments. (line 6) |
12222 | * display-shell-version (C-x C-v): Miscellaneous Commands. | |
74091dd4 | 12223 | (line 116) |
d233b485 | 12224 | * do-lowercase-version (M-A, M-B, M-X, ...): Miscellaneous Commands. |
a0c0a00f | 12225 | (line 14) |
8868edaf | 12226 | * downcase-word (M-l): Commands For Text. (line 62) |
a0c0a00f | 12227 | * dump-functions (): Miscellaneous Commands. |
d233b485 | 12228 | (line 74) |
a0c0a00f | 12229 | * dump-macros (): Miscellaneous Commands. |
d233b485 | 12230 | (line 86) |
a0c0a00f | 12231 | * dump-variables (): Miscellaneous Commands. |
d233b485 | 12232 | (line 80) |
a0c0a00f CR |
12233 | * dynamic-complete-history (M-<TAB>): Commands For Completion. |
12234 | (line 90) | |
d233b485 | 12235 | * edit-and-execute-command (C-x C-e): Miscellaneous Commands. |
74091dd4 | 12236 | (line 140) |
a0c0a00f CR |
12237 | * end-kbd-macro (C-x )): Keyboard Macros. (line 9) |
12238 | * end-of-file (usually C-d): Commands For Text. (line 6) | |
12239 | * end-of-history (M->): Commands For History. | |
12240 | (line 23) | |
12241 | * end-of-line (C-e): Commands For Moving. (line 9) | |
12242 | * exchange-point-and-mark (C-x C-x): Miscellaneous Commands. | |
d233b485 | 12243 | (line 37) |
74091dd4 CR |
12244 | * fetch-history (): Commands For History. |
12245 | (line 103) | |
a0c0a00f CR |
12246 | * forward-backward-delete-char (): Commands For Text. (line 21) |
12247 | * forward-char (C-f): Commands For Moving. (line 12) | |
12248 | * forward-search-history (C-s): Commands For History. | |
8868edaf | 12249 | (line 33) |
a0c0a00f CR |
12250 | * forward-word (M-f): Commands For Moving. (line 18) |
12251 | * glob-complete-word (M-g): Miscellaneous Commands. | |
d233b485 | 12252 | (line 98) |
74091dd4 | 12253 | * glob-expand-word (C-x *): Miscellaneous Commands. |
d233b485 | 12254 | (line 104) |
74091dd4 CR |
12255 | * glob-list-expansions (C-x g): Miscellaneous Commands. |
12256 | (line 110) | |
a0c0a00f | 12257 | * history-and-alias-expand-line (): Miscellaneous Commands. |
74091dd4 | 12258 | (line 134) |
a0c0a00f | 12259 | * history-expand-line (M-^): Miscellaneous Commands. |
74091dd4 | 12260 | (line 124) |
a0c0a00f | 12261 | * history-search-backward (): Commands For History. |
8868edaf | 12262 | (line 57) |
a0c0a00f | 12263 | * history-search-forward (): Commands For History. |
8868edaf | 12264 | (line 51) |
d233b485 | 12265 | * history-substring-search-backward (): Commands For History. |
8868edaf | 12266 | (line 69) |
d233b485 | 12267 | * history-substring-search-forward (): Commands For History. |
8868edaf | 12268 | (line 63) |
a0c0a00f | 12269 | * insert-comment (M-#): Miscellaneous Commands. |
d233b485 | 12270 | (line 61) |
a0c0a00f CR |
12271 | * insert-completions (M-*): Commands For Completion. |
12272 | (line 22) | |
12273 | * insert-last-argument (M-. or M-_): Miscellaneous Commands. | |
74091dd4 | 12274 | (line 137) |
a0c0a00f CR |
12275 | * kill-line (C-k): Commands For Killing. |
12276 | (line 6) | |
12277 | * kill-region (): Commands For Killing. | |
8868edaf | 12278 | (line 61) |
a0c0a00f | 12279 | * kill-whole-line (): Commands For Killing. |
a0c0a00f | 12280 | (line 19) |
8868edaf CR |
12281 | * kill-word (M-d): Commands For Killing. |
12282 | (line 23) | |
a0c0a00f | 12283 | * magic-space (): Miscellaneous Commands. |
74091dd4 | 12284 | (line 127) |
a0c0a00f CR |
12285 | * menu-complete (): Commands For Completion. |
12286 | (line 26) | |
12287 | * menu-complete-backward (): Commands For Completion. | |
12288 | (line 38) | |
12289 | * next-history (C-n): Commands For History. | |
12290 | (line 17) | |
d233b485 | 12291 | * next-screen-line (): Commands For Moving. (line 41) |
a0c0a00f | 12292 | * non-incremental-forward-search-history (M-n): Commands For History. |
8868edaf | 12293 | (line 45) |
a0c0a00f | 12294 | * non-incremental-reverse-search-history (M-p): Commands For History. |
8868edaf CR |
12295 | (line 39) |
12296 | * operate-and-get-next (C-o): Commands For History. | |
12297 | (line 96) | |
12298 | * overwrite-mode (): Commands For Text. (line 70) | |
a0c0a00f CR |
12299 | * possible-command-completions (C-x !): Commands For Completion. |
12300 | (line 86) | |
12301 | * possible-completions (M-?): Commands For Completion. | |
12302 | (line 15) | |
12303 | * possible-filename-completions (C-x /): Commands For Completion. | |
12304 | (line 52) | |
12305 | * possible-hostname-completions (C-x @): Commands For Completion. | |
12306 | (line 76) | |
12307 | * possible-username-completions (C-x ~): Commands For Completion. | |
12308 | (line 60) | |
12309 | * possible-variable-completions (C-x $): Commands For Completion. | |
12310 | (line 68) | |
12311 | * prefix-meta (<ESC>): Miscellaneous Commands. | |
d233b485 | 12312 | (line 19) |
a0c0a00f CR |
12313 | * previous-history (C-p): Commands For History. |
12314 | (line 13) | |
d233b485 | 12315 | * previous-screen-line (): Commands For Moving. (line 34) |
a0c0a00f CR |
12316 | * print-last-kbd-macro (): Keyboard Macros. (line 17) |
12317 | * quoted-insert (C-q or C-v): Commands For Text. (line 26) | |
12318 | * re-read-init-file (C-x C-r): Miscellaneous Commands. | |
12319 | (line 6) | |
8868edaf | 12320 | * redraw-current-line (): Commands For Moving. (line 57) |
a0c0a00f CR |
12321 | * reverse-search-history (C-r): Commands For History. |
12322 | (line 27) | |
12323 | * revert-line (M-r): Miscellaneous Commands. | |
d233b485 | 12324 | (line 26) |
a0c0a00f CR |
12325 | * self-insert (a, b, A, 1, !, ...): Commands For Text. (line 30) |
12326 | * set-mark (C-@): Miscellaneous Commands. | |
d233b485 | 12327 | (line 33) |
a0c0a00f | 12328 | * shell-backward-kill-word (): Commands For Killing. |
8868edaf CR |
12329 | (line 37) |
12330 | * shell-backward-word (M-C-b): Commands For Moving. (line 30) | |
a0c0a00f | 12331 | * shell-expand-line (M-C-e): Miscellaneous Commands. |
74091dd4 | 12332 | (line 119) |
8868edaf CR |
12333 | * shell-forward-word (M-C-f): Commands For Moving. (line 26) |
12334 | * shell-kill-word (M-C-d): Commands For Killing. | |
12335 | (line 32) | |
12336 | * shell-transpose-words (M-C-t): Commands For Killing. | |
12337 | (line 41) | |
a0c0a00f | 12338 | * skip-csi-sequence (): Miscellaneous Commands. |
d233b485 | 12339 | (line 52) |
74091dd4 CR |
12340 | * spell-correct-word (C-x s): Miscellaneous Commands. |
12341 | (line 92) | |
a0c0a00f CR |
12342 | * start-kbd-macro (C-x (): Keyboard Macros. (line 6) |
12343 | * tilde-expand (M-&): Miscellaneous Commands. | |
d233b485 | 12344 | (line 30) |
8868edaf CR |
12345 | * transpose-chars (C-t): Commands For Text. (line 47) |
12346 | * transpose-words (M-t): Commands For Text. (line 53) | |
a0c0a00f | 12347 | * undo (C-_ or C-x C-u): Miscellaneous Commands. |
d233b485 | 12348 | (line 23) |
a0c0a00f CR |
12349 | * universal-argument (): Numeric Arguments. (line 10) |
12350 | * unix-filename-rubout (): Commands For Killing. | |
8868edaf | 12351 | (line 52) |
a0c0a00f | 12352 | * unix-line-discard (C-u): Commands For Killing. |
8868edaf | 12353 | (line 16) |
a0c0a00f | 12354 | * unix-word-rubout (C-w): Commands For Killing. |
8868edaf CR |
12355 | (line 48) |
12356 | * upcase-word (M-u): Commands For Text. (line 58) | |
a0c0a00f | 12357 | * yank (C-y): Commands For Killing. |
8868edaf | 12358 | (line 79) |
a0c0a00f | 12359 | * yank-last-arg (M-. or M-_): Commands For History. |
8868edaf | 12360 | (line 84) |
a0c0a00f | 12361 | * yank-nth-arg (M-C-y): Commands For History. |
8868edaf | 12362 | (line 75) |
a0c0a00f | 12363 | * yank-pop (M-y): Commands For Killing. |
8868edaf | 12364 | (line 82) |
a0c0a00f CR |
12365 | |
12366 | \1f | |
12367 | File: bash.info, Node: Concept Index, Prev: Function Index, Up: Indexes | |
12368 | ||
12369 | D.5 Concept Index | |
12370 | ================= | |
12371 | ||
12372 | \0\b[index\0\b] | |
12373 | * Menu: | |
12374 | ||
12375 | * alias expansion: Aliases. (line 6) | |
12376 | * arithmetic evaluation: Shell Arithmetic. (line 6) | |
12377 | * arithmetic expansion: Arithmetic Expansion. | |
12378 | (line 6) | |
12379 | * arithmetic, shell: Shell Arithmetic. (line 6) | |
12380 | * arrays: Arrays. (line 6) | |
12381 | * background: Job Control Basics. (line 6) | |
12382 | * Bash configuration: Basic Installation. (line 6) | |
12383 | * Bash installation: Basic Installation. (line 6) | |
12384 | * Bourne shell: Basic Shell Features. | |
12385 | (line 6) | |
12386 | * brace expansion: Brace Expansion. (line 6) | |
12387 | * builtin: Definitions. (line 17) | |
12388 | * command editing: Readline Bare Essentials. | |
12389 | (line 6) | |
12390 | * command execution: Command Search and Execution. | |
12391 | (line 6) | |
12392 | * command expansion: Simple Command Expansion. | |
12393 | (line 6) | |
12394 | * command history: Bash History Facilities. | |
12395 | (line 6) | |
12396 | * command search: Command Search and Execution. | |
12397 | (line 6) | |
12398 | * command substitution: Command Substitution. | |
12399 | (line 6) | |
12400 | * command timing: Pipelines. (line 9) | |
12401 | * commands, compound: Compound Commands. (line 6) | |
12402 | * commands, conditional: Conditional Constructs. | |
12403 | (line 6) | |
12404 | * commands, grouping: Command Grouping. (line 6) | |
12405 | * commands, lists: Lists. (line 6) | |
12406 | * commands, looping: Looping Constructs. (line 6) | |
12407 | * commands, pipelines: Pipelines. (line 6) | |
12408 | * commands, shell: Shell Commands. (line 6) | |
12409 | * commands, simple: Simple Commands. (line 6) | |
12410 | * comments, shell: Comments. (line 6) | |
8868edaf CR |
12411 | * Compatibility Level: Shell Compatibility Mode. |
12412 | (line 6) | |
12413 | * Compatibility Mode: Shell Compatibility Mode. | |
12414 | (line 6) | |
a0c0a00f CR |
12415 | * completion builtins: Programmable Completion Builtins. |
12416 | (line 6) | |
12417 | * configuration: Basic Installation. (line 6) | |
12418 | * control operator: Definitions. (line 21) | |
12419 | * coprocess: Coprocesses. (line 6) | |
12420 | * directory stack: The Directory Stack. (line 6) | |
12421 | * editing command lines: Readline Bare Essentials. | |
12422 | (line 6) | |
12423 | * environment: Environment. (line 6) | |
12424 | * evaluation, arithmetic: Shell Arithmetic. (line 6) | |
12425 | * event designators: Event Designators. (line 6) | |
12426 | * execution environment: Command Execution Environment. | |
12427 | (line 6) | |
12428 | * exit status: Definitions. (line 26) | |
12429 | * exit status <1>: Exit Status. (line 6) | |
12430 | * expansion: Shell Expansions. (line 6) | |
12431 | * expansion, arithmetic: Arithmetic Expansion. | |
12432 | (line 6) | |
12433 | * expansion, brace: Brace Expansion. (line 6) | |
12434 | * expansion, filename: Filename Expansion. (line 9) | |
12435 | * expansion, parameter: Shell Parameter Expansion. | |
12436 | (line 6) | |
12437 | * expansion, pathname: Filename Expansion. (line 9) | |
12438 | * expansion, tilde: Tilde Expansion. (line 6) | |
12439 | * expressions, arithmetic: Shell Arithmetic. (line 6) | |
12440 | * expressions, conditional: Bash Conditional Expressions. | |
12441 | (line 6) | |
12442 | * field: Definitions. (line 30) | |
12443 | * filename: Definitions. (line 35) | |
12444 | * filename expansion: Filename Expansion. (line 9) | |
12445 | * foreground: Job Control Basics. (line 6) | |
12446 | * functions, shell: Shell Functions. (line 6) | |
12447 | * history builtins: Bash History Builtins. | |
12448 | (line 6) | |
12449 | * history events: Event Designators. (line 8) | |
12450 | * history expansion: History Interaction. (line 6) | |
12451 | * history list: Bash History Facilities. | |
12452 | (line 6) | |
12453 | * History, how to use: A Programmable Completion Example. | |
d233b485 | 12454 | (line 113) |
a0c0a00f CR |
12455 | * identifier: Definitions. (line 51) |
12456 | * initialization file, readline: Readline Init File. (line 6) | |
12457 | * installation: Basic Installation. (line 6) | |
12458 | * interaction, readline: Readline Interaction. | |
12459 | (line 6) | |
d233b485 | 12460 | * interactive shell: Invoking Bash. (line 131) |
a0c0a00f CR |
12461 | * interactive shell <1>: Interactive Shells. (line 6) |
12462 | * internationalization: Locale Translation. (line 6) | |
74091dd4 CR |
12463 | * internationalized scripts: Creating Internationalized Scripts. |
12464 | (line 3) | |
a0c0a00f CR |
12465 | * job: Definitions. (line 38) |
12466 | * job control: Definitions. (line 42) | |
12467 | * job control <1>: Job Control Basics. (line 6) | |
12468 | * kill ring: Readline Killing Commands. | |
12469 | (line 18) | |
12470 | * killing text: Readline Killing Commands. | |
12471 | (line 6) | |
12472 | * localization: Locale Translation. (line 6) | |
d233b485 | 12473 | * login shell: Invoking Bash. (line 128) |
a0c0a00f CR |
12474 | * matching, pattern: Pattern Matching. (line 6) |
12475 | * metacharacter: Definitions. (line 46) | |
12476 | * name: Definitions. (line 51) | |
12477 | * native languages: Locale Translation. (line 6) | |
12478 | * notation, readline: Readline Bare Essentials. | |
12479 | (line 6) | |
12480 | * operator, shell: Definitions. (line 57) | |
12481 | * parameter expansion: Shell Parameter Expansion. | |
12482 | (line 6) | |
12483 | * parameters: Shell Parameters. (line 6) | |
12484 | * parameters, positional: Positional Parameters. | |
12485 | (line 6) | |
12486 | * parameters, special: Special Parameters. (line 6) | |
12487 | * pathname expansion: Filename Expansion. (line 9) | |
12488 | * pattern matching: Pattern Matching. (line 6) | |
12489 | * pipeline: Pipelines. (line 6) | |
12490 | * POSIX: Definitions. (line 9) | |
12491 | * POSIX Mode: Bash POSIX Mode. (line 6) | |
12492 | * process group: Definitions. (line 62) | |
12493 | * process group ID: Definitions. (line 66) | |
12494 | * process substitution: Process Substitution. | |
12495 | (line 6) | |
12496 | * programmable completion: Programmable Completion. | |
12497 | (line 6) | |
12498 | * prompting: Controlling the Prompt. | |
12499 | (line 6) | |
12500 | * quoting: Quoting. (line 6) | |
12501 | * quoting, ANSI: ANSI-C Quoting. (line 6) | |
12502 | * Readline, how to use: Job Control Variables. | |
12503 | (line 23) | |
12504 | * redirection: Redirections. (line 6) | |
12505 | * reserved word: Definitions. (line 70) | |
8868edaf | 12506 | * reserved words: Reserved Words. (line 6) |
a0c0a00f CR |
12507 | * restricted shell: The Restricted Shell. |
12508 | (line 6) | |
12509 | * return status: Definitions. (line 75) | |
12510 | * shell arithmetic: Shell Arithmetic. (line 6) | |
12511 | * shell function: Shell Functions. (line 6) | |
12512 | * shell script: Shell Scripts. (line 6) | |
12513 | * shell variable: Shell Parameters. (line 6) | |
12514 | * shell, interactive: Interactive Shells. (line 6) | |
12515 | * signal: Definitions. (line 78) | |
12516 | * signal handling: Signals. (line 6) | |
12517 | * special builtin: Definitions. (line 82) | |
12518 | * special builtin <1>: Special Builtins. (line 6) | |
12519 | * startup files: Bash Startup Files. (line 6) | |
74091dd4 CR |
12520 | * string translations: Creating Internationalized Scripts. |
12521 | (line 3) | |
a0c0a00f CR |
12522 | * suspending jobs: Job Control Basics. (line 6) |
12523 | * tilde expansion: Tilde Expansion. (line 6) | |
12524 | * token: Definitions. (line 86) | |
12525 | * translation, native languages: Locale Translation. (line 6) | |
12526 | * variable, shell: Shell Parameters. (line 6) | |
12527 | * variables, readline: Readline Init File Syntax. | |
12528 | (line 37) | |
12529 | * word: Definitions. (line 90) | |
12530 | * word splitting: Word Splitting. (line 6) | |
12531 | * yanking text: Readline Killing Commands. | |
12532 | (line 6) | |
12533 | ||
12534 | ||
12535 | \1f | |
12536 | Tag Table: | |
74091dd4 CR |
12537 | Node: Top\7f896 |
12538 | Node: Introduction\7f2815 | |
12539 | Node: What is Bash?\7f3028 | |
12540 | Node: What is a shell?\7f4139 | |
12541 | Node: Definitions\7f6674 | |
12542 | Node: Basic Shell Features\7f9622 | |
12543 | Node: Shell Syntax\7f10838 | |
12544 | Node: Shell Operation\7f11861 | |
12545 | Node: Quoting\7f13151 | |
12546 | Node: Escape Character\7f14452 | |
12547 | Node: Single Quotes\7f14934 | |
12548 | Node: Double Quotes\7f15279 | |
12549 | Node: ANSI-C Quoting\7f16554 | |
12550 | Node: Locale Translation\7f17861 | |
12551 | Node: Creating Internationalized Scripts\7f19169 | |
12552 | Node: Comments\7f23283 | |
12553 | Node: Shell Commands\7f23898 | |
12554 | Node: Reserved Words\7f24833 | |
12555 | Node: Simple Commands\7f25586 | |
12556 | Node: Pipelines\7f26237 | |
12557 | Node: Lists\7f29233 | |
12558 | Node: Compound Commands\7f31025 | |
12559 | Node: Looping Constructs\7f32034 | |
12560 | Node: Conditional Constructs\7f34526 | |
12561 | Node: Command Grouping\7f49011 | |
12562 | Node: Coprocesses\7f50486 | |
12563 | Node: GNU Parallel\7f53146 | |
12564 | Node: Shell Functions\7f54060 | |
12565 | Node: Shell Parameters\7f61942 | |
12566 | Node: Positional Parameters\7f66327 | |
12567 | Node: Special Parameters\7f67226 | |
12568 | Node: Shell Expansions\7f70437 | |
12569 | Node: Brace Expansion\7f72561 | |
12570 | Node: Tilde Expansion\7f75292 | |
12571 | Node: Shell Parameter Expansion\7f77910 | |
12572 | Node: Command Substitution\7f96258 | |
12573 | Node: Arithmetic Expansion\7f97610 | |
12574 | Node: Process Substitution\7f98575 | |
12575 | Node: Word Splitting\7f99692 | |
12576 | Node: Filename Expansion\7f101633 | |
12577 | Node: Pattern Matching\7f104379 | |
12578 | Node: Quote Removal\7f109378 | |
12579 | Node: Redirections\7f109670 | |
12580 | Node: Executing Commands\7f119327 | |
12581 | Node: Simple Command Expansion\7f119994 | |
12582 | Node: Command Search and Execution\7f122101 | |
12583 | Node: Command Execution Environment\7f124476 | |
12584 | Node: Environment\7f127508 | |
12585 | Node: Exit Status\7f129168 | |
12586 | Node: Signals\7f130949 | |
12587 | Node: Shell Scripts\7f134395 | |
12588 | Node: Shell Builtin Commands\7f137419 | |
12589 | Node: Bourne Shell Builtins\7f139454 | |
12590 | Node: Bash Builtins\7f160917 | |
12591 | Node: Modifying Shell Behavior\7f191770 | |
12592 | Node: The Set Builtin\7f192112 | |
12593 | Node: The Shopt Builtin\7f202710 | |
12594 | Node: Special Builtins\7f218619 | |
12595 | Node: Shell Variables\7f219595 | |
12596 | Node: Bourne Shell Variables\7f220029 | |
12597 | Node: Bash Variables\7f222130 | |
12598 | Node: Bash Features\7f254942 | |
12599 | Node: Invoking Bash\7f255952 | |
12600 | Node: Bash Startup Files\7f261962 | |
12601 | Node: Interactive Shells\7f267090 | |
12602 | Node: What is an Interactive Shell?\7f267498 | |
12603 | Node: Is this Shell Interactive?\7f268144 | |
12604 | Node: Interactive Shell Behavior\7f268956 | |
12605 | Node: Bash Conditional Expressions\7f272582 | |
12606 | Node: Shell Arithmetic\7f277221 | |
12607 | Node: Aliases\7f280162 | |
12608 | Node: Arrays\7f282772 | |
12609 | Node: The Directory Stack\7f289160 | |
12610 | Node: Directory Stack Builtins\7f289941 | |
12611 | Node: Controlling the Prompt\7f294198 | |
12612 | Node: The Restricted Shell\7f297160 | |
12613 | Node: Bash POSIX Mode\7f299767 | |
12614 | Node: Shell Compatibility Mode\7f311682 | |
12615 | Node: Job Control\7f320246 | |
12616 | Node: Job Control Basics\7f320703 | |
12617 | Node: Job Control Builtins\7f325702 | |
12618 | Node: Job Control Variables\7f331494 | |
12619 | Node: Command Line Editing\7f332647 | |
12620 | Node: Introduction and Notation\7f334315 | |
12621 | Node: Readline Interaction\7f335935 | |
12622 | Node: Readline Bare Essentials\7f337123 | |
12623 | Node: Readline Movement Commands\7f338909 | |
12624 | Node: Readline Killing Commands\7f339866 | |
12625 | Node: Readline Arguments\7f341784 | |
12626 | Node: Searching\7f342825 | |
12627 | Node: Readline Init File\7f345008 | |
12628 | Node: Readline Init File Syntax\7f346266 | |
12629 | Node: Conditional Init Constructs\7f369849 | |
12630 | Node: Sample Init File\7f374042 | |
12631 | Node: Bindable Readline Commands\7f377163 | |
12632 | Node: Commands For Moving\7f378364 | |
12633 | Node: Commands For History\7f380412 | |
12634 | Node: Commands For Text\7f385403 | |
12635 | Node: Commands For Killing\7f389049 | |
12636 | Node: Numeric Arguments\7f392079 | |
12637 | Node: Commands For Completion\7f393215 | |
12638 | Node: Keyboard Macros\7f397403 | |
12639 | Node: Miscellaneous Commands\7f398088 | |
12640 | Node: Readline vi Mode\7f404030 | |
12641 | Node: Programmable Completion\7f404934 | |
12642 | Node: Programmable Completion Builtins\7f412711 | |
12643 | Node: A Programmable Completion Example\7f423460 | |
12644 | Node: Using History Interactively\7f428705 | |
12645 | Node: Bash History Facilities\7f429386 | |
12646 | Node: Bash History Builtins\7f432388 | |
12647 | Node: History Interaction\7f437409 | |
12648 | Node: Event Designators\7f441026 | |
12649 | Node: Word Designators\7f442377 | |
12650 | Node: Modifiers\7f444134 | |
12651 | Node: Installing Bash\7f445939 | |
12652 | Node: Basic Installation\7f447073 | |
12653 | Node: Compilers and Options\7f450792 | |
12654 | Node: Compiling For Multiple Architectures\7f451530 | |
12655 | Node: Installation Names\7f453219 | |
12656 | Node: Specifying the System Type\7f455325 | |
12657 | Node: Sharing Defaults\7f456039 | |
12658 | Node: Operation Controls\7f456709 | |
12659 | Node: Optional Features\7f457664 | |
12660 | Node: Reporting Bugs\7f468880 | |
12661 | Node: Major Differences From The Bourne Shell\7f470152 | |
12662 | Node: GNU Free Documentation License\7f486998 | |
12663 | Node: Indexes\7f512172 | |
12664 | Node: Builtin Index\7f512623 | |
12665 | Node: Reserved Word Index\7f519447 | |
12666 | Node: Variable Index\7f521892 | |
12667 | Node: Function Index\7f538663 | |
12668 | Node: Concept Index\7f552444 | |
a0c0a00f CR |
12669 | \1f |
12670 | End Tag Table | |
8868edaf CR |
12671 | |
12672 | \1f | |
12673 | Local Variables: | |
12674 | coding: utf-8 | |
12675 | End: |