]>
Commit | Line | Data |
---|---|---|
54a5fbe1 | 1 | This is bashref.info, produced by makeinfo version 6.0 from |
8a0829e9 | 2 | bashref.texi. |
e8ce775d | 3 | |
8a0829e9 | 4 | This text is a brief description of the features that are present in the |
690150f9 | 5 | Bash shell (version 4.4, 8 February 2016). |
d3a24ed2 | 6 | |
690150f9 | 7 | This is Edition 4.4, last updated 8 February 2016, of 'The GNU Bash |
8a0829e9 | 8 | Reference Manual', for 'Bash', Version 4.4. |
d3a24ed2 | 9 | |
690150f9 | 10 | Copyright (C) 1988-2016 Free Software Foundation, Inc. |
d3a24ed2 CR |
11 | |
12 | Permission is granted to copy, distribute and/or modify this | |
13 | document under the terms of the GNU Free Documentation License, | |
c302751c | 14 | Version 1.3 or any later version published by the Free Software |
9f178efb CR |
15 | Foundation; with no Invariant Sections, no Front-Cover Texts, and |
16 | no Back-Cover Texts. A copy of the license is included in the | |
17 | section entitled "GNU Free Documentation License". | |
d3a24ed2 | 18 | INFO-DIR-SECTION Basics |
e8ce775d | 19 | START-INFO-DIR-ENTRY |
cce855bc | 20 | * Bash: (bash). The GNU Bourne-Again SHell. |
e8ce775d | 21 | END-INFO-DIR-ENTRY |
ccc6cda3 | 22 | |
ccc6cda3 JA |
23 | \1f |
24 | File: bashref.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) | |
25 | ||
26 | Bash Features | |
27 | ************* | |
28 | ||
8a0829e9 | 29 | This text is a brief description of the features that are present in the |
690150f9 | 30 | Bash shell (version 4.4, 8 February 2016). The Bash home page is |
8a0829e9 | 31 | <http://www.gnu.org/software/bash/>. |
ccc6cda3 | 32 | |
690150f9 | 33 | This is Edition 4.4, last updated 8 February 2016, of 'The GNU Bash |
8a0829e9 | 34 | Reference Manual', for 'Bash', Version 4.4. |
ccc6cda3 JA |
35 | |
36 | Bash contains features that appear in other popular shells, and some | |
37 | features that only appear in Bash. Some of the shells that Bash has | |
8a0829e9 CR |
38 | borrowed concepts from are the Bourne Shell ('sh'), the Korn Shell |
39 | ('ksh'), and the C-shell ('csh' and its successor, 'tcsh'). The | |
9f178efb CR |
40 | following menu breaks the features up into categories, noting which |
41 | features were inspired by other shells and which are specific to Bash. | |
ccc6cda3 JA |
42 | |
43 | This manual is meant as a brief introduction to features found in | |
44 | Bash. The Bash manual page should be used as the definitive reference | |
45 | on shell behavior. | |
46 | ||
47 | * Menu: | |
48 | ||
49 | * Introduction:: An introduction to the shell. | |
ccc6cda3 JA |
50 | * Definitions:: Some definitions used in the rest of this |
51 | manual. | |
ccc6cda3 | 52 | * Basic Shell Features:: The shell "building blocks". |
bb70624e | 53 | * Shell Builtin Commands:: Commands that are a part of the shell. |
bb70624e | 54 | * Shell Variables:: Variables used or set by Bash. |
ccc6cda3 | 55 | * Bash Features:: Features found only in Bash. |
1c72c0cd CR |
56 | * Job Control:: What job control is and how Bash allows you |
57 | to use it. | |
ccc6cda3 JA |
58 | * Command Line Editing:: Chapter describing the command line |
59 | editing features. | |
c2a47ea9 | 60 | * Using History Interactively:: Command History Expansion |
ccc6cda3 | 61 | * Installing Bash:: How to build and install Bash on your system. |
ccc6cda3 | 62 | * Reporting Bugs:: How to report bugs in Bash. |
bb70624e JA |
63 | * Major Differences From The Bourne Shell:: A terse list of the differences |
64 | between Bash and historical | |
65 | versions of /bin/sh. | |
c2a47ea9 | 66 | * GNU Free Documentation License:: Copying and sharing this documentation. |
d3ad40de | 67 | * Indexes:: Various indexes for this manual. |
ccc6cda3 JA |
68 | |
69 | \1f | |
8a0829e9 | 70 | File: bashref.info, Node: Introduction, Next: Definitions, Up: Top |
ccc6cda3 | 71 | |
37c41ab1 CR |
72 | 1 Introduction |
73 | ************** | |
ccc6cda3 JA |
74 | |
75 | * Menu: | |
76 | ||
77 | * What is Bash?:: A short description of Bash. | |
ccc6cda3 JA |
78 | * What is a shell?:: A brief introduction to shells. |
79 | ||
80 | \1f | |
81 | File: bashref.info, Node: What is Bash?, Next: What is a shell?, Up: Introduction | |
82 | ||
37c41ab1 CR |
83 | 1.1 What is Bash? |
84 | ================= | |
ccc6cda3 | 85 | |
37c41ab1 | 86 | Bash is the shell, or command language interpreter, for the GNU |
8a0829e9 | 87 | operating system. The name is an acronym for the 'Bourne-Again SHell', |
bb70624e | 88 | a pun on Stephen Bourne, the author of the direct ancestor of the |
8a0829e9 CR |
89 | current Unix shell 'sh', which appeared in the Seventh Edition Bell Labs |
90 | Research version of Unix. | |
ccc6cda3 | 91 | |
8a0829e9 CR |
92 | Bash is largely compatible with 'sh' and incorporates useful features |
93 | from the Korn shell 'ksh' and the C shell 'csh'. It is intended to be a | |
94 | conformant implementation of the IEEE POSIX Shell and Tools portion of | |
95 | the IEEE POSIX specification (IEEE Standard 1003.1). It offers | |
96 | functional improvements over 'sh' for both interactive and programming | |
97 | use. | |
ccc6cda3 | 98 | |
bb70624e | 99 | While the GNU operating system provides other shells, including a |
8a0829e9 | 100 | version of 'csh', Bash is the default shell. Like other GNU software, |
bb70624e JA |
101 | Bash is quite portable. It currently runs on nearly every version of |
102 | Unix and a few other operating systems - independently-supported ports | |
d3a24ed2 | 103 | exist for MS-DOS, OS/2, and Windows platforms. |
ccc6cda3 JA |
104 | |
105 | \1f | |
106 | File: bashref.info, Node: What is a shell?, Prev: What is Bash?, Up: Introduction | |
107 | ||
37c41ab1 CR |
108 | 1.2 What is a shell? |
109 | ==================== | |
ccc6cda3 | 110 | |
8a0829e9 CR |
111 | At its base, a shell is simply a macro processor that executes commands. |
112 | The term macro processor means functionality where text and symbols are | |
113 | expanded to create larger expressions. | |
d3a24ed2 CR |
114 | |
115 | A Unix shell is both a command interpreter and a programming | |
116 | language. As a command interpreter, the shell provides the user | |
117 | interface to the rich set of GNU utilities. The programming language | |
d3ad40de | 118 | features allow these utilities to be combined. Files containing |
cce855bc | 119 | commands can be created, and become commands themselves. These new |
bb70624e | 120 | commands have the same status as system commands in directories such as |
8a0829e9 | 121 | '/bin', allowing users or groups to establish custom environments to |
d3a24ed2 CR |
122 | automate their common tasks. |
123 | ||
124 | Shells may be used interactively or non-interactively. In | |
125 | interactive mode, they accept input typed from the keyboard. When | |
126 | executing non-interactively, shells execute commands read from a file. | |
ccc6cda3 | 127 | |
bb70624e | 128 | A shell allows execution of GNU commands, both synchronously and |
cce855bc JA |
129 | asynchronously. The shell waits for synchronous commands to complete |
130 | before accepting more input; asynchronous commands continue to execute | |
131 | in parallel with the shell while it reads and executes additional | |
132 | commands. The "redirection" constructs permit fine-grained control of | |
bb70624e | 133 | the input and output of those commands. Moreover, the shell allows |
d3a24ed2 | 134 | control over the contents of commands' environments. |
bb70624e JA |
135 | |
136 | Shells also provide a small set of built-in commands ("builtins") | |
137 | implementing functionality impossible or inconvenient to obtain via | |
8a0829e9 | 138 | separate utilities. For example, 'cd', 'break', 'continue', and 'exec' |
74d0116b | 139 | cannot be implemented outside of the shell because they directly |
8a0829e9 | 140 | manipulate the shell itself. The 'history', 'getopts', 'kill', or 'pwd' |
74d0116b CR |
141 | builtins, among others, could be implemented in separate utilities, but |
142 | they are more convenient to use as builtin commands. All of the shell | |
143 | builtins are described in subsequent sections. | |
ccc6cda3 JA |
144 | |
145 | While executing commands is essential, most of the power (and | |
146 | complexity) of shells is due to their embedded programming languages. | |
8a0829e9 CR |
147 | Like any high-level language, the shell provides variables, flow control |
148 | constructs, quoting, and functions. | |
ccc6cda3 | 149 | |
bb70624e JA |
150 | Shells offer features geared specifically for interactive use rather |
151 | than to augment the programming language. These interactive features | |
d3a24ed2 CR |
152 | include job control, command line editing, command history and aliases. |
153 | Each of these features is described in this manual. | |
ccc6cda3 JA |
154 | |
155 | \1f | |
156 | File: bashref.info, Node: Definitions, Next: Basic Shell Features, Prev: Introduction, Up: Top | |
157 | ||
37c41ab1 CR |
158 | 2 Definitions |
159 | ************* | |
ccc6cda3 | 160 | |
37c41ab1 | 161 | These definitions are used throughout the remainder of this manual. |
ccc6cda3 | 162 | |
8a0829e9 CR |
163 | 'POSIX' |
164 | A family of open system standards based on Unix. Bash is primarily | |
165 | concerned with the Shell and Utilities portion of the POSIX 1003.1 | |
166 | standard. | |
ccc6cda3 | 167 | |
8a0829e9 | 168 | 'blank' |
ccc6cda3 JA |
169 | A space or tab character. |
170 | ||
8a0829e9 | 171 | 'builtin' |
ccc6cda3 JA |
172 | A command that is implemented internally by the shell itself, |
173 | rather than by an executable program somewhere in the file system. | |
174 | ||
8a0829e9 CR |
175 | 'control operator' |
176 | A 'token' that performs a control function. It is a 'newline' or | |
690150f9 CR |
177 | one of the following: '||', '&&', '&', ';', ';;', ';&', ';;&', '|', |
178 | '|&', '(', or ')'. | |
ccc6cda3 | 179 | |
8a0829e9 | 180 | 'exit status' |
f73dda09 JA |
181 | The value returned by a command to its caller. The value is |
182 | restricted to eight bits, so the maximum value is 255. | |
ccc6cda3 | 183 | |
8a0829e9 | 184 | 'field' |
ccc6cda3 | 185 | A unit of text that is the result of one of the shell expansions. |
8a0829e9 CR |
186 | After expansion, when executing a command, the resulting fields are |
187 | used as the command name and arguments. | |
ccc6cda3 | 188 | |
8a0829e9 | 189 | 'filename' |
ccc6cda3 JA |
190 | A string of characters used to identify a file. |
191 | ||
8a0829e9 | 192 | 'job' |
ccc6cda3 JA |
193 | A set of processes comprising a pipeline, and any processes |
194 | descended from it, that are all in the same process group. | |
195 | ||
8a0829e9 | 196 | 'job control' |
d166f048 JA |
197 | A mechanism by which users can selectively stop (suspend) and |
198 | restart (resume) execution of processes. | |
ccc6cda3 | 199 | |
8a0829e9 | 200 | 'metacharacter' |
ccc6cda3 | 201 | A character that, when unquoted, separates words. A metacharacter |
54a5fbe1 CR |
202 | is a 'space', 'tab', 'newline', or one of the following characters: |
203 | '|', '&', ';', '(', ')', '<', or '>'. | |
ccc6cda3 | 204 | |
8a0829e9 CR |
205 | 'name' |
206 | A 'word' consisting solely of letters, numbers, and underscores, | |
207 | and beginning with a letter or underscore. 'Name's are used as | |
ccc6cda3 | 208 | shell variable and function names. Also referred to as an |
8a0829e9 | 209 | 'identifier'. |
ccc6cda3 | 210 | |
8a0829e9 CR |
211 | 'operator' |
212 | A 'control operator' or a 'redirection operator'. *Note | |
a9fac3b2 | 213 | Redirections::, for a list of redirection operators. Operators |
8a0829e9 | 214 | contain at least one unquoted 'metacharacter'. |
ccc6cda3 | 215 | |
8a0829e9 | 216 | 'process group' |
ccc6cda3 JA |
217 | A collection of related processes each having the same process |
218 | group ID. | |
219 | ||
8a0829e9 CR |
220 | 'process group ID' |
221 | A unique identifier that represents a 'process group' during its | |
ccc6cda3 JA |
222 | lifetime. |
223 | ||
8a0829e9 CR |
224 | 'reserved word' |
225 | A 'word' that has a special meaning to the shell. Most reserved | |
226 | words introduce shell flow control constructs, such as 'for' and | |
227 | 'while'. | |
ccc6cda3 | 228 | |
8a0829e9 CR |
229 | 'return status' |
230 | A synonym for 'exit status'. | |
ccc6cda3 | 231 | |
8a0829e9 | 232 | 'signal' |
bb70624e | 233 | A mechanism by which a process may be notified by the kernel of an |
ccc6cda3 JA |
234 | event occurring in the system. |
235 | ||
8a0829e9 | 236 | 'special builtin' |
ccc6cda3 | 237 | A shell builtin command that has been classified as special by the |
ac18b312 | 238 | POSIX standard. |
ccc6cda3 | 239 | |
8a0829e9 CR |
240 | 'token' |
241 | A sequence of characters considered a single unit by the shell. It | |
242 | is either a 'word' or an 'operator'. | |
ccc6cda3 | 243 | |
8a0829e9 CR |
244 | 'word' |
245 | A sequence of characters treated as a unit by the shell. Words may | |
246 | not include unquoted 'metacharacters'. | |
ccc6cda3 JA |
247 | |
248 | \1f | |
bb70624e | 249 | File: bashref.info, Node: Basic Shell Features, Next: Shell Builtin Commands, Prev: Definitions, Up: Top |
ccc6cda3 | 250 | |
37c41ab1 CR |
251 | 3 Basic Shell Features |
252 | ********************** | |
ccc6cda3 | 253 | |
8a0829e9 CR |
254 | Bash is an acronym for 'Bourne-Again SHell'. The Bourne shell is the |
255 | traditional Unix shell originally written by Stephen Bourne. All of the | |
256 | Bourne shell builtin commands are available in Bash, The rules for | |
37c41ab1 | 257 | evaluation and quoting are taken from the POSIX specification for the |
8a0829e9 | 258 | 'standard' Unix shell. |
ccc6cda3 | 259 | |
8a0829e9 | 260 | This chapter briefly summarizes the shell's 'building blocks': |
ccc6cda3 JA |
261 | commands, control structures, shell functions, shell parameters, shell |
262 | expansions, redirections, which are a way to direct input and output | |
263 | from and to named files, and how the shell executes commands. | |
264 | ||
265 | * Menu: | |
266 | ||
267 | * Shell Syntax:: What your input means to the shell. | |
cce855bc | 268 | * Shell Commands:: The types of commands you can use. |
ccc6cda3 | 269 | * Shell Functions:: Grouping commands by name. |
d3a24ed2 CR |
270 | * Shell Parameters:: How the shell stores values. |
271 | * Shell Expansions:: How Bash expands parameters and the various | |
ccc6cda3 JA |
272 | expansions available. |
273 | * Redirections:: A way to control where input and output go. | |
274 | * Executing Commands:: What happens when you run a command. | |
275 | * Shell Scripts:: Executing files of shell commands. | |
276 | ||
277 | \1f | |
cce855bc | 278 | File: bashref.info, Node: Shell Syntax, Next: Shell Commands, Up: Basic Shell Features |
ccc6cda3 | 279 | |
37c41ab1 CR |
280 | 3.1 Shell Syntax |
281 | ================ | |
ccc6cda3 JA |
282 | |
283 | * Menu: | |
284 | ||
285 | * Shell Operation:: The basic operation of the shell. | |
ccc6cda3 | 286 | * Quoting:: How to remove the special meaning from characters. |
ccc6cda3 JA |
287 | * Comments:: How to specify comments. |
288 | ||
8a0829e9 | 289 | When the shell reads input, it proceeds through a sequence of |
bb70624e | 290 | operations. If the input indicates the beginning of a comment, the |
8a0829e9 | 291 | shell ignores the comment symbol ('#'), and the rest of that line. |
bb70624e | 292 | |
8a0829e9 | 293 | Otherwise, roughly speaking, the shell reads its input and divides |
bb70624e JA |
294 | the input into words and operators, employing the quoting rules to |
295 | select which meanings to assign various words and characters. | |
296 | ||
297 | The shell then parses these tokens into commands and other | |
298 | constructs, removes the special meaning of certain words or characters, | |
299 | expands others, redirects input and output as needed, executes the | |
300 | specified command, waits for the command's exit status, and makes that | |
301 | exit status available for further inspection or processing. | |
302 | ||
ccc6cda3 JA |
303 | \1f |
304 | File: bashref.info, Node: Shell Operation, Next: Quoting, Up: Shell Syntax | |
305 | ||
37c41ab1 CR |
306 | 3.1.1 Shell Operation |
307 | --------------------- | |
ccc6cda3 | 308 | |
37c41ab1 | 309 | The following is a brief description of the shell's operation when it |
ccc6cda3 JA |
310 | reads and executes a command. Basically, the shell does the following: |
311 | ||
28ef6c31 | 312 | 1. Reads its input from a file (*note Shell Scripts::), from a string |
8a0829e9 | 313 | supplied as an argument to the '-c' invocation option (*note |
28ef6c31 | 314 | Invoking Bash::), or from the user's terminal. |
ccc6cda3 JA |
315 | |
316 | 2. Breaks the input into words and operators, obeying the quoting | |
6a8fd0ed | 317 | rules described in *note Quoting::. These tokens are separated by |
8a0829e9 CR |
318 | 'metacharacters'. Alias expansion is performed by this step (*note |
319 | Aliases::). | |
ccc6cda3 | 320 | |
cce855bc | 321 | 3. Parses the tokens into simple and compound commands (*note Shell |
28ef6c31 | 322 | Commands::). |
ccc6cda3 | 323 | |
28ef6c31 | 324 | 4. Performs the various shell expansions (*note Shell Expansions::), |
ccc6cda3 | 325 | breaking the expanded tokens into lists of filenames (*note |
28ef6c31 | 326 | Filename Expansion::) and commands and arguments. |
ccc6cda3 | 327 | |
28ef6c31 | 328 | 5. Performs any necessary redirections (*note Redirections::) and |
ccc6cda3 JA |
329 | removes the redirection operators and their operands from the |
330 | argument list. | |
331 | ||
28ef6c31 | 332 | 6. Executes the command (*note Executing Commands::). |
ccc6cda3 JA |
333 | |
334 | 7. Optionally waits for the command to complete and collects its exit | |
28ef6c31 | 335 | status (*note Exit Status::). |
ccc6cda3 | 336 | |
ccc6cda3 JA |
337 | \1f |
338 | File: bashref.info, Node: Quoting, Next: Comments, Prev: Shell Operation, Up: Shell Syntax | |
339 | ||
37c41ab1 CR |
340 | 3.1.2 Quoting |
341 | ------------- | |
ccc6cda3 JA |
342 | |
343 | * Menu: | |
344 | ||
345 | * Escape Character:: How to remove the special meaning from a single | |
346 | character. | |
347 | * Single Quotes:: How to inhibit all interpretation of a sequence | |
348 | of characters. | |
349 | * Double Quotes:: How to suppress most of the interpretation of a | |
350 | sequence of characters. | |
351 | * ANSI-C Quoting:: How to expand ANSI-C sequences in quoted strings. | |
ccc6cda3 JA |
352 | * Locale Translation:: How to translate strings into different languages. |
353 | ||
8a0829e9 CR |
354 | Quoting is used to remove the special meaning of certain characters or |
355 | words to the shell. Quoting can be used to disable special treatment | |
356 | for special characters, to prevent reserved words from being recognized | |
357 | as such, and to prevent parameter expansion. | |
ccc6cda3 | 358 | |
28ef6c31 | 359 | Each of the shell metacharacters (*note Definitions::) has special |
cce855bc | 360 | meaning to the shell and must be quoted if it is to represent itself. |
01ed5ba4 | 361 | When the command history expansion facilities are being used (*note |
8a0829e9 | 362 | History Interaction::), the HISTORY EXPANSION character, usually '!', |
01ed5ba4 CR |
363 | must be quoted to prevent history expansion. *Note Bash History |
364 | Facilities::, for more details concerning history expansion. | |
d3a24ed2 CR |
365 | |
366 | There are three quoting mechanisms: the ESCAPE CHARACTER, single | |
367 | quotes, and double quotes. | |
ccc6cda3 JA |
368 | |
369 | \1f | |
370 | File: bashref.info, Node: Escape Character, Next: Single Quotes, Up: Quoting | |
371 | ||
37c41ab1 CR |
372 | 3.1.2.1 Escape Character |
373 | ........................ | |
ccc6cda3 | 374 | |
8a0829e9 CR |
375 | A non-quoted backslash '\' is the Bash escape character. It preserves |
376 | the literal value of the next character that follows, with the exception | |
377 | of 'newline'. If a '\newline' pair appears, and the backslash itself is | |
378 | not quoted, the '\newline' is treated as a line continuation (that is, | |
379 | it is removed from the input stream and effectively ignored). | |
ccc6cda3 JA |
380 | |
381 | \1f | |
382 | File: bashref.info, Node: Single Quotes, Next: Double Quotes, Prev: Escape Character, Up: Quoting | |
383 | ||
37c41ab1 CR |
384 | 3.1.2.2 Single Quotes |
385 | ..................... | |
ccc6cda3 | 386 | |
8a0829e9 | 387 | Enclosing characters in single quotes (''') preserves the literal value |
37c41ab1 | 388 | of each character within the quotes. A single quote may not occur |
bb70624e | 389 | between single quotes, even when preceded by a backslash. |
ccc6cda3 JA |
390 | |
391 | \1f | |
392 | File: bashref.info, Node: Double Quotes, Next: ANSI-C Quoting, Prev: Single Quotes, Up: Quoting | |
393 | ||
37c41ab1 CR |
394 | 3.1.2.3 Double Quotes |
395 | ..................... | |
ccc6cda3 | 396 | |
8a0829e9 CR |
397 | Enclosing characters in double quotes ('"') preserves the literal value |
398 | of all characters within the quotes, with the exception of '$', '`', | |
690150f9 CR |
399 | '\', and, when history expansion is enabled, '!'. When the shell is in |
400 | POSIX mode (*note Bash POSIX Mode::), the '!' has no special meaning | |
401 | within double quotes, even when history expansion is enabled. The | |
402 | characters '$' and '`' retain their special meaning within double quotes | |
403 | (*note Shell Expansions::). The backslash retains its special meaning | |
404 | only when followed by one of the following characters: '$', '`', '"', | |
405 | '\', or 'newline'. Within double quotes, backslashes that are followed | |
406 | by one of these characters are removed. Backslashes preceding | |
407 | characters without a special meaning are left unmodified. A double | |
408 | quote may be quoted within double quotes by preceding it with a | |
409 | backslash. If enabled, history expansion will be performed unless an | |
410 | '!' appearing in double quotes is escaped using a backslash. The | |
411 | backslash preceding the '!' is not removed. | |
ccc6cda3 | 412 | |
8a0829e9 | 413 | The special parameters '*' and '@' have special meaning when in |
28ef6c31 | 414 | double quotes (*note Shell Parameter Expansion::). |
ccc6cda3 JA |
415 | |
416 | \1f | |
417 | File: bashref.info, Node: ANSI-C Quoting, Next: Locale Translation, Prev: Double Quotes, Up: Quoting | |
418 | ||
37c41ab1 CR |
419 | 3.1.2.4 ANSI-C Quoting |
420 | ...................... | |
ccc6cda3 | 421 | |
8a0829e9 | 422 | Words of the form '$'STRING'' are treated specially. The word expands |
37c41ab1 CR |
423 | to STRING, with backslash-escaped characters replaced as specified by |
424 | the ANSI C standard. Backslash escape sequences, if present, are | |
425 | decoded as follows: | |
ccc6cda3 | 426 | |
8a0829e9 | 427 | '\a' |
ccc6cda3 | 428 | alert (bell) |
8a0829e9 | 429 | '\b' |
ccc6cda3 | 430 | backspace |
8a0829e9 CR |
431 | '\e' |
432 | '\E' | |
ccc6cda3 | 433 | an escape character (not ANSI C) |
8a0829e9 | 434 | '\f' |
ccc6cda3 | 435 | form feed |
8a0829e9 | 436 | '\n' |
ccc6cda3 | 437 | newline |
8a0829e9 | 438 | '\r' |
ccc6cda3 | 439 | carriage return |
8a0829e9 | 440 | '\t' |
ccc6cda3 | 441 | horizontal tab |
8a0829e9 | 442 | '\v' |
ccc6cda3 | 443 | vertical tab |
8a0829e9 | 444 | '\\' |
ccc6cda3 | 445 | backslash |
8a0829e9 | 446 | '\'' |
bb70624e | 447 | single quote |
8a0829e9 | 448 | '\"' |
984a1947 | 449 | double quote |
54a5fbe1 CR |
450 | '\?' |
451 | question mark | |
8a0829e9 | 452 | '\NNN' |
f73dda09 | 453 | the eight-bit character whose value is the octal value NNN (one to |
cce855bc | 454 | three digits) |
8a0829e9 | 455 | '\xHH' |
f73dda09 JA |
456 | the eight-bit character whose value is the hexadecimal value HH |
457 | (one or two hex digits) | |
8a0829e9 | 458 | '\uHHHH' |
220537f2 CR |
459 | the Unicode (ISO/IEC 10646) character whose value is the |
460 | hexadecimal value HHHH (one to four hex digits) | |
8a0829e9 | 461 | '\UHHHHHHHH' |
220537f2 CR |
462 | the Unicode (ISO/IEC 10646) character whose value is the |
463 | hexadecimal value HHHHHHHH (one to eight hex digits) | |
8a0829e9 | 464 | '\cX' |
7117c2d2 JA |
465 | a control-X character |
466 | ||
8a0829e9 CR |
467 | The expanded result is single-quoted, as if the dollar sign had not been |
468 | present. | |
ccc6cda3 JA |
469 | |
470 | \1f | |
471 | File: bashref.info, Node: Locale Translation, Prev: ANSI-C Quoting, Up: Quoting | |
472 | ||
37c41ab1 CR |
473 | 3.1.2.5 Locale-Specific Translation |
474 | ................................... | |
ccc6cda3 | 475 | |
8a0829e9 CR |
476 | A double-quoted string preceded by a dollar sign ('$') will cause the |
477 | string to be translated according to the current locale. If the current | |
478 | locale is 'C' or 'POSIX', the dollar sign is ignored. If the string is | |
479 | translated and replaced, the replacement is double-quoted. | |
ccc6cda3 | 480 | |
8a0829e9 | 481 | Some systems use the message catalog selected by the 'LC_MESSAGES' |
28ef6c31 | 482 | shell variable. Others create the name of the message catalog from the |
8a0829e9 CR |
483 | value of the 'TEXTDOMAIN' shell variable, possibly adding a suffix of |
484 | '.mo'. If you use the 'TEXTDOMAIN' variable, you may need to set the | |
485 | 'TEXTDOMAINDIR' variable to the location of the message catalog files. | |
f73dda09 | 486 | Still others use both variables in this fashion: |
8a0829e9 | 487 | 'TEXTDOMAINDIR'/'LC_MESSAGES'/LC_MESSAGES/'TEXTDOMAIN'.mo. |
28ef6c31 | 488 | |
ccc6cda3 JA |
489 | \1f |
490 | File: bashref.info, Node: Comments, Prev: Quoting, Up: Shell Syntax | |
491 | ||
37c41ab1 CR |
492 | 3.1.3 Comments |
493 | -------------- | |
ccc6cda3 | 494 | |
37c41ab1 | 495 | In a non-interactive shell, or an interactive shell in which the |
8a0829e9 CR |
496 | 'interactive_comments' option to the 'shopt' builtin is enabled (*note |
497 | The Shopt Builtin::), a word beginning with '#' causes that word and all | |
498 | remaining characters on that line to be ignored. An interactive shell | |
499 | without the 'interactive_comments' option enabled does not allow | |
500 | comments. The 'interactive_comments' option is on by default in | |
bb70624e JA |
501 | interactive shells. *Note Interactive Shells::, for a description of |
502 | what makes a shell interactive. | |
cce855bc JA |
503 | |
504 | \1f | |
505 | File: bashref.info, Node: Shell Commands, Next: Shell Functions, Prev: Shell Syntax, Up: Basic Shell Features | |
506 | ||
37c41ab1 CR |
507 | 3.2 Shell Commands |
508 | ================== | |
cce855bc | 509 | |
8a0829e9 | 510 | A simple shell command such as 'echo a b c' consists of the command |
bb70624e JA |
511 | itself followed by arguments, separated by spaces. |
512 | ||
513 | More complex shell commands are composed of simple commands arranged | |
514 | together in a variety of ways: in a pipeline in which the output of one | |
515 | command becomes the input of a second, in a loop or conditional | |
516 | construct, or in some other grouping. | |
517 | ||
cce855bc JA |
518 | * Menu: |
519 | ||
520 | * Simple Commands:: The most common type of command. | |
521 | * Pipelines:: Connecting the input and output of several | |
522 | commands. | |
523 | * Lists:: How to execute commands sequentially. | |
d3a24ed2 | 524 | * Compound Commands:: Shell commands for control flow. |
8e1a6eaa | 525 | * Coprocesses:: Two-way communication between commands. |
220537f2 | 526 | * GNU Parallel:: Running commands in parallel. |
ccc6cda3 JA |
527 | |
528 | \1f | |
cce855bc | 529 | File: bashref.info, Node: Simple Commands, Next: Pipelines, Up: Shell Commands |
ccc6cda3 | 530 | |
37c41ab1 CR |
531 | 3.2.1 Simple Commands |
532 | --------------------- | |
ccc6cda3 | 533 | |
37c41ab1 | 534 | A simple command is the kind of command encountered most often. It's |
8a0829e9 CR |
535 | just a sequence of words separated by 'blank's, terminated by one of the |
536 | shell's control operators (*note Definitions::). The first word | |
537 | generally specifies a command to be executed, with the rest of the words | |
538 | being that command's arguments. | |
ccc6cda3 | 539 | |
28ef6c31 | 540 | The return status (*note Exit Status::) of a simple command is its |
8a0829e9 CR |
541 | exit status as provided by the POSIX 1003.1 'waitpid' function, or 128+N |
542 | if the command was terminated by signal N. | |
ccc6cda3 JA |
543 | |
544 | \1f | |
cce855bc | 545 | File: bashref.info, Node: Pipelines, Next: Lists, Prev: Simple Commands, Up: Shell Commands |
ccc6cda3 | 546 | |
37c41ab1 CR |
547 | 3.2.2 Pipelines |
548 | --------------- | |
ccc6cda3 | 549 | |
8a0829e9 CR |
550 | A 'pipeline' is a sequence of one or more commands separated by one of |
551 | the control operators '|' or '|&'. | |
ccc6cda3 JA |
552 | |
553 | The format for a pipeline is | |
122f603c | 554 | [time [-p]] [!] COMMAND1 [ | or |& COMMAND2 ] ... |
ccc6cda3 | 555 | |
f73dda09 | 556 | The output of each command in the pipeline is connected via a pipe to |
8a0829e9 CR |
557 | the input of the next command. That is, each command reads the previous |
558 | command's output. This connection is performed before any redirections | |
559 | specified by the command. | |
ed35cb4a | 560 | |
8a0829e9 | 561 | If '|&' is used, COMMAND1's standard error, in addition to its |
1101193a | 562 | standard output, is connected to COMMAND2's standard input through the |
8a0829e9 | 563 | pipe; it is shorthand for '2>&1 |'. This implicit redirection of the |
1101193a CR |
564 | standard error to the standard output is performed after any |
565 | redirections specified by the command. | |
ccc6cda3 | 566 | |
8a0829e9 | 567 | The reserved word 'time' causes timing statistics to be printed for |
cce855bc JA |
568 | the pipeline once it finishes. The statistics currently consist of |
569 | elapsed (wall-clock) time and user and system time consumed by the | |
8a0829e9 | 570 | command's execution. The '-p' option changes the output format to that |
9ec5ed66 | 571 | specified by POSIX. When the shell is in POSIX mode (*note Bash POSIX |
8a0829e9 CR |
572 | Mode::), it does not recognize 'time' as a reserved word if the next |
573 | token begins with a '-'. The 'TIMEFORMAT' variable may be set to a | |
9ec5ed66 CR |
574 | format string that specifies how the timing information should be |
575 | displayed. *Note Bash Variables::, for a description of the available | |
8a0829e9 CR |
576 | formats. The use of 'time' as a reserved word permits the timing of |
577 | shell builtins, shell functions, and pipelines. An external 'time' | |
9ec5ed66 | 578 | command cannot time these easily. |
cce855bc | 579 | |
8a0829e9 CR |
580 | When the shell is in POSIX mode (*note Bash POSIX Mode::), 'time' may |
581 | be followed by a newline. In this case, the shell displays the total | |
582 | user and system time consumed by the shell and its children. The | |
583 | 'TIMEFORMAT' variable may be used to specify the format of the time | |
220537f2 CR |
584 | information. |
585 | ||
28ef6c31 | 586 | If the pipeline is not executed asynchronously (*note Lists::), the |
cce855bc | 587 | shell waits for all commands in the pipeline to complete. |
ccc6cda3 | 588 | |
cce855bc | 589 | Each command in a pipeline is executed in its own subshell (*note |
28ef6c31 | 590 | Command Execution Environment::). The exit status of a pipeline is the |
8a0829e9 CR |
591 | exit status of the last command in the pipeline, unless the 'pipefail' |
592 | option is enabled (*note The Set Builtin::). If 'pipefail' is enabled, | |
5e13499c CR |
593 | the pipeline's return status is the value of the last (rightmost) |
594 | command to exit with a non-zero status, or zero if all commands exit | |
8a0829e9 | 595 | successfully. If the reserved word '!' precedes the pipeline, the exit |
5e13499c CR |
596 | status is the logical negation of the exit status as described above. |
597 | The shell waits for all commands in the pipeline to terminate before | |
598 | returning a value. | |
ccc6cda3 JA |
599 | |
600 | \1f | |
d3a24ed2 | 601 | File: bashref.info, Node: Lists, Next: Compound Commands, Prev: Pipelines, Up: Shell Commands |
ccc6cda3 | 602 | |
37c41ab1 CR |
603 | 3.2.3 Lists of Commands |
604 | ----------------------- | |
ccc6cda3 | 605 | |
8a0829e9 CR |
606 | A 'list' is a sequence of one or more pipelines separated by one of the |
607 | operators ';', '&', '&&', or '||', and optionally terminated by one of | |
608 | ';', '&', or a 'newline'. | |
ccc6cda3 | 609 | |
8a0829e9 CR |
610 | Of these list operators, '&&' and '||' have equal precedence, |
611 | followed by ';' and '&', which have equal precedence. | |
ccc6cda3 | 612 | |
8a0829e9 | 613 | A sequence of one or more newlines may appear in a 'list' to delimit |
7117c2d2 JA |
614 | commands, equivalent to a semicolon. |
615 | ||
8a0829e9 | 616 | If a command is terminated by the control operator '&', the shell |
cce855bc JA |
617 | executes the command asynchronously in a subshell. This is known as |
618 | executing the command in the BACKGROUND. The shell does not wait for | |
bb70624e | 619 | the command to finish, and the return status is 0 (true). When job |
28ef6c31 | 620 | control is not active (*note Job Control::), the standard input for |
bb70624e | 621 | asynchronous commands, in the absence of any explicit redirections, is |
8a0829e9 | 622 | redirected from '/dev/null'. |
cce855bc | 623 | |
8a0829e9 | 624 | Commands separated by a ';' are executed sequentially; the shell |
cce855bc JA |
625 | waits for each command to terminate in turn. The return status is the |
626 | exit status of the last command executed. | |
ccc6cda3 | 627 | |
6a8fd0ed | 628 | AND and OR lists are sequences of one or more pipelines separated by |
8a0829e9 CR |
629 | the control operators '&&' and '||', respectively. AND and OR lists are |
630 | executed with left associativity. | |
6a8fd0ed CR |
631 | |
632 | An AND list has the form | |
bb70624e | 633 | COMMAND1 && COMMAND2 |
ccc6cda3 | 634 | |
8a0829e9 CR |
635 | COMMAND2 is executed if, and only if, COMMAND1 returns an exit status of |
636 | zero. | |
ccc6cda3 JA |
637 | |
638 | An OR list has the form | |
bb70624e | 639 | COMMAND1 || COMMAND2 |
ccc6cda3 | 640 | |
bb70624e | 641 | COMMAND2 is executed if, and only if, COMMAND1 returns a non-zero exit |
ccc6cda3 JA |
642 | status. |
643 | ||
644 | The return status of AND and OR lists is the exit status of the last | |
645 | command executed in the list. | |
646 | ||
647 | \1f | |
8e1a6eaa | 648 | File: bashref.info, Node: Compound Commands, Next: Coprocesses, Prev: Lists, Up: Shell Commands |
d3a24ed2 | 649 | |
37c41ab1 CR |
650 | 3.2.4 Compound Commands |
651 | ----------------------- | |
d3a24ed2 CR |
652 | |
653 | * Menu: | |
654 | ||
655 | * Looping Constructs:: Shell commands for iterative action. | |
656 | * Conditional Constructs:: Shell commands for conditional execution. | |
657 | * Command Grouping:: Ways to group commands. | |
658 | ||
8a0829e9 CR |
659 | Compound commands are the shell programming constructs. Each construct |
660 | begins with a reserved word or control operator and is terminated by a | |
661 | corresponding reserved word or operator. Any redirections (*note | |
662 | Redirections::) associated with a compound command apply to all commands | |
663 | within that compound command unless explicitly overridden. | |
d3a24ed2 | 664 | |
74d0116b CR |
665 | In most cases a list of commands in a compound command's description |
666 | may be separated from the rest of the command by one or more newlines, | |
667 | and may be followed by a newline in place of a semicolon. | |
668 | ||
d3a24ed2 CR |
669 | Bash provides looping constructs, conditional commands, and |
670 | mechanisms to group commands and execute them as a unit. | |
671 | ||
672 | \1f | |
673 | File: bashref.info, Node: Looping Constructs, Next: Conditional Constructs, Up: Compound Commands | |
ccc6cda3 | 674 | |
37c41ab1 CR |
675 | 3.2.4.1 Looping Constructs |
676 | .......................... | |
ccc6cda3 | 677 | |
37c41ab1 | 678 | Bash supports the following looping constructs. |
ccc6cda3 | 679 | |
8a0829e9 | 680 | Note that wherever a ';' appears in the description of a command's |
cce855bc JA |
681 | syntax, it may be replaced with one or more newlines. |
682 | ||
8a0829e9 CR |
683 | 'until' |
684 | The syntax of the 'until' command is: | |
122f603c | 685 | |
ccc6cda3 | 686 | until TEST-COMMANDS; do CONSEQUENT-COMMANDS; done |
122f603c | 687 | |
cce855bc JA |
688 | Execute CONSEQUENT-COMMANDS as long as TEST-COMMANDS has an exit |
689 | status which is not zero. The return status is the exit status of | |
690 | the last command executed in CONSEQUENT-COMMANDS, or zero if none | |
691 | was executed. | |
ccc6cda3 | 692 | |
8a0829e9 CR |
693 | 'while' |
694 | The syntax of the 'while' command is: | |
122f603c | 695 | |
ccc6cda3 JA |
696 | while TEST-COMMANDS; do CONSEQUENT-COMMANDS; done |
697 | ||
cce855bc JA |
698 | Execute CONSEQUENT-COMMANDS as long as TEST-COMMANDS has an exit |
699 | status of zero. The return status is the exit status of the last | |
700 | command executed in CONSEQUENT-COMMANDS, or zero if none was | |
701 | executed. | |
ccc6cda3 | 702 | |
8a0829e9 CR |
703 | 'for' |
704 | The syntax of the 'for' command is: | |
ccc6cda3 | 705 | |
4a8bb13f | 706 | for NAME [ [in [WORDS ...] ] ; ] do COMMANDS; done |
122f603c | 707 | |
cce855bc | 708 | Expand WORDS, and execute COMMANDS once for each member in the |
8a0829e9 CR |
709 | resultant list, with NAME bound to the current member. If 'in |
710 | WORDS' is not present, the 'for' command executes the COMMANDS once | |
711 | for each positional parameter that is set, as if 'in "$@"' had been | |
712 | specified (*note Special Parameters::). The return status is the | |
713 | exit status of the last command that executes. If there are no | |
714 | items in the expansion of WORDS, no commands are executed, and the | |
715 | return status is zero. | |
bb70624e | 716 | |
8a0829e9 | 717 | An alternate form of the 'for' command is also supported: |
bb70624e JA |
718 | |
719 | for (( EXPR1 ; EXPR2 ; EXPR3 )) ; do COMMANDS ; done | |
122f603c | 720 | |
bb70624e | 721 | First, the arithmetic expression EXPR1 is evaluated according to |
28ef6c31 | 722 | the rules described below (*note Shell Arithmetic::). The |
bb70624e JA |
723 | arithmetic expression EXPR2 is then evaluated repeatedly until it |
724 | evaluates to zero. Each time EXPR2 evaluates to a non-zero value, | |
725 | COMMANDS are executed and the arithmetic expression EXPR3 is | |
726 | evaluated. If any expression is omitted, it behaves as if it | |
727 | evaluates to 1. The return value is the exit status of the last | |
9ec5ed66 | 728 | command in COMMANDS that is executed, or false if any of the |
bb70624e | 729 | expressions is invalid. |
ccc6cda3 | 730 | |
8a0829e9 | 731 | The 'break' and 'continue' builtins (*note Bourne Shell Builtins::) |
ccc6cda3 JA |
732 | may be used to control loop execution. |
733 | ||
734 | \1f | |
d3a24ed2 | 735 | File: bashref.info, Node: Conditional Constructs, Next: Command Grouping, Prev: Looping Constructs, Up: Compound Commands |
ccc6cda3 | 736 | |
37c41ab1 CR |
737 | 3.2.4.2 Conditional Constructs |
738 | .............................. | |
ccc6cda3 | 739 | |
8a0829e9 CR |
740 | 'if' |
741 | The syntax of the 'if' command is: | |
ccc6cda3 JA |
742 | |
743 | if TEST-COMMANDS; then | |
744 | CONSEQUENT-COMMANDS; | |
745 | [elif MORE-TEST-COMMANDS; then | |
746 | MORE-CONSEQUENTS;] | |
747 | [else ALTERNATE-CONSEQUENTS;] | |
748 | fi | |
749 | ||
cce855bc JA |
750 | The TEST-COMMANDS list is executed, and if its return status is |
751 | zero, the CONSEQUENT-COMMANDS list is executed. If TEST-COMMANDS | |
8a0829e9 | 752 | returns a non-zero status, each 'elif' list is executed in turn, |
cce855bc | 753 | and if its exit status is zero, the corresponding MORE-CONSEQUENTS |
8a0829e9 | 754 | is executed and the command completes. If 'else |
cce855bc | 755 | ALTERNATE-CONSEQUENTS' is present, and the final command in the |
8a0829e9 | 756 | final 'if' or 'elif' clause has a non-zero exit status, then |
cce855bc | 757 | ALTERNATE-CONSEQUENTS is executed. The return status is the exit |
8a0829e9 CR |
758 | status of the last command executed, or zero if no condition tested |
759 | true. | |
ccc6cda3 | 760 | |
8a0829e9 CR |
761 | 'case' |
762 | The syntax of the 'case' command is: | |
ccc6cda3 | 763 | |
122f603c | 764 | case WORD in [ [(] PATTERN [| PATTERN]...) COMMAND-LIST ;;]... esac |
ccc6cda3 | 765 | |
8a0829e9 CR |
766 | 'case' will selectively execute the COMMAND-LIST corresponding to |
767 | the first PATTERN that matches WORD. If the 'nocasematch' shell | |
768 | option (see the description of 'shopt' in *note The Shopt | |
769 | Builtin::) is enabled, the match is performed without regard to the | |
770 | case of alphabetic characters. The '|' is used to separate | |
771 | multiple patterns, and the ')' operator terminates a pattern list. | |
cce855bc | 772 | A list of patterns and an associated command-list is known as a |
ed35cb4a CR |
773 | CLAUSE. |
774 | ||
8a0829e9 CR |
775 | Each clause must be terminated with ';;', ';&', or ';;&'. The WORD |
776 | undergoes tilde expansion, parameter expansion, command | |
cce855bc JA |
777 | substitution, arithmetic expansion, and quote removal before |
778 | matching is attempted. Each PATTERN undergoes tilde expansion, | |
779 | parameter expansion, command substitution, and arithmetic | |
780 | expansion. | |
781 | ||
8a0829e9 CR |
782 | There may be an arbitrary number of 'case' clauses, each terminated |
783 | by a ';;', ';&', or ';;&'. The first pattern that matches | |
9f178efb | 784 | determines the command-list that is executed. It's a common idiom |
8a0829e9 | 785 | to use '*' as the final pattern to define the default case, since |
9f178efb | 786 | that pattern will always match. |
ccc6cda3 | 787 | |
8a0829e9 | 788 | Here is an example using 'case' in a script that could be used to |
ccc6cda3 JA |
789 | describe one interesting feature of an animal: |
790 | ||
791 | echo -n "Enter the name of an animal: " | |
792 | read ANIMAL | |
793 | echo -n "The $ANIMAL has " | |
794 | case $ANIMAL in | |
795 | horse | dog | cat) echo -n "four";; | |
796 | man | kangaroo ) echo -n "two";; | |
797 | *) echo -n "an unknown number of";; | |
798 | esac | |
799 | echo " legs." | |
800 | ||
8a0829e9 CR |
801 | If the ';;' operator is used, no subsequent matches are attempted |
802 | after the first pattern match. Using ';&' in place of ';;' causes | |
803 | execution to continue with the COMMAND-LIST associated with the | |
804 | next clause, if any. Using ';;&' in place of ';;' causes the shell | |
805 | to test the patterns in the next clause, if any, and execute any | |
806 | associated COMMAND-LIST on a successful match. | |
ed35cb4a | 807 | |
cce855bc JA |
808 | The return status is zero if no PATTERN is matched. Otherwise, the |
809 | return status is the exit status of the COMMAND-LIST executed. | |
810 | ||
8a0829e9 CR |
811 | 'select' |
812 | ||
813 | The 'select' construct allows the easy generation of menus. It has | |
814 | almost the same syntax as the 'for' command: | |
cce855bc JA |
815 | |
816 | select NAME [in WORDS ...]; do COMMANDS; done | |
817 | ||
8a0829e9 | 818 | The list of words following 'in' is expanded, generating a list of |
cce855bc | 819 | items. The set of expanded words is printed on the standard error |
8a0829e9 CR |
820 | output stream, each preceded by a number. If the 'in WORDS' is |
821 | omitted, the positional parameters are printed, as if 'in "$@"' had | |
822 | been specified. The 'PS3' prompt is then displayed and a line is | |
823 | read from the standard input. If the line consists of a number | |
824 | corresponding to one of the displayed words, then the value of NAME | |
825 | is set to that word. If the line is empty, the words and prompt | |
826 | are displayed again. If 'EOF' is read, the 'select' command | |
827 | completes. Any other value read causes NAME to be set to null. | |
828 | The line read is saved in the variable 'REPLY'. | |
829 | ||
830 | The COMMANDS are executed after each selection until a 'break' | |
831 | command is executed, at which point the 'select' command completes. | |
cce855bc JA |
832 | |
833 | Here is an example that allows the user to pick a filename from the | |
834 | current directory, and displays the name and index of the file | |
835 | selected. | |
836 | ||
837 | select fname in *; | |
838 | do | |
839 | echo you picked $fname \($REPLY\) | |
840 | break; | |
841 | done | |
842 | ||
8a0829e9 | 843 | '((...))' |
ccc6cda3 JA |
844 | (( EXPRESSION )) |
845 | ||
cce855bc | 846 | The arithmetic EXPRESSION is evaluated according to the rules |
28ef6c31 | 847 | described below (*note Shell Arithmetic::). If the value of the |
cce855bc JA |
848 | expression is non-zero, the return status is 0; otherwise the |
849 | return status is 1. This is exactly equivalent to | |
ccc6cda3 | 850 | let "EXPRESSION" |
8a0829e9 | 851 | *Note Bash Builtins::, for a full description of the 'let' builtin. |
cce855bc | 852 | |
8a0829e9 | 853 | '[[...]]' |
cce855bc JA |
854 | [[ EXPRESSION ]] |
855 | ||
856 | Return a status of 0 or 1 depending on the evaluation of the | |
8a0829e9 CR |
857 | conditional expression EXPRESSION. Expressions are composed of the |
858 | primaries described below in *note Bash Conditional Expressions::. | |
859 | Word splitting and filename expansion are not performed on the | |
860 | words between the '[[' and ']]'; tilde expansion, parameter and | |
861 | variable expansion, arithmetic expansion, command substitution, | |
862 | process substitution, and quote removal are performed. Conditional | |
863 | operators such as '-f' must be unquoted to be recognized as | |
864 | primaries. | |
865 | ||
866 | When used with '[[', the '<' and '>' operators sort | |
d5362af8 CR |
867 | lexicographically using the current locale. |
868 | ||
8a0829e9 | 869 | When the '==' and '!=' operators are used, the string to the right |
cce855bc | 870 | of the operator is considered a pattern and matched according to |
1101193a | 871 | the rules described below in *note Pattern Matching::, as if the |
8a0829e9 CR |
872 | 'extglob' shell option were enabled. The '=' operator is identical |
873 | to '=='. If the 'nocasematch' shell option (see the description of | |
874 | 'shopt' in *note The Shopt Builtin::) is enabled, the match is | |
875 | performed without regard to the case of alphabetic characters. The | |
876 | return value is 0 if the string matches ('==') or does not match | |
877 | ('!=')the pattern, and 1 otherwise. Any part of the pattern may be | |
878 | quoted to force the quoted portion to be matched as a string. | |
879 | ||
880 | An additional binary operator, '=~', is available, with the same | |
881 | precedence as '==' and '!='. When it is used, the string to the | |
5e13499c CR |
882 | right of the operator is considered an extended regular expression |
883 | and matched accordingly (as in regex3)). The return value is 0 if | |
884 | the string matches the pattern, and 1 otherwise. If the regular | |
8a0829e9 CR |
885 | expression is syntactically incorrect, the conditional expression's |
886 | return value is 2. If the 'nocasematch' shell option (see the | |
887 | description of 'shopt' in *note The Shopt Builtin::) is enabled, | |
888 | the match is performed without regard to the case of alphabetic | |
889 | characters. Any part of the pattern may be quoted to force the | |
890 | quoted portion to be matched as a string. Bracket expressions in | |
891 | regular expressions must be treated carefully, since normal quoting | |
892 | characters lose their meanings between brackets. If the pattern is | |
893 | stored in a shell variable, quoting the variable expansion forces | |
894 | the entire pattern to be matched as a string. Substrings matched | |
895 | by parenthesized subexpressions within the regular expression are | |
896 | saved in the array variable 'BASH_REMATCH'. The element of | |
897 | 'BASH_REMATCH' with index 0 is the portion of the string matching | |
898 | the entire regular expression. The element of 'BASH_REMATCH' with | |
899 | index N is the portion of the string matching the Nth parenthesized | |
900 | subexpression. | |
45c0f7f8 CR |
901 | |
902 | For example, the following will match a line (stored in the shell | |
903 | variable LINE) if there is a sequence of characters in the value | |
8a0829e9 CR |
904 | consisting of any number, including zero, of space characters, zero |
905 | or one instances of 'a', then a 'b': | |
45c0f7f8 CR |
906 | [[ $line =~ [[:space:]]*(a)?b ]] |
907 | ||
8a0829e9 CR |
908 | That means values like 'aab' and ' aaaaaab' will match, as will a |
909 | line containing a 'b' anywhere in its value. | |
45c0f7f8 CR |
910 | |
911 | Storing the regular expression in a shell variable is often a | |
912 | useful way to avoid problems with quoting characters that are | |
913 | special to the shell. It is sometimes difficult to specify a | |
8a0829e9 CR |
914 | regular expression literally without using quotes, or to keep track |
915 | of the quoting used by regular expressions while paying attention | |
916 | to the shell's quote removal. Using a shell variable to store the | |
917 | pattern decreases these problems. For example, the following is | |
918 | equivalent to the above: | |
45c0f7f8 CR |
919 | pattern='[[:space:]]*(a)?b' |
920 | [[ $line =~ $pattern ]] | |
921 | ||
922 | If you want to match a character that's special to the regular | |
923 | expression grammar, it has to be quoted to remove its special | |
8a0829e9 CR |
924 | meaning. This means that in the pattern 'xxx.txt', the '.' matches |
925 | any character in the string (its usual regular expression meaning), | |
926 | but in the pattern '"xxx.txt"' it can only match a literal '.'. | |
927 | Shell programmers should take special care with backslashes, since | |
928 | backslashes are used both by the shell and regular expressions to | |
929 | remove the special meaning from the following character. The | |
930 | following two sets of commands are _not_ equivalent: | |
45c0f7f8 CR |
931 | pattern='\.' |
932 | ||
933 | [[ . =~ $pattern ]] | |
934 | [[ . =~ \. ]] | |
935 | ||
936 | [[ . =~ "$pattern" ]] | |
937 | [[ . =~ '\.' ]] | |
938 | ||
939 | The first two matches will succeed, but the second two will not, | |
8a0829e9 CR |
940 | because in the second two the backslash will be part of the pattern |
941 | to be matched. In the first two examples, the backslash removes | |
942 | the special meaning from '.', so the literal '.' matches. If the | |
943 | string in the first examples were anything other than '.', say 'a', | |
944 | the pattern would not match, because the quoted '.' in the pattern | |
945 | loses its special meaning of matching any single character. | |
5e13499c | 946 | |
cce855bc JA |
947 | Expressions may be combined using the following operators, listed |
948 | in decreasing order of precedence: | |
949 | ||
8a0829e9 CR |
950 | '( EXPRESSION )' |
951 | Returns the value of EXPRESSION. This may be used to override | |
952 | the normal precedence of operators. | |
cce855bc | 953 | |
8a0829e9 | 954 | '! EXPRESSION' |
cce855bc JA |
955 | True if EXPRESSION is false. |
956 | ||
8a0829e9 | 957 | 'EXPRESSION1 && EXPRESSION2' |
cce855bc JA |
958 | True if both EXPRESSION1 and EXPRESSION2 are true. |
959 | ||
8a0829e9 | 960 | 'EXPRESSION1 || EXPRESSION2' |
cce855bc | 961 | True if either EXPRESSION1 or EXPRESSION2 is true. |
122f603c | 962 | |
8a0829e9 CR |
963 | The '&&' and '||' operators do not evaluate EXPRESSION2 if the |
964 | value of EXPRESSION1 is sufficient to determine the return value of | |
965 | the entire conditional expression. | |
ccc6cda3 JA |
966 | |
967 | \1f | |
d3a24ed2 | 968 | File: bashref.info, Node: Command Grouping, Prev: Conditional Constructs, Up: Compound Commands |
ccc6cda3 | 969 | |
37c41ab1 CR |
970 | 3.2.4.3 Grouping Commands |
971 | ......................... | |
ccc6cda3 | 972 | |
37c41ab1 CR |
973 | Bash provides two ways to group a list of commands to be executed as a |
974 | unit. When commands are grouped, redirections may be applied to the | |
8a0829e9 CR |
975 | entire command list. For example, the output of all the commands in the |
976 | list may be redirected to a single stream. | |
ccc6cda3 | 977 | |
8a0829e9 | 978 | '()' |
ccc6cda3 JA |
979 | ( LIST ) |
980 | ||
981 | Placing a list of commands between parentheses causes a subshell | |
d3a24ed2 CR |
982 | environment to be created (*note Command Execution Environment::), |
983 | and each of the commands in LIST to be executed in that subshell. | |
984 | Since the LIST is executed in a subshell, variable assignments do | |
985 | not remain in effect after the subshell completes. | |
ccc6cda3 | 986 | |
8a0829e9 | 987 | '{}' |
ccc6cda3 JA |
988 | { LIST; } |
989 | ||
990 | Placing a list of commands between curly braces causes the list to | |
991 | be executed in the current shell context. No subshell is created. | |
cce855bc | 992 | The semicolon (or newline) following LIST is required. |
ccc6cda3 JA |
993 | |
994 | In addition to the creation of a subshell, there is a subtle | |
995 | difference between these two constructs due to historical reasons. The | |
8a0829e9 CR |
996 | braces are 'reserved words', so they must be separated from the LIST by |
997 | 'blank's or other shell metacharacters. The parentheses are | |
998 | 'operators', and are recognized as separate tokens by the shell even if | |
d7f49990 | 999 | they are not separated from the LIST by whitespace. |
ccc6cda3 JA |
1000 | |
1001 | The exit status of both of these constructs is the exit status of | |
1002 | LIST. | |
1003 | ||
8e1a6eaa | 1004 | \1f |
220537f2 | 1005 | File: bashref.info, Node: Coprocesses, Next: GNU Parallel, Prev: Compound Commands, Up: Shell Commands |
8e1a6eaa CR |
1006 | |
1007 | 3.2.5 Coprocesses | |
1008 | ----------------- | |
1009 | ||
8a0829e9 | 1010 | A 'coprocess' is a shell command preceded by the 'coproc' reserved word. |
8e1a6eaa | 1011 | A coprocess is executed asynchronously in a subshell, as if the command |
8a0829e9 | 1012 | had been terminated with the '&' control operator, with a two-way pipe |
8e1a6eaa CR |
1013 | established between the executing shell and the coprocess. |
1014 | ||
1015 | The format for a coprocess is: | |
122f603c | 1016 | coproc [NAME] COMMAND [REDIRECTIONS] |
8e1a6eaa CR |
1017 | |
1018 | This creates a coprocess named NAME. If NAME is not supplied, the | |
db31fb26 CR |
1019 | default name is COPROC. NAME must not be supplied if COMMAND is a |
1020 | simple command (*note Simple Commands::); otherwise, it is interpreted | |
1021 | as the first word of the simple command. | |
8e1a6eaa | 1022 | |
122f603c | 1023 | When the coprocess is executed, the shell creates an array variable |
8a0829e9 | 1024 | (*note Arrays::) named 'NAME' in the context of the executing shell. |
122f603c | 1025 | The standard output of COMMAND is connected via a pipe to a file |
8e1a6eaa | 1026 | descriptor in the executing shell, and that file descriptor is assigned |
8a0829e9 | 1027 | to 'NAME'[0]. The standard input of COMMAND is connected via a pipe to |
122f603c | 1028 | a file descriptor in the executing shell, and that file descriptor is |
8a0829e9 CR |
1029 | assigned to 'NAME'[1]. This pipe is established before any redirections |
1030 | specified by the command (*note Redirections::). The file descriptors | |
1031 | can be utilized as arguments to shell commands and redirections using | |
1032 | standard word expansions. The file descriptors are not available in | |
1033 | subshells. | |
8e1a6eaa | 1034 | |
e05be32d | 1035 | The process ID of the shell spawned to execute the coprocess is |
8a0829e9 | 1036 | available as the value of the variable 'NAME'_PID. The 'wait' builtin |
8e1a6eaa CR |
1037 | command may be used to wait for the coprocess to terminate. |
1038 | ||
ad4aef08 | 1039 | Since the coprocess is created as an asynchronous command, the |
8a0829e9 | 1040 | 'coproc' command always returns success. The return status of a |
ad4aef08 | 1041 | coprocess is the exit status of COMMAND. |
8e1a6eaa | 1042 | |
220537f2 CR |
1043 | \1f |
1044 | File: bashref.info, Node: GNU Parallel, Prev: Coprocesses, Up: Shell Commands | |
1045 | ||
1046 | 3.2.6 GNU Parallel | |
1047 | ------------------ | |
1048 | ||
c2fa6583 CR |
1049 | There are ways to run commands in parallel that are not built into Bash. |
1050 | GNU Parallel is a tool to do just that. | |
1051 | ||
1052 | GNU Parallel, as its name suggests, can be used to build and run | |
220537f2 CR |
1053 | commands in parallel. You may run the same command with different |
1054 | arguments, whether they are filenames, usernames, hostnames, or lines | |
c2fa6583 CR |
1055 | read from files. GNU Parallel provides shorthand references to many of |
1056 | the most common operations (input lines, various portions of the input | |
1057 | line, different ways to specify the input source, and so on). Parallel | |
8a0829e9 | 1058 | can replace 'xargs' or feed commands from its input sources to several |
c2fa6583 | 1059 | different instances of Bash. |
220537f2 CR |
1060 | |
1061 | For a complete description, refer to the GNU Parallel documentation. | |
1062 | A few examples should provide a brief introduction to its use. | |
1063 | ||
8a0829e9 | 1064 | For example, it is easy to replace 'xargs' to gzip all html files in |
c2fa6583 CR |
1065 | the current directory and its subdirectories: |
1066 | find . -type f -name '*.html' -print | parallel gzip | |
8a0829e9 CR |
1067 | If you need to protect special characters such as newlines in file |
1068 | names, use find's '-print0' option and parallel's '-0' option. | |
220537f2 CR |
1069 | |
1070 | You can use Parallel to move files from the current directory when | |
8a0829e9 | 1071 | the number of files is too large to process with one 'mv' invocation: |
220537f2 CR |
1072 | ls | parallel mv {} destdir |
1073 | ||
1074 | As you can see, the {} is replaced with each line read from standard | |
8a0829e9 | 1075 | input. While using 'ls' will work in most instances, it is not |
c2fa6583 CR |
1076 | sufficient to deal with all filenames. If you need to accommodate |
1077 | special characters in filenames, you can use | |
1078 | ||
1079 | find . -depth 1 \! -name '.*' -print0 | parallel -0 mv {} destdir | |
1080 | ||
1081 | as alluded to above. | |
1082 | ||
8a0829e9 CR |
1083 | This will run as many 'mv' commands as there are files in the current |
1084 | directory. You can emulate a parallel 'xargs' by adding the '-X' | |
c2fa6583 CR |
1085 | option: |
1086 | find . -depth 1 \! -name '.*' -print0 | parallel -0 -X mv {} destdir | |
220537f2 CR |
1087 | |
1088 | GNU Parallel can replace certain common idioms that operate on lines | |
c2fa6583 | 1089 | read from a file (in this case, filenames listed one per line): |
1101193a | 1090 | while IFS= read -r x; do |
c2fa6583 CR |
1091 | do-something1 "$x" "config-$x" |
1092 | do-something2 < "$x" | |
1093 | done < file | process-output | |
220537f2 CR |
1094 | |
1095 | with a more compact syntax reminiscent of lambdas: | |
1096 | cat list | parallel "do-something1 {} config-{} ; do-something2 < {}" | process-output | |
1097 | ||
8a0829e9 CR |
1098 | Parallel provides a built-in mechanism to remove filename extensions, |
1099 | which lends itself to batch file transformations or renaming: | |
220537f2 | 1100 | ls *.gz | parallel -j+0 "zcat {} | bzip2 >{.}.bz2 && rm {}" |
8a0829e9 | 1101 | This will recompress all files in the current directory with names |
c2fa6583 | 1102 | ending in .gz using bzip2, running one job per CPU (-j+0) in parallel. |
8a0829e9 | 1103 | (We use 'ls' for brevity here; using 'find' as above is more robust in |
c2fa6583 CR |
1104 | the face of filenames containing unexpected characters.) Parallel can |
1105 | take arguments from the command line; the above can also be written as | |
1106 | ||
1107 | parallel "zcat {} | bzip2 >{.}.bz2 && rm {}" ::: *.gz | |
220537f2 CR |
1108 | |
1109 | If a command generates output, you may want to preserve the input | |
1110 | order in the output. For instance, the following command | |
1111 | { echo foss.org.my ; echo debian.org; echo freenetproject.org; } | parallel traceroute | |
8a0829e9 CR |
1112 | will display as output the traceroute invocation that finishes first. |
1113 | Adding the '-k' option | |
220537f2 | 1114 | { echo foss.org.my ; echo debian.org; echo freenetproject.org; } | parallel -k traceroute |
8a0829e9 | 1115 | will ensure that the output of 'traceroute foss.org.my' is displayed |
220537f2 CR |
1116 | first. |
1117 | ||
c2fa6583 | 1118 | Finally, Parallel can be used to run a sequence of shell commands in |
8a0829e9 CR |
1119 | parallel, similar to 'cat file | bash'. It is not uncommon to take a |
1120 | list of filenames, create a series of shell commands to operate on them, | |
1121 | and feed that list of commnds to a shell. Parallel can speed this up. | |
1122 | Assuming that 'file' contains a list of shell commands, one per line, | |
c2fa6583 CR |
1123 | |
1124 | parallel -j 10 < file | |
1125 | ||
1126 | will evaluate the commands using the shell (since no explicit command is | |
1127 | supplied as an argument), in blocks of ten shell jobs at a time. | |
1128 | ||
ccc6cda3 | 1129 | \1f |
cce855bc | 1130 | File: bashref.info, Node: Shell Functions, Next: Shell Parameters, Prev: Shell Commands, Up: Basic Shell Features |
ccc6cda3 | 1131 | |
37c41ab1 CR |
1132 | 3.3 Shell Functions |
1133 | =================== | |
ccc6cda3 | 1134 | |
37c41ab1 CR |
1135 | Shell functions are a way to group commands for later execution using a |
1136 | single name for the group. They are executed just like a "regular" | |
1137 | command. When the name of a shell function is used as a simple command | |
1138 | name, the list of commands associated with that function name is | |
8a0829e9 CR |
1139 | executed. Shell functions are executed in the current shell context; no |
1140 | new process is created to interpret them. | |
ccc6cda3 | 1141 | |
8a0829e9 | 1142 | Functions are declared using this syntax: |
9ec5ed66 | 1143 | NAME () COMPOUND-COMMAND [ REDIRECTIONS ] |
9ec5ed66 | 1144 | |
122f603c CR |
1145 | or |
1146 | ||
1147 | function NAME [()] COMPOUND-COMMAND [ REDIRECTIONS ] | |
ccc6cda3 JA |
1148 | |
1149 | This defines a shell function named NAME. The reserved word | |
8a0829e9 | 1150 | 'function' is optional. If the 'function' reserved word is supplied, |
d3a24ed2 CR |
1151 | the parentheses are optional. The BODY of the function is the compound |
1152 | command COMPOUND-COMMAND (*note Compound Commands::). That command is | |
8a0829e9 CR |
1153 | usually a LIST enclosed between { and }, but may be any compound command |
1154 | listed above, with one exception: If the 'function' reserved word is | |
1155 | used, but the parentheses are not supplied, the braces are required. | |
1156 | COMPOUND-COMMAND is executed whenever NAME is specified as the name of a | |
1157 | command. When the shell is in POSIX mode (*note Bash POSIX Mode::), | |
1158 | NAME may not be the same as one of the special builtins (*note Special | |
1159 | Builtins::). Any redirections (*note Redirections::) associated with | |
1160 | the shell function are performed when the function is executed. | |
1161 | ||
1162 | A function definition may be deleted using the '-f' option to the | |
1163 | 'unset' builtin (*note Bourne Shell Builtins::). | |
ac18b312 | 1164 | |
d3a24ed2 CR |
1165 | The exit status of a function definition is zero unless a syntax |
1166 | error occurs or a readonly function with the same name already exists. | |
1167 | When executed, the exit status of a function is the exit status of the | |
1168 | last command executed in the body. | |
1169 | ||
1170 | Note that for historical reasons, in the most common usage the curly | |
8a0829e9 CR |
1171 | braces that surround the body of the function must be separated from the |
1172 | body by 'blank's or newlines. This is because the braces are reserved | |
1173 | words and are only recognized as such when they are separated from the | |
1174 | command list by whitespace or another shell metacharacter. Also, when | |
1175 | using the braces, the LIST must be terminated by a semicolon, a '&', or | |
1176 | a newline. | |
1177 | ||
1178 | When a function is executed, the arguments to the function become the | |
1179 | positional parameters during its execution (*note Positional | |
1180 | Parameters::). The special parameter '#' that expands to the number of | |
de8913bd | 1181 | positional parameters is updated to reflect the change. Special |
8a0829e9 | 1182 | parameter '0' is unchanged. The first element of the 'FUNCNAME' |
d3a24ed2 | 1183 | variable is set to the name of the function while the function is |
4a8bb13f CR |
1184 | executing. |
1185 | ||
1186 | All other aspects of the shell execution environment are identical | |
8a0829e9 CR |
1187 | between a function and its caller with these exceptions: the 'DEBUG' and |
1188 | 'RETURN' traps are not inherited unless the function has been given the | |
1189 | 'trace' attribute using the 'declare' builtin or the '-o functrace' | |
1190 | option has been enabled with the 'set' builtin, (in which case all | |
1191 | functions inherit the 'DEBUG' and 'RETURN' traps), and the 'ERR' trap is | |
1192 | not inherited unless the '-o errtrace' shell option has been enabled. | |
1193 | *Note Bourne Shell Builtins::, for the description of the 'trap' | |
4a8bb13f | 1194 | builtin. |
ccc6cda3 | 1195 | |
8a0829e9 | 1196 | The 'FUNCNEST' variable, if set to a numeric value greater than 0, |
220537f2 CR |
1197 | defines a maximum function nesting level. Function invocations that |
1198 | exceed the limit cause the entire command to abort. | |
1199 | ||
8a0829e9 CR |
1200 | If the builtin command 'return' is executed in a function, the |
1201 | function completes and execution resumes with the next command after the | |
1202 | function call. Any command associated with the 'RETURN' trap is | |
d3a24ed2 | 1203 | executed before execution resumes. When a function completes, the |
8a0829e9 CR |
1204 | values of the positional parameters and the special parameter '#' are |
1205 | restored to the values they had prior to the function's execution. If a | |
1206 | numeric argument is given to 'return', that is the function's return | |
1207 | status; otherwise the function's return status is the exit status of the | |
1208 | last command executed before the 'return'. | |
ccc6cda3 | 1209 | |
8a0829e9 | 1210 | Variables local to the function may be declared with the 'local' |
ccc6cda3 JA |
1211 | builtin. These variables are visible only to the function and the |
1212 | commands it invokes. | |
1213 | ||
8a0829e9 CR |
1214 | Function names and definitions may be listed with the '-f' option to |
1215 | the 'declare' ('typeset') builtin command (*note Bash Builtins::). The | |
1216 | '-F' option to 'declare' or 'typeset' will list the function names only | |
1217 | (and optionally the source file and line number, if the 'extdebug' shell | |
1218 | option is enabled). Functions may be exported so that subshells | |
1219 | automatically have them defined with the '-f' option to the 'export' | |
d3a24ed2 CR |
1220 | builtin (*note Bourne Shell Builtins::). Note that shell functions and |
1221 | variables with the same name may result in multiple identically-named | |
1222 | entries in the environment passed to the shell's children. Care should | |
1223 | be taken in cases where this may cause a problem. | |
1224 | ||
8a0829e9 | 1225 | Functions may be recursive. The 'FUNCNEST' variable may be used to |
9ec5ed66 CR |
1226 | limit the depth of the function call stack and restrict the number of |
1227 | function invocations. By default, no limit is placed on the number of | |
8a0829e9 | 1228 | recursive calls. |
ccc6cda3 JA |
1229 | |
1230 | \1f | |
1231 | File: bashref.info, Node: Shell Parameters, Next: Shell Expansions, Prev: Shell Functions, Up: Basic Shell Features | |
1232 | ||
37c41ab1 CR |
1233 | 3.4 Shell Parameters |
1234 | ==================== | |
ccc6cda3 JA |
1235 | |
1236 | * Menu: | |
1237 | ||
1238 | * Positional Parameters:: The shell's command-line arguments. | |
d3a24ed2 | 1239 | * Special Parameters:: Parameters denoted by special characters. |
ccc6cda3 | 1240 | |
8a0829e9 | 1241 | A PARAMETER is an entity that stores values. It can be a 'name', a |
d3a24ed2 | 1242 | number, or one of the special characters listed below. A VARIABLE is a |
8a0829e9 CR |
1243 | parameter denoted by a 'name'. A variable has a VALUE and zero or more |
1244 | ATTRIBUTES. Attributes are assigned using the 'declare' builtin command | |
1245 | (see the description of the 'declare' builtin in *note Bash Builtins::). | |
ccc6cda3 JA |
1246 | |
1247 | A parameter is set if it has been assigned a value. The null string | |
1248 | is a valid value. Once a variable is set, it may be unset only by using | |
8a0829e9 | 1249 | the 'unset' builtin command. |
ccc6cda3 JA |
1250 | |
1251 | A variable may be assigned to by a statement of the form | |
1252 | NAME=[VALUE] | |
8a0829e9 | 1253 | If VALUE is not given, the variable is assigned the null string. All |
ccc6cda3 JA |
1254 | VALUEs undergo tilde expansion, parameter and variable expansion, |
1255 | command substitution, arithmetic expansion, and quote removal (detailed | |
8a0829e9 CR |
1256 | below). If the variable has its 'integer' attribute set, then VALUE is |
1257 | evaluated as an arithmetic expression even if the '$((...))' expansion | |
d3a24ed2 | 1258 | is not used (*note Arithmetic Expansion::). Word splitting is not |
8a0829e9 | 1259 | performed, with the exception of '"$@"' as explained below. Filename |
d3a24ed2 | 1260 | expansion is not performed. Assignment statements may also appear as |
8a0829e9 CR |
1261 | arguments to the 'alias', 'declare', 'typeset', 'export', 'readonly', |
1262 | and 'local' builtin commands (DECLARATION commands). When in POSIX mode | |
1263 | (*note Bash POSIX Mode::), these builtins may appear in a command after | |
1264 | one or more instances of the 'command' builtin and retain these | |
fc527055 | 1265 | assignment statement properties. |
ccc6cda3 | 1266 | |
eb2bb562 | 1267 | In the context where an assignment statement is assigning a value to |
8a0829e9 | 1268 | a shell variable or array index (*note Arrays::), the '+=' operator can |
fc527055 | 1269 | be used to append to or add to the variable's previous value. This |
8a0829e9 CR |
1270 | includes arguments to builtin commands such as 'declare' that accept |
1271 | assignment statements (DECLARATION commands). When '+=' is applied to a | |
1272 | variable for which the INTEGER attribute has been set, VALUE is | |
fc527055 | 1273 | evaluated as an arithmetic expression and added to the variable's |
8a0829e9 | 1274 | current value, which is also evaluated. When '+=' is applied to an |
fc527055 | 1275 | array variable using compound assignment (*note Arrays::), the |
8a0829e9 | 1276 | variable's value is not unset (as it is when using '='), and new values |
fc527055 | 1277 | are appended to the array beginning at one greater than the array's |
8a0829e9 | 1278 | maximum index (for indexed arrays), or added as additional key-value |
fc527055 CR |
1279 | pairs in an associative array. When applied to a string-valued |
1280 | variable, VALUE is expanded and appended to the variable's value. | |
eb2bb562 | 1281 | |
8a0829e9 | 1282 | A variable can be assigned the NAMEREF attribute using the '-n' |
9f178efb CR |
1283 | option to the \fBdeclare\fP or \fBlocal\fP builtin commands (*note Bash |
1284 | Builtins::) to create a NAMEREF, or a reference to another variable. | |
1285 | This allows variables to be manipulated indirectly. Whenever the | |
fc527055 CR |
1286 | nameref variable is referenced, assigned to, unset, or has its |
1287 | attributes modified (other than the nameref attribute itself), the | |
1288 | operation is actually performed on the variable specified by the nameref | |
1289 | variable's value. A nameref is commonly used within shell functions to | |
1290 | refer to a variable whose name is passed as an argument to the function. | |
1291 | For instance, if a variable name is passed to a shell function as its | |
1292 | first argument, running | |
9f178efb | 1293 | declare -n ref=$1 |
8a0829e9 CR |
1294 | inside the function creates a nameref variable REF whose value is the |
1295 | variable name passed as the first argument. References and assignments | |
1296 | to REF, and changes to its attributes, are treated as references, | |
1297 | assignments, and attribute modifications to the variable whose name was | |
1298 | passed as '$1'. | |
9f178efb | 1299 | |
8a0829e9 | 1300 | If the control variable in a 'for' loop has the nameref attribute, |
9f178efb CR |
1301 | the list of words can be a list of shell variables, and a name reference |
1302 | will be established for each word in the list, in turn, when the loop is | |
fc527055 | 1303 | executed. Array variables cannot be given the nameref attribute. |
9f178efb | 1304 | However, nameref variables can reference array variables and subscripted |
8a0829e9 CR |
1305 | array variables. Namerefs can be unset using the '-n' option to the |
1306 | 'unset' builtin (*note Bourne Shell Builtins::). Otherwise, if 'unset' | |
9f178efb CR |
1307 | is executed with the name of a nameref variable as an argument, the |
1308 | variable referenced by the nameref variable will be unset. | |
1309 | ||
ccc6cda3 JA |
1310 | \1f |
1311 | File: bashref.info, Node: Positional Parameters, Next: Special Parameters, Up: Shell Parameters | |
1312 | ||
37c41ab1 CR |
1313 | 3.4.1 Positional Parameters |
1314 | --------------------------- | |
ccc6cda3 | 1315 | |
37c41ab1 | 1316 | A POSITIONAL PARAMETER is a parameter denoted by one or more digits, |
8a0829e9 | 1317 | other than the single digit '0'. Positional parameters are assigned |
ccc6cda3 | 1318 | from the shell's arguments when it is invoked, and may be reassigned |
8a0829e9 CR |
1319 | using the 'set' builtin command. Positional parameter 'N' may be |
1320 | referenced as '${N}', or as '$N' when 'N' consists of a single digit. | |
bb70624e | 1321 | Positional parameters may not be assigned to with assignment statements. |
8a0829e9 | 1322 | The 'set' and 'shift' builtins are used to set and unset them (*note |
28ef6c31 JA |
1323 | Shell Builtin Commands::). The positional parameters are temporarily |
1324 | replaced when a shell function is executed (*note Shell Functions::). | |
ccc6cda3 | 1325 | |
8a0829e9 CR |
1326 | When a positional parameter consisting of more than a single digit is |
1327 | expanded, it must be enclosed in braces. | |
ccc6cda3 JA |
1328 | |
1329 | \1f | |
1330 | File: bashref.info, Node: Special Parameters, Prev: Positional Parameters, Up: Shell Parameters | |
1331 | ||
37c41ab1 CR |
1332 | 3.4.2 Special Parameters |
1333 | ------------------------ | |
ccc6cda3 | 1334 | |
37c41ab1 | 1335 | The shell treats several parameters specially. These parameters may |
ccc6cda3 JA |
1336 | only be referenced; assignment to them is not allowed. |
1337 | ||
8a0829e9 CR |
1338 | '*' |
1339 | ($*) Expands to the positional parameters, starting from one. When | |
1340 | the expansion is not within double quotes, each positional | |
595e3e69 CR |
1341 | parameter expands to a separate word. In contexts where it is |
1342 | performed, those words are subject to further word splitting and | |
1343 | pathname expansion. When the expansion occurs within double | |
1344 | quotes, it expands to a single word with the value of each | |
8a0829e9 CR |
1345 | parameter separated by the first character of the 'IFS' special |
1346 | variable. That is, '"$*"' is equivalent to '"$1C$2C..."', where C | |
1347 | is the first character of the value of the 'IFS' variable. If | |
1348 | 'IFS' is unset, the parameters are separated by spaces. If 'IFS' | |
595e3e69 | 1349 | is null, the parameters are joined without intervening separators. |
ccc6cda3 | 1350 | |
8a0829e9 CR |
1351 | '@' |
1352 | ($@) Expands to the positional parameters, starting from one. When | |
1353 | the expansion occurs within double quotes, each parameter expands | |
1354 | to a separate word. That is, '"$@"' is equivalent to '"$1" "$2" | |
1355 | ...'. If the double-quoted expansion occurs within a word, the | |
1356 | expansion of the first parameter is joined with the beginning part | |
1357 | of the original word, and the expansion of the last parameter is | |
1358 | joined with the last part of the original word. When there are no | |
1359 | positional parameters, '"$@"' and '$@' expand to nothing (i.e., | |
1360 | they are removed). | |
1361 | ||
1362 | '#' | |
6e51e0d0 | 1363 | ($#) Expands to the number of positional parameters in decimal. |
ccc6cda3 | 1364 | |
8a0829e9 CR |
1365 | '?' |
1366 | ($?) Expands to the exit status of the most recently executed | |
6e51e0d0 | 1367 | foreground pipeline. |
ccc6cda3 | 1368 | |
8a0829e9 | 1369 | '-' |
6e51e0d0 | 1370 | ($-, a hyphen.) Expands to the current option flags as specified |
8a0829e9 CR |
1371 | upon invocation, by the 'set' builtin command, or those set by the |
1372 | shell itself (such as the '-i' option). | |
ccc6cda3 | 1373 | |
8a0829e9 CR |
1374 | '$' |
1375 | ($$) Expands to the process ID of the shell. In a '()' subshell, | |
6e51e0d0 CR |
1376 | it expands to the process ID of the invoking shell, not the |
1377 | subshell. | |
ccc6cda3 | 1378 | |
8a0829e9 CR |
1379 | '!' |
1380 | ($!) Expands to the process ID of the job most recently placed | |
1381 | into the background, whether executed as an asynchronous command or | |
1382 | using the 'bg' builtin (*note Job Control Builtins::). | |
1383 | ||
1384 | '0' | |
1385 | ($0) Expands to the name of the shell or shell script. This is set | |
1386 | at shell initialization. If Bash is invoked with a file of | |
1387 | commands (*note Shell Scripts::), '$0' is set to the name of that | |
1388 | file. If Bash is started with the '-c' option (*note Invoking | |
1389 | Bash::), then '$0' is set to the first argument after the string to | |
1390 | be executed, if one is present. Otherwise, it is set to the | |
6e51e0d0 | 1391 | filename used to invoke Bash, as given by argument zero. |
ccc6cda3 | 1392 | |
8a0829e9 | 1393 | '_' |
6e51e0d0 | 1394 | ($_, an underscore.) At shell startup, set to the absolute |
8a0829e9 CR |
1395 | pathname used to invoke the shell or shell script being executed as |
1396 | passed in the environment or argument list. Subsequently, expands | |
1397 | to the last argument to the previous command, after expansion. | |
1398 | Also set to the full pathname used to invoke each command executed | |
1399 | and placed in the environment exported to that command. When | |
1400 | checking mail, this parameter holds the name of the mail file. | |
ccc6cda3 JA |
1401 | |
1402 | \1f | |
1403 | File: bashref.info, Node: Shell Expansions, Next: Redirections, Prev: Shell Parameters, Up: Basic Shell Features | |
1404 | ||
37c41ab1 CR |
1405 | 3.5 Shell Expansions |
1406 | ==================== | |
ccc6cda3 | 1407 | |
37c41ab1 | 1408 | Expansion is performed on the command line after it has been split into |
8a0829e9 | 1409 | 'token's. There are seven kinds of expansion performed: |
122f603c | 1410 | |
ccc6cda3 | 1411 | * brace expansion |
ccc6cda3 | 1412 | * tilde expansion |
ccc6cda3 | 1413 | * parameter and variable expansion |
ccc6cda3 | 1414 | * command substitution |
ccc6cda3 | 1415 | * arithmetic expansion |
ccc6cda3 | 1416 | * word splitting |
ccc6cda3 JA |
1417 | * filename expansion |
1418 | ||
1419 | * Menu: | |
1420 | ||
cce855bc JA |
1421 | * Brace Expansion:: Expansion of expressions within braces. |
1422 | * Tilde Expansion:: Expansion of the ~ character. | |
ccc6cda3 JA |
1423 | * Shell Parameter Expansion:: How Bash expands variables to their values. |
1424 | * Command Substitution:: Using the output of a command as an argument. | |
cce855bc | 1425 | * Arithmetic Expansion:: How to use arithmetic in shell expansions. |
ccc6cda3 JA |
1426 | * Process Substitution:: A way to write and read to and from a |
1427 | command. | |
1428 | * Word Splitting:: How the results of expansion are split into separate | |
1429 | arguments. | |
1430 | * Filename Expansion:: A shorthand for specifying filenames matching patterns. | |
1431 | * Quote Removal:: How and when quote characters are removed from | |
1432 | words. | |
1433 | ||
d76edd30 CR |
1434 | The order of expansions is: brace expansion; tilde expansion, |
1435 | parameter and variable expansion, arithmetic expansion, and command | |
1436 | substitution (done in a left-to-right fashion); word splitting; and | |
1437 | filename expansion. | |
ccc6cda3 JA |
1438 | |
1439 | On systems that can support it, there is an additional expansion | |
1440 | available: PROCESS SUBSTITUTION. This is performed at the same time as | |
d76edd30 CR |
1441 | tilde, parameter, variable, and arithmetic expansion and command |
1442 | substitution. | |
ccc6cda3 JA |
1443 | |
1444 | Only brace expansion, word splitting, and filename expansion can | |
1445 | change the number of words of the expansion; other expansions expand a | |
1446 | single word to a single word. The only exceptions to this are the | |
8a0829e9 | 1447 | expansions of '"$@"' (*note Special Parameters::) and '"${NAME[@]}"' |
28ef6c31 | 1448 | (*note Arrays::). |
ccc6cda3 | 1449 | |
8a0829e9 | 1450 | After all expansions, 'quote removal' (*note Quote Removal::) is |
ccc6cda3 JA |
1451 | performed. |
1452 | ||
1453 | \1f | |
cce855bc JA |
1454 | File: bashref.info, Node: Brace Expansion, Next: Tilde Expansion, Up: Shell Expansions |
1455 | ||
37c41ab1 CR |
1456 | 3.5.1 Brace Expansion |
1457 | --------------------- | |
cce855bc | 1458 | |
37c41ab1 | 1459 | Brace expansion is a mechanism by which arbitrary strings may be |
cce855bc | 1460 | generated. This mechanism is similar to FILENAME EXPANSION (*note |
122f603c | 1461 | Filename Expansion::), but the filenames generated need not exist. |
cce855bc | 1462 | Patterns to be brace expanded take the form of an optional PREAMBLE, |
f6da9f85 | 1463 | followed by either a series of comma-separated strings or a sequence |
d3a24ed2 CR |
1464 | expression between a pair of braces, followed by an optional POSTSCRIPT. |
1465 | The preamble is prefixed to each string contained within the braces, and | |
1466 | the postscript is then appended to each resulting string, expanding left | |
1467 | to right. | |
cce855bc JA |
1468 | |
1469 | Brace expansions may be nested. The results of each expanded string | |
1470 | are not sorted; left to right order is preserved. For example, | |
1471 | bash$ echo a{d,c,b}e | |
1472 | ade ace abe | |
1473 | ||
8a0829e9 | 1474 | A sequence expression takes the form '{X..Y[..INCR]}', where X and Y |
ed35cb4a CR |
1475 | are either integers or single characters, and INCR, an optional |
1476 | increment, is an integer. When integers are supplied, the expression | |
1477 | expands to each number between X and Y, inclusive. Supplied integers | |
8a0829e9 | 1478 | may be prefixed with '0' to force each term to have the same width. |
ed35cb4a | 1479 | When either X or Y begins with a zero, the shell attempts to force all |
8a0829e9 CR |
1480 | generated terms to contain the same number of digits, zero-padding where |
1481 | necessary. When characters are supplied, the expression expands to each | |
1482 | character lexicographically between X and Y, inclusive, using the | |
1483 | default C locale. Note that both X and Y must be of the same type. | |
ad4aef08 CR |
1484 | When the increment is supplied, it is used as the difference between |
1485 | each term. The default increment is 1 or -1 as appropriate. | |
d3a24ed2 | 1486 | |
cce855bc JA |
1487 | Brace expansion is performed before any other expansions, and any |
1488 | characters special to other expansions are preserved in the result. It | |
1489 | is strictly textual. Bash does not apply any syntactic interpretation | |
bb70624e | 1490 | to the context of the expansion or the text between the braces. To |
8a0829e9 | 1491 | avoid conflicts with parameter expansion, the string '${' is not |
bb70624e | 1492 | considered eligible for brace expansion. |
cce855bc JA |
1493 | |
1494 | A correctly-formed brace expansion must contain unquoted opening and | |
d3a24ed2 CR |
1495 | closing braces, and at least one unquoted comma or a valid sequence |
1496 | expression. Any incorrectly formed brace expansion is left unchanged. | |
1497 | ||
8a0829e9 | 1498 | A { or ',' may be quoted with a backslash to prevent its being |
d3a24ed2 | 1499 | considered part of a brace expression. To avoid conflicts with |
8a0829e9 | 1500 | parameter expansion, the string '${' is not considered eligible for |
d3a24ed2 | 1501 | brace expansion. |
cce855bc JA |
1502 | |
1503 | This construct is typically used as shorthand when the common prefix | |
1504 | of the strings to be generated is longer than in the above example: | |
1505 | mkdir /usr/local/src/bash/{old,new,dist,bugs} | |
1506 | or | |
1507 | chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}} | |
1508 | ||
1509 | \1f | |
1510 | File: bashref.info, Node: Tilde Expansion, Next: Shell Parameter Expansion, Prev: Brace Expansion, Up: Shell Expansions | |
1511 | ||
37c41ab1 CR |
1512 | 3.5.2 Tilde Expansion |
1513 | --------------------- | |
cce855bc | 1514 | |
8a0829e9 | 1515 | If a word begins with an unquoted tilde character ('~'), all of the |
cce855bc JA |
1516 | characters up to the first unquoted slash (or all characters, if there |
1517 | is no unquoted slash) are considered a TILDE-PREFIX. If none of the | |
1518 | characters in the tilde-prefix are quoted, the characters in the | |
1519 | tilde-prefix following the tilde are treated as a possible LOGIN NAME. | |
1520 | If this login name is the null string, the tilde is replaced with the | |
8a0829e9 | 1521 | value of the 'HOME' shell variable. If 'HOME' is unset, the home |
cce855bc JA |
1522 | directory of the user executing the shell is substituted instead. |
1523 | Otherwise, the tilde-prefix is replaced with the home directory | |
1524 | associated with the specified login name. | |
1525 | ||
8a0829e9 CR |
1526 | If the tilde-prefix is '~+', the value of the shell variable 'PWD' |
1527 | replaces the tilde-prefix. If the tilde-prefix is '~-', the value of | |
1528 | the shell variable 'OLDPWD', if it is set, is substituted. | |
cce855bc JA |
1529 | |
1530 | If the characters following the tilde in the tilde-prefix consist of | |
8a0829e9 | 1531 | a number N, optionally prefixed by a '+' or a '-', the tilde-prefix is |
cce855bc | 1532 | replaced with the corresponding element from the directory stack, as it |
8a0829e9 | 1533 | would be displayed by the 'dirs' builtin invoked with the characters |
cce855bc | 1534 | following tilde in the tilde-prefix as an argument (*note The Directory |
28ef6c31 | 1535 | Stack::). If the tilde-prefix, sans the tilde, consists of a number |
8a0829e9 | 1536 | without a leading '+' or '-', '+' is assumed. |
cce855bc JA |
1537 | |
1538 | If the login name is invalid, or the tilde expansion fails, the word | |
1539 | is left unchanged. | |
1540 | ||
1541 | Each variable assignment is checked for unquoted tilde-prefixes | |
8a0829e9 | 1542 | immediately following a ':' or the first '='. In these cases, tilde |
122f603c | 1543 | expansion is also performed. Consequently, one may use filenames with |
8a0829e9 CR |
1544 | tildes in assignments to 'PATH', 'MAILPATH', and 'CDPATH', and the shell |
1545 | assigns the expanded value. | |
cce855bc JA |
1546 | |
1547 | The following table shows how Bash treats unquoted tilde-prefixes: | |
1548 | ||
8a0829e9 CR |
1549 | '~' |
1550 | The value of '$HOME' | |
1551 | '~/foo' | |
1552 | '$HOME/foo' | |
cce855bc | 1553 | |
8a0829e9 CR |
1554 | '~fred/foo' |
1555 | The subdirectory 'foo' of the home directory of the user 'fred' | |
cce855bc | 1556 | |
8a0829e9 CR |
1557 | '~+/foo' |
1558 | '$PWD/foo' | |
cce855bc | 1559 | |
8a0829e9 CR |
1560 | '~-/foo' |
1561 | '${OLDPWD-'~-'}/foo' | |
cce855bc | 1562 | |
8a0829e9 CR |
1563 | '~N' |
1564 | The string that would be displayed by 'dirs +N' | |
cce855bc | 1565 | |
8a0829e9 CR |
1566 | '~+N' |
1567 | The string that would be displayed by 'dirs +N' | |
cce855bc | 1568 | |
8a0829e9 CR |
1569 | '~-N' |
1570 | The string that would be displayed by 'dirs -N' | |
cce855bc JA |
1571 | |
1572 | \1f | |
1573 | File: bashref.info, Node: Shell Parameter Expansion, Next: Command Substitution, Prev: Tilde Expansion, Up: Shell Expansions | |
ccc6cda3 | 1574 | |
37c41ab1 CR |
1575 | 3.5.3 Shell Parameter Expansion |
1576 | ------------------------------- | |
ccc6cda3 | 1577 | |
8a0829e9 | 1578 | The '$' character introduces parameter expansion, command substitution, |
37c41ab1 CR |
1579 | or arithmetic expansion. The parameter name or symbol to be expanded |
1580 | may be enclosed in braces, which are optional but serve to protect the | |
1581 | variable to be expanded from characters immediately following it which | |
1582 | could be interpreted as part of the name. | |
ccc6cda3 | 1583 | |
8a0829e9 | 1584 | When braces are used, the matching ending brace is the first '}' not |
cce855bc JA |
1585 | escaped by a backslash or within a quoted string, and not within an |
1586 | embedded arithmetic expansion, command substitution, or parameter | |
1587 | expansion. | |
1588 | ||
ccc6cda3 | 1589 | The basic form of parameter expansion is ${PARAMETER}. The value of |
9f178efb CR |
1590 | PARAMETER is substituted. The PARAMETER is a shell parameter as |
1591 | described above (*note Shell Parameters::) or an array reference (*note | |
1592 | Arrays::). The braces are required when PARAMETER is a positional | |
1593 | parameter with more than one digit, or when PARAMETER is followed by a | |
1594 | character that is not to be interpreted as part of its name. | |
1595 | ||
8a0829e9 CR |
1596 | If the first character of PARAMETER is an exclamation point (!), and |
1597 | PARAMETER is not a NAMEREF, it introduces a level of variable | |
1598 | indirection. Bash uses the value of the variable formed from the rest | |
1599 | of PARAMETER as the name of the variable; this variable is then expanded | |
1600 | and that value is used in the rest of the substitution, rather than the | |
1601 | value of PARAMETER itself. This is known as 'indirect expansion'. If | |
1602 | PARAMETER is a nameref, this expands to the name of the variable | |
1603 | referenced by PARAMETER instead of performing the complete indirect | |
1604 | expansion. The exceptions to this are the expansions of ${!PREFIX*} and | |
1605 | ${!NAME[@]} described below. The exclamation point must immediately | |
1606 | follow the left brace in order to introduce indirection. | |
ccc6cda3 JA |
1607 | |
1608 | In each of the cases below, WORD is subject to tilde expansion, | |
1609 | parameter expansion, command substitution, and arithmetic expansion. | |
bb70624e | 1610 | |
db31fb26 | 1611 | When not performing substring expansion, using the form described |
8a0829e9 | 1612 | below (e.g., ':-'), Bash tests for a parameter that is unset or null. |
9f178efb CR |
1613 | Omitting the colon results in a test only for a parameter that is unset. |
1614 | Put another way, if the colon is included, the operator tests for both | |
db31fb26 CR |
1615 | PARAMETER's existence and that its value is not null; if the colon is |
1616 | omitted, the operator tests only for existence. | |
ccc6cda3 | 1617 | |
8a0829e9 | 1618 | '${PARAMETER:-WORD}' |
ccc6cda3 JA |
1619 | If PARAMETER is unset or null, the expansion of WORD is |
1620 | substituted. Otherwise, the value of PARAMETER is substituted. | |
1621 | ||
8a0829e9 CR |
1622 | '${PARAMETER:=WORD}' |
1623 | If PARAMETER is unset or null, the expansion of WORD is assigned to | |
1624 | PARAMETER. The value of PARAMETER is then substituted. Positional | |
1625 | parameters and special parameters may not be assigned to in this | |
1626 | way. | |
ccc6cda3 | 1627 | |
8a0829e9 | 1628 | '${PARAMETER:?WORD}' |
ccc6cda3 JA |
1629 | If PARAMETER is null or unset, the expansion of WORD (or a message |
1630 | to that effect if WORD is not present) is written to the standard | |
1631 | error and the shell, if it is not interactive, exits. Otherwise, | |
1632 | the value of PARAMETER is substituted. | |
1633 | ||
8a0829e9 | 1634 | '${PARAMETER:+WORD}' |
ccc6cda3 JA |
1635 | If PARAMETER is null or unset, nothing is substituted, otherwise |
1636 | the expansion of WORD is substituted. | |
1637 | ||
8a0829e9 CR |
1638 | '${PARAMETER:OFFSET}' |
1639 | '${PARAMETER:OFFSET:LENGTH}' | |
9f178efb CR |
1640 | This is referred to as Substring Expansion. It expands to up to |
1641 | LENGTH characters of the value of PARAMETER starting at the | |
8a0829e9 CR |
1642 | character specified by OFFSET. If PARAMETER is '@', an indexed |
1643 | array subscripted by '@' or '*', or an associative array name, the | |
9f178efb CR |
1644 | results differ as described below. If LENGTH is omitted, it |
1645 | expands to the substring of the value of PARAMETER starting at the | |
1646 | character specified by OFFSET and extending to the end of the | |
1647 | value. LENGTH and OFFSET are arithmetic expressions (*note Shell | |
1648 | Arithmetic::). | |
ccc6cda3 | 1649 | |
ccc6cda3 | 1650 | If OFFSET evaluates to a number less than zero, the value is used |
9f178efb CR |
1651 | as an offset in characters from the end of the value of PARAMETER. |
1652 | If LENGTH evaluates to a number less than zero, it is interpreted | |
1653 | as an offset in characters from the end of the value of PARAMETER | |
1654 | rather than a number of characters, and the expansion is the | |
1655 | characters between OFFSET and that result. Note that a negative | |
1656 | offset must be separated from the colon by at least one space to | |
8a0829e9 | 1657 | avoid being confused with the ':-' expansion. |
9f178efb CR |
1658 | |
1659 | Here are some examples illustrating substring expansion on | |
1660 | parameters and subscripted arrays: | |
1661 | ||
1662 | $ string=01234567890abcdefgh | |
1663 | $ echo ${string:7} | |
1664 | 7890abcdefgh | |
1665 | $ echo ${string:7:0} | |
1666 | ||
1667 | $ echo ${string:7:2} | |
1668 | 78 | |
1669 | $ echo ${string:7:-2} | |
1670 | 7890abcdef | |
1671 | $ echo ${string: -7} | |
1672 | bcdefgh | |
1673 | $ echo ${string: -7:0} | |
1674 | ||
1675 | $ echo ${string: -7:2} | |
1676 | bc | |
1677 | $ echo ${string: -7:-2} | |
1678 | bcdef | |
1679 | $ set -- 01234567890abcdefgh | |
1680 | $ echo ${1:7} | |
1681 | 7890abcdefgh | |
1682 | $ echo ${1:7:0} | |
1683 | ||
1684 | $ echo ${1:7:2} | |
1685 | 78 | |
1686 | $ echo ${1:7:-2} | |
1687 | 7890abcdef | |
1688 | $ echo ${1: -7} | |
1689 | bcdefgh | |
1690 | $ echo ${1: -7:0} | |
1691 | ||
1692 | $ echo ${1: -7:2} | |
1693 | bc | |
1694 | $ echo ${1: -7:-2} | |
1695 | bcdef | |
1696 | $ array[0]=01234567890abcdefgh | |
1697 | $ echo ${array[0]:7} | |
1698 | 7890abcdefgh | |
1699 | $ echo ${array[0]:7:0} | |
1700 | ||
1701 | $ echo ${array[0]:7:2} | |
1702 | 78 | |
1703 | $ echo ${array[0]:7:-2} | |
1704 | 7890abcdef | |
1705 | $ echo ${array[0]: -7} | |
1706 | bcdefgh | |
1707 | $ echo ${array[0]: -7:0} | |
1708 | ||
1709 | $ echo ${array[0]: -7:2} | |
1710 | bc | |
1711 | $ echo ${array[0]: -7:-2} | |
1712 | bcdef | |
1713 | ||
8a0829e9 | 1714 | If PARAMETER is '@', the result is LENGTH positional parameters |
9f178efb CR |
1715 | beginning at OFFSET. A negative OFFSET is taken relative to one |
1716 | greater than the greatest positional parameter, so an offset of -1 | |
1717 | evaluates to the last positional parameter. It is an expansion | |
1718 | error if LENGTH evaluates to a number less than zero. | |
1719 | ||
1720 | The following examples illustrate substring expansion using | |
1721 | positional parameters: | |
1722 | ||
1723 | $ set -- 1 2 3 4 5 6 7 8 9 0 a b c d e f g h | |
1724 | $ echo ${@:7} | |
1725 | 7 8 9 0 a b c d e f g h | |
1726 | $ echo ${@:7:0} | |
1727 | ||
1728 | $ echo ${@:7:2} | |
1729 | 7 8 | |
1730 | $ echo ${@:7:-2} | |
1731 | bash: -2: substring expression < 0 | |
1732 | $ echo ${@: -7:2} | |
1733 | b c | |
1734 | $ echo ${@:0} | |
1735 | ./bash 1 2 3 4 5 6 7 8 9 0 a b c d e f g h | |
1736 | $ echo ${@:0:2} | |
1737 | ./bash 1 | |
1738 | $ echo ${@: -7:0} | |
1739 | ||
8a0829e9 CR |
1740 | |
1741 | If PARAMETER is an indexed array name subscripted by '@' or '*', | |
9f178efb | 1742 | the result is the LENGTH members of the array beginning with |
8a0829e9 CR |
1743 | '${PARAMETER[OFFSET]}'. A negative OFFSET is taken relative to one |
1744 | greater than the maximum index of the specified array. It is an | |
1745 | expansion error if LENGTH evaluates to a number less than zero. | |
9f178efb CR |
1746 | |
1747 | These examples show how you can use substring expansion with | |
1748 | indexed arrays: | |
1749 | ||
1750 | $ array=(0 1 2 3 4 5 6 7 8 9 0 a b c d e f g h) | |
1751 | $ echo ${array[@]:7} | |
1752 | 7 8 9 0 a b c d e f g h | |
1753 | $ echo ${array[@]:7:2} | |
1754 | 7 8 | |
1755 | $ echo ${array[@]: -7:2} | |
1756 | b c | |
1757 | $ echo ${array[@]: -7:-2} | |
1758 | bash: -2: substring expression < 0 | |
1759 | $ echo ${array[@]:0} | |
1760 | 0 1 2 3 4 5 6 7 8 9 0 a b c d e f g h | |
1761 | $ echo ${array[@]:0:2} | |
1762 | 0 1 | |
1763 | $ echo ${array[@]: -7:0} | |
1764 | ||
8a0829e9 | 1765 | |
9f178efb CR |
1766 | Substring expansion applied to an associative array produces |
1767 | undefined results. | |
1768 | ||
eb2bb562 | 1769 | Substring indexing is zero-based unless the positional parameters |
d3ad40de | 1770 | are used, in which case the indexing starts at 1 by default. If |
8a0829e9 | 1771 | OFFSET is 0, and the positional parameters are used, '$@' is |
d3ad40de | 1772 | prefixed to the list. |
ccc6cda3 | 1773 | |
8a0829e9 CR |
1774 | '${!PREFIX*}' |
1775 | '${!PREFIX@}' | |
bb70624e | 1776 | Expands to the names of variables whose names begin with PREFIX, |
8a0829e9 CR |
1777 | separated by the first character of the 'IFS' special variable. |
1778 | When '@' is used and the expansion appears within double quotes, | |
d3ad40de | 1779 | each variable name expands to a separate word. |
bb70624e | 1780 | |
8a0829e9 CR |
1781 | '${!NAME[@]}' |
1782 | '${!NAME[*]}' | |
d3a24ed2 CR |
1783 | If NAME is an array variable, expands to the list of array indices |
1784 | (keys) assigned in NAME. If NAME is not an array, expands to 0 if | |
8a0829e9 CR |
1785 | NAME is set and null otherwise. When '@' is used and the expansion |
1786 | appears within double quotes, each key expands to a separate word. | |
d3a24ed2 | 1787 | |
8a0829e9 | 1788 | '${#PARAMETER}' |
cce855bc | 1789 | The length in characters of the expanded value of PARAMETER is |
8a0829e9 CR |
1790 | substituted. If PARAMETER is '*' or '@', the value substituted is |
1791 | the number of positional parameters. If PARAMETER is an array name | |
1792 | subscripted by '*' or '@', the value substituted is the number of | |
1793 | elements in the array. If PARAMETER is an indexed array name | |
1794 | subscripted by a negative number, that number is interpreted as | |
1795 | relative to one greater than the maximum index of PARAMETER, so | |
1796 | negative indices count back from the end of the array, and an index | |
1797 | of -1 references the last element. | |
1798 | ||
1799 | '${PARAMETER#WORD}' | |
1800 | '${PARAMETER##WORD}' | |
ccc6cda3 | 1801 | The WORD is expanded to produce a pattern just as in filename |
8a0829e9 CR |
1802 | expansion (*note Filename Expansion::). If the pattern matches the |
1803 | beginning of the expanded value of PARAMETER, then the result of | |
1804 | the expansion is the expanded value of PARAMETER with the shortest | |
1805 | matching pattern (the '#' case) or the longest matching pattern | |
1806 | (the '##' case) deleted. If PARAMETER is '@' or '*', the pattern | |
1807 | removal operation is applied to each positional parameter in turn, | |
1808 | and the expansion is the resultant list. If PARAMETER is an array | |
1809 | variable subscripted with '@' or '*', the pattern removal operation | |
1810 | is applied to each member of the array in turn, and the expansion | |
1811 | is the resultant list. | |
1812 | ||
1813 | '${PARAMETER%WORD}' | |
1814 | '${PARAMETER%%WORD}' | |
ccc6cda3 | 1815 | The WORD is expanded to produce a pattern just as in filename |
cce855bc JA |
1816 | expansion. If the pattern matches a trailing portion of the |
1817 | expanded value of PARAMETER, then the result of the expansion is | |
8a0829e9 CR |
1818 | the value of PARAMETER with the shortest matching pattern (the '%' |
1819 | case) or the longest matching pattern (the '%%' case) deleted. If | |
1820 | PARAMETER is '@' or '*', the pattern removal operation is applied | |
cce855bc | 1821 | to each positional parameter in turn, and the expansion is the |
8a0829e9 CR |
1822 | resultant list. If PARAMETER is an array variable subscripted with |
1823 | '@' or '*', the pattern removal operation is applied to each member | |
1824 | of the array in turn, and the expansion is the resultant list. | |
1825 | ||
1826 | '${PARAMETER/PATTERN/STRING}' | |
ccc6cda3 | 1827 | |
ccc6cda3 JA |
1828 | The PATTERN is expanded to produce a pattern just as in filename |
1829 | expansion. PARAMETER is expanded and the longest match of PATTERN | |
ac18b312 | 1830 | against its value is replaced with STRING. If PATTERN begins with |
8a0829e9 CR |
1831 | '/', all matches of PATTERN are replaced with STRING. Normally |
1832 | only the first match is replaced. If PATTERN begins with '#', it | |
1833 | must match at the beginning of the expanded value of PARAMETER. If | |
1834 | PATTERN begins with '%', it must match at the end of the expanded | |
1835 | value of PARAMETER. If STRING is null, matches of PATTERN are | |
1836 | deleted and the '/' following PATTERN may be omitted. If the | |
1837 | 'nocasematch' shell option (see the description of 'shopt' in *note | |
1838 | The Shopt Builtin::) is enabled, the match is performed without | |
1839 | regard to the case of alphabetic characters. If PARAMETER is '@' | |
1840 | or '*', the substitution operation is applied to each positional | |
1841 | parameter in turn, and the expansion is the resultant list. If | |
1842 | PARAMETER is an array variable subscripted with '@' or '*', the | |
1843 | substitution operation is applied to each member of the array in | |
1844 | turn, and the expansion is the resultant list. | |
1845 | ||
1846 | '${PARAMETER^PATTERN}' | |
1847 | '${PARAMETER^^PATTERN}' | |
1848 | '${PARAMETER,PATTERN}' | |
1849 | '${PARAMETER,,PATTERN}' | |
09767ff0 CR |
1850 | This expansion modifies the case of alphabetic characters in |
1851 | PARAMETER. The PATTERN is expanded to produce a pattern just as in | |
45c0f7f8 CR |
1852 | filename expansion. Each character in the expanded value of |
1853 | PARAMETER is tested against PATTERN, and, if it matches the | |
1854 | pattern, its case is converted. The pattern should not attempt to | |
8a0829e9 CR |
1855 | match more than one character. The '^' operator converts lowercase |
1856 | letters matching PATTERN to uppercase; the ',' operator converts | |
1857 | matching uppercase letters to lowercase. The '^^' and ',,' | |
1858 | expansions convert each matched character in the expanded value; | |
1859 | the '^' and ',' expansions match and convert only the first | |
45c0f7f8 | 1860 | character in the expanded value. If PATTERN is omitted, it is |
8a0829e9 CR |
1861 | treated like a '?', which matches every character. If PARAMETER is |
1862 | '@' or '*', the case modification operation is applied to each | |
45c0f7f8 | 1863 | positional parameter in turn, and the expansion is the resultant |
8a0829e9 CR |
1864 | list. If PARAMETER is an array variable subscripted with '@' or |
1865 | '*', the case modification operation is applied to each member of | |
45c0f7f8 | 1866 | the array in turn, and the expansion is the resultant list. |
09767ff0 | 1867 | |
8a0829e9 CR |
1868 | '${PARAMETER@OPERATOR}' |
1869 | The expansion is either a transformation of the value of PARAMETER | |
1870 | or information about PARAMETER itself, depending on the value of | |
1871 | OPERATOR. Each OPERATOR is a single letter: | |
1872 | ||
1873 | 'Q' | |
1874 | The expansion is a string that is the value of PARAMETER | |
1875 | quoted in a format that can be reused as input. | |
1876 | 'E' | |
1877 | The expansion is a string that is the value of PARAMETER with | |
1878 | backslash escape sequences expanded as with the '$'...'' | |
1879 | quoting mechansim. | |
1880 | 'P' | |
1881 | The expansion is a string that is the result of expanding the | |
1882 | value of PARAMETER as if it were a prompt string (*note | |
1883 | Controlling the Prompt::). | |
1884 | 'A' | |
54a5fbe1 CR |
1885 | The expansion is a string in the form of an assignment |
1886 | statement or 'declare' command that, if evaluated, will | |
1887 | recreate PARAMETER with its attributes and value. | |
8a0829e9 CR |
1888 | 'a' |
1889 | The expansion is a string consisting of flag values | |
1890 | representing PARAMETER's attributes. | |
1891 | ||
1892 | If PARAMETER is '@' or '*', the operation is applied to each | |
1893 | positional parameter in turn, and the expansion is the resultant | |
1894 | list. If PARAMETER is an array variable subscripted with '@' or | |
1895 | '*', the operation is applied to each member of the array in turn, | |
1896 | and the expansion is the resultant list. | |
1897 | ||
1898 | The result of the expansion is subject to word splitting and | |
1899 | pathname expansion as described below. | |
1900 | ||
ccc6cda3 | 1901 | \1f |
cce855bc | 1902 | File: bashref.info, Node: Command Substitution, Next: Arithmetic Expansion, Prev: Shell Parameter Expansion, Up: Shell Expansions |
ccc6cda3 | 1903 | |
37c41ab1 CR |
1904 | 3.5.4 Command Substitution |
1905 | -------------------------- | |
ccc6cda3 | 1906 | |
37c41ab1 | 1907 | Command substitution allows the output of a command to replace the |
bb70624e JA |
1908 | command itself. Command substitution occurs when a command is enclosed |
1909 | as follows: | |
ccc6cda3 | 1910 | $(COMMAND) |
8a0829e9 | 1911 | or |
ccc6cda3 JA |
1912 | `COMMAND` |
1913 | ||
690150f9 CR |
1914 | Bash performs the expansion by executing COMMAND in a subshell |
1915 | environment and replacing the command substitution with the standard | |
1916 | output of the command, with any trailing newlines deleted. Embedded | |
1917 | newlines are not deleted, but they may be removed during word splitting. | |
1918 | The command substitution '$(cat FILE)' can be replaced by the equivalent | |
1919 | but faster '$(< FILE)'. | |
ccc6cda3 JA |
1920 | |
1921 | When the old-style backquote form of substitution is used, backslash | |
8a0829e9 | 1922 | retains its literal meaning except when followed by '$', '`', or '\'. |
cce855bc | 1923 | The first backquote not preceded by a backslash terminates the command |
8a0829e9 | 1924 | substitution. When using the '$(COMMAND)' form, all characters between |
cce855bc | 1925 | the parentheses make up the command; none are treated specially. |
ccc6cda3 | 1926 | |
cce855bc JA |
1927 | Command substitutions may be nested. To nest when using the |
1928 | backquoted form, escape the inner backquotes with backslashes. | |
ccc6cda3 JA |
1929 | |
1930 | If the substitution appears within double quotes, word splitting and | |
1931 | filename expansion are not performed on the results. | |
1932 | ||
1933 | \1f | |
cce855bc JA |
1934 | File: bashref.info, Node: Arithmetic Expansion, Next: Process Substitution, Prev: Command Substitution, Up: Shell Expansions |
1935 | ||
37c41ab1 CR |
1936 | 3.5.5 Arithmetic Expansion |
1937 | -------------------------- | |
cce855bc | 1938 | |
37c41ab1 | 1939 | Arithmetic expansion allows the evaluation of an arithmetic expression |
8a0829e9 CR |
1940 | and the substitution of the result. The format for arithmetic expansion |
1941 | is: | |
cce855bc JA |
1942 | |
1943 | $(( EXPRESSION )) | |
1944 | ||
1945 | The expression is treated as if it were within double quotes, but a | |
1946 | double quote inside the parentheses is not treated specially. All | |
1101193a CR |
1947 | tokens in the expression undergo parameter and variable expansion, |
1948 | command substitution, and quote removal. The result is treated as the | |
1949 | arithmetic expression to be evaluated. Arithmetic expansions may be | |
1950 | nested. | |
cce855bc JA |
1951 | |
1952 | The evaluation is performed according to the rules listed below | |
8a0829e9 CR |
1953 | (*note Shell Arithmetic::). If the expression is invalid, Bash prints a |
1954 | message indicating failure to the standard error and no substitution | |
cce855bc JA |
1955 | occurs. |
1956 | ||
1957 | \1f | |
1958 | File: bashref.info, Node: Process Substitution, Next: Word Splitting, Prev: Arithmetic Expansion, Up: Shell Expansions | |
ccc6cda3 | 1959 | |
37c41ab1 CR |
1960 | 3.5.6 Process Substitution |
1961 | -------------------------- | |
ccc6cda3 | 1962 | |
690150f9 CR |
1963 | Process substitution allows a process's input or output to be referred |
1964 | to using a filename. It takes the form of | |
ccc6cda3 | 1965 | <(LIST) |
8a0829e9 | 1966 | or |
ccc6cda3 | 1967 | >(LIST) |
690150f9 CR |
1968 | The process LIST is run asynchronously, and its input or output appears |
1969 | as a filename. This filename is passed as an argument to the current | |
1970 | command as the result of the expansion. If the '>(LIST)' form is used, | |
1971 | writing to the file will provide input for LIST. If the '<(LIST)' form | |
1972 | is used, the file passed as an argument should be read to obtain the | |
1973 | output of LIST. Note that no space may appear between the '<' or '>' | |
1974 | and the left parenthesis, otherwise the construct would be interpreted | |
1975 | as a redirection. Process substitution is supported on systems that | |
1976 | support named pipes (FIFOs) or the '/dev/fd' method of naming open | |
1977 | files. | |
ccc6cda3 | 1978 | |
cce855bc JA |
1979 | When available, process substitution is performed simultaneously with |
1980 | parameter and variable expansion, command substitution, and arithmetic | |
1981 | expansion. | |
ccc6cda3 JA |
1982 | |
1983 | \1f | |
1984 | File: bashref.info, Node: Word Splitting, Next: Filename Expansion, Prev: Process Substitution, Up: Shell Expansions | |
1985 | ||
37c41ab1 CR |
1986 | 3.5.7 Word Splitting |
1987 | -------------------- | |
ccc6cda3 | 1988 | |
37c41ab1 | 1989 | The shell scans the results of parameter expansion, command |
ccc6cda3 JA |
1990 | substitution, and arithmetic expansion that did not occur within double |
1991 | quotes for word splitting. | |
1992 | ||
8a0829e9 CR |
1993 | The shell treats each character of '$IFS' as a delimiter, and splits |
1994 | the results of the other expansions into words using these characters as | |
1995 | field terminators. If 'IFS' is unset, or its value is exactly | |
1996 | '<space><tab><newline>', the default, then sequences of ' <space>', | |
1997 | '<tab>', and '<newline>' at the beginning and end of the results of the | |
1998 | previous expansions are ignored, and any sequence of 'IFS' characters | |
1999 | not at the beginning or end serves to delimit words. If 'IFS' has a | |
1101193a | 2000 | value other than the default, then sequences of the whitespace |
690150f9 CR |
2001 | characters 'space', 'tab', and 'newline' are ignored at the beginning |
2002 | and end of the word, as long as the whitespace character is in the value | |
2003 | of 'IFS' (an 'IFS' whitespace character). Any character in 'IFS' that | |
2004 | is not 'IFS' whitespace, along with any adjacent 'IFS' whitespace | |
2005 | characters, delimits a field. A sequence of 'IFS' whitespace characters | |
2006 | is also treated as a delimiter. If the value of 'IFS' is null, no word | |
1101193a | 2007 | splitting occurs. |
ccc6cda3 | 2008 | |
690150f9 CR |
2009 | Explicit null arguments ('""' or '''') are retained and passed to |
2010 | commands as empty strings. Unquoted implicit null arguments, resulting | |
2011 | from the expansion of parameters that have no values, are removed. If a | |
2012 | parameter with no value is expanded within double quotes, a null | |
2013 | argument results and is retained and passed to a command as an empty | |
2014 | string. When a quoted null argument appears as part of a word whose | |
2015 | expansion is non-null, the null argument is removed. That is, the word | |
2016 | '-d''' becomes '-d' after word splitting and null argument removal. | |
ccc6cda3 JA |
2017 | |
2018 | Note that if no expansion occurs, no splitting is performed. | |
2019 | ||
2020 | \1f | |
2021 | File: bashref.info, Node: Filename Expansion, Next: Quote Removal, Prev: Word Splitting, Up: Shell Expansions | |
2022 | ||
37c41ab1 CR |
2023 | 3.5.8 Filename Expansion |
2024 | ------------------------ | |
ccc6cda3 | 2025 | |
cce855bc JA |
2026 | * Menu: |
2027 | ||
2028 | * Pattern Matching:: How the shell matches patterns. | |
2029 | ||
8a0829e9 CR |
2030 | After word splitting, unless the '-f' option has been set (*note The Set |
2031 | Builtin::), Bash scans each word for the characters '*', '?', and '['. | |
2032 | If one of these characters appears, then the word is regarded as a | |
2033 | PATTERN, and replaced with an alphabetically sorted list of filenames | |
122f603c | 2034 | matching the pattern (*note Pattern Matching::). If no matching |
8a0829e9 CR |
2035 | filenames are found, and the shell option 'nullglob' is disabled, the |
2036 | word is left unchanged. If the 'nullglob' option is set, and no matches | |
2037 | are found, the word is removed. If the 'failglob' shell option is set, | |
2038 | and no matches are found, an error message is printed and the command is | |
2039 | not executed. If the shell option 'nocaseglob' is enabled, the match is | |
2040 | performed without regard to the case of alphabetic characters. | |
2041 | ||
2042 | When a pattern is used for filename expansion, the character '.' at | |
2043 | the start of a filename or immediately following a slash must be matched | |
2044 | explicitly, unless the shell option 'dotglob' is set. When matching a | |
2045 | filename, the slash character must always be matched explicitly. In | |
2046 | other cases, the '.' character is not treated specially. | |
2047 | ||
2048 | See the description of 'shopt' in *note The Shopt Builtin::, for a | |
2049 | description of the 'nocaseglob', 'nullglob', 'failglob', and 'dotglob' | |
5e13499c | 2050 | options. |
ccc6cda3 | 2051 | |
8a0829e9 CR |
2052 | The 'GLOBIGNORE' shell variable may be used to restrict the set of |
2053 | filenames matching a pattern. If 'GLOBIGNORE' is set, each matching | |
2054 | filename that also matches one of the patterns in 'GLOBIGNORE' is | |
2055 | removed from the list of matches. If the 'nocaseglob' option is set, | |
2056 | the matching against the patterns in 'GLOBIGNORE' is performed without | |
2057 | regard to case. The filenames '.' and '..' are always ignored when | |
2058 | 'GLOBIGNORE' is set and not null. However, setting 'GLOBIGNORE' to a | |
2059 | non-null value has the effect of enabling the 'dotglob' shell option, so | |
2060 | all other filenames beginning with a '.' will match. To get the old | |
2061 | behavior of ignoring filenames beginning with a '.', make '.*' one of | |
2062 | the patterns in 'GLOBIGNORE'. The 'dotglob' option is disabled when | |
2063 | 'GLOBIGNORE' is unset. | |
ccc6cda3 | 2064 | |
cce855bc JA |
2065 | \1f |
2066 | File: bashref.info, Node: Pattern Matching, Up: Filename Expansion | |
2067 | ||
37c41ab1 CR |
2068 | 3.5.8.1 Pattern Matching |
2069 | ........................ | |
cce855bc | 2070 | |
37c41ab1 CR |
2071 | Any character that appears in a pattern, other than the special pattern |
2072 | characters described below, matches itself. The NUL character may not | |
2073 | occur in a pattern. A backslash escapes the following character; the | |
2074 | escaping backslash is discarded when matching. The special pattern | |
2075 | characters must be quoted if they are to be matched literally. | |
cce855bc | 2076 | |
ccc6cda3 | 2077 | The special pattern characters have the following meanings: |
8a0829e9 CR |
2078 | '*' |
2079 | Matches any string, including the null string. When the 'globstar' | |
2080 | shell option is enabled, and '*' is used in a filename expansion | |
2081 | context, two adjacent '*'s used as a single pattern will match all | |
2082 | files and zero or more directories and subdirectories. If followed | |
2083 | by a '/', two adjacent '*'s will match only directories and | |
2084 | subdirectories. | |
2085 | '?' | |
ccc6cda3 | 2086 | Matches any single character. |
8a0829e9 | 2087 | '[...]' |
ccc6cda3 | 2088 | Matches any one of the enclosed characters. A pair of characters |
28ef6c31 | 2089 | separated by a hyphen denotes a RANGE EXPRESSION; any character |
ad4aef08 | 2090 | that falls between those two characters, inclusive, using the |
28ef6c31 | 2091 | current locale's collating sequence and character set, is matched. |
8a0829e9 CR |
2092 | If the first character following the '[' is a '!' or a '^' then any |
2093 | character not enclosed is matched. A '-' may be matched by | |
2094 | including it as the first or last character in the set. A ']' may | |
28ef6c31 JA |
2095 | be matched by including it as the first character in the set. The |
2096 | sorting order of characters in range expressions is determined by | |
8a0829e9 | 2097 | the current locale and the values of the 'LC_COLLATE' and 'LC_ALL' |
74d0116b | 2098 | shell variables, if set. |
28ef6c31 | 2099 | |
8a0829e9 CR |
2100 | For example, in the default C locale, '[a-dx-z]' is equivalent to |
2101 | '[abcdxyz]'. Many locales sort characters in dictionary order, and | |
2102 | in these locales '[a-dx-z]' is typically not equivalent to | |
2103 | '[abcdxyz]'; it might be equivalent to '[aBbCcDdxXyYz]', for | |
28ef6c31 JA |
2104 | example. To obtain the traditional interpretation of ranges in |
2105 | bracket expressions, you can force the use of the C locale by | |
8a0829e9 CR |
2106 | setting the 'LC_COLLATE' or 'LC_ALL' environment variable to the |
2107 | value 'C', or enable the 'globasciiranges' shell option. | |
ccc6cda3 | 2108 | |
8a0829e9 CR |
2109 | Within '[' and ']', CHARACTER CLASSES can be specified using the |
2110 | syntax '[:'CLASS':]', where CLASS is one of the following classes | |
ac18b312 | 2111 | defined in the POSIX standard: |
cce855bc | 2112 | alnum alpha ascii blank cntrl digit graph lower |
7117c2d2 | 2113 | print punct space upper word xdigit |
cce855bc | 2114 | A character class matches any character belonging to that class. |
8a0829e9 CR |
2115 | The 'word' character class matches letters, digits, and the |
2116 | character '_'. | |
cce855bc | 2117 | |
8a0829e9 CR |
2118 | Within '[' and ']', an EQUIVALENCE CLASS can be specified using the |
2119 | syntax '[='C'=]', which matches all characters with the same | |
cce855bc JA |
2120 | collation weight (as defined by the current locale) as the |
2121 | character C. | |
2122 | ||
8a0829e9 CR |
2123 | Within '[' and ']', the syntax '[.'SYMBOL'.]' matches the collating |
2124 | symbol SYMBOL. | |
cce855bc | 2125 | |
8a0829e9 | 2126 | If the 'extglob' shell option is enabled using the 'shopt' builtin, |
cce855bc JA |
2127 | several extended pattern matching operators are recognized. In the |
2128 | following description, a PATTERN-LIST is a list of one or more patterns | |
8a0829e9 | 2129 | separated by a '|'. Composite patterns may be formed using one or more |
cce855bc JA |
2130 | of the following sub-patterns: |
2131 | ||
8a0829e9 | 2132 | '?(PATTERN-LIST)' |
cce855bc JA |
2133 | Matches zero or one occurrence of the given patterns. |
2134 | ||
8a0829e9 | 2135 | '*(PATTERN-LIST)' |
cce855bc JA |
2136 | Matches zero or more occurrences of the given patterns. |
2137 | ||
8a0829e9 | 2138 | '+(PATTERN-LIST)' |
cce855bc JA |
2139 | Matches one or more occurrences of the given patterns. |
2140 | ||
8a0829e9 | 2141 | '@(PATTERN-LIST)' |
eb2bb562 | 2142 | Matches one of the given patterns. |
cce855bc | 2143 | |
8a0829e9 | 2144 | '!(PATTERN-LIST)' |
cce855bc JA |
2145 | Matches anything except one of the given patterns. |
2146 | ||
ccc6cda3 JA |
2147 | \1f |
2148 | File: bashref.info, Node: Quote Removal, Prev: Filename Expansion, Up: Shell Expansions | |
2149 | ||
37c41ab1 CR |
2150 | 3.5.9 Quote Removal |
2151 | ------------------- | |
ccc6cda3 | 2152 | |
37c41ab1 | 2153 | After the preceding expansions, all unquoted occurrences of the |
8a0829e9 | 2154 | characters '\', ''', and '"' that did not result from one of the above |
ccc6cda3 JA |
2155 | expansions are removed. |
2156 | ||
2157 | \1f | |
2158 | File: bashref.info, Node: Redirections, Next: Executing Commands, Prev: Shell Expansions, Up: Basic Shell Features | |
2159 | ||
37c41ab1 CR |
2160 | 3.6 Redirections |
2161 | ================ | |
ccc6cda3 | 2162 | |
37c41ab1 | 2163 | Before a command is executed, its input and output may be REDIRECTED |
abe2eb5b CR |
2164 | using a special notation interpreted by the shell. Redirection allows |
2165 | commands' file handles to be duplicated, opened, closed, made to refer | |
2166 | to different files, and can change the files the command reads from and | |
2167 | writes to. Redirection may also be used to modify file handles in the | |
2168 | current shell execution environment. The following redirection | |
2169 | operators may precede or appear anywhere within a simple command or may | |
2170 | follow a command. Redirections are processed in the order they appear, | |
2171 | from left to right. | |
ccc6cda3 | 2172 | |
8a0829e9 CR |
2173 | Each redirection that may be preceded by a file descriptor number may |
2174 | instead be preceded by a word of the form {VARNAME}. In this case, for | |
2175 | each redirection operator except >&- and <&-, the shell will allocate a | |
2176 | file descriptor greater than 10 and assign it to {VARNAME}. If >&- or | |
2177 | <&- is preceded by {VARNAME}, the value of VARNAME defines the file | |
2178 | descriptor to close. | |
a8fd3f3e | 2179 | |
ccc6cda3 | 2180 | In the following descriptions, if the file descriptor number is |
8a0829e9 CR |
2181 | omitted, and the first character of the redirection operator is '<', the |
2182 | redirection refers to the standard input (file descriptor 0). If the | |
2183 | first character of the redirection operator is '>', the redirection | |
ccc6cda3 JA |
2184 | refers to the standard output (file descriptor 1). |
2185 | ||
cce855bc JA |
2186 | The word following the redirection operator in the following |
2187 | descriptions, unless otherwise noted, is subjected to brace expansion, | |
2188 | tilde expansion, parameter expansion, command substitution, arithmetic | |
8a0829e9 CR |
2189 | expansion, quote removal, filename expansion, and word splitting. If it |
2190 | expands to more than one word, Bash reports an error. | |
ccc6cda3 | 2191 | |
8a0829e9 CR |
2192 | Note that the order of redirections is significant. For example, the |
2193 | command | |
ccc6cda3 | 2194 | ls > DIRLIST 2>&1 |
8a0829e9 | 2195 | directs both standard output (file descriptor 1) and standard error |
bb70624e | 2196 | (file descriptor 2) to the file DIRLIST, while the command |
ccc6cda3 | 2197 | ls 2>&1 > DIRLIST |
8a0829e9 CR |
2198 | directs only the standard output to file DIRLIST, because the standard |
2199 | error was made a copy of the standard output before the standard output | |
2200 | was redirected to DIRLIST. | |
ccc6cda3 | 2201 | |
bb70624e JA |
2202 | Bash handles several filenames specially when they are used in |
2203 | redirections, as described in the following table: | |
2204 | ||
8a0829e9 | 2205 | '/dev/fd/FD' |
bb70624e JA |
2206 | If FD is a valid integer, file descriptor FD is duplicated. |
2207 | ||
8a0829e9 | 2208 | '/dev/stdin' |
bb70624e JA |
2209 | File descriptor 0 is duplicated. |
2210 | ||
8a0829e9 | 2211 | '/dev/stdout' |
bb70624e JA |
2212 | File descriptor 1 is duplicated. |
2213 | ||
8a0829e9 | 2214 | '/dev/stderr' |
bb70624e JA |
2215 | File descriptor 2 is duplicated. |
2216 | ||
8a0829e9 | 2217 | '/dev/tcp/HOST/PORT' |
bb70624e | 2218 | If HOST is a valid hostname or Internet address, and PORT is an |
9f178efb CR |
2219 | integer port number or service name, Bash attempts to open the |
2220 | corresponding TCP socket. | |
bb70624e | 2221 | |
8a0829e9 | 2222 | '/dev/udp/HOST/PORT' |
bb70624e | 2223 | If HOST is a valid hostname or Internet address, and PORT is an |
9f178efb CR |
2224 | integer port number or service name, Bash attempts to open the |
2225 | corresponding UDP socket. | |
bb70624e | 2226 | |
cce855bc JA |
2227 | A failure to open or create a file causes the redirection to fail. |
2228 | ||
eb2bb562 CR |
2229 | Redirections using file descriptors greater than 9 should be used |
2230 | with care, as they may conflict with file descriptors the shell uses | |
2231 | internally. | |
2232 | ||
37c41ab1 CR |
2233 | 3.6.1 Redirecting Input |
2234 | ----------------------- | |
ccc6cda3 | 2235 | |
37c41ab1 | 2236 | Redirection of input causes the file whose name results from the |
8a0829e9 CR |
2237 | expansion of WORD to be opened for reading on file descriptor 'n', or |
2238 | the standard input (file descriptor 0) if 'n' is not specified. | |
ccc6cda3 JA |
2239 | |
2240 | The general format for redirecting input is: | |
7117c2d2 | 2241 | [N]<WORD |
ccc6cda3 | 2242 | |
37c41ab1 CR |
2243 | 3.6.2 Redirecting Output |
2244 | ------------------------ | |
ccc6cda3 | 2245 | |
37c41ab1 | 2246 | Redirection of output causes the file whose name results from the |
7117c2d2 JA |
2247 | expansion of WORD to be opened for writing on file descriptor N, or the |
2248 | standard output (file descriptor 1) if N is not specified. If the file | |
2249 | does not exist it is created; if it does exist it is truncated to zero | |
2250 | size. | |
ccc6cda3 JA |
2251 | |
2252 | The general format for redirecting output is: | |
7117c2d2 | 2253 | [N]>[|]WORD |
ccc6cda3 | 2254 | |
8a0829e9 CR |
2255 | If the redirection operator is '>', and the 'noclobber' option to the |
2256 | 'set' builtin has been enabled, the redirection will fail if the file | |
2257 | whose name results from the expansion of WORD exists and is a regular | |
2258 | file. If the redirection operator is '>|', or the redirection operator | |
2259 | is '>' and the 'noclobber' option is not enabled, the redirection is | |
2260 | attempted even if the file named by WORD exists. | |
ccc6cda3 | 2261 | |
37c41ab1 CR |
2262 | 3.6.3 Appending Redirected Output |
2263 | --------------------------------- | |
ccc6cda3 | 2264 | |
8a0829e9 CR |
2265 | Redirection of output in this fashion causes the file whose name results |
2266 | from the expansion of WORD to be opened for appending on file descriptor | |
2267 | N, or the standard output (file descriptor 1) if N is not specified. If | |
2268 | the file does not exist it is created. | |
ccc6cda3 JA |
2269 | |
2270 | The general format for appending output is: | |
7117c2d2 | 2271 | [N]>>WORD |
ccc6cda3 | 2272 | |
37c41ab1 CR |
2273 | 3.6.4 Redirecting Standard Output and Standard Error |
2274 | ---------------------------------------------------- | |
ccc6cda3 | 2275 | |
ed35cb4a CR |
2276 | This construct allows both the standard output (file descriptor 1) and |
2277 | the standard error output (file descriptor 2) to be redirected to the | |
2278 | file whose name is the expansion of WORD. | |
ccc6cda3 JA |
2279 | |
2280 | There are two formats for redirecting standard output and standard | |
2281 | error: | |
2282 | &>WORD | |
8a0829e9 | 2283 | and |
ccc6cda3 | 2284 | >&WORD |
8a0829e9 | 2285 | Of the two forms, the first is preferred. This is semantically |
ccc6cda3 JA |
2286 | equivalent to |
2287 | >WORD 2>&1 | |
8a0829e9 | 2288 | When using the second form, WORD may not expand to a number or '-'. |
77638cbf CR |
2289 | If it does, other redirection operators apply (see Duplicating File |
2290 | Descriptors below) for compatibility reasons. | |
ccc6cda3 | 2291 | |
ed35cb4a CR |
2292 | 3.6.5 Appending Standard Output and Standard Error |
2293 | -------------------------------------------------- | |
2294 | ||
2295 | This construct allows both the standard output (file descriptor 1) and | |
8a0829e9 CR |
2296 | the standard error output (file descriptor 2) to be appended to the file |
2297 | whose name is the expansion of WORD. | |
ed35cb4a CR |
2298 | |
2299 | The format for appending standard output and standard error is: | |
2300 | &>>WORD | |
8a0829e9 | 2301 | This is semantically equivalent to |
ed35cb4a | 2302 | >>WORD 2>&1 |
f6da9f85 | 2303 | (see Duplicating File Descriptors below). |
ed35cb4a CR |
2304 | |
2305 | 3.6.6 Here Documents | |
37c41ab1 | 2306 | -------------------- |
ccc6cda3 | 2307 | |
37c41ab1 | 2308 | This type of redirection instructs the shell to read input from the |
ccc6cda3 JA |
2309 | current source until a line containing only WORD (with no trailing |
2310 | blanks) is seen. All of the lines read up to that point are then used | |
8a0829e9 CR |
2311 | as the standard input (or file descriptor N if N is specified) for a |
2312 | command. | |
ccc6cda3 | 2313 | |
7117c2d2 | 2314 | The format of here-documents is: |
8a0829e9 | 2315 | [N]<<[-]WORD |
ccc6cda3 JA |
2316 | HERE-DOCUMENT |
2317 | DELIMITER | |
2318 | ||
8a0829e9 CR |
2319 | No parameter and variable expansion, command substitution, arithmetic |
2320 | expansion, or filename expansion is performed on WORD. If any | |
2321 | characters in WORD are quoted, the DELIMITER is the result of quote | |
122f603c CR |
2322 | removal on WORD, and the lines in the here-document are not expanded. |
2323 | If WORD is unquoted, all lines of the here-document are subjected to | |
8a0829e9 CR |
2324 | parameter expansion, command substitution, and arithmetic expansion, the |
2325 | character sequence '\newline' is ignored, and '\' must be used to quote | |
2326 | the characters '\', '$', and '`'. | |
ccc6cda3 | 2327 | |
8a0829e9 CR |
2328 | If the redirection operator is '<<-', then all leading tab characters |
2329 | are stripped from input lines and the line containing DELIMITER. This | |
2330 | allows here-documents within shell scripts to be indented in a natural | |
2331 | fashion. | |
ccc6cda3 | 2332 | |
ed35cb4a | 2333 | 3.6.7 Here Strings |
37c41ab1 | 2334 | ------------------ |
7117c2d2 | 2335 | |
37c41ab1 | 2336 | A variant of here documents, the format is: |
8a0829e9 | 2337 | [N]<<< WORD |
7117c2d2 | 2338 | |
122f603c CR |
2339 | The WORD undergoes brace expansion, tilde expansion, parameter and |
2340 | variable expansion, command substitution, arithmetic expansion, and | |
278286c9 | 2341 | quote removal. Pathname expansion and word splitting are not performed. |
690150f9 CR |
2342 | The result is supplied as a single string, with a newline appended, to |
2343 | the command on its standard input (or file descriptor N if N is | |
2344 | specified). | |
7117c2d2 | 2345 | |
ed35cb4a | 2346 | 3.6.8 Duplicating File Descriptors |
37c41ab1 | 2347 | ---------------------------------- |
ccc6cda3 | 2348 | |
37c41ab1 | 2349 | The redirection operator |
7117c2d2 | 2350 | [N]<&WORD |
8a0829e9 CR |
2351 | is used to duplicate input file descriptors. If WORD expands to one or |
2352 | more digits, the file descriptor denoted by N is made to be a copy of | |
2353 | that file descriptor. If the digits in WORD do not specify a file | |
cce855bc | 2354 | descriptor open for input, a redirection error occurs. If WORD |
8a0829e9 | 2355 | evaluates to '-', file descriptor N is closed. If N is not specified, |
7117c2d2 | 2356 | the standard input (file descriptor 0) is used. |
ccc6cda3 JA |
2357 | |
2358 | The operator | |
7117c2d2 | 2359 | [N]>&WORD |
8a0829e9 | 2360 | is used similarly to duplicate output file descriptors. If N is not |
cce855bc JA |
2361 | specified, the standard output (file descriptor 1) is used. If the |
2362 | digits in WORD do not specify a file descriptor open for output, a | |
8a0829e9 CR |
2363 | redirection error occurs. If WORD evaluates to '-', file descriptor N |
2364 | is closed. As a special case, if N is omitted, and WORD does not expand | |
2365 | to one or more digits or '-', the standard output and standard error are | |
2366 | redirected as described previously. | |
7117c2d2 | 2367 | |
ed35cb4a | 2368 | 3.6.9 Moving File Descriptors |
37c41ab1 | 2369 | ----------------------------- |
7117c2d2 | 2370 | |
37c41ab1 | 2371 | The redirection operator |
7117c2d2 | 2372 | [N]<&DIGIT- |
8a0829e9 CR |
2373 | moves the file descriptor DIGIT to file descriptor N, or the standard |
2374 | input (file descriptor 0) if N is not specified. DIGIT is closed after | |
2375 | being duplicated to N. | |
7117c2d2 JA |
2376 | |
2377 | Similarly, the redirection operator | |
2378 | [N]>&DIGIT- | |
8a0829e9 CR |
2379 | moves the file descriptor DIGIT to file descriptor N, or the standard |
2380 | output (file descriptor 1) if N is not specified. | |
7117c2d2 | 2381 | |
ed35cb4a CR |
2382 | 3.6.10 Opening File Descriptors for Reading and Writing |
2383 | ------------------------------------------------------- | |
ccc6cda3 | 2384 | |
37c41ab1 | 2385 | The redirection operator |
7117c2d2 | 2386 | [N]<>WORD |
8a0829e9 | 2387 | causes the file whose name is the expansion of WORD to be opened for |
7117c2d2 JA |
2388 | both reading and writing on file descriptor N, or on file descriptor 0 |
2389 | if N is not specified. If the file does not exist, it is created. | |
ccc6cda3 JA |
2390 | |
2391 | \1f | |
2392 | File: bashref.info, Node: Executing Commands, Next: Shell Scripts, Prev: Redirections, Up: Basic Shell Features | |
2393 | ||
37c41ab1 CR |
2394 | 3.7 Executing Commands |
2395 | ====================== | |
ccc6cda3 JA |
2396 | |
2397 | * Menu: | |
2398 | ||
cce855bc JA |
2399 | * Simple Command Expansion:: How Bash expands simple commands before |
2400 | executing them. | |
ccc6cda3 | 2401 | * Command Search and Execution:: How Bash finds commands and runs them. |
cce855bc JA |
2402 | * Command Execution Environment:: The environment in which Bash |
2403 | executes commands that are not | |
2404 | shell builtins. | |
ccc6cda3 | 2405 | * Environment:: The environment given to a command. |
ccc6cda3 JA |
2406 | * Exit Status:: The status returned by commands and how Bash |
2407 | interprets it. | |
ccc6cda3 JA |
2408 | * Signals:: What happens when Bash or a command it runs |
2409 | receives a signal. | |
2410 | ||
2411 | \1f | |
cce855bc JA |
2412 | File: bashref.info, Node: Simple Command Expansion, Next: Command Search and Execution, Up: Executing Commands |
2413 | ||
37c41ab1 CR |
2414 | 3.7.1 Simple Command Expansion |
2415 | ------------------------------ | |
cce855bc | 2416 | |
37c41ab1 | 2417 | When a simple command is executed, the shell performs the following |
cce855bc JA |
2418 | expansions, assignments, and redirections, from left to right. |
2419 | ||
2420 | 1. The words that the parser has marked as variable assignments (those | |
2421 | preceding the command name) and redirections are saved for later | |
2422 | processing. | |
2423 | ||
2424 | 2. The words that are not variable assignments or redirections are | |
28ef6c31 | 2425 | expanded (*note Shell Expansions::). If any words remain after |
cce855bc JA |
2426 | expansion, the first word is taken to be the name of the command |
2427 | and the remaining words are the arguments. | |
2428 | ||
2429 | 3. Redirections are performed as described above (*note | |
28ef6c31 | 2430 | Redirections::). |
cce855bc | 2431 | |
8a0829e9 | 2432 | 4. The text after the '=' in each variable assignment undergoes tilde |
cce855bc JA |
2433 | expansion, parameter expansion, command substitution, arithmetic |
2434 | expansion, and quote removal before being assigned to the variable. | |
2435 | ||
2436 | If no command name results, the variable assignments affect the | |
2437 | current shell environment. Otherwise, the variables are added to the | |
2438 | environment of the executed command and do not affect the current shell | |
2439 | environment. If any of the assignments attempts to assign a value to a | |
2440 | readonly variable, an error occurs, and the command exits with a | |
2441 | non-zero status. | |
2442 | ||
2443 | If no command name results, redirections are performed, but do not | |
2444 | affect the current shell environment. A redirection error causes the | |
2445 | command to exit with a non-zero status. | |
2446 | ||
2447 | If there is a command name left after expansion, execution proceeds | |
2448 | as described below. Otherwise, the command exits. If one of the | |
2449 | expansions contained a command substitution, the exit status of the | |
2450 | command is the exit status of the last command substitution performed. | |
2451 | If there were no command substitutions, the command exits with a status | |
2452 | of zero. | |
2453 | ||
2454 | \1f | |
2455 | File: bashref.info, Node: Command Search and Execution, Next: Command Execution Environment, Prev: Simple Command Expansion, Up: Executing Commands | |
ccc6cda3 | 2456 | |
37c41ab1 CR |
2457 | 3.7.2 Command Search and Execution |
2458 | ---------------------------------- | |
ccc6cda3 | 2459 | |
37c41ab1 | 2460 | After a command has been split into words, if it results in a simple |
ccc6cda3 JA |
2461 | command and an optional list of arguments, the following actions are |
2462 | taken. | |
2463 | ||
2464 | 1. If the command name contains no slashes, the shell attempts to | |
2465 | locate it. If there exists a shell function by that name, that | |
6a8fd0ed | 2466 | function is invoked as described in *note Shell Functions::. |
ccc6cda3 | 2467 | |
8a0829e9 CR |
2468 | 2. If the name does not match a function, the shell searches for it in |
2469 | the list of shell builtins. If a match is found, that builtin is | |
2470 | invoked. | |
2471 | ||
2472 | 3. If the name is neither a shell function nor a builtin, and contains | |
2473 | no slashes, Bash searches each element of '$PATH' for a directory | |
2474 | containing an executable file by that name. Bash uses a hash table | |
2475 | to remember the full pathnames of executable files to avoid | |
2476 | multiple 'PATH' searches (see the description of 'hash' in *note | |
2477 | Bourne Shell Builtins::). A full search of the directories in | |
2478 | '$PATH' is performed only if the command is not found in the hash | |
2479 | table. If the search is unsuccessful, the shell searches for a | |
2480 | defined shell function named 'command_not_found_handle'. If that | |
2481 | function exists, it is invoked with the original command and the | |
2482 | original command's arguments as its arguments, and the function's | |
2483 | exit status becomes the exit status of the shell. If that function | |
2484 | is not defined, the shell prints an error message and returns an | |
2485 | exit status of 127. | |
2486 | ||
2487 | 4. If the search is successful, or if the command name contains one or | |
2488 | more slashes, the shell executes the named program in a separate | |
2489 | execution environment. Argument 0 is set to the name given, and | |
2490 | the remaining arguments to the command are set to the arguments | |
2491 | supplied, if any. | |
ccc6cda3 JA |
2492 | |
2493 | 5. If this execution fails because the file is not in executable | |
cce855bc | 2494 | format, and the file is not a directory, it is assumed to be a |
6a8fd0ed | 2495 | SHELL SCRIPT and the shell executes it as described in *note Shell |
cce855bc JA |
2496 | Scripts::. |
2497 | ||
2498 | 6. If the command was not begun asynchronously, the shell waits for | |
2499 | the command to complete and collects its exit status. | |
2500 | ||
cce855bc JA |
2501 | \1f |
2502 | File: bashref.info, Node: Command Execution Environment, Next: Environment, Prev: Command Search and Execution, Up: Executing Commands | |
2503 | ||
37c41ab1 CR |
2504 | 3.7.3 Command Execution Environment |
2505 | ----------------------------------- | |
cce855bc | 2506 | |
37c41ab1 | 2507 | The shell has an EXECUTION ENVIRONMENT, which consists of the following: |
cce855bc JA |
2508 | |
2509 | * open files inherited by the shell at invocation, as modified by | |
8a0829e9 | 2510 | redirections supplied to the 'exec' builtin |
cce855bc | 2511 | |
8a0829e9 | 2512 | * the current working directory as set by 'cd', 'pushd', or 'popd', |
cce855bc JA |
2513 | or inherited by the shell at invocation |
2514 | ||
8a0829e9 CR |
2515 | * the file creation mode mask as set by 'umask' or inherited from the |
2516 | shell's parent | |
cce855bc | 2517 | |
8a0829e9 | 2518 | * current traps set by 'trap' |
cce855bc | 2519 | |
8a0829e9 | 2520 | * shell parameters that are set by variable assignment or with 'set' |
cce855bc JA |
2521 | or inherited from the shell's parent in the environment |
2522 | ||
2523 | * shell functions defined during execution or inherited from the | |
2524 | shell's parent in the environment | |
2525 | ||
2526 | * options enabled at invocation (either by default or with | |
8a0829e9 | 2527 | command-line arguments) or by 'set' |
cce855bc | 2528 | |
8a0829e9 | 2529 | * options enabled by 'shopt' (*note The Shopt Builtin::) |
cce855bc | 2530 | |
8a0829e9 | 2531 | * shell aliases defined with 'alias' (*note Aliases::) |
cce855bc JA |
2532 | |
2533 | * various process IDs, including those of background jobs (*note | |
8a0829e9 | 2534 | Lists::), the value of '$$', and the value of '$PPID' |
cce855bc | 2535 | |
8a0829e9 CR |
2536 | When a simple command other than a builtin or shell function is to be |
2537 | executed, it is invoked in a separate execution environment that | |
cce855bc JA |
2538 | consists of the following. Unless otherwise noted, the values are |
2539 | inherited from the shell. | |
2540 | ||
2541 | * the shell's open files, plus any modifications and additions | |
2542 | specified by redirections to the command | |
2543 | ||
2544 | * the current working directory | |
2545 | ||
2546 | * the file creation mode mask | |
2547 | ||
d3a24ed2 CR |
2548 | * shell variables and functions marked for export, along with |
2549 | variables exported for the command, passed in the environment | |
2550 | (*note Environment::) | |
cce855bc JA |
2551 | |
2552 | * traps caught by the shell are reset to the values inherited from | |
2553 | the shell's parent, and traps ignored by the shell are ignored | |
2554 | ||
2555 | A command invoked in this separate environment cannot affect the | |
2556 | shell's execution environment. | |
2557 | ||
d3a24ed2 CR |
2558 | Command substitution, commands grouped with parentheses, and |
2559 | asynchronous commands are invoked in a subshell environment that is a | |
2560 | duplicate of the shell environment, except that traps caught by the | |
2561 | shell are reset to the values that the shell inherited from its parent | |
2562 | at invocation. Builtin commands that are invoked as part of a pipeline | |
2563 | are also executed in a subshell environment. Changes made to the | |
2564 | subshell environment cannot affect the shell's execution environment. | |
ccc6cda3 | 2565 | |
db31fb26 | 2566 | Subshells spawned to execute command substitutions inherit the value |
8a0829e9 CR |
2567 | of the '-e' option from the parent shell. When not in POSIX mode, Bash |
2568 | clears the '-e' option in such subshells. | |
db31fb26 | 2569 | |
8a0829e9 CR |
2570 | If a command is followed by a '&' and job control is not active, the |
2571 | default standard input for the command is the empty file '/dev/null'. | |
f73dda09 JA |
2572 | Otherwise, the invoked command inherits the file descriptors of the |
2573 | calling shell as modified by redirections. | |
2574 | ||
ccc6cda3 | 2575 | \1f |
cce855bc | 2576 | File: bashref.info, Node: Environment, Next: Exit Status, Prev: Command Execution Environment, Up: Executing Commands |
ccc6cda3 | 2577 | |
37c41ab1 CR |
2578 | 3.7.4 Environment |
2579 | ----------------- | |
ccc6cda3 | 2580 | |
37c41ab1 | 2581 | When a program is invoked it is given an array of strings called the |
ccc6cda3 | 2582 | ENVIRONMENT. This is a list of name-value pairs, of the form |
8a0829e9 | 2583 | 'name=value'. |
ccc6cda3 | 2584 | |
bb70624e | 2585 | Bash provides several ways to manipulate the environment. On |
ccc6cda3 JA |
2586 | invocation, the shell scans its own environment and creates a parameter |
2587 | for each name found, automatically marking it for EXPORT to child | |
8a0829e9 CR |
2588 | processes. Executed commands inherit the environment. The 'export' and |
2589 | 'declare -x' commands allow parameters and functions to be added to and | |
2590 | deleted from the environment. If the value of a parameter in the | |
ccc6cda3 JA |
2591 | environment is modified, the new value becomes part of the environment, |
2592 | replacing the old. The environment inherited by any executed command | |
2593 | consists of the shell's initial environment, whose values may be | |
8a0829e9 CR |
2594 | modified in the shell, less any pairs removed by the 'unset' and 'export |
2595 | -n' commands, plus any additions via the 'export' and 'declare -x' | |
2596 | commands. | |
ccc6cda3 JA |
2597 | |
2598 | The environment for any simple command or function may be augmented | |
2599 | temporarily by prefixing it with parameter assignments, as described in | |
6a8fd0ed | 2600 | *note Shell Parameters::. These assignment statements affect only the |
ccc6cda3 JA |
2601 | environment seen by that command. |
2602 | ||
8a0829e9 | 2603 | If the '-k' option is set (*note The Set Builtin::), then all |
ccc6cda3 JA |
2604 | parameter assignments are placed in the environment for a command, not |
2605 | just those that precede the command name. | |
2606 | ||
8a0829e9 | 2607 | When Bash invokes an external command, the variable '$_' is set to |
122f603c | 2608 | the full pathname of the command and passed to that command in its |
ccc6cda3 JA |
2609 | environment. |
2610 | ||
2611 | \1f | |
2612 | File: bashref.info, Node: Exit Status, Next: Signals, Prev: Environment, Up: Executing Commands | |
2613 | ||
37c41ab1 CR |
2614 | 3.7.5 Exit Status |
2615 | ----------------- | |
ccc6cda3 | 2616 | |
29d25b54 CR |
2617 | The exit status of an executed command is the value returned by the |
2618 | WAITPID system call or equivalent function. Exit statuses fall between | |
2619 | 0 and 255, though, as explained below, the shell may use values above | |
2620 | 125 specially. Exit statuses from shell builtins and compound commands | |
122f603c | 2621 | are also limited to this range. Under certain circumstances, the shell |
29d25b54 CR |
2622 | will use special values to indicate specific failure modes. |
2623 | ||
2624 | For the shell's purposes, a command which exits with a zero exit | |
2625 | status has succeeded. A non-zero exit status indicates failure. This | |
cce855bc JA |
2626 | seemingly counter-intuitive scheme is used so there is one well-defined |
2627 | way to indicate success and a variety of ways to indicate various | |
8a0829e9 CR |
2628 | failure modes. When a command terminates on a fatal signal whose number |
2629 | is N, Bash uses the value 128+N as the exit status. | |
ccc6cda3 JA |
2630 | |
2631 | If a command is not found, the child process created to execute it | |
2632 | returns a status of 127. If a command is found but is not executable, | |
2633 | the return status is 126. | |
2634 | ||
cce855bc JA |
2635 | If a command fails because of an error during expansion or |
2636 | redirection, the exit status is greater than zero. | |
2637 | ||
ccc6cda3 | 2638 | The exit status is used by the Bash conditional commands (*note |
28ef6c31 JA |
2639 | Conditional Constructs::) and some of the list constructs (*note |
2640 | Lists::). | |
ccc6cda3 JA |
2641 | |
2642 | All of the Bash builtins return an exit status of zero if they | |
2643 | succeed and a non-zero status on failure, so they may be used by the | |
cce855bc | 2644 | conditional and list constructs. All builtins return an exit status of |
fc527055 CR |
2645 | 2 to indicate incorrect usage, generally invalid options or missing |
2646 | arguments. | |
ccc6cda3 JA |
2647 | |
2648 | \1f | |
2649 | File: bashref.info, Node: Signals, Prev: Exit Status, Up: Executing Commands | |
2650 | ||
37c41ab1 CR |
2651 | 3.7.6 Signals |
2652 | ------------- | |
ccc6cda3 | 2653 | |
37c41ab1 | 2654 | When Bash is interactive, in the absence of any traps, it ignores |
8a0829e9 CR |
2655 | 'SIGTERM' (so that 'kill 0' does not kill an interactive shell), and |
2656 | 'SIGINT' is caught and handled (so that the 'wait' builtin is | |
2657 | interruptible). When Bash receives a 'SIGINT', it breaks out of any | |
2658 | executing loops. In all cases, Bash ignores 'SIGQUIT'. If job control | |
2659 | is in effect (*note Job Control::), Bash ignores 'SIGTTIN', 'SIGTTOU', | |
2660 | and 'SIGTSTP'. | |
ccc6cda3 | 2661 | |
5e13499c CR |
2662 | Non-builtin commands started by Bash have signal handlers set to the |
2663 | values inherited by the shell from its parent. When job control is not | |
8a0829e9 | 2664 | in effect, asynchronous commands ignore 'SIGINT' and 'SIGQUIT' in |
5e13499c CR |
2665 | addition to these inherited handlers. Commands run as a result of |
2666 | command substitution ignore the keyboard-generated job control signals | |
8a0829e9 | 2667 | 'SIGTTIN', 'SIGTTOU', and 'SIGTSTP'. |
ccc6cda3 | 2668 | |
8a0829e9 CR |
2669 | The shell exits by default upon receipt of a 'SIGHUP'. Before |
2670 | exiting, an interactive shell resends the 'SIGHUP' to all jobs, running | |
2671 | or stopped. Stopped jobs are sent 'SIGCONT' to ensure that they receive | |
2672 | the 'SIGHUP'. To prevent the shell from sending the 'SIGHUP' signal to | |
f73dda09 | 2673 | a particular job, it should be removed from the jobs table with the |
8a0829e9 CR |
2674 | 'disown' builtin (*note Job Control Builtins::) or marked to not receive |
2675 | 'SIGHUP' using 'disown -h'. | |
cce855bc | 2676 | |
8a0829e9 CR |
2677 | If the 'huponexit' shell option has been set with 'shopt' (*note The |
2678 | Shopt Builtin::), Bash sends a 'SIGHUP' to all jobs when an interactive | |
2679 | login shell exits. | |
cce855bc | 2680 | |
5e13499c CR |
2681 | If Bash is waiting for a command to complete and receives a signal |
2682 | for which a trap has been set, the trap will not be executed until the | |
8a0829e9 CR |
2683 | command completes. When Bash is waiting for an asynchronous command via |
2684 | the 'wait' builtin, the reception of a signal for which a trap has been | |
2685 | set will cause the 'wait' builtin to return immediately with an exit | |
2686 | status greater than 128, immediately after which the trap is executed. | |
ccc6cda3 JA |
2687 | |
2688 | \1f | |
2689 | File: bashref.info, Node: Shell Scripts, Prev: Executing Commands, Up: Basic Shell Features | |
2690 | ||
37c41ab1 CR |
2691 | 3.8 Shell Scripts |
2692 | ================= | |
ccc6cda3 | 2693 | |
37c41ab1 CR |
2694 | A shell script is a text file containing shell commands. When such a |
2695 | file is used as the first non-option argument when invoking Bash, and | |
8a0829e9 | 2696 | neither the '-c' nor '-s' option is supplied (*note Invoking Bash::), |
ccc6cda3 | 2697 | Bash reads and executes commands from the file, then exits. This mode |
f73dda09 JA |
2698 | of operation creates a non-interactive shell. The shell first searches |
2699 | for the file in the current directory, and looks in the directories in | |
8a0829e9 | 2700 | '$PATH' if not found there. |
f73dda09 | 2701 | |
8a0829e9 | 2702 | When Bash runs a shell script, it sets the special parameter '0' to |
f73dda09 JA |
2703 | the name of the file, rather than the name of the shell, and the |
2704 | positional parameters are set to the remaining arguments, if any are | |
2705 | given. If no additional arguments are supplied, the positional | |
2706 | parameters are unset. | |
ccc6cda3 | 2707 | |
8a0829e9 CR |
2708 | A shell script may be made executable by using the 'chmod' command to |
2709 | turn on the execute bit. When Bash finds such a file while searching | |
2710 | the '$PATH' for a command, it spawns a subshell to execute it. In other | |
2711 | words, executing | |
ccc6cda3 | 2712 | filename ARGUMENTS |
8a0829e9 | 2713 | is equivalent to executing |
ccc6cda3 JA |
2714 | bash filename ARGUMENTS |
2715 | ||
8a0829e9 | 2716 | if 'filename' is an executable shell script. This subshell |
ccc6cda3 | 2717 | reinitializes itself, so that the effect is as if a new shell had been |
cce855bc | 2718 | invoked to interpret the script, with the exception that the locations |
8a0829e9 | 2719 | of commands remembered by the parent (see the description of 'hash' in |
6a8fd0ed | 2720 | *note Bourne Shell Builtins::) are retained by the child. |
ccc6cda3 | 2721 | |
bb70624e JA |
2722 | Most versions of Unix make this a part of the operating system's |
2723 | command execution mechanism. If the first line of a script begins with | |
8a0829e9 CR |
2724 | the two characters '#!', the remainder of the line specifies an |
2725 | interpreter for the program. Thus, you can specify Bash, 'awk', Perl, | |
bb70624e JA |
2726 | or some other interpreter and write the rest of the script file in that |
2727 | language. | |
2728 | ||
2729 | The arguments to the interpreter consist of a single optional | |
2730 | argument following the interpreter name on the first line of the script | |
2731 | file, followed by the name of the script file, followed by the rest of | |
2732 | the arguments. Bash will perform this action on operating systems that | |
2733 | do not handle it themselves. Note that some older versions of Unix | |
2734 | limit the interpreter name and argument to a maximum of 32 characters. | |
2735 | ||
8a0829e9 CR |
2736 | Bash scripts often begin with '#! /bin/bash' (assuming that Bash has |
2737 | been installed in '/bin'), since this ensures that Bash will be used to | |
bb70624e | 2738 | interpret the script, even if it is executed under another shell. |
ccc6cda3 JA |
2739 | |
2740 | \1f | |
bb70624e | 2741 | File: bashref.info, Node: Shell Builtin Commands, Next: Shell Variables, Prev: Basic Shell Features, Up: Top |
ccc6cda3 | 2742 | |
37c41ab1 CR |
2743 | 4 Shell Builtin Commands |
2744 | ************************ | |
ccc6cda3 JA |
2745 | |
2746 | * Menu: | |
2747 | ||
2748 | * Bourne Shell Builtins:: Builtin commands inherited from the Bourne | |
2749 | Shell. | |
bb70624e | 2750 | * Bash Builtins:: Table of builtins specific to Bash. |
d3ad40de CR |
2751 | * Modifying Shell Behavior:: Builtins to modify shell attributes and |
2752 | optional behavior. | |
bb70624e | 2753 | * Special Builtins:: Builtin commands classified specially by |
ac18b312 | 2754 | POSIX. |
bb70624e | 2755 | |
8a0829e9 CR |
2756 | Builtin commands are contained within the shell itself. When the name |
2757 | of a builtin command is used as the first word of a simple command | |
28ef6c31 | 2758 | (*note Simple Commands::), the shell executes the command directly, |
bb70624e JA |
2759 | without invoking another program. Builtin commands are necessary to |
2760 | implement functionality impossible or inconvenient to obtain with | |
2761 | separate utilities. | |
ccc6cda3 | 2762 | |
ac18b312 | 2763 | This section briefly describes the builtins which Bash inherits from |
8a0829e9 CR |
2764 | the Bourne Shell, as well as the builtin commands which are unique to or |
2765 | have been extended in Bash. | |
bb70624e | 2766 | |
fc527055 | 2767 | Several builtin commands are described in other chapters: builtin |
bb70624e | 2768 | commands which provide the Bash interface to the job control facilities |
28ef6c31 JA |
2769 | (*note Job Control Builtins::), the directory stack (*note Directory |
2770 | Stack Builtins::), the command history (*note Bash History Builtins::), | |
2771 | and the programmable completion facilities (*note Programmable | |
2772 | Completion Builtins::). | |
bb70624e JA |
2773 | |
2774 | Many of the builtins have been extended by POSIX or Bash. | |
ccc6cda3 | 2775 | |
c2258e1c | 2776 | Unless otherwise noted, each builtin command documented as accepting |
8a0829e9 CR |
2777 | options preceded by '-' accepts '--' to signify the end of the options. |
2778 | The ':', 'true', 'false', and 'test' builtins do not accept options and | |
54a5fbe1 CR |
2779 | do not treat '--' specially. The 'exit', 'logout', 'return', 'break', |
2780 | 'continue', 'let', and 'shift' builtins accept and process arguments | |
2781 | beginning with '-' without requiring '--'. Other builtins that accept | |
2782 | arguments but are not specified as accepting options interpret arguments | |
2783 | beginning with '-' as invalid options and require '--' to prevent this | |
8a0829e9 | 2784 | interpretation. |
c2258e1c | 2785 | |
ccc6cda3 | 2786 | \1f |
bb70624e | 2787 | File: bashref.info, Node: Bourne Shell Builtins, Next: Bash Builtins, Up: Shell Builtin Commands |
ccc6cda3 | 2788 | |
37c41ab1 CR |
2789 | 4.1 Bourne Shell Builtins |
2790 | ========================= | |
ccc6cda3 | 2791 | |
37c41ab1 | 2792 | The following shell builtin commands are inherited from the Bourne |
ac18b312 | 2793 | Shell. These commands are implemented as specified by the POSIX |
ccc6cda3 JA |
2794 | standard. |
2795 | ||
8a0829e9 | 2796 | ': (a colon)' |
ccc6cda3 | 2797 | : [ARGUMENTS] |
122f603c | 2798 | |
ccc6cda3 | 2799 | Do nothing beyond expanding ARGUMENTS and performing redirections. |
cce855bc | 2800 | The return status is zero. |
ccc6cda3 | 2801 | |
8a0829e9 | 2802 | '. (a period)' |
b72432fd | 2803 | . FILENAME [ARGUMENTS] |
122f603c | 2804 | |
8a0829e9 CR |
2805 | Read and execute commands from the FILENAME argument in the current |
2806 | shell context. If FILENAME does not contain a slash, the 'PATH' | |
2807 | variable is used to find FILENAME. When Bash is not in POSIX mode, | |
2808 | the current directory is searched if FILENAME is not found in | |
2809 | '$PATH'. If any ARGUMENTS are supplied, they become the positional | |
2810 | parameters when FILENAME is executed. Otherwise the positional | |
eac8fb1b CR |
2811 | parameters are unchanged. If the '-T' option is enabled, 'source' |
2812 | inherits any trap on 'DEBUG'; if it is not, any 'DEBUG' trap string | |
2813 | is saved and restored around the call to 'source', and 'source' | |
2814 | unsets the 'DEBUG' trap while it executes. If '-T' is not set, and | |
2815 | the sourced file changes the 'DEBUG' trap, the new value is | |
2816 | retained when 'source' completes. The return status is the exit | |
2817 | status of the last command executed, or zero if no commands are | |
2818 | executed. If FILENAME is not found, or cannot be read, the return | |
2819 | status is non-zero. This builtin is equivalent to 'source'. | |
8a0829e9 CR |
2820 | |
2821 | 'break' | |
ccc6cda3 | 2822 | break [N] |
122f603c | 2823 | |
8a0829e9 CR |
2824 | Exit from a 'for', 'while', 'until', or 'select' loop. If N is |
2825 | supplied, the Nth enclosing loop is exited. N must be greater than | |
2826 | or equal to 1. The return status is zero unless N is not greater | |
2827 | than or equal to 1. | |
ccc6cda3 | 2828 | |
8a0829e9 | 2829 | 'cd' |
d76edd30 | 2830 | cd [-L|[-P [-e]] [-@] [DIRECTORY] |
122f603c | 2831 | |
8a0829e9 CR |
2832 | Change the current working directory to DIRECTORY. If DIRECTORY is |
2833 | not supplied, the value of the 'HOME' shell variable is used. Any | |
2834 | additional arguments following DIRECTORY are ignored. If the shell | |
2835 | variable 'CDPATH' exists, it is used as a search path: each | |
2836 | directory name in 'CDPATH' is searched for DIRECTORY, with | |
2837 | alternative directory names in 'CDPATH' separated by a colon (':'). | |
2838 | If DIRECTORY begins with a slash, 'CDPATH' is not used. | |
d3a24ed2 | 2839 | |
8a0829e9 CR |
2840 | The '-P' option means to not follow symbolic links: symbolic links |
2841 | are resolved while 'cd' is traversing DIRECTORY and before | |
2842 | processing an instance of '..' in DIRECTORY. | |
45c0f7f8 | 2843 | |
8a0829e9 CR |
2844 | By default, or when the '-L' option is supplied, symbolic links in |
2845 | DIRECTORY are resolved after 'cd' processes an instance of '..' in | |
45c0f7f8 CR |
2846 | DIRECTORY. |
2847 | ||
8a0829e9 | 2848 | If '..' appears in DIRECTORY, it is processed by removing the |
45c0f7f8 CR |
2849 | immediately preceding pathname component, back to a slash or the |
2850 | beginning of DIRECTORY. | |
2851 | ||
8a0829e9 | 2852 | If the '-e' option is supplied with '-P' and the current working |
45c0f7f8 | 2853 | directory cannot be successfully determined after a successful |
8a0829e9 | 2854 | directory change, 'cd' will return an unsuccessful status. |
d76edd30 | 2855 | |
8a0829e9 | 2856 | On systems that support it, the '-@' option presents the extended |
d76edd30 CR |
2857 | attributes associated with a file as a directory. |
2858 | ||
8a0829e9 | 2859 | If DIRECTORY is '-', it is converted to '$OLDPWD' before the |
45c0f7f8 | 2860 | directory change is attempted. |
d3a24ed2 | 2861 | |
8a0829e9 | 2862 | If a non-empty directory name from 'CDPATH' is used, or if '-' is |
d3a24ed2 CR |
2863 | the first argument, and the directory change is successful, the |
2864 | absolute pathname of the new working directory is written to the | |
2865 | standard output. | |
2866 | ||
2867 | The return status is zero if the directory is successfully changed, | |
2868 | non-zero otherwise. | |
ccc6cda3 | 2869 | |
8a0829e9 | 2870 | 'continue' |
ccc6cda3 | 2871 | continue [N] |
122f603c | 2872 | |
8a0829e9 CR |
2873 | Resume the next iteration of an enclosing 'for', 'while', 'until', |
2874 | or 'select' loop. If N is supplied, the execution of the Nth | |
cce855bc JA |
2875 | enclosing loop is resumed. N must be greater than or equal to 1. |
2876 | The return status is zero unless N is not greater than or equal to | |
2877 | 1. | |
ccc6cda3 | 2878 | |
8a0829e9 | 2879 | 'eval' |
ccc6cda3 | 2880 | eval [ARGUMENTS] |
122f603c | 2881 | |
ccc6cda3 | 2882 | The arguments are concatenated together into a single command, |
cce855bc | 2883 | which is then read and executed, and its exit status returned as |
8a0829e9 CR |
2884 | the exit status of 'eval'. If there are no arguments or only empty |
2885 | arguments, the return status is zero. | |
ccc6cda3 | 2886 | |
8a0829e9 | 2887 | 'exec' |
cce855bc | 2888 | exec [-cl] [-a NAME] [COMMAND [ARGUMENTS]] |
122f603c | 2889 | |
cce855bc | 2890 | If COMMAND is supplied, it replaces the shell without creating a |
8a0829e9 | 2891 | new process. If the '-l' option is supplied, the shell places a |
d3ad40de | 2892 | dash at the beginning of the zeroth argument passed to COMMAND. |
8a0829e9 CR |
2893 | This is what the 'login' program does. The '-c' option causes |
2894 | COMMAND to be executed with an empty environment. If '-a' is | |
d3ad40de | 2895 | supplied, the shell passes NAME as the zeroth argument to COMMAND. |
122f603c | 2896 | If COMMAND cannot be executed for some reason, a non-interactive |
8a0829e9 | 2897 | shell exits, unless the 'execfail' shell option is enabled. In |
122f603c CR |
2898 | that case, it returns failure. An interactive shell returns |
2899 | failure if the file cannot be executed. If no COMMAND is | |
2900 | specified, redirections may be used to affect the current shell | |
8a0829e9 CR |
2901 | environment. If there are no redirection errors, the return status |
2902 | is zero; otherwise the return status is non-zero. | |
ccc6cda3 | 2903 | |
8a0829e9 | 2904 | 'exit' |
ccc6cda3 | 2905 | exit [N] |
122f603c | 2906 | |
bb70624e JA |
2907 | Exit the shell, returning a status of N to the shell's parent. If |
2908 | N is omitted, the exit status is that of the last command executed. | |
8a0829e9 | 2909 | Any trap on 'EXIT' is executed before the shell terminates. |
ccc6cda3 | 2910 | |
8a0829e9 | 2911 | 'export' |
ccc6cda3 | 2912 | export [-fn] [-p] [NAME[=VALUE]] |
122f603c | 2913 | |
ccc6cda3 | 2914 | Mark each NAME to be passed to child processes in the environment. |
8a0829e9 CR |
2915 | If the '-f' option is supplied, the NAMEs refer to shell functions; |
2916 | otherwise the names refer to shell variables. The '-n' option | |
2917 | means to no longer mark each NAME for export. If no NAMES are | |
2918 | supplied, or if the '-p' option is given, a list of names of all | |
2919 | exported variables is displayed. The '-p' option displays output | |
2920 | in a form that may be reused as input. If a variable name is | |
2921 | followed by =VALUE, the value of the variable is set to VALUE. | |
2922 | ||
2923 | The return status is zero unless an invalid option is supplied, one | |
2924 | of the names is not a valid shell variable name, or '-f' is | |
d3a24ed2 | 2925 | supplied with a name that is not a shell function. |
ccc6cda3 | 2926 | |
8a0829e9 | 2927 | 'getopts' |
ccc6cda3 | 2928 | getopts OPTSTRING NAME [ARGS] |
122f603c | 2929 | |
8a0829e9 | 2930 | 'getopts' is used by shell scripts to parse positional parameters. |
bb70624e JA |
2931 | OPTSTRING contains the option characters to be recognized; if a |
2932 | character is followed by a colon, the option is expected to have an | |
122f603c | 2933 | argument, which should be separated from it by whitespace. The |
8a0829e9 CR |
2934 | colon (':') and question mark ('?') may not be used as option |
2935 | characters. Each time it is invoked, 'getopts' places the next | |
2936 | option in the shell variable NAME, initializing NAME if it does not | |
2937 | exist, and the index of the next argument to be processed into the | |
2938 | variable 'OPTIND'. 'OPTIND' is initialized to 1 each time the | |
bb70624e | 2939 | shell or a shell script is invoked. When an option requires an |
8a0829e9 CR |
2940 | argument, 'getopts' places that argument into the variable |
2941 | 'OPTARG'. The shell does not reset 'OPTIND' automatically; it must | |
2942 | be manually reset between multiple calls to 'getopts' within the | |
2943 | same shell invocation if a new set of parameters is to be used. | |
ccc6cda3 | 2944 | |
8a0829e9 CR |
2945 | When the end of options is encountered, 'getopts' exits with a |
2946 | return value greater than zero. 'OPTIND' is set to the index of | |
2947 | the first non-option argument, and NAME is set to '?'. | |
cce855bc | 2948 | |
8a0829e9 CR |
2949 | 'getopts' normally parses the positional parameters, but if more |
2950 | arguments are given in ARGS, 'getopts' parses those instead. | |
cce855bc | 2951 | |
8a0829e9 | 2952 | 'getopts' can report errors in two ways. If the first character of |
ccc6cda3 | 2953 | OPTSTRING is a colon, SILENT error reporting is used. In normal |
122f603c | 2954 | operation, diagnostic messages are printed when invalid options or |
8a0829e9 | 2955 | missing option arguments are encountered. If the variable 'OPTERR' |
cce855bc | 2956 | is set to 0, no error messages will be displayed, even if the first |
8a0829e9 | 2957 | character of 'optstring' is not a colon. |
ccc6cda3 | 2958 | |
8a0829e9 CR |
2959 | If an invalid option is seen, 'getopts' places '?' into NAME and, |
2960 | if not silent, prints an error message and unsets 'OPTARG'. If | |
2961 | 'getopts' is silent, the option character found is placed in | |
2962 | 'OPTARG' and no diagnostic message is printed. | |
ccc6cda3 | 2963 | |
8a0829e9 CR |
2964 | If a required argument is not found, and 'getopts' is not silent, a |
2965 | question mark ('?') is placed in NAME, 'OPTARG' is unset, and a | |
2966 | diagnostic message is printed. If 'getopts' is silent, then a | |
2967 | colon (':') is placed in NAME and 'OPTARG' is set to the option | |
ccc6cda3 JA |
2968 | character found. |
2969 | ||
8a0829e9 | 2970 | 'hash' |
ac18b312 | 2971 | hash [-r] [-p FILENAME] [-dt] [NAME] |
122f603c | 2972 | |
8a0829e9 | 2973 | Each time 'hash' is invoked, it remembers the full pathnames of the |
eb0b2ad8 | 2974 | commands specified as NAME arguments, so they need not be searched |
8a0829e9 CR |
2975 | for on subsequent invocations. The commands are found by searching |
2976 | through the directories listed in '$PATH'. Any | |
2977 | previously-remembered pathname is discarded. The '-p' option | |
eb0b2ad8 | 2978 | inhibits the path search, and FILENAME is used as the location of |
8a0829e9 CR |
2979 | NAME. The '-r' option causes the shell to forget all remembered |
2980 | locations. The '-d' option causes the shell to forget the | |
2981 | remembered location of each NAME. If the '-t' option is supplied, | |
eb0b2ad8 | 2982 | the full pathname to which each NAME corresponds is printed. If |
8a0829e9 CR |
2983 | multiple NAME arguments are supplied with '-t' the NAME is printed |
2984 | before the hashed full pathname. The '-l' option causes output to | |
eb0b2ad8 | 2985 | be displayed in a format that may be reused as input. If no |
8a0829e9 CR |
2986 | arguments are given, or if only '-l' is supplied, information about |
2987 | remembered commands is printed. The return status is zero unless a | |
2988 | NAME is not found or an invalid option is supplied. | |
ccc6cda3 | 2989 | |
8a0829e9 | 2990 | 'pwd' |
ccc6cda3 | 2991 | pwd [-LP] |
122f603c | 2992 | |
bb70624e | 2993 | Print the absolute pathname of the current working directory. If |
8a0829e9 CR |
2994 | the '-P' option is supplied, the pathname printed will not contain |
2995 | symbolic links. If the '-L' option is supplied, the pathname | |
bb70624e JA |
2996 | printed may contain symbolic links. The return status is zero |
2997 | unless an error is encountered while determining the name of the | |
2998 | current directory or an invalid option is supplied. | |
ccc6cda3 | 2999 | |
8a0829e9 | 3000 | 'readonly' |
d9e1f41e | 3001 | readonly [-aAf] [-p] [NAME[=VALUE]] ... |
122f603c | 3002 | |
cce855bc | 3003 | Mark each NAME as readonly. The values of these names may not be |
8a0829e9 CR |
3004 | changed by subsequent assignment. If the '-f' option is supplied, |
3005 | each NAME refers to a shell function. The '-a' option means each | |
3006 | NAME refers to an indexed array variable; the '-A' option means | |
3007 | each NAME refers to an associative array variable. If both options | |
3008 | are supplied, '-A' takes precedence. If no NAME arguments are | |
3009 | given, or if the '-p' option is supplied, a list of all readonly | |
3010 | names is printed. The other options may be used to restrict the | |
3011 | output to a subset of the set of readonly names. The '-p' option | |
3012 | causes output to be displayed in a format that may be reused as | |
3013 | input. If a variable name is followed by =VALUE, the value of the | |
3014 | variable is set to VALUE. The return status is zero unless an | |
3015 | invalid option is supplied, one of the NAME arguments is not a | |
3016 | valid shell variable or function name, or the '-f' option is | |
d9e1f41e | 3017 | supplied with a name that is not a shell function. |
ccc6cda3 | 3018 | |
8a0829e9 | 3019 | 'return' |
ccc6cda3 | 3020 | return [N] |
122f603c CR |
3021 | |
3022 | Cause a shell function to stop executing and return the value N to | |
3023 | its caller. If N is not supplied, the return value is the exit | |
8a0829e9 | 3024 | status of the last command executed in the function. If 'return' |
fc527055 CR |
3025 | is executed by a trap handler, the last command used to determine |
3026 | the status is the last command executed before the trap handler. | |
8a0829e9 | 3027 | if 'return' is executed during a 'DEBUG' trap, the last command |
fc527055 | 3028 | used to determine the status is the last command executed by the |
8a0829e9 CR |
3029 | trap handler before 'return' was invoked. 'return' may also be |
3030 | used to terminate execution of a script being executed with the '.' | |
3031 | ('source') builtin, returning either N or the exit status of the | |
3032 | last command executed within the script as the exit status of the | |
3033 | script. If N is supplied, the return value is its least | |
3034 | significant 8 bits. Any command associated with the 'RETURN' trap | |
fc527055 | 3035 | is executed before execution resumes after the function or script. |
8a0829e9 CR |
3036 | The return status is non-zero if 'return' is supplied a non-numeric |
3037 | argument or is used outside a function and not during the execution | |
3038 | of a script by '.' or 'source'. | |
ccc6cda3 | 3039 | |
8a0829e9 | 3040 | 'shift' |
ccc6cda3 | 3041 | shift [N] |
122f603c | 3042 | |
cce855bc | 3043 | Shift the positional parameters to the left by N. The positional |
8a0829e9 CR |
3044 | parameters from N+1 ... '$#' are renamed to '$1' ... '$#'-N. |
3045 | Parameters represented by the numbers '$#' to '$#'-N+1 are unset. | |
3046 | N must be a non-negative number less than or equal to '$#'. If N | |
3047 | is zero or greater than '$#', the positional parameters are not | |
bb70624e | 3048 | changed. If N is not supplied, it is assumed to be 1. The return |
8a0829e9 | 3049 | status is zero unless N is greater than '$#' or less than zero, |
bb70624e | 3050 | non-zero otherwise. |
ccc6cda3 | 3051 | |
8a0829e9 CR |
3052 | 'test' |
3053 | '[' | |
122f603c CR |
3054 | test EXPR |
3055 | ||
ad4aef08 | 3056 | Evaluate a conditional express ion EXPR and return a status of 0 |
122f603c CR |
3057 | (true) or 1 (false). Each operator and operand must be a separate |
3058 | argument. Expressions are composed of the primaries described | |
8a0829e9 | 3059 | below in *note Bash Conditional Expressions::. 'test' does not |
122f603c | 3060 | accept any options, nor does it accept and ignore an argument of |
8a0829e9 | 3061 | '--' as signifying the end of options. |
cce855bc | 3062 | |
8a0829e9 CR |
3063 | When the '[' form is used, the last argument to the command must be |
3064 | a ']'. | |
bb70624e | 3065 | |
cce855bc | 3066 | Expressions may be combined using the following operators, listed |
d7f49990 | 3067 | in decreasing order of precedence. The evaluation depends on the |
510e20a2 CR |
3068 | number of arguments; see below. Operator precedence is used when |
3069 | there are five or more arguments. | |
cce855bc | 3070 | |
8a0829e9 | 3071 | '! EXPR' |
cce855bc JA |
3072 | True if EXPR is false. |
3073 | ||
8a0829e9 | 3074 | '( EXPR )' |
cce855bc JA |
3075 | Returns the value of EXPR. This may be used to override the |
3076 | normal precedence of operators. | |
3077 | ||
8a0829e9 | 3078 | 'EXPR1 -a EXPR2' |
cce855bc JA |
3079 | True if both EXPR1 and EXPR2 are true. |
3080 | ||
8a0829e9 | 3081 | 'EXPR1 -o EXPR2' |
cce855bc JA |
3082 | True if either EXPR1 or EXPR2 is true. |
3083 | ||
8a0829e9 | 3084 | The 'test' and '[' builtins evaluate conditional expressions using |
cce855bc JA |
3085 | a set of rules based on the number of arguments. |
3086 | ||
8a0829e9 | 3087 | 0 arguments |
cce855bc JA |
3088 | The expression is false. |
3089 | ||
8a0829e9 | 3090 | 1 argument |
cce855bc JA |
3091 | The expression is true if and only if the argument is not |
3092 | null. | |
3093 | ||
8a0829e9 CR |
3094 | 2 arguments |
3095 | If the first argument is '!', the expression is true if and | |
3096 | only if the second argument is null. If the first argument is | |
3097 | one of the unary conditional operators (*note Bash Conditional | |
3098 | Expressions::), the expression is true if the unary test is | |
3099 | true. If the first argument is not a valid unary operator, | |
3100 | the expression is false. | |
cce855bc | 3101 | |
8a0829e9 | 3102 | 3 arguments |
510e20a2 | 3103 | The following conditions are applied in the order listed. If |
8a0829e9 CR |
3104 | the second argument is one of the binary conditional operators |
3105 | (*note Bash Conditional Expressions::), the result of the | |
3106 | expression is the result of the binary test using the first | |
3107 | and third arguments as operands. The '-a' and '-o' operators | |
3108 | are considered binary operators when there are three | |
3109 | arguments. If the first argument is '!', the value is the | |
3110 | negation of the two-argument test using the second and third | |
3111 | arguments. If the first argument is exactly '(' and the third | |
3112 | argument is exactly ')', the result is the one-argument test | |
3113 | of the second argument. Otherwise, the expression is false. | |
3114 | ||
3115 | 4 arguments | |
3116 | If the first argument is '!', the result is the negation of | |
cce855bc JA |
3117 | the three-argument expression composed of the remaining |
3118 | arguments. Otherwise, the expression is parsed and evaluated | |
3119 | according to precedence using the rules listed above. | |
3120 | ||
8a0829e9 | 3121 | 5 or more arguments |
cce855bc JA |
3122 | The expression is parsed and evaluated according to precedence |
3123 | using the rules listed above. | |
ccc6cda3 | 3124 | |
8a0829e9 | 3125 | When used with 'test' or '[', the '<' and '>' operators sort |
54a1fa7c CR |
3126 | lexicographically using ASCII ordering. |
3127 | ||
8a0829e9 | 3128 | 'times' |
ccc6cda3 | 3129 | times |
122f603c | 3130 | |
ccc6cda3 | 3131 | Print out the user and system times used by the shell and its |
cce855bc | 3132 | children. The return status is zero. |
ccc6cda3 | 3133 | |
8a0829e9 | 3134 | 'trap' |
d166f048 | 3135 | trap [-lp] [ARG] [SIGSPEC ...] |
122f603c | 3136 | |
ccc6cda3 | 3137 | The commands in ARG are to be read and executed when the shell |
9f422431 | 3138 | receives signal SIGSPEC. If ARG is absent (and there is a single |
8a0829e9 | 3139 | SIGSPEC) or equal to '-', each specified signal's disposition is |
9f422431 CR |
3140 | reset to the value it had when the shell was started. If ARG is |
3141 | the null string, then the signal specified by each SIGSPEC is | |
3142 | ignored by the shell and commands it invokes. If ARG is not | |
8a0829e9 | 3143 | present and '-p' has been supplied, the shell displays the trap |
9f422431 | 3144 | commands associated with each SIGSPEC. If no arguments are |
8a0829e9 | 3145 | supplied, or only '-p' is given, 'trap' prints the list of commands |
9f422431 | 3146 | associated with each signal number in a form that may be reused as |
8a0829e9 | 3147 | shell input. The '-l' option causes the shell to print a list of |
9f422431 CR |
3148 | signal names and their corresponding numbers. Each SIGSPEC is |
3149 | either a signal name or a signal number. Signal names are case | |
8a0829e9 CR |
3150 | insensitive and the 'SIG' prefix is optional. |
3151 | ||
3152 | If a SIGSPEC is '0' or 'EXIT', ARG is executed when the shell | |
3153 | exits. If a SIGSPEC is 'DEBUG', the command ARG is executed before | |
3154 | every simple command, 'for' command, 'case' command, 'select' | |
3155 | command, every arithmetic 'for' command, and before the first | |
3156 | command executes in a shell function. Refer to the description of | |
3157 | the 'extdebug' option to the 'shopt' builtin (*note The Shopt | |
3158 | Builtin::) for details of its effect on the 'DEBUG' trap. If a | |
3159 | SIGSPEC is 'RETURN', the command ARG is executed each time a shell | |
3160 | function or a script executed with the '.' or 'source' builtins | |
3161 | finishes executing. | |
3162 | ||
3163 | If a SIGSPEC is 'ERR', the command ARG is executed whenever a | |
3164 | pipeline (which may consist of a single simple command), a list, or | |
3165 | a compound command returns a non-zero exit status, subject to the | |
3166 | following conditions. The 'ERR' trap is not executed if the failed | |
3167 | command is part of the command list immediately following an | |
3168 | 'until' or 'while' keyword, part of the test following the 'if' or | |
3169 | 'elif' reserved words, part of a command executed in a '&&' or '||' | |
3170 | list except the command following the final '&&' or '||', any | |
ad4aef08 | 3171 | command in a pipeline but the last, or if the command's return |
8a0829e9 CR |
3172 | status is being inverted using '!'. These are the same conditions |
3173 | obeyed by the 'errexit' ('-e') option. | |
d3a24ed2 | 3174 | |
ccc6cda3 | 3175 | Signals ignored upon entry to the shell cannot be trapped or reset. |
d3ad40de | 3176 | Trapped signals that are not being ignored are reset to their |
4a8bb13f CR |
3177 | original values in a subshell or subshell environment when one is |
3178 | created. | |
ccc6cda3 | 3179 | |
8a0829e9 CR |
3180 | The return status is zero unless a SIGSPEC does not specify a valid |
3181 | signal. | |
cce855bc | 3182 | |
8a0829e9 | 3183 | 'umask' |
cce855bc | 3184 | umask [-p] [-S] [MODE] |
122f603c | 3185 | |
8a0829e9 CR |
3186 | Set the shell process's file creation mask to MODE. If MODE begins |
3187 | with a digit, it is interpreted as an octal number; if not, it is | |
3188 | interpreted as a symbolic mode mask similar to that accepted by the | |
3189 | 'chmod' command. If MODE is omitted, the current value of the mask | |
3190 | is printed. If the '-S' option is supplied without a MODE | |
3191 | argument, the mask is printed in a symbolic format. If the '-p' | |
3192 | option is supplied, and MODE is omitted, the output is in a form | |
3193 | that may be reused as input. The return status is zero if the mode | |
3194 | is successfully changed or if no MODE argument is supplied, and | |
3195 | non-zero otherwise. | |
ccc6cda3 | 3196 | |
bb70624e | 3197 | Note that when the mode is interpreted as an octal number, each |
8a0829e9 CR |
3198 | number of the umask is subtracted from '7'. Thus, a umask of '022' |
3199 | results in permissions of '755'. | |
bb70624e | 3200 | |
8a0829e9 | 3201 | 'unset' |
9f178efb | 3202 | unset [-fnv] [NAME] |
122f603c | 3203 | |
8a0829e9 | 3204 | Remove each variable or function NAME. If the '-v' option is |
74d0116b | 3205 | given, each NAME refers to a shell variable and that variable is |
8a0829e9 CR |
3206 | remvoved. If the '-f' option is given, the NAMEs refer to shell |
3207 | functions, and the function definition is removed. If the '-n' | |
9f178efb CR |
3208 | option is supplied, and NAME is a variable with the NAMEREF |
3209 | attribute, NAME will be unset rather than the variable it | |
8a0829e9 CR |
3210 | references. '-n' has no effect if the '-f' option is supplied. If |
3211 | no options are supplied, each NAME refers to a variable; if there | |
3212 | is no variable by that name, any function with that name is unset. | |
3213 | Readonly variables and functions may not be unset. The return | |
3214 | status is zero unless a NAME is readonly. | |
ccc6cda3 JA |
3215 | |
3216 | \1f | |
d3ad40de | 3217 | File: bashref.info, Node: Bash Builtins, Next: Modifying Shell Behavior, Prev: Bourne Shell Builtins, Up: Shell Builtin Commands |
ccc6cda3 | 3218 | |
37c41ab1 CR |
3219 | 4.2 Bash Builtin Commands |
3220 | ========================= | |
ccc6cda3 | 3221 | |
8a0829e9 CR |
3222 | This section describes builtin commands which are unique to or have been |
3223 | extended in Bash. Some of these commands are specified in the POSIX | |
3224 | standard. | |
ccc6cda3 | 3225 | |
8a0829e9 | 3226 | 'alias' |
122f603c | 3227 | alias [-p] [NAME[=VALUE] ...] |
ccc6cda3 | 3228 | |
8a0829e9 | 3229 | Without arguments or with the '-p' option, 'alias' prints the list |
bb70624e JA |
3230 | of aliases on the standard output in a form that allows them to be |
3231 | reused as input. If arguments are supplied, an alias is defined | |
3232 | for each NAME whose VALUE is given. If no VALUE is given, the name | |
6a8fd0ed | 3233 | and value of the alias is printed. Aliases are described in *note |
bb70624e | 3234 | Aliases::. |
ccc6cda3 | 3235 | |
8a0829e9 | 3236 | 'bind' |
45c0f7f8 | 3237 | bind [-m KEYMAP] [-lpsvPSVX] |
bb70624e JA |
3238 | bind [-m KEYMAP] [-q FUNCTION] [-u FUNCTION] [-r KEYSEQ] |
3239 | bind [-m KEYMAP] -f FILENAME | |
3240 | bind [-m KEYMAP] -x KEYSEQ:SHELL-COMMAND | |
3241 | bind [-m KEYMAP] KEYSEQ:FUNCTION-NAME | |
fc527055 | 3242 | bind [-m KEYMAP] KEYSEQ:READLINE-COMMAND |
ccc6cda3 | 3243 | |
28ef6c31 | 3244 | Display current Readline (*note Command Line Editing::) key and |
7117c2d2 JA |
3245 | function bindings, bind a key sequence to a Readline function or |
3246 | macro, or set a Readline variable. Each non-option argument is a | |
8a0829e9 CR |
3247 | command as it would appear in a Readline initialization file (*note |
3248 | Readline Init File::), but each binding or command must be passed | |
3249 | as a separate argument; e.g., '"\C-x\C-r":re-read-init-file'. | |
ed35cb4a CR |
3250 | |
3251 | Options, if supplied, have the following meanings: | |
ccc6cda3 | 3252 | |
8a0829e9 | 3253 | '-m KEYMAP' |
bb70624e | 3254 | Use KEYMAP as the keymap to be affected by the subsequent |
8a0829e9 CR |
3255 | bindings. Acceptable KEYMAP names are 'emacs', |
3256 | 'emacs-standard', 'emacs-meta', 'emacs-ctlx', 'vi', 'vi-move', | |
3257 | 'vi-command', and 'vi-insert'. 'vi' is equivalent to | |
690150f9 CR |
3258 | 'vi-command' ('vi-move' is also a synonym); 'emacs' is |
3259 | equivalent to 'emacs-standard'. | |
cce855bc | 3260 | |
8a0829e9 | 3261 | '-l' |
bb70624e | 3262 | List the names of all Readline functions. |
cce855bc | 3263 | |
8a0829e9 | 3264 | '-p' |
bb70624e | 3265 | Display Readline function names and bindings in such a way |
8a0829e9 CR |
3266 | that they can be used as input or in a Readline initialization |
3267 | file. | |
cce855bc | 3268 | |
8a0829e9 | 3269 | '-P' |
bb70624e | 3270 | List current Readline function names and bindings. |
cce855bc | 3271 | |
8a0829e9 | 3272 | '-v' |
bb70624e JA |
3273 | Display Readline variable names and values in such a way that |
3274 | they can be used as input or in a Readline initialization | |
3275 | file. | |
ccc6cda3 | 3276 | |
8a0829e9 | 3277 | '-V' |
bb70624e | 3278 | List current Readline variable names and values. |
ccc6cda3 | 3279 | |
8a0829e9 CR |
3280 | '-s' |
3281 | Display Readline key sequences bound to macros and the strings | |
3282 | they output in such a way that they can be used as input or in | |
3283 | a Readline initialization file. | |
ccc6cda3 | 3284 | |
8a0829e9 CR |
3285 | '-S' |
3286 | Display Readline key sequences bound to macros and the strings | |
3287 | they output. | |
ccc6cda3 | 3288 | |
8a0829e9 | 3289 | '-f FILENAME' |
bb70624e | 3290 | Read key bindings from FILENAME. |
ccc6cda3 | 3291 | |
8a0829e9 | 3292 | '-q FUNCTION' |
bb70624e | 3293 | Query about which keys invoke the named FUNCTION. |
ccc6cda3 | 3294 | |
8a0829e9 | 3295 | '-u FUNCTION' |
bb70624e | 3296 | Unbind all keys bound to the named FUNCTION. |
ccc6cda3 | 3297 | |
8a0829e9 | 3298 | '-r KEYSEQ' |
bb70624e | 3299 | Remove any current binding for KEYSEQ. |
ccc6cda3 | 3300 | |
8a0829e9 | 3301 | '-x KEYSEQ:SHELL-COMMAND' |
bb70624e | 3302 | Cause SHELL-COMMAND to be executed whenever KEYSEQ is entered. |
ed35cb4a | 3303 | When SHELL-COMMAND is executed, the shell sets the |
8a0829e9 CR |
3304 | 'READLINE_LINE' variable to the contents of the Readline line |
3305 | buffer and the 'READLINE_POINT' variable to the current | |
ed35cb4a | 3306 | location of the insertion point. If the executed command |
8a0829e9 | 3307 | changes the value of 'READLINE_LINE' or 'READLINE_POINT', |
ed35cb4a | 3308 | those new values will be reflected in the editing state. |
761783bf | 3309 | |
8a0829e9 | 3310 | '-X' |
45c0f7f8 CR |
3311 | List all key sequences bound to shell commands and the |
3312 | associated commands in a format that can be reused as input. | |
3313 | ||
bb70624e JA |
3314 | The return status is zero unless an invalid option is supplied or |
3315 | an error occurs. | |
ccc6cda3 | 3316 | |
8a0829e9 | 3317 | 'builtin' |
bb70624e | 3318 | builtin [SHELL-BUILTIN [ARGS]] |
122f603c | 3319 | |
bb70624e | 3320 | Run a shell builtin, passing it ARGS, and return its exit status. |
8a0829e9 CR |
3321 | This is useful when defining a shell function with the same name as |
3322 | a shell builtin, retaining the functionality of the builtin within | |
3323 | the function. The return status is non-zero if SHELL-BUILTIN is | |
3324 | not a shell builtin command. | |
ccc6cda3 | 3325 | |
8a0829e9 | 3326 | 'caller' |
d3a24ed2 | 3327 | caller [EXPR] |
122f603c | 3328 | |
8a0829e9 CR |
3329 | Returns the context of any active subroutine call (a shell function |
3330 | or a script executed with the '.' or 'source' builtins). | |
d3a24ed2 | 3331 | |
8a0829e9 CR |
3332 | Without EXPR, 'caller' displays the line number and source filename |
3333 | of the current subroutine call. If a non-negative integer is | |
3334 | supplied as EXPR, 'caller' displays the line number, subroutine | |
3335 | name, and source file corresponding to that position in the current | |
3336 | execution call stack. This extra information may be used, for | |
3337 | example, to print a stack trace. The current frame is frame 0. | |
d3a24ed2 CR |
3338 | |
3339 | The return value is 0 unless the shell is not executing a | |
3340 | subroutine call or EXPR does not correspond to a valid position in | |
3341 | the call stack. | |
3342 | ||
8a0829e9 | 3343 | 'command' |
bb70624e | 3344 | command [-pVv] COMMAND [ARGUMENTS ...] |
122f603c | 3345 | |
bb70624e JA |
3346 | Runs COMMAND with ARGUMENTS ignoring any shell function named |
3347 | COMMAND. Only shell builtin commands or commands found by | |
8a0829e9 CR |
3348 | searching the 'PATH' are executed. If there is a shell function |
3349 | named 'ls', running 'command ls' within the function will execute | |
3350 | the external command 'ls' instead of calling the function | |
3351 | recursively. The '-p' option means to use a default value for | |
3352 | 'PATH' that is guaranteed to find all of the standard utilities. | |
3353 | The return status in this case is 127 if COMMAND cannot be found or | |
3354 | an error occurred, and the exit status of COMMAND otherwise. | |
3355 | ||
3356 | If either the '-V' or '-v' option is supplied, a description of | |
3357 | COMMAND is printed. The '-v' option causes a single word | |
bb70624e | 3358 | indicating the command or file name used to invoke COMMAND to be |
8a0829e9 CR |
3359 | displayed; the '-V' option produces a more verbose description. In |
3360 | this case, the return status is zero if COMMAND is found, and | |
bb70624e | 3361 | non-zero if not. |
ccc6cda3 | 3362 | |
8a0829e9 | 3363 | 'declare' |
9f178efb | 3364 | declare [-aAfFgilnrtux] [-p] [NAME[=VALUE] ...] |
ccc6cda3 | 3365 | |
8a0829e9 CR |
3366 | Declare variables and give them attributes. If no NAMEs are given, |
3367 | then display the values of variables instead. | |
ccc6cda3 | 3368 | |
8a0829e9 CR |
3369 | The '-p' option will display the attributes and values of each |
3370 | NAME. When '-p' is used with NAME arguments, additional options, | |
3371 | other than '-f' and '-F', are ignored. | |
6a8fd0ed | 3372 | |
8a0829e9 | 3373 | When '-p' is supplied without NAME arguments, 'declare' will |
6a8fd0ed CR |
3374 | display the attributes and values of all variables having the |
3375 | attributes specified by the additional options. If no other | |
8a0829e9 CR |
3376 | options are supplied with '-p', 'declare' will display the |
3377 | attributes and values of all shell variables. The '-f' option will | |
3378 | restrict the display to shell functions. | |
6a8fd0ed | 3379 | |
8a0829e9 CR |
3380 | The '-F' option inhibits the display of function definitions; only |
3381 | the function name and attributes are printed. If the 'extdebug' | |
3382 | shell option is enabled using 'shopt' (*note The Shopt Builtin::), | |
54a5fbe1 CR |
3383 | the source file name and line number where each NAME is defined are |
3384 | displayed as well. '-F' implies '-f'. | |
220537f2 | 3385 | |
8a0829e9 CR |
3386 | The '-g' option forces variables to be created or modified at the |
3387 | global scope, even when 'declare' is executed in a shell function. | |
d9e1f41e | 3388 | It is ignored in all other cases. |
220537f2 CR |
3389 | |
3390 | The following options can be used to restrict output to variables | |
3391 | with the specified attributes or to give variables attributes: | |
ccc6cda3 | 3392 | |
8a0829e9 | 3393 | '-a' |
09767ff0 CR |
3394 | Each NAME is an indexed array variable (*note Arrays::). |
3395 | ||
8a0829e9 | 3396 | '-A' |
09767ff0 | 3397 | Each NAME is an associative array variable (*note Arrays::). |
ccc6cda3 | 3398 | |
8a0829e9 | 3399 | '-f' |
bb70624e | 3400 | Use function names only. |
ccc6cda3 | 3401 | |
8a0829e9 | 3402 | '-i' |
bb70624e | 3403 | The variable is to be treated as an integer; arithmetic |
28ef6c31 | 3404 | evaluation (*note Shell Arithmetic::) is performed when the |
bb70624e | 3405 | variable is assigned a value. |
ccc6cda3 | 3406 | |
8a0829e9 | 3407 | '-l' |
8e1a6eaa CR |
3408 | When the variable is assigned a value, all upper-case |
3409 | characters are converted to lower-case. The upper-case | |
3410 | attribute is disabled. | |
3411 | ||
8a0829e9 | 3412 | '-n' |
9f178efb | 3413 | Give each NAME the NAMEREF attribute, making it a name |
8a0829e9 CR |
3414 | reference to another variable. That other variable is defined |
3415 | by the value of NAME. All references, assignments, and | |
3416 | attribute modifications to NAME, except for changing the '-n' | |
3417 | attribute itself, are performed on the variable referenced by | |
3418 | NAME's value. The nameref attribute cannot be applied to | |
3419 | array variables. | |
3420 | ||
3421 | '-r' | |
bb70624e JA |
3422 | Make NAMEs readonly. These names cannot then be assigned |
3423 | values by subsequent assignment statements or unset. | |
ccc6cda3 | 3424 | |
8a0829e9 CR |
3425 | '-t' |
3426 | Give each NAME the 'trace' attribute. Traced functions | |
3427 | inherit the 'DEBUG' and 'RETURN' traps from the calling shell. | |
8fed3589 | 3428 | The trace attribute has no special meaning for variables. |
7117c2d2 | 3429 | |
8a0829e9 | 3430 | '-u' |
8e1a6eaa CR |
3431 | When the variable is assigned a value, all lower-case |
3432 | characters are converted to upper-case. The lower-case | |
3433 | attribute is disabled. | |
3434 | ||
8a0829e9 | 3435 | '-x' |
bb70624e JA |
3436 | Mark each NAME for export to subsequent commands via the |
3437 | environment. | |
ccc6cda3 | 3438 | |
8a0829e9 CR |
3439 | Using '+' instead of '-' turns off the attribute instead, with the |
3440 | exceptions that '+a' may not be used to destroy an array variable | |
3441 | and '+r' will not remove the readonly attribute. When used in a | |
3442 | function, 'declare' makes each NAME local, as with the 'local' | |
3443 | command, unless the '-g' option is used. If a variable name is | |
220537f2 | 3444 | followed by =VALUE, the value of the variable is set to VALUE. |
ccc6cda3 | 3445 | |
8a0829e9 | 3446 | When using '-a' or '-A' and the compound assignment syntax to |
15baad62 CR |
3447 | create array variables, additional attributes do not take effect |
3448 | until subsequent assignments. | |
3449 | ||
bb70624e | 3450 | The return status is zero unless an invalid option is encountered, |
8a0829e9 | 3451 | an attempt is made to define a function using '-f foo=bar', an |
bb70624e JA |
3452 | attempt is made to assign a value to a readonly variable, an |
3453 | attempt is made to assign a value to an array variable without | |
28ef6c31 | 3454 | using the compound assignment syntax (*note Arrays::), one of the |
bb70624e JA |
3455 | NAMES is not a valid shell variable name, an attempt is made to |
3456 | turn off readonly status for a readonly variable, an attempt is | |
3457 | made to turn off array status for an array variable, or an attempt | |
8a0829e9 | 3458 | is made to display a non-existent function with '-f'. |
ccc6cda3 | 3459 | |
8a0829e9 | 3460 | 'echo' |
bb70624e | 3461 | echo [-neE] [ARG ...] |
122f603c | 3462 | |
bb70624e | 3463 | Output the ARGs, separated by spaces, terminated with a newline. |
8a0829e9 CR |
3464 | The return status is 0 unless a write error occurs. If '-n' is |
3465 | specified, the trailing newline is suppressed. If the '-e' option | |
74d0116b | 3466 | is given, interpretation of the following backslash-escaped |
8a0829e9 CR |
3467 | characters is enabled. The '-E' option disables the interpretation |
3468 | of these escape characters, even on systems where they are | |
3469 | interpreted by default. The 'xpg_echo' shell option may be used to | |
3470 | dynamically determine whether or not 'echo' expands these escape | |
3471 | characters by default. 'echo' does not interpret '--' to mean the | |
3472 | end of options. | |
3473 | ||
3474 | 'echo' interprets the following escape sequences: | |
3475 | '\a' | |
bb70624e | 3476 | alert (bell) |
8a0829e9 | 3477 | '\b' |
bb70624e | 3478 | backspace |
8a0829e9 | 3479 | '\c' |
a9fac3b2 | 3480 | suppress further output |
8a0829e9 CR |
3481 | '\e' |
3482 | '\E' | |
bb70624e | 3483 | escape |
8a0829e9 | 3484 | '\f' |
bb70624e | 3485 | form feed |
8a0829e9 | 3486 | '\n' |
bb70624e | 3487 | new line |
8a0829e9 | 3488 | '\r' |
bb70624e | 3489 | carriage return |
8a0829e9 | 3490 | '\t' |
bb70624e | 3491 | horizontal tab |
8a0829e9 | 3492 | '\v' |
bb70624e | 3493 | vertical tab |
8a0829e9 | 3494 | '\\' |
bb70624e | 3495 | backslash |
8a0829e9 | 3496 | '\0NNN' |
7117c2d2 JA |
3497 | the eight-bit character whose value is the octal value NNN |
3498 | (zero to three octal digits) | |
8a0829e9 | 3499 | '\xHH' |
f73dda09 JA |
3500 | the eight-bit character whose value is the hexadecimal value |
3501 | HH (one or two hex digits) | |
8a0829e9 | 3502 | '\uHHHH' |
220537f2 CR |
3503 | the Unicode (ISO/IEC 10646) character whose value is the |
3504 | hexadecimal value HHHH (one to four hex digits) | |
8a0829e9 | 3505 | '\UHHHHHHHH' |
220537f2 CR |
3506 | the Unicode (ISO/IEC 10646) character whose value is the |
3507 | hexadecimal value HHHHHHHH (one to eight hex digits) | |
3508 | ||
8a0829e9 | 3509 | 'enable' |
d3ad40de | 3510 | enable [-a] [-dnps] [-f FILENAME] [NAME ...] |
122f603c | 3511 | |
bb70624e | 3512 | Enable and disable builtin shell commands. Disabling a builtin |
8a0829e9 CR |
3513 | allows a disk command which has the same name as a shell builtin to |
3514 | be executed without specifying a full pathname, even though the | |
3515 | shell normally searches for builtins before disk commands. If '-n' | |
3516 | is used, the NAMEs become disabled. Otherwise NAMEs are enabled. | |
3517 | For example, to use the 'test' binary found via '$PATH' instead of | |
3518 | the shell builtin version, type 'enable -n test'. | |
3519 | ||
3520 | If the '-p' option is supplied, or no NAME arguments appear, a list | |
3521 | of shell builtins is printed. With no other arguments, the list | |
3522 | consists of all enabled shell builtins. The '-a' option means to | |
3523 | list each builtin with an indication of whether or not it is | |
3524 | enabled. | |
3525 | ||
3526 | The '-f' option means to load the new builtin command NAME from | |
bb70624e | 3527 | shared object FILENAME, on systems that support dynamic loading. |
8a0829e9 | 3528 | The '-d' option will delete a builtin loaded with '-f'. |
ccc6cda3 | 3529 | |
bb70624e | 3530 | If there are no options, a list of the shell builtins is displayed. |
8a0829e9 CR |
3531 | The '-s' option restricts 'enable' to the POSIX special builtins. |
3532 | If '-s' is used with '-f', the new builtin becomes a special | |
28ef6c31 | 3533 | builtin (*note Special Builtins::). |
ccc6cda3 | 3534 | |
bb70624e JA |
3535 | The return status is zero unless a NAME is not a shell builtin or |
3536 | there is an error loading a new builtin from a shared object. | |
ccc6cda3 | 3537 | |
8a0829e9 | 3538 | 'help' |
ed35cb4a | 3539 | help [-dms] [PATTERN] |
122f603c | 3540 | |
bb70624e | 3541 | Display helpful information about builtin commands. If PATTERN is |
8a0829e9 | 3542 | specified, 'help' gives detailed help on all commands matching |
ed35cb4a CR |
3543 | PATTERN, otherwise a list of the builtins is printed. |
3544 | ||
3545 | Options, if supplied, have the following meanings: | |
3546 | ||
8a0829e9 | 3547 | '-d' |
ed35cb4a | 3548 | Display a short description of each PATTERN |
8a0829e9 | 3549 | '-m' |
ed35cb4a CR |
3550 | Display the description of each PATTERN in a manpage-like |
3551 | format | |
8a0829e9 | 3552 | '-s' |
ed35cb4a CR |
3553 | Display only a short usage synopsis for each PATTERN |
3554 | ||
3555 | The return status is zero unless no command matches PATTERN. | |
ccc6cda3 | 3556 | |
8a0829e9 | 3557 | 'let' |
122f603c CR |
3558 | let EXPRESSION [EXPRESSION ...] |
3559 | ||
8a0829e9 | 3560 | The 'let' builtin allows arithmetic to be performed on shell |
bb70624e | 3561 | variables. Each EXPRESSION is evaluated according to the rules |
6a8fd0ed | 3562 | given below in *note Shell Arithmetic::. If the last EXPRESSION |
8a0829e9 | 3563 | evaluates to 0, 'let' returns 1; otherwise 0 is returned. |
ccc6cda3 | 3564 | |
8a0829e9 | 3565 | 'local' |
d3a24ed2 | 3566 | local [OPTION] NAME[=VALUE] ... |
122f603c | 3567 | |
bb70624e JA |
3568 | For each argument, a local variable named NAME is created, and |
3569 | assigned VALUE. The OPTION can be any of the options accepted by | |
8a0829e9 | 3570 | 'declare'. 'local' can only be used within a function; it makes |
bb70624e | 3571 | the variable NAME have a visible scope restricted to that function |
8a0829e9 CR |
3572 | and its children. If NAME is '-', the set of shell options is made |
3573 | local to the function in which 'local' is invoked: shell options | |
3574 | changed using the 'set' builtin inside the function are restored to | |
3575 | their original values when the function returns. The return status | |
3576 | is zero unless 'local' is used outside a function, an invalid NAME | |
3577 | is supplied, or NAME is a readonly variable. | |
3578 | ||
3579 | 'logout' | |
bb70624e | 3580 | logout [N] |
122f603c | 3581 | |
bb70624e | 3582 | Exit a login shell, returning a status of N to the shell's parent. |
ccc6cda3 | 3583 | |
8a0829e9 | 3584 | 'mapfile' |
fc527055 | 3585 | mapfile [-d DELIM] [-n COUNT] [-O ORIGIN] [-s COUNT] [-t] [-u FD] |
122f603c CR |
3586 | [-C CALLBACK] [-c QUANTUM] [ARRAY] |
3587 | ||
d6593885 | 3588 | Read lines from the standard input into the indexed array variable |
8a0829e9 CR |
3589 | ARRAY, or from file descriptor FD if the '-u' option is supplied. |
3590 | The variable 'MAPFILE' is the default ARRAY. Options, if supplied, | |
3591 | have the following meanings: | |
122f603c | 3592 | |
8a0829e9 | 3593 | '-d' |
fc527055 CR |
3594 | The first character of DELIM is used to terminate each input |
3595 | line, rather than newline. | |
8a0829e9 | 3596 | '-n' |
ed35cb4a CR |
3597 | Copy at most COUNT lines. If COUNT is 0, all lines are |
3598 | copied. | |
8a0829e9 | 3599 | '-O' |
ed35cb4a CR |
3600 | Begin assigning to ARRAY at index ORIGIN. The default index |
3601 | is 0. | |
8a0829e9 | 3602 | '-s' |
ed35cb4a | 3603 | Discard the first COUNT lines read. |
8a0829e9 | 3604 | '-t' |
0385211b | 3605 | Remove a trailing DELIM (default newline) from each line read. |
8a0829e9 | 3606 | '-u' |
ed35cb4a CR |
3607 | Read lines from file descriptor FD instead of the standard |
3608 | input. | |
8a0829e9 CR |
3609 | '-C' |
3610 | Evaluate CALLBACK each time QUANTUMP lines are read. The '-c' | |
3611 | option specifies QUANTUM. | |
3612 | '-c' | |
ed35cb4a CR |
3613 | Specify the number of lines read between each call to |
3614 | CALLBACK. | |
3615 | ||
8a0829e9 CR |
3616 | If '-C' is specified without '-c', the default quantum is 5000. |
3617 | When CALLBACK is evaluated, it is supplied the index of the next | |
220537f2 CR |
3618 | array element to be assigned and the line to be assigned to that |
3619 | element as additional arguments. CALLBACK is evaluated after the | |
3620 | line is read but before the array element is assigned. | |
ed35cb4a | 3621 | |
8a0829e9 | 3622 | If not supplied with an explicit origin, 'mapfile' will clear ARRAY |
ed35cb4a CR |
3623 | before assigning to it. |
3624 | ||
8a0829e9 CR |
3625 | 'mapfile' returns successfully unless an invalid option or option |
3626 | argument is supplied, ARRAY is invalid or unassignable, or ARRAY is | |
3627 | not an indexed array. | |
ed35cb4a | 3628 | |
8a0829e9 | 3629 | 'printf' |
29d25b54 | 3630 | printf [-v VAR] FORMAT [ARGUMENTS] |
122f603c | 3631 | |
bb70624e | 3632 | Write the formatted ARGUMENTS to the standard output under the |
8a0829e9 | 3633 | control of the FORMAT. The '-v' option causes the output to be |
220537f2 CR |
3634 | assigned to the variable VAR rather than being printed to the |
3635 | standard output. | |
3636 | ||
3637 | The FORMAT is a character string which contains three types of | |
3638 | objects: plain characters, which are simply copied to standard | |
3639 | output, character escape sequences, which are converted and copied | |
3640 | to the standard output, and format specifications, each of which | |
3641 | causes printing of the next successive ARGUMENT. In addition to | |
8a0829e9 CR |
3642 | the standard 'printf(1)' formats, 'printf' interprets the following |
3643 | extensions: | |
3644 | ||
3645 | '%b' | |
3646 | Causes 'printf' to expand backslash escape sequences in the | |
690150f9 CR |
3647 | corresponding ARGUMENT in the same way as 'echo -e' (*note |
3648 | Bash Builtins::). | |
8a0829e9 CR |
3649 | '%q' |
3650 | Causes 'printf' to output the corresponding ARGUMENT in a | |
220537f2 | 3651 | format that can be reused as shell input. |
8a0829e9 CR |
3652 | '%(DATEFMT)T' |
3653 | Causes 'printf' to output the date-time string resulting from | |
3654 | using DATEFMT as a format string for 'strftime'(3). The | |
220537f2 CR |
3655 | corresponding ARGUMENT is an integer representing the number |
3656 | of seconds since the epoch. Two special argument values may | |
8a0829e9 CR |
3657 | be used: -1 represents the current time, and -2 represents the |
3658 | time the shell was invoked. If no argument is specified, | |
ad4aef08 | 3659 | conversion behaves as if -1 had been given. This is an |
8a0829e9 | 3660 | exception to the usual 'printf' behavior. |
ccc6cda3 | 3661 | |
8a0829e9 CR |
3662 | Arguments to non-string format specifiers are treated as C language |
3663 | constants, except that a leading plus or minus sign is allowed, and | |
3664 | if the leading character is a single or double quote, the value is | |
3665 | the ASCII value of the following character. | |
eb0b2ad8 | 3666 | |
bb70624e JA |
3667 | The FORMAT is reused as necessary to consume all of the ARGUMENTS. |
3668 | If the FORMAT requires more ARGUMENTS than are supplied, the extra | |
3669 | format specifications behave as if a zero value or null string, as | |
3670 | appropriate, had been supplied. The return value is zero on | |
3671 | success, non-zero on failure. | |
ccc6cda3 | 3672 | |
8a0829e9 | 3673 | 'read' |
122f603c CR |
3674 | read [-ers] [-a ANAME] [-d DELIM] [-i TEXT] [-n NCHARS] |
3675 | [-N NCHARS] [-p PROMPT] [-t TIMEOUT] [-u FD] [NAME ...] | |
3676 | ||
7117c2d2 | 3677 | One line is read from the standard input, or from the file |
690150f9 CR |
3678 | descriptor FD supplied as an argument to the '-u' option, split |
3679 | into words as described above in *note Word Splitting::, and the | |
7117c2d2 | 3680 | first word is assigned to the first NAME, the second word to the |
690150f9 CR |
3681 | second NAME, and so on. If there are more words than names, the |
3682 | remaining words and their intervening delimiters are assigned to | |
3683 | the last NAME. If there are fewer words read from the input stream | |
3684 | than names, the remaining names are assigned empty values. The | |
3685 | characters in the value of the 'IFS' variable are used to split the | |
3686 | line into words using the same rules the shell uses for expansion | |
3687 | (described above in *note Word Splitting::). The backslash | |
3688 | character '\' may be used to remove any special meaning for the | |
3689 | next character read and for line continuation. If no names are | |
3690 | supplied, the line read is assigned to the variable 'REPLY'. The | |
3691 | exit status is zero, unless end-of-file is encountered, 'read' | |
3692 | times out (in which case the status is greater than 128), a | |
3693 | variable assignment error (such as assigning to a readonly | |
3694 | variable) occurs, or an invalid file descriptor is supplied as the | |
3695 | argument to '-u'. | |
8e1a6eaa CR |
3696 | |
3697 | Options, if supplied, have the following meanings: | |
ccc6cda3 | 3698 | |
8a0829e9 | 3699 | '-a ANAME' |
bb70624e JA |
3700 | The words are assigned to sequential indices of the array |
3701 | variable ANAME, starting at 0. All elements are removed from | |
3702 | ANAME before the assignment. Other NAME arguments are | |
3703 | ignored. | |
ccc6cda3 | 3704 | |
8a0829e9 | 3705 | '-d DELIM' |
bb70624e JA |
3706 | The first character of DELIM is used to terminate the input |
3707 | line, rather than newline. | |
ccc6cda3 | 3708 | |
8a0829e9 | 3709 | '-e' |
28ef6c31 | 3710 | Readline (*note Command Line Editing::) is used to obtain the |
a9fac3b2 CR |
3711 | line. Readline uses the current (or default, if line editing |
3712 | was not previously active) editing settings. | |
ccc6cda3 | 3713 | |
8a0829e9 | 3714 | '-i TEXT' |
6a8fd0ed CR |
3715 | If Readline is being used to read the line, TEXT is placed |
3716 | into the editing buffer before editing begins. | |
3717 | ||
8a0829e9 CR |
3718 | '-n NCHARS' |
3719 | 'read' returns after reading NCHARS characters rather than | |
3720 | waiting for a complete line of input, but honors a delimiter | |
d5362af8 CR |
3721 | if fewer than NCHARS characters are read before the delimiter. |
3722 | ||
8a0829e9 CR |
3723 | '-N NCHARS' |
3724 | 'read' returns after reading exactly NCHARS characters rather | |
d5362af8 | 3725 | than waiting for a complete line of input, unless EOF is |
8a0829e9 | 3726 | encountered or 'read' times out. Delimiter characters |
a3143574 | 3727 | encountered in the input are not treated specially and do not |
0385211b CR |
3728 | cause 'read' to return until NCHARS characters are read. The |
3729 | result is not split on the characters in 'IFS'; the intent is | |
3730 | that the variable is assigned exactly the characters read | |
3731 | (with the exception of backslash; see the '-r' option below). | |
cce855bc | 3732 | |
8a0829e9 | 3733 | '-p PROMPT' |
bb70624e JA |
3734 | Display PROMPT, without a trailing newline, before attempting |
3735 | to read any input. The prompt is displayed only if input is | |
3736 | coming from a terminal. | |
ccc6cda3 | 3737 | |
8a0829e9 | 3738 | '-r' |
bb70624e JA |
3739 | If this option is given, backslash does not act as an escape |
3740 | character. The backslash is considered to be part of the | |
8a0829e9 CR |
3741 | line. In particular, a backslash-newline pair may not be used |
3742 | as a line continuation. | |
ccc6cda3 | 3743 | |
8a0829e9 | 3744 | '-s' |
bb70624e JA |
3745 | Silent mode. If input is coming from a terminal, characters |
3746 | are not echoed. | |
cce855bc | 3747 | |
8a0829e9 CR |
3748 | '-t TIMEOUT' |
3749 | Cause 'read' to time out and return failure if a complete line | |
3750 | of input (or a specified number of characters) is not read | |
3751 | within TIMEOUT seconds. TIMEOUT may be a decimal number with | |
3752 | a fractional portion following the decimal point. This option | |
3753 | is only effective if 'read' is reading input from a terminal, | |
3754 | pipe, or other special file; it has no effect when reading | |
3755 | from regular files. If 'read' times out, 'read' saves any | |
3756 | partial input read into the specified variable NAME. If | |
3757 | TIMEOUT is 0, 'read' returns immediately, without trying to | |
122f603c CR |
3758 | read and data. The exit status is 0 if input is available on |
3759 | the specified file descriptor, non-zero otherwise. The exit | |
a9fac3b2 | 3760 | status is greater than 128 if the timeout is exceeded. |
cce855bc | 3761 | |
8a0829e9 | 3762 | '-u FD' |
7117c2d2 JA |
3763 | Read input from file descriptor FD. |
3764 | ||
8a0829e9 | 3765 | 'readarray' |
fc527055 | 3766 | readarray [-d DELIM] [-n COUNT] [-O ORIGIN] [-s COUNT] [-t] [-u FD] |
122f603c CR |
3767 | [-C CALLBACK] [-c QUANTUM] [ARRAY] |
3768 | ||
d6593885 | 3769 | Read lines from the standard input into the indexed array variable |
8a0829e9 | 3770 | ARRAY, or from file descriptor FD if the '-u' option is supplied. |
db31fb26 | 3771 | |
8a0829e9 | 3772 | A synonym for 'mapfile'. |
db31fb26 | 3773 | |
8a0829e9 | 3774 | 'source' |
bb70624e | 3775 | source FILENAME |
122f603c | 3776 | |
8a0829e9 | 3777 | A synonym for '.' (*note Bourne Shell Builtins::). |
ccc6cda3 | 3778 | |
8a0829e9 | 3779 | 'type' |
7117c2d2 | 3780 | type [-afptP] [NAME ...] |
122f603c | 3781 | |
bb70624e JA |
3782 | For each NAME, indicate how it would be interpreted if used as a |
3783 | command name. | |
cce855bc | 3784 | |
8a0829e9 CR |
3785 | If the '-t' option is used, 'type' prints a single word which is |
3786 | one of 'alias', 'function', 'builtin', 'file' or 'keyword', if NAME | |
3787 | is an alias, shell function, shell builtin, disk file, or shell | |
3788 | reserved word, respectively. If the NAME is not found, then | |
3789 | nothing is printed, and 'type' returns a failure status. | |
ccc6cda3 | 3790 | |
8a0829e9 CR |
3791 | If the '-p' option is used, 'type' either returns the name of the |
3792 | disk file that would be executed, or nothing if '-t' would not | |
3793 | return 'file'. | |
ccc6cda3 | 3794 | |
8a0829e9 CR |
3795 | The '-P' option forces a path search for each NAME, even if '-t' |
3796 | would not return 'file'. | |
7117c2d2 | 3797 | |
8a0829e9 CR |
3798 | If a command is hashed, '-p' and '-P' print the hashed value, which |
3799 | is not necessarily the file that appears first in '$PATH'. | |
7117c2d2 | 3800 | |
8a0829e9 | 3801 | If the '-a' option is used, 'type' returns all of the places that |
bb70624e | 3802 | contain an executable named FILE. This includes aliases and |
8a0829e9 | 3803 | functions, if and only if the '-p' option is not also used. |
ccc6cda3 | 3804 | |
8a0829e9 CR |
3805 | If the '-f' option is used, 'type' does not attempt to find shell |
3806 | functions, as with the 'command' builtin. | |
7117c2d2 | 3807 | |
ed35cb4a CR |
3808 | The return status is zero if all of the NAMES are found, non-zero |
3809 | if any are not found. | |
ccc6cda3 | 3810 | |
8a0829e9 | 3811 | 'typeset' |
9f178efb | 3812 | typeset [-afFgrxilnrtux] [-p] [NAME[=VALUE] ...] |
122f603c | 3813 | |
8a0829e9 CR |
3814 | The 'typeset' command is supplied for compatibility with the Korn |
3815 | shell. It is a synonym for the 'declare' builtin command. | |
ccc6cda3 | 3816 | |
8a0829e9 CR |
3817 | 'ulimit' |
3818 | ulimit [-HSabcdefiklmnpqrstuvxPT] [LIMIT] | |
122f603c | 3819 | |
8a0829e9 | 3820 | 'ulimit' provides control over the resources available to processes |
bb70624e JA |
3821 | started by the shell, on systems that allow such control. If an |
3822 | option is given, it is interpreted as follows: | |
122f603c | 3823 | |
8a0829e9 | 3824 | '-S' |
bb70624e | 3825 | Change and report the soft limit associated with a resource. |
ccc6cda3 | 3826 | |
8a0829e9 | 3827 | '-H' |
bb70624e | 3828 | Change and report the hard limit associated with a resource. |
ccc6cda3 | 3829 | |
8a0829e9 | 3830 | '-a' |
bb70624e | 3831 | All current limits are reported. |
ccc6cda3 | 3832 | |
8a0829e9 | 3833 | '-b' |
6a8fd0ed CR |
3834 | The maximum socket buffer size. |
3835 | ||
8a0829e9 | 3836 | '-c' |
bb70624e | 3837 | The maximum size of core files created. |
ccc6cda3 | 3838 | |
8a0829e9 | 3839 | '-d' |
bb70624e | 3840 | The maximum size of a process's data segment. |
ccc6cda3 | 3841 | |
8a0829e9 | 3842 | '-e' |
ac18b312 CR |
3843 | The maximum scheduling priority ("nice"). |
3844 | ||
8a0829e9 | 3845 | '-f' |
d3ad40de CR |
3846 | The maximum size of files written by the shell and its |
3847 | children. | |
ccc6cda3 | 3848 | |
8a0829e9 | 3849 | '-i' |
ac18b312 CR |
3850 | The maximum number of pending signals. |
3851 | ||
8a0829e9 CR |
3852 | '-k' |
3853 | The maximum number of kqueues that may be allocated. | |
3854 | ||
3855 | '-l' | |
bb70624e | 3856 | The maximum size that may be locked into memory. |
ccc6cda3 | 3857 | |
8a0829e9 | 3858 | '-m' |
6932f7f5 CR |
3859 | The maximum resident set size (many systems do not honor this |
3860 | limit). | |
ccc6cda3 | 3861 | |
8a0829e9 | 3862 | '-n' |
6932f7f5 CR |
3863 | The maximum number of open file descriptors (most systems do |
3864 | not allow this value to be set). | |
ccc6cda3 | 3865 | |
8a0829e9 | 3866 | '-p' |
bb70624e | 3867 | The pipe buffer size. |
ccc6cda3 | 3868 | |
8a0829e9 | 3869 | '-q' |
ac18b312 CR |
3870 | The maximum number of bytes in POSIX message queues. |
3871 | ||
8a0829e9 | 3872 | '-r' |
ac18b312 CR |
3873 | The maximum real-time scheduling priority. |
3874 | ||
8a0829e9 | 3875 | '-s' |
bb70624e | 3876 | The maximum stack size. |
ccc6cda3 | 3877 | |
8a0829e9 | 3878 | '-t' |
bb70624e | 3879 | The maximum amount of cpu time in seconds. |
ccc6cda3 | 3880 | |
8a0829e9 | 3881 | '-u' |
bb70624e | 3882 | The maximum number of processes available to a single user. |
cce855bc | 3883 | |
8a0829e9 | 3884 | '-v' |
eb0b2ad8 CR |
3885 | The maximum amount of virtual memory available to the shell, |
3886 | and, on some systems, to its children. | |
ccc6cda3 | 3887 | |
8a0829e9 | 3888 | '-x' |
ac18b312 CR |
3889 | The maximum number of file locks. |
3890 | ||
8a0829e9 CR |
3891 | '-P' |
3892 | The maximum number of pseudoterminals. | |
3893 | ||
3894 | '-T' | |
6a8fd0ed CR |
3895 | The maximum number of threads. |
3896 | ||
8a0829e9 | 3897 | If LIMIT is given, and the '-a' option is not used, LIMIT is the |
122f603c | 3898 | new value of the specified resource. The special LIMIT values |
8a0829e9 | 3899 | 'hard', 'soft', and 'unlimited' stand for the current hard limit, |
122f603c | 3900 | the current soft limit, and no limit, respectively. A hard limit |
8a0829e9 CR |
3901 | cannot be increased by a non-root user once it is set; a soft limit |
3902 | may be increased up to the value of the hard limit. Otherwise, the | |
3903 | current value of the soft limit for the specified resource is | |
3904 | printed, unless the '-H' option is supplied. When setting new | |
3905 | limits, if neither '-H' nor '-S' is supplied, both the hard and | |
3906 | soft limits are set. If no option is given, then '-f' is assumed. | |
3907 | Values are in 1024-byte increments, except for '-t', which is in | |
eac8fb1b CR |
3908 | seconds; '-p', which is in units of 512-byte blocks; '-P', '-T', |
3909 | '-b', '-k', '-n' and '-u', which are unscaled values; and, when in | |
3910 | POSIX Mode (*note Bash POSIX Mode::), '-c' and '-f', which are in | |
3911 | 512-byte increments. | |
ccc6cda3 | 3912 | |
f73dda09 JA |
3913 | The return status is zero unless an invalid option or argument is |
3914 | supplied, or an error occurs while setting a new limit. | |
ccc6cda3 | 3915 | |
8a0829e9 | 3916 | 'unalias' |
bb70624e | 3917 | unalias [-a] [NAME ... ] |
ccc6cda3 | 3918 | |
8a0829e9 | 3919 | Remove each NAME from the list of aliases. If '-a' is supplied, |
6a8fd0ed | 3920 | all aliases are removed. Aliases are described in *note Aliases::. |
ccc6cda3 | 3921 | |
bb70624e | 3922 | \1f |
d3ad40de | 3923 | File: bashref.info, Node: Modifying Shell Behavior, Next: Special Builtins, Prev: Bash Builtins, Up: Shell Builtin Commands |
ccc6cda3 | 3924 | |
d3ad40de CR |
3925 | 4.3 Modifying Shell Behavior |
3926 | ============================ | |
3927 | ||
3928 | * Menu: | |
3929 | ||
3930 | * The Set Builtin:: Change the values of shell attributes and | |
3931 | positional parameters. | |
3932 | * The Shopt Builtin:: Modify shell optional behavior. | |
3933 | ||
3934 | \1f | |
3935 | File: bashref.info, Node: The Set Builtin, Next: The Shopt Builtin, Up: Modifying Shell Behavior | |
3936 | ||
3937 | 4.3.1 The Set Builtin | |
3938 | --------------------- | |
9d6e5e30 | 3939 | |
8a0829e9 | 3940 | This builtin is so complicated that it deserves its own section. 'set' |
d3ad40de CR |
3941 | allows you to change the values of shell options and set the positional |
3942 | parameters, or to display the names and values of shell variables. | |
ccc6cda3 | 3943 | |
8a0829e9 | 3944 | 'set' |
e05be32d CR |
3945 | set [--abefhkmnptuvxBCEHPT] [-o OPTION-NAME] [ARGUMENT ...] |
3946 | set [+abefhkmnptuvxBCEHPT] [+o OPTION-NAME] [ARGUMENT ...] | |
ccc6cda3 | 3947 | |
8a0829e9 | 3948 | If no options or arguments are supplied, 'set' displays the names |
bb70624e | 3949 | and values of all shell variables and functions, sorted according |
54cdd75a CR |
3950 | to the current locale, in a format that may be reused as input for |
3951 | setting or resetting the currently-set variables. Read-only | |
8a0829e9 CR |
3952 | variables cannot be reset. In POSIX mode, only shell variables are |
3953 | listed. | |
ccc6cda3 | 3954 | |
bb70624e JA |
3955 | When options are supplied, they set or unset shell attributes. |
3956 | Options, if specified, have the following meanings: | |
ccc6cda3 | 3957 | |
8a0829e9 CR |
3958 | '-a' |
3959 | Each variable or function that is created or modified is given | |
3960 | the export attribute and marked for export to the environment | |
3961 | of subsequent commands. | |
ccc6cda3 | 3962 | |
8a0829e9 | 3963 | '-b' |
bb70624e JA |
3964 | Cause the status of terminated background jobs to be reported |
3965 | immediately, rather than before printing the next primary | |
3966 | prompt. | |
ccc6cda3 | 3967 | |
8a0829e9 | 3968 | '-e' |
6932f7f5 CR |
3969 | Exit immediately if a pipeline (*note Pipelines::), which may |
3970 | consist of a single simple command (*note Simple Commands::), | |
122f603c CR |
3971 | a list (*note Lists::), or a compound command (*note Compound |
3972 | Commands::) returns a non-zero status. The shell does not | |
3973 | exit if the command that fails is part of the command list | |
8a0829e9 CR |
3974 | immediately following a 'while' or 'until' keyword, part of |
3975 | the test in an 'if' statement, part of any command executed in | |
3976 | a '&&' or '||' list except the command following the final | |
3977 | '&&' or '||', any command in a pipeline but the last, or if | |
3978 | the command's return status is being inverted with '!'. If a | |
122f603c | 3979 | compound command other than a subshell returns a non-zero |
8a0829e9 CR |
3980 | status because a command failed while '-e' was being ignored, |
3981 | the shell does not exit. A trap on 'ERR', if set, is executed | |
3982 | before the shell exits. | |
ccc6cda3 | 3983 | |
8a0829e9 CR |
3984 | This option applies to the shell environment and each subshell |
3985 | environment separately (*note Command Execution | |
6932f7f5 CR |
3986 | Environment::), and may cause subshells to exit before |
3987 | executing all the commands in the subshell. | |
3988 | ||
ad4aef08 | 3989 | If a compound command or shell function executes in a context |
8a0829e9 | 3990 | where '-e' is being ignored, none of the commands executed |
ad4aef08 | 3991 | within the compound command or function body will be affected |
8a0829e9 CR |
3992 | by the '-e' setting, even if '-e' is set and a command returns |
3993 | a failure status. If a compound command or shell function | |
3994 | sets '-e' while executing in a context where '-e' is ignored, | |
3995 | that setting will not have any effect until the compound | |
3996 | command or the command containing the function call completes. | |
3997 | ||
3998 | '-f' | |
4a8bb13f | 3999 | Disable filename expansion (globbing). |
ccc6cda3 | 4000 | |
8a0829e9 | 4001 | '-h' |
bb70624e JA |
4002 | Locate and remember (hash) commands as they are looked up for |
4003 | execution. This option is enabled by default. | |
ccc6cda3 | 4004 | |
8a0829e9 | 4005 | '-k' |
bb70624e JA |
4006 | All arguments in the form of assignment statements are placed |
4007 | in the environment for a command, not just those that precede | |
4008 | the command name. | |
ccc6cda3 | 4009 | |
8a0829e9 | 4010 | '-m' |
74d0116b CR |
4011 | Job control is enabled (*note Job Control::). All processes |
4012 | run in a separate process group. When a background job | |
4013 | completes, the shell prints a line containing its exit status. | |
b72432fd | 4014 | |
8a0829e9 | 4015 | '-n' |
fc527055 | 4016 | Read commands but do not execute them. This may be used to |
bb70624e JA |
4017 | check a script for syntax errors. This option is ignored by |
4018 | interactive shells. | |
ccc6cda3 | 4019 | |
8a0829e9 CR |
4020 | '-o OPTION-NAME' |
4021 | ||
bb70624e | 4022 | Set the option corresponding to OPTION-NAME: |
ccc6cda3 | 4023 | |
8a0829e9 CR |
4024 | 'allexport' |
4025 | Same as '-a'. | |
ccc6cda3 | 4026 | |
8a0829e9 CR |
4027 | 'braceexpand' |
4028 | Same as '-B'. | |
ccc6cda3 | 4029 | |
8a0829e9 CR |
4030 | 'emacs' |
4031 | Use an 'emacs'-style line editing interface (*note | |
a9fac3b2 | 4032 | Command Line Editing::). This also affects the editing |
8a0829e9 | 4033 | interface used for 'read -e'. |
ccc6cda3 | 4034 | |
8a0829e9 CR |
4035 | 'errexit' |
4036 | Same as '-e'. | |
d166f048 | 4037 | |
8a0829e9 CR |
4038 | 'errtrace' |
4039 | Same as '-E'. | |
d3a24ed2 | 4040 | |
8a0829e9 CR |
4041 | 'functrace' |
4042 | Same as '-T'. | |
d3a24ed2 | 4043 | |
8a0829e9 CR |
4044 | 'hashall' |
4045 | Same as '-h'. | |
d166f048 | 4046 | |
8a0829e9 CR |
4047 | 'histexpand' |
4048 | Same as '-H'. | |
ccc6cda3 | 4049 | |
8a0829e9 | 4050 | 'history' |
6a8fd0ed | 4051 | Enable command history, as described in *note Bash |
bb70624e JA |
4052 | History Facilities::. This option is on by default in |
4053 | interactive shells. | |
ccc6cda3 | 4054 | |
8a0829e9 | 4055 | 'ignoreeof' |
bb70624e | 4056 | An interactive shell will not exit upon reading EOF. |
ccc6cda3 | 4057 | |
8a0829e9 CR |
4058 | 'keyword' |
4059 | Same as '-k'. | |
ccc6cda3 | 4060 | |
8a0829e9 CR |
4061 | 'monitor' |
4062 | Same as '-m'. | |
ccc6cda3 | 4063 | |
8a0829e9 CR |
4064 | 'noclobber' |
4065 | Same as '-C'. | |
ccc6cda3 | 4066 | |
8a0829e9 CR |
4067 | 'noexec' |
4068 | Same as '-n'. | |
ccc6cda3 | 4069 | |
8a0829e9 CR |
4070 | 'noglob' |
4071 | Same as '-f'. | |
9d6e5e30 | 4072 | |
8a0829e9 | 4073 | 'nolog' |
d3ad40de CR |
4074 | Currently ignored. |
4075 | ||
8a0829e9 CR |
4076 | 'notify' |
4077 | Same as '-b'. | |
d3ad40de | 4078 | |
8a0829e9 CR |
4079 | 'nounset' |
4080 | Same as '-u'. | |
d3ad40de | 4081 | |
8a0829e9 CR |
4082 | 'onecmd' |
4083 | Same as '-t'. | |
d3ad40de | 4084 | |
8a0829e9 CR |
4085 | 'physical' |
4086 | Same as '-P'. | |
d3ad40de | 4087 | |
8a0829e9 | 4088 | 'pipefail' |
d3ad40de CR |
4089 | If set, the return value of a pipeline is the value of |
4090 | the last (rightmost) command to exit with a non-zero | |
4091 | status, or zero if all commands in the pipeline exit | |
4092 | successfully. This option is disabled by default. | |
4093 | ||
8a0829e9 | 4094 | 'posix' |
d3ad40de CR |
4095 | Change the behavior of Bash where the default operation |
4096 | differs from the POSIX standard to match the standard | |
8a0829e9 CR |
4097 | (*note Bash POSIX Mode::). This is intended to make Bash |
4098 | behave as a strict superset of that standard. | |
d3ad40de | 4099 | |
8a0829e9 CR |
4100 | 'privileged' |
4101 | Same as '-p'. | |
d3ad40de | 4102 | |
8a0829e9 CR |
4103 | 'verbose' |
4104 | Same as '-v'. | |
d3ad40de | 4105 | |
8a0829e9 CR |
4106 | 'vi' |
4107 | Use a 'vi'-style line editing interface. This also | |
4108 | affects the editing interface used for 'read -e'. | |
d3ad40de | 4109 | |
8a0829e9 CR |
4110 | 'xtrace' |
4111 | Same as '-x'. | |
d3ad40de | 4112 | |
8a0829e9 CR |
4113 | '-p' |
4114 | Turn on privileged mode. In this mode, the '$BASH_ENV' and | |
4115 | '$ENV' files are not processed, shell functions are not | |
4116 | inherited from the environment, and the 'SHELLOPTS', | |
4117 | 'BASHOPTS', 'CDPATH' and 'GLOBIGNORE' variables, if they | |
8f714a7c CR |
4118 | appear in the environment, are ignored. If the shell is |
4119 | started with the effective user (group) id not equal to the | |
8a0829e9 | 4120 | real user (group) id, and the '-p' option is not supplied, |
8f714a7c | 4121 | these actions are taken and the effective user id is set to |
8a0829e9 | 4122 | the real user id. If the '-p' option is supplied at startup, |
8f714a7c CR |
4123 | the effective user id is not reset. Turning this option off |
4124 | causes the effective user and group ids to be set to the real | |
4125 | user and group ids. | |
d3ad40de | 4126 | |
8a0829e9 | 4127 | '-t' |
d3ad40de CR |
4128 | Exit after reading and executing one command. |
4129 | ||
8a0829e9 | 4130 | '-u' |
2c471a92 | 4131 | Treat unset variables and parameters other than the special |
8a0829e9 | 4132 | parameters '@' or '*' as an error when performing parameter |
d3ad40de CR |
4133 | expansion. An error message will be written to the standard |
4134 | error, and a non-interactive shell will exit. | |
4135 | ||
8a0829e9 | 4136 | '-v' |
d3ad40de CR |
4137 | Print shell input lines as they are read. |
4138 | ||
8a0829e9 CR |
4139 | '-x' |
4140 | Print a trace of simple commands, 'for' commands, 'case' | |
4141 | commands, 'select' commands, and arithmetic 'for' commands and | |
4142 | their arguments or associated word lists after they are | |
4143 | expanded and before they are executed. The value of the 'PS4' | |
d3ad40de CR |
4144 | variable is expanded and the resultant value is printed before |
4145 | the command and its expanded arguments. | |
4146 | ||
8a0829e9 | 4147 | '-B' |
d3ad40de CR |
4148 | The shell will perform brace expansion (*note Brace |
4149 | Expansion::). This option is on by default. | |
4150 | ||
8a0829e9 CR |
4151 | '-C' |
4152 | Prevent output redirection using '>', '>&', and '<>' from | |
d3ad40de CR |
4153 | overwriting existing files. |
4154 | ||
8a0829e9 CR |
4155 | '-E' |
4156 | If set, any trap on 'ERR' is inherited by shell functions, | |
d3ad40de | 4157 | command substitutions, and commands executed in a subshell |
8a0829e9 CR |
4158 | environment. The 'ERR' trap is normally not inherited in such |
4159 | cases. | |
d3ad40de | 4160 | |
8a0829e9 CR |
4161 | '-H' |
4162 | Enable '!' style history substitution (*note History | |
d3ad40de CR |
4163 | Interaction::). This option is on by default for interactive |
4164 | shells. | |
4165 | ||
8a0829e9 CR |
4166 | '-P' |
4167 | If set, do not resolve symbolic links when performing commands | |
4168 | such as 'cd' which change the current directory. The physical | |
4169 | directory is used instead. By default, Bash follows the | |
4170 | logical chain of directories when performing commands which | |
4171 | change the current directory. | |
d3ad40de | 4172 | |
8a0829e9 CR |
4173 | For example, if '/usr/sys' is a symbolic link to |
4174 | '/usr/local/sys' then: | |
d3ad40de CR |
4175 | $ cd /usr/sys; echo $PWD |
4176 | /usr/sys | |
4177 | $ cd ..; pwd | |
4178 | /usr | |
4179 | ||
8a0829e9 | 4180 | If 'set -P' is on, then: |
d3ad40de CR |
4181 | $ cd /usr/sys; echo $PWD |
4182 | /usr/local/sys | |
4183 | $ cd ..; pwd | |
4184 | /usr/local | |
4185 | ||
8a0829e9 CR |
4186 | '-T' |
4187 | If set, any trap on 'DEBUG' and 'RETURN' are inherited by | |
d3ad40de | 4188 | shell functions, command substitutions, and commands executed |
8a0829e9 CR |
4189 | in a subshell environment. The 'DEBUG' and 'RETURN' traps are |
4190 | normally not inherited in such cases. | |
d3ad40de | 4191 | |
8a0829e9 | 4192 | '--' |
d3ad40de CR |
4193 | If no arguments follow this option, then the positional |
4194 | parameters are unset. Otherwise, the positional parameters | |
4195 | are set to the ARGUMENTS, even if some of them begin with a | |
8a0829e9 | 4196 | '-'. |
d3ad40de | 4197 | |
8a0829e9 CR |
4198 | '-' |
4199 | Signal the end of options, cause all remaining ARGUMENTS to be | |
4200 | assigned to the positional parameters. The '-x' and '-v' | |
d3ad40de CR |
4201 | options are turned off. If there are no arguments, the |
4202 | positional parameters remain unchanged. | |
4203 | ||
8a0829e9 | 4204 | Using '+' rather than '-' causes these options to be turned off. |
d3ad40de | 4205 | The options can also be used upon invocation of the shell. The |
8a0829e9 | 4206 | current set of options may be found in '$-'. |
d3ad40de CR |
4207 | |
4208 | The remaining N ARGUMENTS are positional parameters and are | |
8a0829e9 CR |
4209 | assigned, in order, to '$1', '$2', ... '$N'. The special parameter |
4210 | '#' is set to N. | |
d3ad40de CR |
4211 | |
4212 | The return status is always zero unless an invalid option is | |
4213 | supplied. | |
4214 | ||
4215 | \1f | |
4216 | File: bashref.info, Node: The Shopt Builtin, Prev: The Set Builtin, Up: Modifying Shell Behavior | |
4217 | ||
4218 | 4.3.2 The Shopt Builtin | |
4219 | ----------------------- | |
4220 | ||
4221 | This builtin allows you to change additional shell optional behavior. | |
4222 | ||
8a0829e9 | 4223 | 'shopt' |
d3ad40de | 4224 | shopt [-pqsu] [-o] [OPTNAME ...] |
122f603c | 4225 | |
1101193a | 4226 | Toggle the values of settings controlling optional shell behavior. |
8a0829e9 CR |
4227 | The settings can be either those listed below, or, if the '-o' |
4228 | option is used, those available with the '-o' option to the 'set' | |
1101193a | 4229 | builtin command (*note The Set Builtin::). With no options, or |
8a0829e9 CR |
4230 | with the '-p' option, a list of all settable options is displayed, |
4231 | with an indication of whether or not each is set. The '-p' option | |
1101193a CR |
4232 | causes output to be displayed in a form that may be reused as |
4233 | input. Other options have the following meanings: | |
d3ad40de | 4234 | |
8a0829e9 | 4235 | '-s' |
d3ad40de CR |
4236 | Enable (set) each OPTNAME. |
4237 | ||
8a0829e9 | 4238 | '-u' |
d3ad40de CR |
4239 | Disable (unset) each OPTNAME. |
4240 | ||
8a0829e9 | 4241 | '-q' |
d3ad40de CR |
4242 | Suppresses normal output; the return status indicates whether |
4243 | the OPTNAME is set or unset. If multiple OPTNAME arguments | |
8a0829e9 CR |
4244 | are given with '-q', the return status is zero if all OPTNAMES |
4245 | are enabled; non-zero otherwise. | |
d3ad40de | 4246 | |
8a0829e9 | 4247 | '-o' |
d3ad40de | 4248 | Restricts the values of OPTNAME to be those defined for the |
8a0829e9 | 4249 | '-o' option to the 'set' builtin (*note The Set Builtin::). |
d3ad40de | 4250 | |
8a0829e9 | 4251 | If either '-s' or '-u' is used with no OPTNAME arguments, 'shopt' |
122f603c | 4252 | shows only those options which are set or unset, respectively. |
d3ad40de | 4253 | |
8a0829e9 | 4254 | Unless otherwise noted, the 'shopt' options are disabled (off) by |
d3ad40de CR |
4255 | default. |
4256 | ||
4257 | The return status when listing options is zero if all OPTNAMES are | |
4258 | enabled, non-zero otherwise. When setting or unsetting options, | |
4259 | the return status is zero unless an OPTNAME is not a valid shell | |
4260 | option. | |
4261 | ||
8a0829e9 CR |
4262 | The list of 'shopt' options is: |
4263 | ||
4264 | 'autocd' | |
d3ad40de | 4265 | If set, a command name that is the name of a directory is |
8a0829e9 CR |
4266 | executed as if it were the argument to the 'cd' command. This |
4267 | option is only used by interactive shells. | |
d3ad40de | 4268 | |
8a0829e9 CR |
4269 | 'cdable_vars' |
4270 | If this is set, an argument to the 'cd' builtin command that | |
d3ad40de CR |
4271 | is not a directory is assumed to be the name of a variable |
4272 | whose value is the directory to change to. | |
4273 | ||
8a0829e9 | 4274 | 'cdspell' |
d3ad40de | 4275 | If set, minor errors in the spelling of a directory component |
8a0829e9 | 4276 | in a 'cd' command will be corrected. The errors checked for |
d3ad40de CR |
4277 | are transposed characters, a missing character, and a |
4278 | character too many. If a correction is found, the corrected | |
4279 | path is printed, and the command proceeds. This option is | |
4280 | only used by interactive shells. | |
4281 | ||
8a0829e9 | 4282 | 'checkhash' |
d3ad40de | 4283 | If this is set, Bash checks that a command found in the hash |
8a0829e9 CR |
4284 | table exists before trying to execute it. If a hashed command |
4285 | no longer exists, a normal path search is performed. | |
d3ad40de | 4286 | |
8a0829e9 | 4287 | 'checkjobs' |
d3ad40de | 4288 | If set, Bash lists the status of any stopped and running jobs |
8a0829e9 CR |
4289 | before exiting an interactive shell. If any jobs are running, |
4290 | this causes the exit to be deferred until a second exit is | |
4291 | attempted without an intervening command (*note Job | |
d3ad40de CR |
4292 | Control::). The shell always postpones exiting if any jobs |
4293 | are stopped. | |
4294 | ||
8a0829e9 CR |
4295 | 'checkwinsize' |
4296 | If set, Bash checks the window size after each command and, if | |
4297 | necessary, updates the values of 'LINES' and 'COLUMNS'. | |
d3ad40de | 4298 | |
8a0829e9 | 4299 | 'cmdhist' |
d3ad40de CR |
4300 | If set, Bash attempts to save all lines of a multiple-line |
4301 | command in the same history entry. This allows easy | |
4302 | re-editing of multi-line commands. | |
4303 | ||
8a0829e9 | 4304 | 'compat31' |
29d25b54 | 4305 | If set, Bash changes its behavior to that of version 3.1 with |
8a0829e9 CR |
4306 | respect to quoted arguments to the conditional command's '=~' |
4307 | operator and with respect to locale-specific string comparison | |
4308 | when using the '[[' conditional command's '<' and '>' | |
4309 | operators. Bash versions prior to bash-4.1 use ASCII | |
abe2eb5b CR |
4310 | collation and strcmp(3); bash-4.1 and later use the current |
4311 | locale's collation sequence and strcoll(3). | |
29d25b54 | 4312 | |
8a0829e9 | 4313 | 'compat32' |
5cdaaf76 CR |
4314 | If set, Bash changes its behavior to that of version 3.2 with |
4315 | respect to locale-specific string comparison when using the | |
8a0829e9 | 4316 | '[[' conditional command's '<' and '>' operators (see previous |
690150f9 CR |
4317 | item) and the effect of interrupting a command list. Bash |
4318 | versions 3.2 and earlier continue with the next command in the | |
4319 | list after one terminates due to an interrupt. | |
5cdaaf76 | 4320 | |
8a0829e9 | 4321 | 'compat40' |
5cdaaf76 CR |
4322 | If set, Bash changes its behavior to that of version 4.0 with |
4323 | respect to locale-specific string comparison when using the | |
8a0829e9 CR |
4324 | '[[' conditional command's '<' and '>' operators (see |
4325 | description of 'compat31') and the effect of interrupting a | |
abe2eb5b CR |
4326 | command list. Bash versions 4.0 and later interrupt the list |
4327 | as if the shell received the interrupt; previous versions | |
4328 | continue with the next command in the list. | |
5cdaaf76 | 4329 | |
8a0829e9 | 4330 | 'compat41' |
c2fa6583 | 4331 | If set, Bash, when in POSIX mode, treats a single quote in a |
8a0829e9 CR |
4332 | double-quoted parameter expansion as a special character. The |
4333 | single quotes must match (an even number) and the characters | |
4334 | between the single quotes are considered quoted. This is the | |
4335 | behavior of POSIX mode through version 4.1. The default Bash | |
4336 | behavior remains as in previous versions. | |
7d92f73f | 4337 | |
8a0829e9 | 4338 | 'compat42' |
ad4aef08 CR |
4339 | If set, Bash does not process the replacement string in the |
4340 | pattern substitution word expansion using quote removal. | |
4341 | ||
54a5fbe1 CR |
4342 | 'compat43' |
4343 | If set, Bash does not print a warning message if an attempt is | |
4344 | made to use a quoted compound array assignment as an argument | |
690150f9 | 4345 | to 'declare', makes word expansion errors non-fatal errors |
54a5fbe1 | 4346 | that cause the current command to fail (the default behavior |
690150f9 CR |
4347 | is to make them fatal errors that cause the shell to exit), |
4348 | and does not reset the loop state when a shell function is | |
4349 | executed (this allows 'break' or 'continue' in a shell | |
4350 | function to affect loops in the caller's context). | |
54a5fbe1 | 4351 | |
8a0829e9 | 4352 | 'complete_fullquote' |
122f603c CR |
4353 | If set, Bash quotes all shell metacharacters in filenames and |
4354 | directory names when performing completion. If not set, Bash | |
4355 | removes metacharacters such as the dollar sign from the set of | |
4356 | characters that will be quoted in completed filenames when | |
4357 | these metacharacters appear in shell variable references in | |
4358 | words to be completed. This means that dollar signs in | |
4359 | variable names that expand to directories will not be quoted; | |
4360 | however, any dollar signs appearing in filenames will not be | |
4361 | quoted, either. This is active only when bash is using | |
4362 | backslashes to quote completed filenames. This variable is | |
8a0829e9 CR |
4363 | set by default, which is the default Bash behavior in versions |
4364 | through 4.2. | |
122f603c | 4365 | |
8a0829e9 CR |
4366 | 'direxpand' |
4367 | If set, Bash replaces directory names with the results of word | |
4368 | expansion when performing filename completion. This changes | |
4369 | the contents of the readline editing buffer. If not set, Bash | |
4370 | attempts to preserve what the user typed. | |
74d0116b | 4371 | |
8a0829e9 | 4372 | 'dirspell' |
ed35cb4a CR |
4373 | If set, Bash attempts spelling correction on directory names |
4374 | during word completion if the directory name initially | |
4375 | supplied does not exist. | |
4376 | ||
8a0829e9 CR |
4377 | 'dotglob' |
4378 | If set, Bash includes filenames beginning with a '.' in the | |
d3ad40de CR |
4379 | results of filename expansion. |
4380 | ||
8a0829e9 | 4381 | 'execfail' |
d3ad40de | 4382 | If this is set, a non-interactive shell will not exit if it |
8a0829e9 CR |
4383 | cannot execute the file specified as an argument to the 'exec' |
4384 | builtin command. An interactive shell does not exit if 'exec' | |
d3ad40de CR |
4385 | fails. |
4386 | ||
8a0829e9 | 4387 | 'expand_aliases' |
d3ad40de | 4388 | If set, aliases are expanded as described below under Aliases, |
6a8fd0ed | 4389 | *note Aliases::. This option is enabled by default for |
d3ad40de CR |
4390 | interactive shells. |
4391 | ||
8a0829e9 | 4392 | 'extdebug' |
d3ad40de CR |
4393 | If set, behavior intended for use by debuggers is enabled: |
4394 | ||
8a0829e9 CR |
4395 | 1. The '-F' option to the 'declare' builtin (*note Bash |
4396 | Builtins::) displays the source file name and line number | |
4397 | corresponding to each function name supplied as an | |
4398 | argument. | |
d3ad40de | 4399 | |
8a0829e9 CR |
4400 | 2. If the command run by the 'DEBUG' trap returns a non-zero |
4401 | value, the next command is skipped and not executed. | |
d3ad40de | 4402 | |
8a0829e9 CR |
4403 | 3. If the command run by the 'DEBUG' trap returns a value of |
4404 | 2, and the shell is executing in a subroutine (a shell | |
4405 | function or a shell script executed by the '.' or | |
4406 | 'source' builtins), the shell simulates a call to | |
4407 | 'return'. | |
d3ad40de | 4408 | |
8a0829e9 | 4409 | 4. 'BASH_ARGC' and 'BASH_ARGV' are updated as described in |
d3ad40de CR |
4410 | their descriptions (*note Bash Variables::). |
4411 | ||
fc527055 | 4412 | 5. Function tracing is enabled: command substitution, shell |
8a0829e9 CR |
4413 | functions, and subshells invoked with '( COMMAND )' |
4414 | inherit the 'DEBUG' and 'RETURN' traps. | |
9d6e5e30 | 4415 | |
fc527055 | 4416 | 6. Error tracing is enabled: command substitution, shell |
8a0829e9 CR |
4417 | functions, and subshells invoked with '( COMMAND )' |
4418 | inherit the 'ERR' trap. | |
9d6e5e30 | 4419 | |
8a0829e9 | 4420 | 'extglob' |
d3ad40de CR |
4421 | If set, the extended pattern matching features described above |
4422 | (*note Pattern Matching::) are enabled. | |
9d6e5e30 | 4423 | |
8a0829e9 CR |
4424 | 'extquote' |
4425 | If set, '$'STRING'' and '$"STRING"' quoting is performed | |
4426 | within '${PARAMETER}' expansions enclosed in double quotes. | |
d3ad40de | 4427 | This option is enabled by default. |
9d6e5e30 | 4428 | |
8a0829e9 CR |
4429 | 'failglob' |
4430 | If set, patterns which fail to match filenames during filename | |
4431 | expansion result in an expansion error. | |
9d6e5e30 | 4432 | |
8a0829e9 CR |
4433 | 'force_fignore' |
4434 | If set, the suffixes specified by the 'FIGNORE' shell variable | |
4435 | cause words to be ignored when performing word completion even | |
4436 | if the ignored words are the only possible completions. *Note | |
4437 | Bash Variables::, for a description of 'FIGNORE'. This option | |
4438 | is enabled by default. | |
9d6e5e30 | 4439 | |
8a0829e9 | 4440 | 'globasciiranges' |
1101193a CR |
4441 | If set, range expressions used in pattern matching bracket |
4442 | expressions (*note Pattern Matching::) behave as if in the | |
4443 | traditional C locale when performing comparisons. That is, | |
4444 | the current locale's collating sequence is not taken into | |
8a0829e9 | 4445 | account, so 'b' will not collate between 'A' and 'B', and |
1101193a CR |
4446 | upper-case and lower-case ASCII characters will collate |
4447 | together. | |
74d0116b | 4448 | |
8a0829e9 CR |
4449 | 'globstar' |
4450 | If set, the pattern '**' used in a filename expansion context | |
d9e1f41e | 4451 | will match all files and zero or more directories and |
8a0829e9 | 4452 | subdirectories. If the pattern is followed by a '/', only |
ed35cb4a CR |
4453 | directories and subdirectories match. |
4454 | ||
8a0829e9 | 4455 | 'gnu_errfmt' |
d3ad40de CR |
4456 | If set, shell error messages are written in the standard GNU |
4457 | error message format. | |
9d6e5e30 | 4458 | |
8a0829e9 | 4459 | 'histappend' |
d3ad40de | 4460 | If set, the history list is appended to the file named by the |
8a0829e9 | 4461 | value of the 'HISTFILE' variable when the shell exits, rather |
d3ad40de | 4462 | than overwriting the file. |
9d6e5e30 | 4463 | |
8a0829e9 | 4464 | 'histreedit' |
d3ad40de CR |
4465 | If set, and Readline is being used, a user is given the |
4466 | opportunity to re-edit a failed history substitution. | |
9d6e5e30 | 4467 | |
8a0829e9 | 4468 | 'histverify' |
d3ad40de CR |
4469 | If set, and Readline is being used, the results of history |
4470 | substitution are not immediately passed to the shell parser. | |
4471 | Instead, the resulting line is loaded into the Readline | |
4472 | editing buffer, allowing further modification. | |
9d6e5e30 | 4473 | |
8a0829e9 | 4474 | 'hostcomplete' |
d3ad40de | 4475 | If set, and Readline is being used, Bash will attempt to |
8a0829e9 | 4476 | perform hostname completion when a word containing a '@' is |
d3ad40de CR |
4477 | being completed (*note Commands For Completion::). This |
4478 | option is enabled by default. | |
9d6e5e30 | 4479 | |
8a0829e9 CR |
4480 | 'huponexit' |
4481 | If set, Bash will send 'SIGHUP' to all jobs when an | |
d3ad40de | 4482 | interactive login shell exits (*note Signals::). |
9d6e5e30 | 4483 | |
690150f9 CR |
4484 | 'inherit_errexit' |
4485 | If set, command substitution inherits the value of the | |
4486 | 'errexit' option, instead of unsetting it in the subshell | |
4487 | environment. This option is enabled when POSIX mode is | |
4488 | enabled. | |
4489 | ||
8a0829e9 CR |
4490 | 'interactive_comments' |
4491 | Allow a word beginning with '#' to cause that word and all | |
d3ad40de CR |
4492 | remaining characters on that line to be ignored in an |
4493 | interactive shell. This option is enabled by default. | |
9d6e5e30 | 4494 | |
8a0829e9 CR |
4495 | 'lastpipe' |
4496 | If set, and job control is not active, the shell runs the last | |
4497 | command of a pipeline not executed in the background in the | |
4498 | current shell environment. | |
9ec5ed66 | 4499 | |
8a0829e9 CR |
4500 | 'lithist' |
4501 | If enabled, and the 'cmdhist' option is enabled, multi-line | |
d3ad40de CR |
4502 | commands are saved to the history with embedded newlines |
4503 | rather than using semicolon separators where possible. | |
9d6e5e30 | 4504 | |
8a0829e9 | 4505 | 'login_shell' |
d3ad40de CR |
4506 | The shell sets this option if it is started as a login shell |
4507 | (*note Invoking Bash::). The value may not be changed. | |
9d6e5e30 | 4508 | |
8a0829e9 | 4509 | 'mailwarn' |
d3ad40de | 4510 | If set, and a file that Bash is checking for mail has been |
8a0829e9 CR |
4511 | accessed since the last time it was checked, the message '"The |
4512 | mail in MAILFILE has been read"' is displayed. | |
9d6e5e30 | 4513 | |
8a0829e9 | 4514 | 'no_empty_cmd_completion' |
d3ad40de | 4515 | If set, and Readline is being used, Bash will not attempt to |
8a0829e9 | 4516 | search the 'PATH' for possible completions when completion is |
d3ad40de | 4517 | attempted on an empty line. |
9d6e5e30 | 4518 | |
8a0829e9 | 4519 | 'nocaseglob' |
d3ad40de CR |
4520 | If set, Bash matches filenames in a case-insensitive fashion |
4521 | when performing filename expansion. | |
9d6e5e30 | 4522 | |
8a0829e9 | 4523 | 'nocasematch' |
d3ad40de | 4524 | If set, Bash matches patterns in a case-insensitive fashion |
8a0829e9 CR |
4525 | when performing matching while executing 'case' or '[[' |
4526 | conditional commands, when performing pattern substitution | |
4527 | word expansions, or when filtering possible completions as | |
4528 | part of programmable completion. | |
9d6e5e30 | 4529 | |
8a0829e9 | 4530 | 'nullglob' |
d3ad40de CR |
4531 | If set, Bash allows filename patterns which match no files to |
4532 | expand to a null string, rather than themselves. | |
9d6e5e30 | 4533 | |
8a0829e9 | 4534 | 'progcomp' |
d3ad40de CR |
4535 | If set, the programmable completion facilities (*note |
4536 | Programmable Completion::) are enabled. This option is | |
4537 | enabled by default. | |
9d6e5e30 | 4538 | |
8a0829e9 | 4539 | 'promptvars' |
d3ad40de CR |
4540 | If set, prompt strings undergo parameter expansion, command |
4541 | substitution, arithmetic expansion, and quote removal after | |
122f603c CR |
4542 | being expanded as described below (*note Controlling the |
4543 | Prompt::). This option is enabled by default. | |
9d6e5e30 | 4544 | |
8a0829e9 | 4545 | 'restricted_shell' |
d3ad40de CR |
4546 | The shell sets this option if it is started in restricted mode |
4547 | (*note The Restricted Shell::). The value may not be changed. | |
4548 | This is not reset when the startup files are executed, | |
4549 | allowing the startup files to discover whether or not a shell | |
4550 | is restricted. | |
9d6e5e30 | 4551 | |
8a0829e9 CR |
4552 | 'shift_verbose' |
4553 | If this is set, the 'shift' builtin prints an error message | |
d3ad40de CR |
4554 | when the shift count exceeds the number of positional |
4555 | parameters. | |
9d6e5e30 | 4556 | |
8a0829e9 CR |
4557 | 'sourcepath' |
4558 | If set, the 'source' builtin uses the value of 'PATH' to find | |
d3ad40de CR |
4559 | the directory containing the file supplied as an argument. |
4560 | This option is enabled by default. | |
9d6e5e30 | 4561 | |
8a0829e9 CR |
4562 | 'xpg_echo' |
4563 | If set, the 'echo' builtin expands backslash-escape sequences | |
d3ad40de | 4564 | by default. |
9d6e5e30 | 4565 | |
d3ad40de CR |
4566 | The return status when listing options is zero if all OPTNAMES are |
4567 | enabled, non-zero otherwise. When setting or unsetting options, | |
4568 | the return status is zero unless an OPTNAME is not a valid shell | |
4569 | option. | |
9d6e5e30 | 4570 | |
9d6e5e30 | 4571 | \1f |
d3ad40de | 4572 | File: bashref.info, Node: Special Builtins, Prev: Modifying Shell Behavior, Up: Shell Builtin Commands |
ccc6cda3 | 4573 | |
37c41ab1 CR |
4574 | 4.4 Special Builtins |
4575 | ==================== | |
ccc6cda3 | 4576 | |
ac18b312 CR |
4577 | For historical reasons, the POSIX standard has classified several |
4578 | builtin commands as _special_. When Bash is executing in POSIX mode, | |
4579 | the special builtins differ from other builtin commands in three | |
bb70624e | 4580 | respects: |
ccc6cda3 | 4581 | |
bb70624e JA |
4582 | 1. Special builtins are found before shell functions during command |
4583 | lookup. | |
ccc6cda3 | 4584 | |
bb70624e JA |
4585 | 2. If a special builtin returns an error status, a non-interactive |
4586 | shell exits. | |
ccc6cda3 | 4587 | |
bb70624e JA |
4588 | 3. Assignment statements preceding the command stay in effect in the |
4589 | shell environment after the command completes. | |
ccc6cda3 | 4590 | |
bb70624e JA |
4591 | When Bash is not executing in POSIX mode, these builtins behave no |
4592 | differently than the rest of the Bash builtin commands. The Bash POSIX | |
6a8fd0ed | 4593 | mode is described in *note Bash POSIX Mode::. |
ccc6cda3 | 4594 | |
bb70624e JA |
4595 | These are the POSIX special builtins: |
4596 | break : . continue eval exec exit export readonly return set | |
4597 | shift trap unset | |
ccc6cda3 | 4598 | |
bb70624e JA |
4599 | \1f |
4600 | File: bashref.info, Node: Shell Variables, Next: Bash Features, Prev: Shell Builtin Commands, Up: Top | |
cce855bc | 4601 | |
37c41ab1 CR |
4602 | 5 Shell Variables |
4603 | ***************** | |
ccc6cda3 | 4604 | |
bb70624e | 4605 | * Menu: |
ccc6cda3 | 4606 | |
bb70624e JA |
4607 | * Bourne Shell Variables:: Variables which Bash uses in the same way |
4608 | as the Bourne Shell. | |
4609 | * Bash Variables:: List of variables that exist in Bash. | |
ccc6cda3 | 4610 | |
8a0829e9 | 4611 | This chapter describes the shell variables that Bash uses. Bash |
bb70624e | 4612 | automatically assigns default values to a number of variables. |
cce855bc | 4613 | |
bb70624e JA |
4614 | \1f |
4615 | File: bashref.info, Node: Bourne Shell Variables, Next: Bash Variables, Up: Shell Variables | |
ccc6cda3 | 4616 | |
37c41ab1 CR |
4617 | 5.1 Bourne Shell Variables |
4618 | ========================== | |
cce855bc | 4619 | |
37c41ab1 CR |
4620 | Bash uses certain shell variables in the same way as the Bourne shell. |
4621 | In some cases, Bash assigns a default value to the variable. | |
cce855bc | 4622 | |
8a0829e9 CR |
4623 | 'CDPATH' |
4624 | A colon-separated list of directories used as a search path for the | |
4625 | 'cd' builtin command. | |
ccc6cda3 | 4626 | |
8a0829e9 CR |
4627 | 'HOME' |
4628 | The current user's home directory; the default for the 'cd' builtin | |
bb70624e | 4629 | command. The value of this variable is also used by tilde |
28ef6c31 | 4630 | expansion (*note Tilde Expansion::). |
ccc6cda3 | 4631 | |
8a0829e9 | 4632 | 'IFS' |
bb70624e JA |
4633 | A list of characters that separate fields; used when the shell |
4634 | splits words as part of expansion. | |
ccc6cda3 | 4635 | |
8a0829e9 | 4636 | 'MAIL' |
e05be32d | 4637 | If this parameter is set to a filename or directory name and the |
8a0829e9 | 4638 | 'MAILPATH' variable is not set, Bash informs the user of the |
e05be32d | 4639 | arrival of mail in the specified file or Maildir-format directory. |
cce855bc | 4640 | |
8a0829e9 | 4641 | 'MAILPATH' |
bb70624e JA |
4642 | A colon-separated list of filenames which the shell periodically |
4643 | checks for new mail. Each list entry can specify the message that | |
8a0829e9 CR |
4644 | is printed when new mail arrives in the mail file by separating the |
4645 | filename from the message with a '?'. When used in the text of the | |
4646 | message, '$_' expands to the name of the current mail file. | |
cce855bc | 4647 | |
8a0829e9 CR |
4648 | 'OPTARG' |
4649 | The value of the last option argument processed by the 'getopts' | |
bb70624e | 4650 | builtin. |
ccc6cda3 | 4651 | |
8a0829e9 CR |
4652 | 'OPTIND' |
4653 | The index of the last option argument processed by the 'getopts' | |
bb70624e | 4654 | builtin. |
ccc6cda3 | 4655 | |
8a0829e9 | 4656 | 'PATH' |
bb70624e | 4657 | A colon-separated list of directories in which the shell looks for |
d3a24ed2 | 4658 | commands. A zero-length (null) directory name in the value of |
8a0829e9 | 4659 | 'PATH' indicates the current directory. A null directory name may |
d3a24ed2 | 4660 | appear as two adjacent colons, or as an initial or trailing colon. |
ccc6cda3 | 4661 | |
8a0829e9 CR |
4662 | 'PS1' |
4663 | The primary prompt string. The default value is '\s-\v\$ '. *Note | |
4664 | Controlling the Prompt::, for the complete list of escape sequences | |
4665 | that are expanded before 'PS1' is displayed. | |
ccc6cda3 | 4666 | |
8a0829e9 CR |
4667 | 'PS2' |
4668 | The secondary prompt string. The default value is '> '. | |
761783bf | 4669 | |
bb70624e JA |
4670 | \1f |
4671 | File: bashref.info, Node: Bash Variables, Prev: Bourne Shell Variables, Up: Shell Variables | |
ccc6cda3 | 4672 | |
37c41ab1 CR |
4673 | 5.2 Bash Variables |
4674 | ================== | |
ccc6cda3 | 4675 | |
37c41ab1 | 4676 | These variables are set or used by Bash, but other shells do not |
bb70624e | 4677 | normally treat them specially. |
ccc6cda3 | 4678 | |
bb70624e JA |
4679 | A few variables used by Bash are described in different chapters: |
4680 | variables for controlling the job control facilities (*note Job Control | |
28ef6c31 | 4681 | Variables::). |
ccc6cda3 | 4682 | |
8a0829e9 | 4683 | 'BASH' |
bb70624e | 4684 | The full pathname used to execute the current instance of Bash. |
ccc6cda3 | 4685 | |
8a0829e9 | 4686 | 'BASHOPTS' |
8f714a7c | 4687 | A colon-separated list of enabled shell options. Each word in the |
8a0829e9 CR |
4688 | list is a valid argument for the '-s' option to the 'shopt' builtin |
4689 | command (*note The Shopt Builtin::). The options appearing in | |
4690 | 'BASHOPTS' are those reported as 'on' by 'shopt'. If this variable | |
4691 | is in the environment when Bash starts up, each shell option in the | |
4692 | list will be enabled before reading any startup files. This | |
4693 | variable is readonly. | |
4694 | ||
4695 | 'BASHPID' | |
e05be32d | 4696 | Expands to the process ID of the current Bash process. This |
8a0829e9 | 4697 | differs from '$$' under certain circumstances, such as subshells |
d3ad40de CR |
4698 | that do not require Bash to be re-initialized. |
4699 | ||
8a0829e9 | 4700 | 'BASH_ALIASES' |
09767ff0 | 4701 | An associative array variable whose members correspond to the |
8a0829e9 | 4702 | internal list of aliases as maintained by the 'alias' builtin. |
09767ff0 | 4703 | (*note Bourne Shell Builtins::). Elements added to this array |
690150f9 CR |
4704 | appear in the alias list; however, unsetting array elements |
4705 | currently does not cause aliases to be removed from the alias list. | |
4706 | If 'BASH_ALIASES' is unset, it loses its special properties, even | |
4707 | if it is subsequently reset. | |
09767ff0 | 4708 | |
8a0829e9 | 4709 | 'BASH_ARGC' |
d3a24ed2 CR |
4710 | An array variable whose values are the number of parameters in each |
4711 | frame of the current bash execution call stack. The number of | |
4712 | parameters to the current subroutine (shell function or script | |
8a0829e9 | 4713 | executed with '.' or 'source') is at the top of the stack. When a |
d3a24ed2 | 4714 | subroutine is executed, the number of parameters passed is pushed |
8a0829e9 CR |
4715 | onto 'BASH_ARGC'. The shell sets 'BASH_ARGC' only when in extended |
4716 | debugging mode (see *note The Shopt Builtin:: for a description of | |
4717 | the 'extdebug' option to the 'shopt' builtin). | |
d3a24ed2 | 4718 | |
8a0829e9 | 4719 | 'BASH_ARGV' |
d3a24ed2 CR |
4720 | An array variable containing all of the parameters in the current |
4721 | bash execution call stack. The final parameter of the last | |
4722 | subroutine call is at the top of the stack; the first parameter of | |
4723 | the initial call is at the bottom. When a subroutine is executed, | |
8a0829e9 CR |
4724 | the parameters supplied are pushed onto 'BASH_ARGV'. The shell |
4725 | sets 'BASH_ARGV' only when in extended debugging mode (see *note | |
4726 | The Shopt Builtin:: for a description of the 'extdebug' option to | |
4727 | the 'shopt' builtin). | |
d3a24ed2 | 4728 | |
8a0829e9 | 4729 | 'BASH_CMDS' |
09767ff0 | 4730 | An associative array variable whose members correspond to the |
8a0829e9 | 4731 | internal hash table of commands as maintained by the 'hash' builtin |
09767ff0 | 4732 | (*note Bourne Shell Builtins::). Elements added to this array |
690150f9 CR |
4733 | appear in the hash table; however, unsetting array elements |
4734 | currently does not cause command names to be removed from the hash | |
4735 | table. If 'BASH_CMDS' is unset, it loses its special properties, | |
4736 | even if it is subsequently reset. | |
09767ff0 | 4737 | |
8a0829e9 | 4738 | 'BASH_COMMAND' |
d3a24ed2 | 4739 | The command currently being executed or about to be executed, |
8a0829e9 CR |
4740 | unless the shell is executing a command as the result of a trap, in |
4741 | which case it is the command executing at the time of the trap. | |
d3a24ed2 | 4742 | |
8a0829e9 | 4743 | 'BASH_COMPAT' |
ad4aef08 CR |
4744 | The value is used to set the shell's compatibility level. *Note |
4745 | The Shopt Builtin::, for a description of the various compatibility | |
8a0829e9 CR |
4746 | levels and their effects. The value may be a decimal number (e.g., |
4747 | 4.2) or an integer (e.g., 42) corresponding to the desired | |
4748 | compatibility level. If 'BASH_COMPAT' is unset or set to the empty | |
4749 | string, the compatibility level is set to the default for the | |
4750 | current version. If 'BASH_COMPAT' is set to a value that is not | |
4751 | one of the valid compatibility levels, the shell prints an error | |
4752 | message and sets the compatibility level to the default for the | |
4753 | current version. The valid compatibility levels correspond to the | |
4754 | compatibility options accepted by the 'shopt' builtin described | |
4755 | above (for example, COMPAT42 means that 4.2 and 42 are valid | |
4756 | values). The current version is also a valid value. | |
4757 | ||
4758 | 'BASH_ENV' | |
bb70624e JA |
4759 | If this variable is set when Bash is invoked to execute a shell |
4760 | script, its value is expanded and used as the name of a startup | |
4761 | file to read before executing the script. *Note Bash Startup | |
4762 | Files::. | |
ccc6cda3 | 4763 | |
8a0829e9 CR |
4764 | 'BASH_EXECUTION_STRING' |
4765 | The command argument to the '-c' invocation option. | |
d3a24ed2 | 4766 | |
8a0829e9 | 4767 | 'BASH_LINENO' |
d3a24ed2 | 4768 | An array variable whose members are the line numbers in source |
9ec5ed66 | 4769 | files where each corresponding member of FUNCNAME was invoked. |
8a0829e9 CR |
4770 | '${BASH_LINENO[$i]}' is the line number in the source file |
4771 | ('${BASH_SOURCE[$i+1]}') where '${FUNCNAME[$i]}' was called (or | |
4772 | '${BASH_LINENO[$i-1]}' if referenced within another shell | |
4773 | function). Use 'LINENO' to obtain the current line number. | |
4774 | ||
54a5fbe1 CR |
4775 | 'BASH_LOADABLES_PATH' |
4776 | A colon-separated list of directories in which the shell looks for | |
4777 | dynamically loadable builtins specified by the 'enable' command. | |
4778 | ||
8a0829e9 CR |
4779 | 'BASH_REMATCH' |
4780 | An array variable whose members are assigned by the '=~' binary | |
4781 | operator to the '[[' conditional command (*note Conditional | |
5e13499c CR |
4782 | Constructs::). The element with index 0 is the portion of the |
4783 | string matching the entire regular expression. The element with | |
8a0829e9 CR |
4784 | index N is the portion of the string matching the Nth parenthesized |
4785 | subexpression. This variable is read-only. | |
5e13499c | 4786 | |
8a0829e9 | 4787 | 'BASH_SOURCE' |
9ec5ed66 | 4788 | An array variable whose members are the source filenames where the |
8a0829e9 CR |
4789 | corresponding shell function names in the 'FUNCNAME' array variable |
4790 | are defined. The shell function '${FUNCNAME[$i]}' is defined in | |
4791 | the file '${BASH_SOURCE[$i]}' and called from | |
4792 | '${BASH_SOURCE[$i+1]}' | |
d3a24ed2 | 4793 | |
8a0829e9 | 4794 | 'BASH_SUBSHELL' |
f6da9f85 CR |
4795 | Incremented by one within each subshell or subshell environment |
4796 | when the shell begins executing in that environment. The initial | |
4797 | value is 0. | |
ccc6cda3 | 4798 | |
8a0829e9 | 4799 | 'BASH_VERSINFO' |
28ef6c31 | 4800 | A readonly array variable (*note Arrays::) whose members hold |
8a0829e9 CR |
4801 | version information for this instance of Bash. The values assigned |
4802 | to the array members are as follows: | |
ccc6cda3 | 4803 | |
8a0829e9 | 4804 | 'BASH_VERSINFO[0]' |
bb70624e | 4805 | The major version number (the RELEASE). |
ccc6cda3 | 4806 | |
8a0829e9 | 4807 | 'BASH_VERSINFO[1]' |
bb70624e | 4808 | The minor version number (the VERSION). |
ccc6cda3 | 4809 | |
8a0829e9 | 4810 | 'BASH_VERSINFO[2]' |
bb70624e | 4811 | The patch level. |
ccc6cda3 | 4812 | |
8a0829e9 | 4813 | 'BASH_VERSINFO[3]' |
bb70624e | 4814 | The build version. |
ccc6cda3 | 4815 | |
8a0829e9 | 4816 | 'BASH_VERSINFO[4]' |
bb70624e | 4817 | The release status (e.g., BETA1). |
ccc6cda3 | 4818 | |
8a0829e9 CR |
4819 | 'BASH_VERSINFO[5]' |
4820 | The value of 'MACHTYPE'. | |
ccc6cda3 | 4821 | |
8a0829e9 | 4822 | 'BASH_VERSION' |
d3a24ed2 CR |
4823 | The version number of the current instance of Bash. |
4824 | ||
8a0829e9 | 4825 | 'BASH_XTRACEFD' |
8f714a7c | 4826 | If set to an integer corresponding to a valid file descriptor, Bash |
8a0829e9 | 4827 | will write the trace output generated when 'set -x' is enabled to |
8f714a7c CR |
4828 | that file descriptor. This allows tracing output to be separated |
4829 | from diagnostic and error messages. The file descriptor is closed | |
8a0829e9 CR |
4830 | when 'BASH_XTRACEFD' is unset or assigned a new value. Unsetting |
4831 | 'BASH_XTRACEFD' or assigning it the empty string causes the trace | |
8f714a7c | 4832 | output to be sent to the standard error. Note that setting |
8a0829e9 | 4833 | 'BASH_XTRACEFD' to 2 (the standard error file descriptor) and then |
8f714a7c CR |
4834 | unsetting it will result in the standard error being closed. |
4835 | ||
8a0829e9 | 4836 | 'CHILD_MAX' |
ad4aef08 CR |
4837 | Set the number of exited child status values for the shell to |
4838 | remember. Bash will not allow this value to be decreased below a | |
4839 | POSIX-mandated minimum, and there is a maximum value (currently | |
4840 | 8192) that this may not exceed. The minimum value is | |
4841 | system-dependent. | |
4842 | ||
8a0829e9 CR |
4843 | 'COLUMNS' |
4844 | Used by the 'select' command to determine the terminal width when | |
4845 | printing selection lists. Automatically set if the 'checkwinsize' | |
4846 | option is enabled (*note The Shopt Builtin::), or in an interactive | |
4847 | shell upon receipt of a 'SIGWINCH'. | |
bb70624e | 4848 | |
8a0829e9 CR |
4849 | 'COMP_CWORD' |
4850 | An index into '${COMP_WORDS}' of the word containing the current | |
bb70624e JA |
4851 | cursor position. This variable is available only in shell |
4852 | functions invoked by the programmable completion facilities (*note | |
28ef6c31 | 4853 | Programmable Completion::). |
bb70624e | 4854 | |
8a0829e9 CR |
4855 | 'COMP_LINE' |
4856 | The current command line. This variable is available only in shell | |
4857 | functions and external commands invoked by the programmable | |
28ef6c31 | 4858 | completion facilities (*note Programmable Completion::). |
bb70624e | 4859 | |
8a0829e9 | 4860 | 'COMP_POINT' |
bb70624e JA |
4861 | The index of the current cursor position relative to the beginning |
4862 | of the current command. If the current cursor position is at the | |
4863 | end of the current command, the value of this variable is equal to | |
8a0829e9 | 4864 | '${#COMP_LINE}'. This variable is available only in shell |
bb70624e | 4865 | functions and external commands invoked by the programmable |
28ef6c31 | 4866 | completion facilities (*note Programmable Completion::). |
bb70624e | 4867 | |
8a0829e9 | 4868 | 'COMP_TYPE' |
d3ad40de CR |
4869 | Set to an integer value corresponding to the type of completion |
4870 | attempted that caused a completion function to be called: TAB, for | |
8a0829e9 CR |
4871 | normal completion, '?', for listing completions after successive |
4872 | tabs, '!', for listing alternatives on partial word completion, | |
4873 | '@', to list completions if the word is not unmodified, or '%', for | |
4874 | menu completion. This variable is available only in shell | |
d3ad40de CR |
4875 | functions and external commands invoked by the programmable |
4876 | completion facilities (*note Programmable Completion::). | |
4877 | ||
8a0829e9 | 4878 | 'COMP_KEY' |
d3ad40de CR |
4879 | The key (or final key of a key sequence) used to invoke the current |
4880 | completion function. | |
4881 | ||
8a0829e9 | 4882 | 'COMP_WORDBREAKS' |
d3a24ed2 | 4883 | The set of characters that the Readline library treats as word |
8a0829e9 | 4884 | separators when performing word completion. If 'COMP_WORDBREAKS' |
d3a24ed2 CR |
4885 | is unset, it loses its special properties, even if it is |
4886 | subsequently reset. | |
4887 | ||
8a0829e9 CR |
4888 | 'COMP_WORDS' |
4889 | An array variable consisting of the individual words in the current | |
4890 | command line. The line is split into words as Readline would split | |
4891 | it, using 'COMP_WORDBREAKS' as described above. This variable is | |
4892 | available only in shell functions invoked by the programmable | |
4893 | completion facilities (*note Programmable Completion::). | |
f73dda09 | 4894 | |
8a0829e9 | 4895 | 'COMPREPLY' |
bb70624e JA |
4896 | An array variable from which Bash reads the possible completions |
4897 | generated by a shell function invoked by the programmable | |
45c0f7f8 CR |
4898 | completion facility (*note Programmable Completion::). Each array |
4899 | element contains one possible completion. | |
ccc6cda3 | 4900 | |
8a0829e9 | 4901 | 'COPROC' |
5cdaaf76 CR |
4902 | An array variable created to hold the file descriptors for output |
4903 | from and input to an unnamed coprocess (*note Coprocesses::). | |
4904 | ||
8a0829e9 | 4905 | 'DIRSTACK' |
bb70624e JA |
4906 | An array variable containing the current contents of the directory |
4907 | stack. Directories appear in the stack in the order they are | |
8a0829e9 | 4908 | displayed by the 'dirs' builtin. Assigning to members of this |
bb70624e | 4909 | array variable may be used to modify directories already in the |
8a0829e9 | 4910 | stack, but the 'pushd' and 'popd' builtins must be used to add and |
bb70624e | 4911 | remove directories. Assignment to this variable will not change |
8a0829e9 | 4912 | the current directory. If 'DIRSTACK' is unset, it loses its |
bb70624e | 4913 | special properties, even if it is subsequently reset. |
cce855bc | 4914 | |
8a0829e9 | 4915 | 'EMACS' |
d3a24ed2 | 4916 | If Bash finds this variable in the environment when the shell |
8a0829e9 | 4917 | starts with value 't', it assumes that the shell is running in an |
e05be32d | 4918 | Emacs shell buffer and disables line editing. |
d3a24ed2 | 4919 | |
8a0829e9 CR |
4920 | 'ENV' |
4921 | Similar to 'BASH_ENV'; used when the shell is invoked in POSIX Mode | |
4922 | (*note Bash POSIX Mode::). | |
5cdaaf76 | 4923 | |
8a0829e9 | 4924 | 'EUID' |
bb70624e JA |
4925 | The numeric effective user id of the current user. This variable |
4926 | is readonly. | |
cce855bc | 4927 | |
eac8fb1b | 4928 | 'EXECIGNORE' |
690150f9 CR |
4929 | A colon-separated list of shell patterns (*note Pattern Matching::) |
4930 | defining the list of filenames to be ignored by command search. | |
4931 | Files whose full pathnames match one of these patterns are not | |
4932 | considered executable files for the purposes of completion and | |
eac8fb1b CR |
4933 | command execution. This does not affect the behavior of the '[', |
4934 | 'test', and '[[' commands. Use this variable to ignore shared | |
4935 | library files that have the executable bit set, but are not | |
690150f9 CR |
4936 | executable files. The pattern matching honors the setting of the |
4937 | 'extglob' shell option. | |
eac8fb1b | 4938 | |
8a0829e9 CR |
4939 | 'FCEDIT' |
4940 | The editor used as a default by the '-e' option to the 'fc' builtin | |
4941 | command. | |
ccc6cda3 | 4942 | |
8a0829e9 | 4943 | 'FIGNORE' |
bb70624e | 4944 | A colon-separated list of suffixes to ignore when performing |
122f603c | 4945 | filename completion. A filename whose suffix matches one of the |
8a0829e9 CR |
4946 | entries in 'FIGNORE' is excluded from the list of matched |
4947 | filenames. A sample value is '.o:~' | |
ccc6cda3 | 4948 | |
8a0829e9 | 4949 | 'FUNCNAME' |
d3a24ed2 | 4950 | An array variable containing the names of all shell functions |
8a0829e9 CR |
4951 | currently in the execution call stack. The element with index 0 is |
4952 | the name of any currently-executing shell function. The | |
4953 | bottom-most element (the one with the highest index) is '"main"'. | |
9ec5ed66 | 4954 | This variable exists only when a shell function is executing. |
54a5fbe1 CR |
4955 | Assignments to 'FUNCNAME' have no effect. If 'FUNCNAME' is unset, |
4956 | it loses its special properties, even if it is subsequently reset. | |
9ec5ed66 | 4957 | |
8a0829e9 CR |
4958 | This variable can be used with 'BASH_LINENO' and 'BASH_SOURCE'. |
4959 | Each element of 'FUNCNAME' has corresponding elements in | |
4960 | 'BASH_LINENO' and 'BASH_SOURCE' to describe the call stack. For | |
4961 | instance, '${FUNCNAME[$i]}' was called from the file | |
4962 | '${BASH_SOURCE[$i+1]}' at line number '${BASH_LINENO[$i]}'. The | |
4963 | 'caller' builtin displays the current call stack using this | |
9ec5ed66 | 4964 | information. |
f73dda09 | 4965 | |
8a0829e9 | 4966 | 'FUNCNEST' |
220537f2 CR |
4967 | If set to a numeric value greater than 0, defines a maximum |
4968 | function nesting level. Function invocations that exceed this | |
4969 | nesting level will cause the current command to abort. | |
4970 | ||
8a0829e9 | 4971 | 'GLOBIGNORE' |
bb70624e JA |
4972 | A colon-separated list of patterns defining the set of filenames to |
4973 | be ignored by filename expansion. If a filename matched by a | |
4974 | filename expansion pattern also matches one of the patterns in | |
690150f9 CR |
4975 | 'GLOBIGNORE', it is removed from the list of matches. The pattern |
4976 | matching honors the setting of the 'extglob' shell option. | |
ccc6cda3 | 4977 | |
8a0829e9 | 4978 | 'GROUPS' |
bb70624e | 4979 | An array variable containing the list of groups of which the |
54a5fbe1 CR |
4980 | current user is a member. Assignments to 'GROUPS' have no effect. |
4981 | If 'GROUPS' is unset, it loses its special properties, even if it | |
4982 | is subsequently reset. | |
ccc6cda3 | 4983 | |
8a0829e9 | 4984 | 'histchars' |
bb70624e | 4985 | Up to three characters which control history expansion, quick |
28ef6c31 JA |
4986 | substitution, and tokenization (*note History Interaction::). The |
4987 | first character is the HISTORY EXPANSION character, that is, the | |
4988 | character which signifies the start of a history expansion, | |
8a0829e9 CR |
4989 | normally '!'. The second character is the character which |
4990 | signifies 'quick substitution' when seen as the first character on | |
4991 | a line, normally '^'. The optional third character is the | |
bb70624e | 4992 | character which indicates that the remainder of the line is a |
8a0829e9 | 4993 | comment when found as the first character of a word, usually '#'. |
bb70624e JA |
4994 | The history comment character causes history substitution to be |
4995 | skipped for the remaining words on the line. It does not | |
8a0829e9 CR |
4996 | necessarily cause the shell parser to treat the rest of the line as |
4997 | a comment. | |
cce855bc | 4998 | |
8a0829e9 | 4999 | 'HISTCMD' |
bb70624e | 5000 | The history number, or index in the history list, of the current |
8a0829e9 | 5001 | command. If 'HISTCMD' is unset, it loses its special properties, |
bb70624e | 5002 | even if it is subsequently reset. |
ccc6cda3 | 5003 | |
8a0829e9 CR |
5004 | 'HISTCONTROL' |
5005 | A colon-separated list of values controlling how commands are saved | |
5006 | on the history list. If the list of values includes 'ignorespace', | |
5007 | lines which begin with a space character are not saved in the | |
5008 | history list. A value of 'ignoredups' causes lines which match the | |
5009 | previous history entry to not be saved. A value of 'ignoreboth' is | |
5010 | shorthand for 'ignorespace' and 'ignoredups'. A value of | |
5011 | 'erasedups' causes all previous lines matching the current line to | |
5012 | be removed from the history list before that line is saved. Any | |
5013 | value not in the above list is ignored. If 'HISTCONTROL' is unset, | |
5014 | or does not include a valid value, all lines read by the shell | |
5015 | parser are saved on the history list, subject to the value of | |
5016 | 'HISTIGNORE'. The second and subsequent lines of a multi-line | |
5017 | compound command are not tested, and are added to the history | |
5018 | regardless of the value of 'HISTCONTROL'. | |
5019 | ||
5020 | 'HISTFILE' | |
f73dda09 | 5021 | The name of the file to which the command history is saved. The |
8a0829e9 | 5022 | default value is '~/.bash_history'. |
f73dda09 | 5023 | |
8a0829e9 | 5024 | 'HISTFILESIZE' |
f73dda09 JA |
5025 | The maximum number of lines contained in the history file. When |
5026 | this variable is assigned a value, the history file is truncated, | |
45c0f7f8 | 5027 | if necessary, to contain no more than that number of lines by |
8a0829e9 CR |
5028 | removing the oldest entries. The history file is also truncated to |
5029 | this size after writing it when a shell exits. If the value is 0, | |
5030 | the history file is truncated to zero size. Non-numeric values and | |
5031 | numeric values less than zero inhibit truncation. The shell sets | |
5032 | the default value to the value of 'HISTSIZE' after reading any | |
5033 | startup files. | |
5034 | ||
5035 | 'HISTIGNORE' | |
bb70624e JA |
5036 | A colon-separated list of patterns used to decide which command |
5037 | lines should be saved on the history list. Each pattern is | |
5038 | anchored at the beginning of the line and must match the complete | |
8a0829e9 CR |
5039 | line (no implicit '*' is appended). Each pattern is tested against |
5040 | the line after the checks specified by 'HISTCONTROL' are applied. | |
5041 | In addition to the normal shell pattern matching characters, '&' | |
5042 | matches the previous history line. '&' may be escaped using a | |
5043 | backslash; the backslash is removed before attempting a match. The | |
5044 | second and subsequent lines of a multi-line compound command are | |
5045 | not tested, and are added to the history regardless of the value of | |
690150f9 CR |
5046 | 'HISTIGNORE'. The pattern matching honors the setting of the |
5047 | 'extglob' shell option. | |
8a0829e9 CR |
5048 | |
5049 | 'HISTIGNORE' subsumes the function of 'HISTCONTROL'. A pattern of | |
5050 | '&' is identical to 'ignoredups', and a pattern of '[ ]*' is | |
5051 | identical to 'ignorespace'. Combining these two patterns, | |
bb70624e | 5052 | separating them with a colon, provides the functionality of |
8a0829e9 | 5053 | 'ignoreboth'. |
ccc6cda3 | 5054 | |
8a0829e9 CR |
5055 | 'HISTSIZE' |
5056 | The maximum number of commands to remember on the history list. If | |
5057 | the value is 0, commands are not saved in the history list. | |
45c0f7f8 CR |
5058 | Numeric values less than zero result in every command being saved |
5059 | on the history list (there is no limit). The shell sets the | |
5060 | default value to 500 after reading any startup files. | |
b72432fd | 5061 | |
8a0829e9 CR |
5062 | 'HISTTIMEFORMAT' |
5063 | If this variable is set and not null, its value is used as a format | |
5064 | string for STRFTIME to print the time stamp associated with each | |
5065 | history entry displayed by the 'history' builtin. If this variable | |
5066 | is set, time stamps are written to the history file so they may be | |
5067 | preserved across shell sessions. This uses the history comment | |
5068 | character to distinguish timestamps from other history lines. | |
5069 | ||
5070 | 'HOSTFILE' | |
5071 | Contains the name of a file in the same format as '/etc/hosts' that | |
bb70624e JA |
5072 | should be read when the shell needs to complete a hostname. The |
5073 | list of possible hostname completions may be changed while the | |
5074 | shell is running; the next time hostname completion is attempted | |
5075 | after the value is changed, Bash adds the contents of the new file | |
8a0829e9 CR |
5076 | to the existing list. If 'HOSTFILE' is set, but has no value, or |
5077 | does not name a readable file, Bash attempts to read '/etc/hosts' | |
3eb2d94a | 5078 | to obtain the list of possible hostname completions. When |
8a0829e9 | 5079 | 'HOSTFILE' is unset, the hostname list is cleared. |
cce855bc | 5080 | |
8a0829e9 | 5081 | 'HOSTNAME' |
bb70624e | 5082 | The name of the current host. |
cce855bc | 5083 | |
8a0829e9 | 5084 | 'HOSTTYPE' |
bb70624e | 5085 | A string describing the machine Bash is running on. |
ccc6cda3 | 5086 | |
8a0829e9 CR |
5087 | 'IGNOREEOF' |
5088 | Controls the action of the shell on receipt of an 'EOF' character | |
bb70624e | 5089 | as the sole input. If set, the value denotes the number of |
8a0829e9 | 5090 | consecutive 'EOF' characters that can be read as the first |
bb70624e | 5091 | character on an input line before the shell will exit. If the |
8a0829e9 CR |
5092 | variable exists but does not have a numeric value (or has no value) |
5093 | then the default is 10. If the variable does not exist, then 'EOF' | |
5094 | signifies the end of input to the shell. This is only in effect | |
5095 | for interactive shells. | |
ccc6cda3 | 5096 | |
8a0829e9 | 5097 | 'INPUTRC' |
bb70624e | 5098 | The name of the Readline initialization file, overriding the |
8a0829e9 | 5099 | default of '~/.inputrc'. |
ccc6cda3 | 5100 | |
8a0829e9 | 5101 | 'LANG' |
bb70624e | 5102 | Used to determine the locale category for any category not |
8a0829e9 | 5103 | specifically selected with a variable starting with 'LC_'. |
ccc6cda3 | 5104 | |
8a0829e9 CR |
5105 | 'LC_ALL' |
5106 | This variable overrides the value of 'LANG' and any other 'LC_' | |
bb70624e | 5107 | variable specifying a locale category. |
cce855bc | 5108 | |
8a0829e9 | 5109 | 'LC_COLLATE' |
bb70624e | 5110 | This variable determines the collation order used when sorting the |
8a0829e9 CR |
5111 | results of filename expansion, and determines the behavior of range |
5112 | expressions, equivalence classes, and collating sequences within | |
5113 | filename expansion and pattern matching (*note Filename | |
28ef6c31 | 5114 | Expansion::). |
ccc6cda3 | 5115 | |
8a0829e9 | 5116 | 'LC_CTYPE' |
bb70624e JA |
5117 | This variable determines the interpretation of characters and the |
5118 | behavior of character classes within filename expansion and pattern | |
28ef6c31 | 5119 | matching (*note Filename Expansion::). |
ccc6cda3 | 5120 | |
8a0829e9 | 5121 | 'LC_MESSAGES' |
bb70624e | 5122 | This variable determines the locale used to translate double-quoted |
8a0829e9 | 5123 | strings preceded by a '$' (*note Locale Translation::). |
ccc6cda3 | 5124 | |
8a0829e9 | 5125 | 'LC_NUMERIC' |
bb70624e JA |
5126 | This variable determines the locale category used for number |
5127 | formatting. | |
ccc6cda3 | 5128 | |
690150f9 CR |
5129 | 'LC_TIME' |
5130 | This variable determines the locale category used for data and time | |
5131 | formatting. | |
5132 | ||
8a0829e9 | 5133 | 'LINENO' |
f73dda09 JA |
5134 | The line number in the script or shell function currently |
5135 | executing. | |
5136 | ||
8a0829e9 CR |
5137 | 'LINES' |
5138 | Used by the 'select' command to determine the column length for | |
5139 | printing selection lists. Automatically set if the 'checkwinsize' | |
5140 | option is enabled (*note The Shopt Builtin::), or in an interactive | |
5141 | shell upon receipt of a 'SIGWINCH'. | |
28ef6c31 | 5142 | |
8a0829e9 | 5143 | 'MACHTYPE' |
bb70624e JA |
5144 | A string that fully describes the system type on which Bash is |
5145 | executing, in the standard GNU CPU-COMPANY-SYSTEM format. | |
ccc6cda3 | 5146 | |
8a0829e9 | 5147 | 'MAILCHECK' |
bb70624e | 5148 | How often (in seconds) that the shell should check for mail in the |
8a0829e9 CR |
5149 | files specified in the 'MAILPATH' or 'MAIL' variables. The default |
5150 | is 60 seconds. When it is time to check for mail, the shell does | |
5151 | so before displaying the primary prompt. If this variable is | |
5152 | unset, or set to a value that is not a number greater than or equal | |
5153 | to zero, the shell disables mail checking. | |
5154 | ||
5155 | 'MAPFILE' | |
5156 | An array variable created to hold the text read by the 'mapfile' | |
5cdaaf76 CR |
5157 | builtin when no variable name is supplied. |
5158 | ||
8a0829e9 CR |
5159 | 'OLDPWD' |
5160 | The previous working directory as set by the 'cd' builtin. | |
ccc6cda3 | 5161 | |
8a0829e9 | 5162 | 'OPTERR' |
bb70624e | 5163 | If set to the value 1, Bash displays error messages generated by |
8a0829e9 | 5164 | the 'getopts' builtin command. |
ccc6cda3 | 5165 | |
8a0829e9 | 5166 | 'OSTYPE' |
bb70624e | 5167 | A string describing the operating system Bash is running on. |
ccc6cda3 | 5168 | |
8a0829e9 CR |
5169 | 'PIPESTATUS' |
5170 | An array variable (*note Arrays::) containing a list of exit status | |
5171 | values from the processes in the most-recently-executed foreground | |
5172 | pipeline (which may contain only a single command). | |
ccc6cda3 | 5173 | |
8a0829e9 | 5174 | 'POSIXLY_CORRECT' |
122f603c CR |
5175 | If this variable is in the environment when Bash starts, the shell |
5176 | enters POSIX mode (*note Bash POSIX Mode::) before reading the | |
8a0829e9 | 5177 | startup files, as if the '--posix' invocation option had been |
122f603c | 5178 | supplied. If it is set while the shell is running, Bash enables |
f73dda09 | 5179 | POSIX mode, as if the command |
8a0829e9 | 5180 | set -o posix |
f73dda09 JA |
5181 | had been executed. |
5182 | ||
8a0829e9 | 5183 | 'PPID' |
bb70624e JA |
5184 | The process ID of the shell's parent process. This variable is |
5185 | readonly. | |
ccc6cda3 | 5186 | |
8a0829e9 CR |
5187 | 'PROMPT_COMMAND' |
5188 | If set, the value is interpreted as a command to execute before the | |
5189 | printing of each primary prompt ('$PS1'). | |
ccc6cda3 | 5190 | |
8a0829e9 | 5191 | 'PROMPT_DIRTRIM' |
09767ff0 CR |
5192 | If set to a number greater than zero, the value is used as the |
5193 | number of trailing directory components to retain when expanding | |
8a0829e9 | 5194 | the '\w' and '\W' prompt string escapes (*note Controlling the |
09767ff0 CR |
5195 | Prompt::). Characters removed are replaced with an ellipsis. |
5196 | ||
690150f9 CR |
5197 | 'PS0' |
5198 | The value of this parameter is expanded like PS1 and displayed by | |
5199 | interactive shells after reading a command and before the command | |
5200 | is executed. | |
5201 | ||
8a0829e9 CR |
5202 | 'PS3' |
5203 | The value of this variable is used as the prompt for the 'select' | |
5204 | command. If this variable is not set, the 'select' command prompts | |
5205 | with '#? ' | |
ccc6cda3 | 5206 | |
8a0829e9 | 5207 | 'PS4' |
bb70624e | 5208 | The value is the prompt printed before the command line is echoed |
8a0829e9 CR |
5209 | when the '-x' option is set (*note The Set Builtin::). The first |
5210 | character of 'PS4' is replicated multiple times, as necessary, to | |
5211 | indicate multiple levels of indirection. The default is '+ '. | |
ccc6cda3 | 5212 | |
8a0829e9 CR |
5213 | 'PWD' |
5214 | The current working directory as set by the 'cd' builtin. | |
ccc6cda3 | 5215 | |
8a0829e9 | 5216 | 'RANDOM' |
bb70624e JA |
5217 | Each time this parameter is referenced, a random integer between 0 |
5218 | and 32767 is generated. Assigning a value to this variable seeds | |
5219 | the random number generator. | |
cce855bc | 5220 | |
8a0829e9 CR |
5221 | 'READLINE_LINE' |
5222 | The contents of the Readline line buffer, for use with 'bind -x' | |
5cdaaf76 CR |
5223 | (*note Bash Builtins::). |
5224 | ||
8a0829e9 | 5225 | 'READLINE_POINT' |
5cdaaf76 | 5226 | The position of the insertion point in the Readline line buffer, |
8a0829e9 | 5227 | for use with 'bind -x' (*note Bash Builtins::). |
5cdaaf76 | 5228 | |
8a0829e9 CR |
5229 | 'REPLY' |
5230 | The default variable for the 'read' builtin. | |
ccc6cda3 | 5231 | |
8a0829e9 | 5232 | 'SECONDS' |
bb70624e | 5233 | This variable expands to the number of seconds since the shell was |
8a0829e9 CR |
5234 | started. Assignment to this variable resets the count to the value |
5235 | assigned, and the expanded value becomes the value assigned plus | |
5236 | the number of seconds since the assignment. | |
ccc6cda3 | 5237 | |
8a0829e9 | 5238 | 'SHELL' |
9f422431 CR |
5239 | The full pathname to the shell is kept in this environment |
5240 | variable. If it is not set when the shell starts, Bash assigns to | |
5241 | it the full pathname of the current user's login shell. | |
5242 | ||
8a0829e9 | 5243 | 'SHELLOPTS' |
bb70624e | 5244 | A colon-separated list of enabled shell options. Each word in the |
8a0829e9 | 5245 | list is a valid argument for the '-o' option to the 'set' builtin |
28ef6c31 | 5246 | command (*note The Set Builtin::). The options appearing in |
8a0829e9 | 5247 | 'SHELLOPTS' are those reported as 'on' by 'set -o'. If this |
bb70624e JA |
5248 | variable is in the environment when Bash starts up, each shell |
5249 | option in the list will be enabled before reading any startup | |
5250 | files. This variable is readonly. | |
ccc6cda3 | 5251 | |
8a0829e9 | 5252 | 'SHLVL' |
bb70624e JA |
5253 | Incremented by one each time a new instance of Bash is started. |
5254 | This is intended to be a count of how deeply your Bash shells are | |
5255 | nested. | |
cce855bc | 5256 | |
8a0829e9 | 5257 | 'TIMEFORMAT' |
bb70624e | 5258 | The value of this parameter is used as a format string specifying |
8a0829e9 CR |
5259 | how the timing information for pipelines prefixed with the 'time' |
5260 | reserved word should be displayed. The '%' character introduces an | |
bb70624e JA |
5261 | escape sequence that is expanded to a time value or other |
5262 | information. The escape sequences and their meanings are as | |
5263 | follows; the braces denote optional portions. | |
cce855bc | 5264 | |
8a0829e9 CR |
5265 | '%%' |
5266 | A literal '%'. | |
ccc6cda3 | 5267 | |
8a0829e9 | 5268 | '%[P][l]R' |
bb70624e | 5269 | The elapsed time in seconds. |
ccc6cda3 | 5270 | |
8a0829e9 | 5271 | '%[P][l]U' |
bb70624e | 5272 | The number of CPU seconds spent in user mode. |
ccc6cda3 | 5273 | |
8a0829e9 | 5274 | '%[P][l]S' |
bb70624e | 5275 | The number of CPU seconds spent in system mode. |
ccc6cda3 | 5276 | |
8a0829e9 | 5277 | '%P' |
bb70624e | 5278 | The CPU percentage, computed as (%U + %S) / %R. |
ccc6cda3 | 5279 | |
bb70624e JA |
5280 | The optional P is a digit specifying the precision, the number of |
5281 | fractional digits after a decimal point. A value of 0 causes no | |
8a0829e9 CR |
5282 | decimal point or fraction to be output. At most three places after |
5283 | the decimal point may be specified; values of P greater than 3 are | |
5284 | changed to 3. If P is not specified, the value 3 is used. | |
ccc6cda3 | 5285 | |
8a0829e9 | 5286 | The optional 'l' specifies a longer format, including minutes, of |
bb70624e JA |
5287 | the form MMmSS.FFs. The value of P determines whether or not the |
5288 | fraction is included. | |
ccc6cda3 | 5289 | |
bb70624e | 5290 | If this variable is not set, Bash acts as if it had the value |
8a0829e9 | 5291 | $'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS' |
bb70624e JA |
5292 | If the value is null, no timing information is displayed. A |
5293 | trailing newline is added when the format string is displayed. | |
ccc6cda3 | 5294 | |
8a0829e9 CR |
5295 | 'TMOUT' |
5296 | If set to a value greater than zero, 'TMOUT' is treated as the | |
5297 | default timeout for the 'read' builtin (*note Bash Builtins::). | |
5298 | The 'select' command (*note Conditional Constructs::) terminates if | |
5299 | input does not arrive after 'TMOUT' seconds when input is coming | |
7117c2d2 JA |
5300 | from a terminal. |
5301 | ||
d3ad40de | 5302 | In an interactive shell, the value is interpreted as the number of |
9f178efb CR |
5303 | seconds to wait for a line of input after issuing the primary |
5304 | prompt. Bash terminates after waiting for that number of seconds | |
5305 | if a complete line of input does not arrive. | |
ccc6cda3 | 5306 | |
8a0829e9 | 5307 | 'TMPDIR' |
1c72c0cd CR |
5308 | If set, Bash uses its value as the name of a directory in which |
5309 | Bash creates temporary files for the shell's use. | |
5310 | ||
8a0829e9 | 5311 | 'UID' |
bb70624e JA |
5312 | The numeric real user id of the current user. This variable is |
5313 | readonly. | |
ccc6cda3 | 5314 | |
bb70624e JA |
5315 | \1f |
5316 | File: bashref.info, Node: Bash Features, Next: Job Control, Prev: Shell Variables, Up: Top | |
ccc6cda3 | 5317 | |
37c41ab1 CR |
5318 | 6 Bash Features |
5319 | *************** | |
ccc6cda3 | 5320 | |
122f603c | 5321 | This chapter describes features unique to Bash. |
ccc6cda3 | 5322 | |
bb70624e | 5323 | * Menu: |
ccc6cda3 | 5324 | |
bb70624e JA |
5325 | * Invoking Bash:: Command line options that you can give |
5326 | to Bash. | |
5327 | * Bash Startup Files:: When and how Bash executes scripts. | |
5328 | * Interactive Shells:: What an interactive shell is. | |
5329 | * Bash Conditional Expressions:: Primitives used in composing expressions for | |
8a0829e9 | 5330 | the 'test' builtin. |
bb70624e JA |
5331 | * Shell Arithmetic:: Arithmetic on shell variables. |
5332 | * Aliases:: Substituting one command for another. | |
5333 | * Arrays:: Array Variables. | |
5334 | * The Directory Stack:: History of visited directories. | |
122f603c | 5335 | * Controlling the Prompt:: Customizing the various prompt strings. |
bb70624e JA |
5336 | * The Restricted Shell:: A more controlled mode of shell execution. |
5337 | * Bash POSIX Mode:: Making Bash behave more closely to what | |
5338 | the POSIX standard specifies. | |
ccc6cda3 | 5339 | |
bb70624e JA |
5340 | \1f |
5341 | File: bashref.info, Node: Invoking Bash, Next: Bash Startup Files, Up: Bash Features | |
ccc6cda3 | 5342 | |
37c41ab1 CR |
5343 | 6.1 Invoking Bash |
5344 | ================= | |
ccc6cda3 | 5345 | |
f73dda09 JA |
5346 | bash [long-opt] [-ir] [-abefhkmnptuvxdBCDHP] [-o OPTION] [-O SHOPT_OPTION] [ARGUMENT ...] |
5347 | bash [long-opt] [-abefhkmnptuvxdBCDHP] [-o OPTION] [-O SHOPT_OPTION] -c STRING [ARGUMENT ...] | |
5348 | bash [long-opt] -s [-abefhkmnptuvxdBCDHP] [-o OPTION] [-O SHOPT_OPTION] [ARGUMENT ...] | |
ccc6cda3 | 5349 | |
8a0829e9 | 5350 | All of the single-character options used with the 'set' builtin |
eb0b2ad8 CR |
5351 | (*note The Set Builtin::) can be used as options when the shell is |
5352 | invoked. In addition, there are several multi-character options that | |
5353 | you can use. These options must appear on the command line before the | |
5354 | single-character options to be recognized. | |
ccc6cda3 | 5355 | |
8a0829e9 | 5356 | '--debugger' |
d3a24ed2 | 5357 | Arrange for the debugger profile to be executed before the shell |
6a8fd0ed | 5358 | starts. Turns on extended debugging mode (see *note The Shopt |
8a0829e9 | 5359 | Builtin:: for a description of the 'extdebug' option to the 'shopt' |
eb0b2ad8 | 5360 | builtin). |
d3a24ed2 | 5361 | |
8a0829e9 CR |
5362 | '--dump-po-strings' |
5363 | A list of all double-quoted strings preceded by '$' is printed on | |
5364 | the standard output in the GNU 'gettext' PO (portable object) file | |
5365 | format. Equivalent to '-D' except for the output format. | |
ccc6cda3 | 5366 | |
8a0829e9 CR |
5367 | '--dump-strings' |
5368 | Equivalent to '-D'. | |
ccc6cda3 | 5369 | |
8a0829e9 | 5370 | '--help' |
d3ad40de | 5371 | Display a usage message on standard output and exit successfully. |
ccc6cda3 | 5372 | |
8a0829e9 CR |
5373 | '--init-file FILENAME' |
5374 | '--rcfile FILENAME' | |
5375 | Execute commands from FILENAME (instead of '~/.bashrc') in an | |
28ef6c31 JA |
5376 | interactive shell. |
5377 | ||
8a0829e9 CR |
5378 | '--login' |
5379 | Equivalent to '-l'. | |
ccc6cda3 | 5380 | |
8a0829e9 | 5381 | '--noediting' |
28ef6c31 | 5382 | Do not use the GNU Readline library (*note Command Line Editing::) |
8a0829e9 | 5383 | to read command lines when the shell is interactive. |
ccc6cda3 | 5384 | |
8a0829e9 CR |
5385 | '--noprofile' |
5386 | Don't load the system-wide startup file '/etc/profile' or any of | |
5387 | the personal initialization files '~/.bash_profile', | |
5388 | '~/.bash_login', or '~/.profile' when Bash is invoked as a login | |
bb70624e | 5389 | shell. |
ccc6cda3 | 5390 | |
8a0829e9 CR |
5391 | '--norc' |
5392 | Don't read the '~/.bashrc' initialization file in an interactive | |
5393 | shell. This is on by default if the shell is invoked as 'sh'. | |
ccc6cda3 | 5394 | |
8a0829e9 | 5395 | '--posix' |
bb70624e | 5396 | Change the behavior of Bash where the default operation differs |
8a0829e9 CR |
5397 | from the POSIX standard to match the standard. This is intended to |
5398 | make Bash behave as a strict superset of that standard. *Note Bash | |
5399 | POSIX Mode::, for a description of the Bash POSIX mode. | |
ccc6cda3 | 5400 | |
8a0829e9 | 5401 | '--restricted' |
28ef6c31 | 5402 | Make the shell a restricted shell (*note The Restricted Shell::). |
ccc6cda3 | 5403 | |
8a0829e9 CR |
5404 | '--verbose' |
5405 | Equivalent to '-v'. Print shell input lines as they're read. | |
ccc6cda3 | 5406 | |
8a0829e9 | 5407 | '--version' |
bb70624e JA |
5408 | Show version information for this instance of Bash on the standard |
5409 | output and exit successfully. | |
ccc6cda3 | 5410 | |
bb70624e | 5411 | There are several single-character options that may be supplied at |
8a0829e9 | 5412 | invocation which are not available with the 'set' builtin. |
ccc6cda3 | 5413 | |
8a0829e9 | 5414 | '-c' |
fc527055 CR |
5415 | Read and execute commands from the first non-option argument |
5416 | COMMAND_STRING, then exit. If there are arguments after the | |
8a0829e9 CR |
5417 | COMMAND_STRING, the first argument is assigned to '$0' and any |
5418 | remaining arguments are assigned to the positional parameters. The | |
5419 | assignment to '$0' sets the name of the shell, which is used in | |
5420 | warning and error messages. | |
ccc6cda3 | 5421 | |
8a0829e9 | 5422 | '-i' |
bb70624e | 5423 | Force the shell to run interactively. Interactive shells are |
6a8fd0ed | 5424 | described in *note Interactive Shells::. |
ccc6cda3 | 5425 | |
8a0829e9 | 5426 | '-l' |
7117c2d2 JA |
5427 | Make this shell act as if it had been directly invoked by login. |
5428 | When the shell is interactive, this is equivalent to starting a | |
8a0829e9 CR |
5429 | login shell with 'exec -l bash'. When the shell is not |
5430 | interactive, the login shell startup files will be executed. 'exec | |
5431 | bash -l' or 'exec bash --login' will replace the current shell with | |
5432 | a Bash login shell. *Note Bash Startup Files::, for a description | |
5433 | of the special behavior of a login shell. | |
7117c2d2 | 5434 | |
8a0829e9 | 5435 | '-r' |
28ef6c31 | 5436 | Make the shell a restricted shell (*note The Restricted Shell::). |
ccc6cda3 | 5437 | |
8a0829e9 | 5438 | '-s' |
bb70624e JA |
5439 | If this option is present, or if no arguments remain after option |
5440 | processing, then commands are read from the standard input. This | |
5441 | option allows the positional parameters to be set when invoking an | |
5442 | interactive shell. | |
ccc6cda3 | 5443 | |
8a0829e9 CR |
5444 | '-D' |
5445 | A list of all double-quoted strings preceded by '$' is printed on | |
eb2bb562 | 5446 | the standard output. These are the strings that are subject to |
8a0829e9 CR |
5447 | language translation when the current locale is not 'C' or 'POSIX' |
5448 | (*note Locale Translation::). This implies the '-n' option; no | |
bb70624e | 5449 | commands will be executed. |
ccc6cda3 | 5450 | |
8a0829e9 CR |
5451 | '[-+]O [SHOPT_OPTION]' |
5452 | SHOPT_OPTION is one of the shell options accepted by the 'shopt' | |
d3ad40de | 5453 | builtin (*note The Shopt Builtin::). If SHOPT_OPTION is present, |
8a0829e9 | 5454 | '-O' sets the value of that option; '+O' unsets it. If |
f73dda09 | 5455 | SHOPT_OPTION is not supplied, the names and values of the shell |
8a0829e9 CR |
5456 | options accepted by 'shopt' are printed on the standard output. If |
5457 | the invocation option is '+O', the output is displayed in a format | |
5458 | that may be reused as input. | |
f73dda09 | 5459 | |
8a0829e9 CR |
5460 | '--' |
5461 | A '--' signals the end of options and disables further option | |
5462 | processing. Any arguments after the '--' are treated as filenames | |
bb70624e | 5463 | and arguments. |
ccc6cda3 | 5464 | |
8a0829e9 CR |
5465 | A _login_ shell is one whose first character of argument zero is '-', |
5466 | or one invoked with the '--login' option. | |
f73dda09 | 5467 | |
28ef6c31 | 5468 | An _interactive_ shell is one started without non-option arguments, |
8a0829e9 | 5469 | unless '-s' is specified, without specifying the '-c' option, and whose |
bb70624e | 5470 | input and output are both connected to terminals (as determined by |
8a0829e9 | 5471 | 'isatty(3)'), or one started with the '-i' option. *Note Interactive |
28ef6c31 | 5472 | Shells::, for more information. |
ccc6cda3 | 5473 | |
8a0829e9 CR |
5474 | If arguments remain after option processing, and neither the '-c' nor |
5475 | the '-s' option has been supplied, the first argument is assumed to be | |
5476 | the name of a file containing shell commands (*note Shell Scripts::). | |
5477 | When Bash is invoked in this fashion, '$0' is set to the name of the | |
28ef6c31 JA |
5478 | file, and the positional parameters are set to the remaining arguments. |
5479 | Bash reads and executes commands from this file, then exits. Bash's | |
5480 | exit status is the exit status of the last command executed in the | |
5481 | script. If no commands are executed, the exit status is 0. | |
ccc6cda3 | 5482 | |
bb70624e JA |
5483 | \1f |
5484 | File: bashref.info, Node: Bash Startup Files, Next: Interactive Shells, Prev: Invoking Bash, Up: Bash Features | |
ccc6cda3 | 5485 | |
37c41ab1 CR |
5486 | 6.2 Bash Startup Files |
5487 | ====================== | |
ccc6cda3 | 5488 | |
d3ad40de | 5489 | This section describes how Bash executes its startup files. If any of |
37c41ab1 | 5490 | the files exist but cannot be read, Bash reports an error. Tildes are |
122f603c | 5491 | expanded in filenames as described above under Tilde Expansion (*note |
37c41ab1 | 5492 | Tilde Expansion::). |
ccc6cda3 | 5493 | |
6a8fd0ed | 5494 | Interactive shells are described in *note Interactive Shells::. |
ccc6cda3 | 5495 | |
8a0829e9 | 5496 | Invoked as an interactive login shell, or with '--login' |
bb70624e | 5497 | ........................................................ |
cce855bc | 5498 | |
37c41ab1 | 5499 | When Bash is invoked as an interactive login shell, or as a |
8a0829e9 CR |
5500 | non-interactive shell with the '--login' option, it first reads and |
5501 | executes commands from the file '/etc/profile', if that file exists. | |
5502 | After reading that file, it looks for '~/.bash_profile', | |
5503 | '~/.bash_login', and '~/.profile', in that order, and reads and executes | |
5504 | commands from the first one that exists and is readable. The | |
5505 | '--noprofile' option may be used when the shell is started to inhibit | |
bb70624e | 5506 | this behavior. |
ccc6cda3 | 5507 | |
0385211b CR |
5508 | When an interactive login shell exits, or a non-interactive login |
5509 | shell executes the 'exit' builtin command, Bash reads and executes | |
5510 | commands from the file '~/.bash_logout', if it exists. | |
ccc6cda3 | 5511 | |
bb70624e JA |
5512 | Invoked as an interactive non-login shell |
5513 | ......................................... | |
ccc6cda3 | 5514 | |
37c41ab1 | 5515 | When an interactive shell that is not a login shell is started, Bash |
8a0829e9 CR |
5516 | reads and executes commands from '~/.bashrc', if that file exists. This |
5517 | may be inhibited by using the '--norc' option. The '--rcfile FILE' | |
5518 | option will force Bash to read and execute commands from FILE instead of | |
5519 | '~/.bashrc'. | |
ccc6cda3 | 5520 | |
8a0829e9 CR |
5521 | So, typically, your '~/.bash_profile' contains the line |
5522 | if [ -f ~/.bashrc ]; then . ~/.bashrc; fi | |
5523 | after (or before) any login-specific initializations. | |
ccc6cda3 | 5524 | |
bb70624e JA |
5525 | Invoked non-interactively |
5526 | ......................... | |
ccc6cda3 | 5527 | |
37c41ab1 | 5528 | When Bash is started non-interactively, to run a shell script, for |
8a0829e9 | 5529 | example, it looks for the variable 'BASH_ENV' in the environment, |
bb70624e JA |
5530 | expands its value if it appears there, and uses the expanded value as |
5531 | the name of a file to read and execute. Bash behaves as if the | |
5532 | following command were executed: | |
8a0829e9 CR |
5533 | if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi |
5534 | but the value of the 'PATH' variable is not used to search for the | |
122f603c | 5535 | filename. |
ccc6cda3 | 5536 | |
28ef6c31 | 5537 | As noted above, if a non-interactive shell is invoked with the |
8a0829e9 | 5538 | '--login' option, Bash attempts to read and execute commands from the |
28ef6c31 JA |
5539 | login shell startup files. |
5540 | ||
8a0829e9 | 5541 | Invoked with name 'sh' |
bb70624e | 5542 | ...................... |
ccc6cda3 | 5543 | |
8a0829e9 CR |
5544 | If Bash is invoked with the name 'sh', it tries to mimic the startup |
5545 | behavior of historical versions of 'sh' as closely as possible, while | |
bb70624e | 5546 | conforming to the POSIX standard as well. |
ccc6cda3 | 5547 | |
bb70624e | 5548 | When invoked as an interactive login shell, or as a non-interactive |
8a0829e9 CR |
5549 | shell with the '--login' option, it first attempts to read and execute |
5550 | commands from '/etc/profile' and '~/.profile', in that order. The | |
5551 | '--noprofile' option may be used to inhibit this behavior. When invoked | |
5552 | as an interactive shell with the name 'sh', Bash looks for the variable | |
5553 | 'ENV', expands its value if it is defined, and uses the expanded value | |
5554 | as the name of a file to read and execute. Since a shell invoked as | |
5555 | 'sh' does not attempt to read and execute commands from any other | |
5556 | startup files, the '--rcfile' option has no effect. A non-interactive | |
5557 | shell invoked with the name 'sh' does not attempt to read any other | |
5558 | startup files. | |
5559 | ||
5560 | When invoked as 'sh', Bash enters POSIX mode after the startup files | |
bb70624e | 5561 | are read. |
b72432fd | 5562 | |
bb70624e JA |
5563 | Invoked in POSIX mode |
5564 | ..................... | |
ccc6cda3 | 5565 | |
8a0829e9 | 5566 | When Bash is started in POSIX mode, as with the '--posix' command line |
37c41ab1 | 5567 | option, it follows the POSIX standard for startup files. In this mode, |
8a0829e9 | 5568 | interactive shells expand the 'ENV' variable and commands are read and |
37c41ab1 CR |
5569 | executed from the file whose name is the expanded value. No other |
5570 | startup files are read. | |
ccc6cda3 | 5571 | |
bb70624e JA |
5572 | Invoked by remote shell daemon |
5573 | .............................. | |
ccc6cda3 | 5574 | |
c2a47ea9 | 5575 | Bash attempts to determine when it is being run with its standard input |
e05be32d | 5576 | connected to a network connection, as when executed by the remote shell |
8a0829e9 | 5577 | daemon, usually 'rshd', or the secure shell daemon 'sshd'. If Bash |
e05be32d | 5578 | determines it is being run in this fashion, it reads and executes |
8a0829e9 CR |
5579 | commands from '~/.bashrc', if that file exists and is readable. It will |
5580 | not do this if invoked as 'sh'. The '--norc' option may be used to | |
5581 | inhibit this behavior, and the '--rcfile' option may be used to force | |
5582 | another file to be read, but neither 'rshd' nor 'sshd' generally invoke | |
5583 | the shell with those options or allow them to be specified. | |
ccc6cda3 | 5584 | |
bb70624e JA |
5585 | Invoked with unequal effective and real UID/GIDs |
5586 | ................................................ | |
5587 | ||
37c41ab1 | 5588 | If Bash is started with the effective user (group) id not equal to the |
8a0829e9 | 5589 | real user (group) id, and the '-p' option is not supplied, no startup |
37c41ab1 | 5590 | files are read, shell functions are not inherited from the environment, |
8a0829e9 | 5591 | the 'SHELLOPTS', 'BASHOPTS', 'CDPATH', and 'GLOBIGNORE' variables, if |
8f714a7c | 5592 | they appear in the environment, are ignored, and the effective user id |
8a0829e9 | 5593 | is set to the real user id. If the '-p' option is supplied at |
8f714a7c CR |
5594 | invocation, the startup behavior is the same, but the effective user id |
5595 | is not reset. | |
bb70624e JA |
5596 | |
5597 | \1f | |
5598 | File: bashref.info, Node: Interactive Shells, Next: Bash Conditional Expressions, Prev: Bash Startup Files, Up: Bash Features | |
5599 | ||
37c41ab1 CR |
5600 | 6.3 Interactive Shells |
5601 | ====================== | |
bb70624e JA |
5602 | |
5603 | * Menu: | |
5604 | ||
5605 | * What is an Interactive Shell?:: What determines whether a shell is Interactive. | |
5606 | * Is this Shell Interactive?:: How to tell if a shell is interactive. | |
5607 | * Interactive Shell Behavior:: What changes in a interactive shell? | |
5608 | ||
5609 | \1f | |
5610 | File: bashref.info, Node: What is an Interactive Shell?, Next: Is this Shell Interactive?, Up: Interactive Shells | |
5611 | ||
37c41ab1 CR |
5612 | 6.3.1 What is an Interactive Shell? |
5613 | ----------------------------------- | |
bb70624e | 5614 | |
8a0829e9 CR |
5615 | An interactive shell is one started without non-option arguments, unless |
5616 | '-s' is specified, without specifying the '-c' option, and whose input | |
5617 | and error output are both connected to terminals (as determined by | |
5618 | 'isatty(3)'), or one started with the '-i' option. | |
bb70624e JA |
5619 | |
5620 | An interactive shell generally reads from and writes to a user's | |
5621 | terminal. | |
5622 | ||
8a0829e9 | 5623 | The '-s' invocation option may be used to set the positional |
bb70624e JA |
5624 | parameters when an interactive shell is started. |
5625 | ||
5626 | \1f | |
5627 | File: bashref.info, Node: Is this Shell Interactive?, Next: Interactive Shell Behavior, Prev: What is an Interactive Shell?, Up: Interactive Shells | |
5628 | ||
37c41ab1 CR |
5629 | 6.3.2 Is this Shell Interactive? |
5630 | -------------------------------- | |
bb70624e | 5631 | |
37c41ab1 | 5632 | To determine within a startup script whether or not Bash is running |
8a0829e9 CR |
5633 | interactively, test the value of the '-' special parameter. It contains |
5634 | 'i' when the shell is interactive. For example: | |
bb70624e JA |
5635 | |
5636 | case "$-" in | |
5637 | *i*) echo This shell is interactive ;; | |
5638 | *) echo This shell is not interactive ;; | |
5639 | esac | |
5640 | ||
8a0829e9 | 5641 | Alternatively, startup scripts may examine the variable 'PS1'; it is |
28ef6c31 | 5642 | unset in non-interactive shells, and set in interactive shells. Thus: |
bb70624e JA |
5643 | |
5644 | if [ -z "$PS1" ]; then | |
5645 | echo This shell is not interactive | |
5646 | else | |
5647 | echo This shell is interactive | |
5648 | fi | |
5649 | ||
5650 | \1f | |
5651 | File: bashref.info, Node: Interactive Shell Behavior, Prev: Is this Shell Interactive?, Up: Interactive Shells | |
5652 | ||
37c41ab1 CR |
5653 | 6.3.3 Interactive Shell Behavior |
5654 | -------------------------------- | |
bb70624e | 5655 | |
37c41ab1 | 5656 | When the shell is running interactively, it changes its behavior in |
bb70624e JA |
5657 | several ways. |
5658 | ||
6a8fd0ed | 5659 | 1. Startup files are read and executed as described in *note Bash |
bb70624e JA |
5660 | Startup Files::. |
5661 | ||
28ef6c31 | 5662 | 2. Job Control (*note Job Control::) is enabled by default. When job |
bb70624e | 5663 | control is in effect, Bash ignores the keyboard-generated job |
8a0829e9 | 5664 | control signals 'SIGTTIN', 'SIGTTOU', and 'SIGTSTP'. |
bb70624e | 5665 | |
8a0829e9 CR |
5666 | 3. Bash expands and displays 'PS1' before reading the first line of a |
5667 | command, and expands and displays 'PS2' before reading the second | |
690150f9 CR |
5668 | and subsequent lines of a multi-line command. Bash displays 'PS0' |
5669 | after it reads a command but before executing it. | |
bb70624e | 5670 | |
8a0829e9 CR |
5671 | 4. Bash executes the value of the 'PROMPT_COMMAND' variable as a |
5672 | command before printing the primary prompt, '$PS1' (*note Bash | |
28ef6c31 | 5673 | Variables::). |
bb70624e | 5674 | |
28ef6c31 | 5675 | 5. Readline (*note Command Line Editing::) is used to read commands |
bb70624e JA |
5676 | from the user's terminal. |
5677 | ||
8a0829e9 CR |
5678 | 6. Bash inspects the value of the 'ignoreeof' option to 'set -o' |
5679 | instead of exiting immediately when it receives an 'EOF' on its | |
28ef6c31 | 5680 | standard input when reading a command (*note The Set Builtin::). |
bb70624e | 5681 | |
28ef6c31 JA |
5682 | 7. Command history (*note Bash History Facilities::) and history |
5683 | expansion (*note History Interaction::) are enabled by default. | |
8a0829e9 | 5684 | Bash will save the command history to the file named by '$HISTFILE' |
9f178efb | 5685 | when a shell with history enabled exits. |
bb70624e | 5686 | |
28ef6c31 | 5687 | 8. Alias expansion (*note Aliases::) is performed by default. |
bb70624e | 5688 | |
8a0829e9 | 5689 | 9. In the absence of any traps, Bash ignores 'SIGTERM' (*note |
28ef6c31 | 5690 | Signals::). |
bb70624e | 5691 | |
8a0829e9 CR |
5692 | 10. In the absence of any traps, 'SIGINT' is caught and handled |
5693 | ((*note Signals::). 'SIGINT' will interrupt some shell builtins. | |
bb70624e | 5694 | |
8a0829e9 CR |
5695 | 11. An interactive login shell sends a 'SIGHUP' to all jobs on exit if |
5696 | the 'huponexit' shell option has been enabled (*note Signals::). | |
bb70624e | 5697 | |
8a0829e9 | 5698 | 12. The '-n' invocation option is ignored, and 'set -n' has no effect |
28ef6c31 | 5699 | (*note The Set Builtin::). |
bb70624e | 5700 | |
8a0829e9 CR |
5701 | 13. Bash will check for mail periodically, depending on the values of |
5702 | the 'MAIL', 'MAILPATH', and 'MAILCHECK' shell variables (*note Bash | |
5703 | Variables::). | |
bb70624e | 5704 | |
8a0829e9 CR |
5705 | 14. Expansion errors due to references to unbound shell variables |
5706 | after 'set -u' has been enabled will not cause the shell to exit | |
5707 | (*note The Set Builtin::). | |
bb70624e | 5708 | |
8a0829e9 CR |
5709 | 15. The shell will not exit on expansion errors caused by VAR being |
5710 | unset or null in '${VAR:?WORD}' expansions (*note Shell Parameter | |
28ef6c31 | 5711 | Expansion::). |
bb70624e | 5712 | |
8a0829e9 CR |
5713 | 16. Redirection errors encountered by shell builtins will not cause |
5714 | the shell to exit. | |
bb70624e | 5715 | |
8a0829e9 | 5716 | 17. When running in POSIX mode, a special builtin returning an error |
28ef6c31 | 5717 | status will not cause the shell to exit (*note Bash POSIX Mode::). |
bb70624e | 5718 | |
8a0829e9 | 5719 | 18. A failed 'exec' will not cause the shell to exit (*note Bourne |
28ef6c31 | 5720 | Shell Builtins::). |
bb70624e | 5721 | |
8a0829e9 | 5722 | 19. Parser syntax errors will not cause the shell to exit. |
bb70624e | 5723 | |
8a0829e9 CR |
5724 | 20. Simple spelling correction for directory arguments to the 'cd' |
5725 | builtin is enabled by default (see the description of the 'cdspell' | |
5726 | option to the 'shopt' builtin in *note The Shopt Builtin::). | |
bb70624e | 5727 | |
8a0829e9 | 5728 | 21. The shell will check the value of the 'TMOUT' variable and exit if |
bb70624e | 5729 | a command is not read within the specified number of seconds after |
8a0829e9 | 5730 | printing '$PS1' (*note Bash Variables::). |
bb70624e JA |
5731 | |
5732 | \1f | |
5733 | File: bashref.info, Node: Bash Conditional Expressions, Next: Shell Arithmetic, Prev: Interactive Shells, Up: Bash Features | |
5734 | ||
37c41ab1 CR |
5735 | 6.4 Bash Conditional Expressions |
5736 | ================================ | |
bb70624e | 5737 | |
8a0829e9 CR |
5738 | Conditional expressions are used by the '[[' compound command and the |
5739 | 'test' and '[' builtin commands. | |
bb70624e | 5740 | |
8a0829e9 CR |
5741 | Expressions may be unary or binary. Unary expressions are often used |
5742 | to examine the status of a file. There are string operators and numeric | |
5743 | comparison operators as well. If the FILE argument to one of the | |
5744 | primaries is of the form '/dev/fd/N', then file descriptor N is checked. | |
5745 | If the FILE argument to one of the primaries is one of '/dev/stdin', | |
5746 | '/dev/stdout', or '/dev/stderr', file descriptor 0, 1, or 2, | |
5747 | respectively, is checked. | |
bb70624e | 5748 | |
8a0829e9 CR |
5749 | When used with '[[', the '<' and '>' operators sort lexicographically |
5750 | using the current locale. The 'test' command uses ASCII ordering. | |
d6593885 | 5751 | |
37c41ab1 CR |
5752 | Unless otherwise specified, primaries that operate on files follow |
5753 | symbolic links and operate on the target of the link, rather than the | |
5754 | link itself. | |
5755 | ||
8a0829e9 | 5756 | '-a FILE' |
bb70624e JA |
5757 | True if FILE exists. |
5758 | ||
8a0829e9 | 5759 | '-b FILE' |
bb70624e JA |
5760 | True if FILE exists and is a block special file. |
5761 | ||
8a0829e9 | 5762 | '-c FILE' |
bb70624e JA |
5763 | True if FILE exists and is a character special file. |
5764 | ||
8a0829e9 | 5765 | '-d FILE' |
bb70624e JA |
5766 | True if FILE exists and is a directory. |
5767 | ||
8a0829e9 | 5768 | '-e FILE' |
bb70624e JA |
5769 | True if FILE exists. |
5770 | ||
8a0829e9 | 5771 | '-f FILE' |
bb70624e JA |
5772 | True if FILE exists and is a regular file. |
5773 | ||
8a0829e9 | 5774 | '-g FILE' |
bb70624e JA |
5775 | True if FILE exists and its set-group-id bit is set. |
5776 | ||
8a0829e9 | 5777 | '-h FILE' |
bb70624e JA |
5778 | True if FILE exists and is a symbolic link. |
5779 | ||
8a0829e9 | 5780 | '-k FILE' |
bb70624e JA |
5781 | True if FILE exists and its "sticky" bit is set. |
5782 | ||
8a0829e9 | 5783 | '-p FILE' |
bb70624e JA |
5784 | True if FILE exists and is a named pipe (FIFO). |
5785 | ||
8a0829e9 | 5786 | '-r FILE' |
bb70624e JA |
5787 | True if FILE exists and is readable. |
5788 | ||
8a0829e9 | 5789 | '-s FILE' |
bb70624e JA |
5790 | True if FILE exists and has a size greater than zero. |
5791 | ||
8a0829e9 | 5792 | '-t FD' |
bb70624e | 5793 | True if file descriptor FD is open and refers to a terminal. |
ccc6cda3 | 5794 | |
8a0829e9 | 5795 | '-u FILE' |
ccc6cda3 JA |
5796 | True if FILE exists and its set-user-id bit is set. |
5797 | ||
8a0829e9 | 5798 | '-w FILE' |
ccc6cda3 JA |
5799 | True if FILE exists and is writable. |
5800 | ||
8a0829e9 | 5801 | '-x FILE' |
ccc6cda3 JA |
5802 | True if FILE exists and is executable. |
5803 | ||
8a0829e9 | 5804 | '-G FILE' |
ccc6cda3 JA |
5805 | True if FILE exists and is owned by the effective group id. |
5806 | ||
8a0829e9 | 5807 | '-L FILE' |
cce855bc JA |
5808 | True if FILE exists and is a symbolic link. |
5809 | ||
8a0829e9 | 5810 | '-N FILE' |
5cdaaf76 CR |
5811 | True if FILE exists and has been modified since it was last read. |
5812 | ||
8a0829e9 | 5813 | '-O FILE' |
5cdaaf76 CR |
5814 | True if FILE exists and is owned by the effective user id. |
5815 | ||
8a0829e9 | 5816 | '-S FILE' |
cce855bc JA |
5817 | True if FILE exists and is a socket. |
5818 | ||
8a0829e9 | 5819 | 'FILE1 -ef FILE2' |
5cdaaf76 | 5820 | True if FILE1 and FILE2 refer to the same device and inode numbers. |
cce855bc | 5821 | |
8a0829e9 CR |
5822 | 'FILE1 -nt FILE2' |
5823 | True if FILE1 is newer (according to modification date) than FILE2, | |
5824 | or if FILE1 exists and FILE2 does not. | |
ccc6cda3 | 5825 | |
8a0829e9 | 5826 | 'FILE1 -ot FILE2' |
7117c2d2 JA |
5827 | True if FILE1 is older than FILE2, or if FILE2 exists and FILE1 |
5828 | does not. | |
ccc6cda3 | 5829 | |
8a0829e9 | 5830 | '-o OPTNAME' |
220537f2 | 5831 | True if the shell option OPTNAME is enabled. The list of options |
8a0829e9 | 5832 | appears in the description of the '-o' option to the 'set' builtin |
28ef6c31 | 5833 | (*note The Set Builtin::). |
ccc6cda3 | 5834 | |
8a0829e9 | 5835 | '-v VARNAME' |
220537f2 CR |
5836 | True if the shell variable VARNAME is set (has been assigned a |
5837 | value). | |
5838 | ||
8a0829e9 | 5839 | '-R VARNAME' |
ad4aef08 CR |
5840 | True if the shell variable VARNAME is set and is a name reference. |
5841 | ||
8a0829e9 | 5842 | '-z STRING' |
ccc6cda3 JA |
5843 | True if the length of STRING is zero. |
5844 | ||
8a0829e9 CR |
5845 | '-n STRING' |
5846 | 'STRING' | |
ccc6cda3 JA |
5847 | True if the length of STRING is non-zero. |
5848 | ||
8a0829e9 CR |
5849 | 'STRING1 == STRING2' |
5850 | 'STRING1 = STRING2' | |
5851 | True if the strings are equal. When used with the '[[' command, | |
ad4aef08 CR |
5852 | this performs pattern matching as described above (*note |
5853 | Conditional Constructs::). | |
5854 | ||
8a0829e9 | 5855 | '=' should be used with the 'test' command for POSIX conformance. |
ccc6cda3 | 5856 | |
8a0829e9 | 5857 | 'STRING1 != STRING2' |
ccc6cda3 JA |
5858 | True if the strings are not equal. |
5859 | ||
8a0829e9 | 5860 | 'STRING1 < STRING2' |
4a8bb13f | 5861 | True if STRING1 sorts before STRING2 lexicographically. |
ccc6cda3 | 5862 | |
8a0829e9 | 5863 | 'STRING1 > STRING2' |
4a8bb13f | 5864 | True if STRING1 sorts after STRING2 lexicographically. |
ccc6cda3 | 5865 | |
8a0829e9 CR |
5866 | 'ARG1 OP ARG2' |
5867 | 'OP' is one of '-eq', '-ne', '-lt', '-le', '-gt', or '-ge'. These | |
ccc6cda3 JA |
5868 | arithmetic binary operators return true if ARG1 is equal to, not |
5869 | equal to, less than, less than or equal to, greater than, or | |
5870 | greater than or equal to ARG2, respectively. ARG1 and ARG2 may be | |
5871 | positive or negative integers. | |
5872 | ||
ccc6cda3 | 5873 | \1f |
bb70624e | 5874 | File: bashref.info, Node: Shell Arithmetic, Next: Aliases, Prev: Bash Conditional Expressions, Up: Bash Features |
ccc6cda3 | 5875 | |
37c41ab1 CR |
5876 | 6.5 Shell Arithmetic |
5877 | ==================== | |
ccc6cda3 | 5878 | |
37c41ab1 | 5879 | The shell allows arithmetic expressions to be evaluated, as one of the |
8a0829e9 | 5880 | shell expansions or by the 'let' and the '-i' option to the 'declare' |
37c41ab1 | 5881 | builtins. |
ccc6cda3 | 5882 | |
7117c2d2 JA |
5883 | Evaluation is done in fixed-width integers with no check for |
5884 | overflow, though division by 0 is trapped and flagged as an error. The | |
d3a24ed2 CR |
5885 | operators and their precedence, associativity, and values are the same |
5886 | as in the C language. The following list of operators is grouped into | |
8a0829e9 CR |
5887 | levels of equal-precedence operators. The levels are listed in order of |
5888 | decreasing precedence. | |
cce855bc | 5889 | |
8a0829e9 | 5890 | 'ID++ ID--' |
bb70624e | 5891 | variable post-increment and post-decrement |
d166f048 | 5892 | |
8a0829e9 | 5893 | '++ID --ID' |
bb70624e | 5894 | variable pre-increment and pre-decrement |
ccc6cda3 | 5895 | |
8a0829e9 | 5896 | '- +' |
bb70624e | 5897 | unary minus and plus |
ccc6cda3 | 5898 | |
8a0829e9 | 5899 | '! ~' |
bb70624e | 5900 | logical and bitwise negation |
ccc6cda3 | 5901 | |
8a0829e9 | 5902 | '**' |
bb70624e | 5903 | exponentiation |
ccc6cda3 | 5904 | |
8a0829e9 | 5905 | '* / %' |
bb70624e | 5906 | multiplication, division, remainder |
ccc6cda3 | 5907 | |
8a0829e9 | 5908 | '+ -' |
bb70624e | 5909 | addition, subtraction |
ccc6cda3 | 5910 | |
8a0829e9 | 5911 | '<< >>' |
bb70624e | 5912 | left and right bitwise shifts |
cce855bc | 5913 | |
8a0829e9 | 5914 | '<= >= < >' |
bb70624e | 5915 | comparison |
cce855bc | 5916 | |
8a0829e9 | 5917 | '== !=' |
bb70624e | 5918 | equality and inequality |
cce855bc | 5919 | |
8a0829e9 | 5920 | '&' |
bb70624e | 5921 | bitwise AND |
cce855bc | 5922 | |
8a0829e9 | 5923 | '^' |
bb70624e | 5924 | bitwise exclusive OR |
cce855bc | 5925 | |
8a0829e9 | 5926 | '|' |
bb70624e | 5927 | bitwise OR |
cce855bc | 5928 | |
8a0829e9 | 5929 | '&&' |
bb70624e | 5930 | logical AND |
ccc6cda3 | 5931 | |
8a0829e9 | 5932 | '||' |
bb70624e | 5933 | logical OR |
ccc6cda3 | 5934 | |
8a0829e9 | 5935 | 'expr ? expr : expr' |
d3a24ed2 | 5936 | conditional operator |
cce855bc | 5937 | |
8a0829e9 | 5938 | '= *= /= %= += -= <<= >>= &= ^= |=' |
bb70624e | 5939 | assignment |
ccc6cda3 | 5940 | |
8a0829e9 | 5941 | 'expr1 , expr2' |
bb70624e | 5942 | comma |
ccc6cda3 | 5943 | |
bb70624e JA |
5944 | Shell variables are allowed as operands; parameter expansion is |
5945 | performed before the expression is evaluated. Within an expression, | |
5946 | shell variables may also be referenced by name without using the | |
d3a24ed2 CR |
5947 | parameter expansion syntax. A shell variable that is null or unset |
5948 | evaluates to 0 when referenced by name without using the parameter | |
8a0829e9 CR |
5949 | expansion syntax. The value of a variable is evaluated as an arithmetic |
5950 | expression when it is referenced, or when a variable which has been | |
5951 | given the INTEGER attribute using 'declare -i' is assigned a value. A | |
5952 | null value evaluates to 0. A shell variable need not have its INTEGER | |
5953 | attribute turned on to be used in an expression. | |
ccc6cda3 | 5954 | |
bb70624e | 5955 | Constants with a leading 0 are interpreted as octal numbers. A |
8a0829e9 CR |
5956 | leading '0x' or '0X' denotes hexadecimal. Otherwise, numbers take the |
5957 | form [BASE'#']N, where the optional BASE is a decimal number between 2 | |
abe2eb5b | 5958 | and 64 representing the arithmetic base, and N is a number in that base. |
8a0829e9 | 5959 | If BASE'#' is omitted, then base 10 is used. When specifying N, the |
abe2eb5b | 5960 | digits greater than 9 are represented by the lowercase letters, the |
8a0829e9 CR |
5961 | uppercase letters, '@', and '_', in that order. If BASE is less than or |
5962 | equal to 36, lowercase and uppercase letters may be used interchangeably | |
5963 | to represent numbers between 10 and 35. | |
ccc6cda3 | 5964 | |
bb70624e JA |
5965 | Operators are evaluated in order of precedence. Sub-expressions in |
5966 | parentheses are evaluated first and may override the precedence rules | |
5967 | above. | |
ccc6cda3 | 5968 | |
bb70624e JA |
5969 | \1f |
5970 | File: bashref.info, Node: Aliases, Next: Arrays, Prev: Shell Arithmetic, Up: Bash Features | |
ccc6cda3 | 5971 | |
37c41ab1 CR |
5972 | 6.6 Aliases |
5973 | =========== | |
ccc6cda3 | 5974 | |
37c41ab1 CR |
5975 | ALIASES allow a string to be substituted for a word when it is used as |
5976 | the first word of a simple command. The shell maintains a list of | |
8a0829e9 CR |
5977 | aliases that may be set and unset with the 'alias' and 'unalias' builtin |
5978 | commands. | |
cce855bc JA |
5979 | |
5980 | The first word of each simple command, if unquoted, is checked to see | |
5981 | if it has an alias. If so, that word is replaced by the text of the | |
8a0829e9 | 5982 | alias. The characters '/', '$', '`', '=' and any of the shell |
de8913bd CR |
5983 | metacharacters or quoting characters listed above may not appear in an |
5984 | alias name. The replacement text may contain any valid shell input, | |
5985 | including shell metacharacters. The first word of the replacement text | |
5986 | is tested for aliases, but a word that is identical to an alias being | |
5987 | expanded is not expanded a second time. This means that one may alias | |
8a0829e9 | 5988 | 'ls' to '"ls -F"', for instance, and Bash does not try to recursively |
122f603c CR |
5989 | expand the replacement text. If the last character of the alias value |
5990 | is a BLANK, then the next command word following the alias is also | |
5991 | checked for alias expansion. | |
cce855bc | 5992 | |
8a0829e9 CR |
5993 | Aliases are created and listed with the 'alias' command, and removed |
5994 | with the 'unalias' command. | |
cce855bc | 5995 | |
8a0829e9 CR |
5996 | There is no mechanism for using arguments in the replacement text, as |
5997 | in 'csh'. If arguments are needed, a shell function should be used | |
28ef6c31 | 5998 | (*note Shell Functions::). |
cce855bc JA |
5999 | |
6000 | Aliases are not expanded when the shell is not interactive, unless | |
8a0829e9 | 6001 | the 'expand_aliases' shell option is set using 'shopt' (*note The Shopt |
d3ad40de | 6002 | Builtin::). |
ccc6cda3 | 6003 | |
cce855bc | 6004 | The rules concerning the definition and use of aliases are somewhat |
8a0829e9 CR |
6005 | confusing. Bash always reads at least one complete line of input before |
6006 | executing any of the commands on that line. Aliases are expanded when a | |
6007 | command is read, not when it is executed. Therefore, an alias | |
6008 | definition appearing on the same line as another command does not take | |
6009 | effect until the next line of input is read. The commands following the | |
6010 | alias definition on that line are not affected by the new alias. This | |
6011 | behavior is also an issue when functions are executed. Aliases are | |
6012 | expanded when a function definition is read, not when the function is | |
6013 | executed, because a function definition is itself a command. As a | |
6014 | consequence, aliases defined in a function are not available until after | |
6015 | that function is executed. To be safe, always put alias definitions on | |
6016 | a separate line, and do not use 'alias' in compound commands. | |
ccc6cda3 | 6017 | |
bb70624e | 6018 | For almost every purpose, shell functions are preferred over aliases. |
ccc6cda3 JA |
6019 | |
6020 | \1f | |
cce855bc | 6021 | File: bashref.info, Node: Arrays, Next: The Directory Stack, Prev: Aliases, Up: Bash Features |
ccc6cda3 | 6022 | |
37c41ab1 CR |
6023 | 6.7 Arrays |
6024 | ========== | |
ccc6cda3 | 6025 | |
09767ff0 | 6026 | Bash provides one-dimensional indexed and associative array variables. |
8a0829e9 CR |
6027 | Any variable may be used as an indexed array; the 'declare' builtin will |
6028 | explicitly declare an array. There is no maximum limit on the size of | |
6029 | an array, nor any requirement that members be indexed or assigned | |
6030 | contiguously. Indexed arrays are referenced using integers (including | |
6031 | arithmetic expressions (*note Shell Arithmetic::)) and are zero-based; | |
6032 | associative arrays use arbitrary strings. Unless otherwise noted, | |
6033 | indexed array indices must be non-negative integers. | |
6034 | ||
6035 | An indexed array is created automatically if any variable is assigned | |
6036 | to using the syntax | |
122f603c | 6037 | NAME[SUBSCRIPT]=VALUE |
ccc6cda3 JA |
6038 | |
6039 | The SUBSCRIPT is treated as an arithmetic expression that must evaluate | |
f6da9f85 | 6040 | to a number. To explicitly declare an array, use |
ccc6cda3 | 6041 | declare -a NAME |
8a0829e9 | 6042 | The syntax |
ccc6cda3 | 6043 | declare -a NAME[SUBSCRIPT] |
8a0829e9 | 6044 | is also accepted; the SUBSCRIPT is ignored. |
09767ff0 | 6045 | |
122f603c | 6046 | Associative arrays are created using |
09767ff0 CR |
6047 | declare -A NAME. |
6048 | ||
8a0829e9 CR |
6049 | Attributes may be specified for an array variable using the 'declare' |
6050 | and 'readonly' builtins. Each attribute applies to all members of an | |
6051 | array. | |
ccc6cda3 JA |
6052 | |
6053 | Arrays are assigned to using compound assignments of the form | |
122f603c | 6054 | NAME=(VALUE1 VALUE2 ... ) |
8a0829e9 | 6055 | where each VALUE is of the form '[SUBSCRIPT]='STRING. Indexed array |
122f603c CR |
6056 | assignments do not require anything but STRING. When assigning to |
6057 | indexed arrays, if the optional subscript is supplied, that index is | |
09767ff0 CR |
6058 | assigned to; otherwise the index of the element assigned is the last |
6059 | index assigned to by the statement plus one. Indexing starts at zero. | |
6060 | ||
6061 | When assigning to an associative array, the subscript is required. | |
6062 | ||
8a0829e9 CR |
6063 | This syntax is also accepted by the 'declare' builtin. Individual |
6064 | array elements may be assigned to using the 'NAME[SUBSCRIPT]=VALUE' | |
09767ff0 | 6065 | syntax introduced above. |
ccc6cda3 | 6066 | |
ad4aef08 CR |
6067 | When assigning to an indexed array, if NAME is subscripted by a |
6068 | negative number, that number is interpreted as relative to one greater | |
6069 | than the maximum index of NAME, so negative indices count back from the | |
6070 | end of the array, and an index of -1 references the last element. | |
6071 | ||
8a0829e9 | 6072 | Any element of an array may be referenced using '${NAME[SUBSCRIPT]}'. |
122f603c | 6073 | The braces are required to avoid conflicts with the shell's filename |
8a0829e9 CR |
6074 | expansion operators. If the SUBSCRIPT is '@' or '*', the word expands |
6075 | to all members of the array NAME. These subscripts differ only when the | |
6076 | word appears within double quotes. If the word is double-quoted, | |
6077 | '${NAME[*]}' expands to a single word with the value of each array | |
6078 | member separated by the first character of the 'IFS' variable, and | |
6079 | '${NAME[@]}' expands each element of NAME to a separate word. When | |
6080 | there are no array members, '${NAME[@]}' expands to nothing. If the | |
6081 | double-quoted expansion occurs within a word, the expansion of the first | |
6082 | parameter is joined with the beginning part of the original word, and | |
6083 | the expansion of the last parameter is joined with the last part of the | |
6084 | original word. This is analogous to the expansion of the special | |
6085 | parameters '@' and '*'. '${#NAME[SUBSCRIPT]}' expands to the length of | |
6086 | '${NAME[SUBSCRIPT]}'. If SUBSCRIPT is '@' or '*', the expansion is the | |
6087 | number of elements in the array. If the SUBSCRIPT used to reference an | |
6088 | element of an indexed array evaluates to a number less than zero, it is | |
6089 | interpreted as relative to one greater than the maximum index of the | |
6090 | array, so negative indices count back from the end of the array, and an | |
6091 | index of -1 refers to the last element. | |
6092 | ||
6093 | Referencing an array variable without a subscript is equivalent to | |
6094 | referencing with a subscript of 0. Any reference to a variable using a | |
6095 | valid subscript is legal, and 'bash' will create an array if necessary. | |
ccc6cda3 | 6096 | |
4a8bb13f CR |
6097 | An array variable is considered set if a subscript has been assigned |
6098 | a value. The null string is a valid value. | |
6099 | ||
1101193a CR |
6100 | It is possible to obtain the keys (indices) of an array as well as |
6101 | the values. ${!NAME[@]} and ${!NAME[*]} expand to the indices assigned | |
6102 | in array variable NAME. The treatment when in double quotes is similar | |
8a0829e9 | 6103 | to the expansion of the special parameters '@' and '*' within double |
1101193a CR |
6104 | quotes. |
6105 | ||
8a0829e9 | 6106 | The 'unset' builtin is used to destroy arrays. 'unset |
ad4aef08 CR |
6107 | NAME[SUBSCRIPT]' destroys the array element at index SUBSCRIPT. |
6108 | Negative subscripts to indexed arrays are interpreted as described | |
6109 | above. Care must be taken to avoid unwanted side effects caused by | |
8a0829e9 CR |
6110 | filename expansion. 'unset NAME', where NAME is an array, removes the |
6111 | entire array. A subscript of '*' or '@' also removes the entire array. | |
ccc6cda3 | 6112 | |
8a0829e9 CR |
6113 | The 'declare', 'local', and 'readonly' builtins each accept a '-a' |
6114 | option to specify an indexed array and a '-A' option to specify an | |
6115 | associative array. If both options are supplied, '-A' takes precedence. | |
6116 | The 'read' builtin accepts a '-a' option to assign a list of words read | |
d9e1f41e | 6117 | from the standard input to an array, and can read values from the |
8a0829e9 | 6118 | standard input into individual array elements. The 'set' and 'declare' |
d9e1f41e CR |
6119 | builtins display array values in a way that allows them to be reused as |
6120 | input. | |
ccc6cda3 JA |
6121 | |
6122 | \1f | |
122f603c | 6123 | File: bashref.info, Node: The Directory Stack, Next: Controlling the Prompt, Prev: Arrays, Up: Bash Features |
cce855bc | 6124 | |
37c41ab1 CR |
6125 | 6.8 The Directory Stack |
6126 | ======================= | |
cce855bc | 6127 | |
bb70624e JA |
6128 | * Menu: |
6129 | ||
6130 | * Directory Stack Builtins:: Bash builtin commands to manipulate | |
6131 | the directory stack. | |
6132 | ||
8a0829e9 CR |
6133 | The directory stack is a list of recently-visited directories. The |
6134 | 'pushd' builtin adds directories to the stack as it changes the current | |
6135 | directory, and the 'popd' builtin removes specified directories from the | |
6136 | stack and changes the current directory to the directory removed. The | |
54a5fbe1 CR |
6137 | 'dirs' builtin displays the contents of the directory stack. The |
6138 | current directory is always the "top" of the directory stack. | |
cce855bc JA |
6139 | |
6140 | The contents of the directory stack are also visible as the value of | |
8a0829e9 | 6141 | the 'DIRSTACK' shell variable. |
cce855bc | 6142 | |
bb70624e JA |
6143 | \1f |
6144 | File: bashref.info, Node: Directory Stack Builtins, Up: The Directory Stack | |
6145 | ||
37c41ab1 CR |
6146 | 6.8.1 Directory Stack Builtins |
6147 | ------------------------------ | |
bb70624e | 6148 | |
8a0829e9 | 6149 | 'dirs' |
122f603c CR |
6150 | dirs [-clpv] [+N | -N] |
6151 | ||
cce855bc | 6152 | Display the list of currently remembered directories. Directories |
8a0829e9 | 6153 | are added to the list with the 'pushd' command; the 'popd' command |
54a5fbe1 CR |
6154 | removes directories from the list. The current directory is always |
6155 | the first directory in the stack. | |
cce855bc | 6156 | |
8a0829e9 | 6157 | '-c' |
cce855bc | 6158 | Clears the directory stack by deleting all of the elements. |
8a0829e9 | 6159 | '-l' |
122f603c CR |
6160 | Produces a listing using full pathnames; the default listing |
6161 | format uses a tilde to denote the home directory. | |
8a0829e9 CR |
6162 | '-p' |
6163 | Causes 'dirs' to print the directory stack with one entry per | |
cce855bc | 6164 | line. |
8a0829e9 CR |
6165 | '-v' |
6166 | Causes 'dirs' to print the directory stack with one entry per | |
cce855bc | 6167 | line, prefixing each entry with its index in the stack. |
8a0829e9 CR |
6168 | '+N' |
6169 | Displays the Nth directory (counting from the left of the list | |
6170 | printed by 'dirs' when invoked without options), starting with | |
6171 | zero. | |
6172 | '-N' | |
122f603c | 6173 | Displays the Nth directory (counting from the right of the |
8a0829e9 | 6174 | list printed by 'dirs' when invoked without options), starting |
122f603c CR |
6175 | with zero. |
6176 | ||
8a0829e9 | 6177 | 'popd' |
122f603c | 6178 | popd [-n] [+N | -N] |
cce855bc | 6179 | |
54a5fbe1 CR |
6180 | When no arguments are given, 'popd' removes the top directory from |
6181 | the stack and performs a 'cd' to the new top directory. The | |
6182 | elements are numbered from 0 starting at the first directory listed | |
6183 | with 'dirs'; that is, 'popd' is equivalent to 'popd +0'. | |
122f603c | 6184 | |
8a0829e9 | 6185 | '-n' |
122f603c CR |
6186 | Suppresses the normal change of directory when removing |
6187 | directories from the stack, so that only the stack is | |
6188 | manipulated. | |
8a0829e9 | 6189 | '+N' |
cce855bc | 6190 | Removes the Nth directory (counting from the left of the list |
8a0829e9 CR |
6191 | printed by 'dirs'), starting with zero. |
6192 | '-N' | |
6193 | Removes the Nth directory (counting from the right of the list | |
6194 | printed by 'dirs'), starting with zero. | |
cce855bc | 6195 | |
8a0829e9 | 6196 | 'pushd' |
122f603c | 6197 | pushd [-n] [+N | -N | DIR] |
cce855bc JA |
6198 | |
6199 | Save the current directory on the top of the directory stack and | |
8a0829e9 | 6200 | then 'cd' to DIR. With no arguments, 'pushd' exchanges the top two |
54a5fbe1 | 6201 | directories and makes the new top the current directory. |
cce855bc | 6202 | |
8a0829e9 | 6203 | '-n' |
54a5fbe1 CR |
6204 | Suppresses the normal change of directory when rotating or |
6205 | adding directories to the stack, so that only the stack is | |
d3ad40de | 6206 | manipulated. |
8a0829e9 | 6207 | '+N' |
cce855bc | 6208 | Brings the Nth directory (counting from the left of the list |
8a0829e9 | 6209 | printed by 'dirs', starting with zero) to the top of the list |
cce855bc | 6210 | by rotating the stack. |
8a0829e9 | 6211 | '-N' |
cce855bc | 6212 | Brings the Nth directory (counting from the right of the list |
8a0829e9 | 6213 | printed by 'dirs', starting with zero) to the top of the list |
cce855bc | 6214 | by rotating the stack. |
8a0829e9 | 6215 | 'DIR' |
54a5fbe1 CR |
6216 | Makes DIR be the top of the stack, making it the new current |
6217 | directory as if it had been supplied as an argument to the | |
6218 | 'cd' builtin. | |
761783bf | 6219 | |
cce855bc | 6220 | \1f |
122f603c | 6221 | File: bashref.info, Node: Controlling the Prompt, Next: The Restricted Shell, Prev: The Directory Stack, Up: Bash Features |
ccc6cda3 | 6222 | |
37c41ab1 CR |
6223 | 6.9 Controlling the Prompt |
6224 | ========================== | |
ccc6cda3 | 6225 | |
8a0829e9 CR |
6226 | The value of the variable 'PROMPT_COMMAND' is examined just before Bash |
6227 | prints each primary prompt. If 'PROMPT_COMMAND' is set and has a | |
bb70624e JA |
6228 | non-null value, then the value is executed just as if it had been typed |
6229 | on the command line. | |
ccc6cda3 JA |
6230 | |
6231 | In addition, the following table describes the special characters | |
8a0829e9 | 6232 | which can appear in the prompt variables 'PS1' to 'PS4': |
ccc6cda3 | 6233 | |
8a0829e9 | 6234 | '\a' |
cce855bc | 6235 | A bell character. |
8a0829e9 | 6236 | '\d' |
cce855bc | 6237 | The date, in "Weekday Month Date" format (e.g., "Tue May 26"). |
8a0829e9 CR |
6238 | '\D{FORMAT}' |
6239 | The FORMAT is passed to 'strftime'(3) and the result is inserted | |
7117c2d2 JA |
6240 | into the prompt string; an empty FORMAT results in a |
6241 | locale-specific time representation. The braces are required. | |
8a0829e9 | 6242 | '\e' |
cce855bc | 6243 | An escape character. |
8a0829e9 CR |
6244 | '\h' |
6245 | The hostname, up to the first '.'. | |
6246 | '\H' | |
cce855bc | 6247 | The hostname. |
8a0829e9 | 6248 | '\j' |
bb70624e | 6249 | The number of jobs currently managed by the shell. |
8a0829e9 | 6250 | '\l' |
bb70624e | 6251 | The basename of the shell's terminal device name. |
8a0829e9 | 6252 | '\n' |
cce855bc | 6253 | A newline. |
8a0829e9 | 6254 | '\r' |
cce855bc | 6255 | A carriage return. |
8a0829e9 CR |
6256 | '\s' |
6257 | The name of the shell, the basename of '$0' (the portion following | |
ccc6cda3 | 6258 | the final slash). |
8a0829e9 | 6259 | '\t' |
cce855bc | 6260 | The time, in 24-hour HH:MM:SS format. |
8a0829e9 | 6261 | '\T' |
cce855bc | 6262 | The time, in 12-hour HH:MM:SS format. |
8a0829e9 | 6263 | '\@' |
cce855bc | 6264 | The time, in 12-hour am/pm format. |
8a0829e9 | 6265 | '\A' |
f73dda09 | 6266 | The time, in 24-hour HH:MM format. |
8a0829e9 | 6267 | '\u' |
cce855bc | 6268 | The username of the current user. |
8a0829e9 | 6269 | '\v' |
cce855bc | 6270 | The version of Bash (e.g., 2.00) |
8a0829e9 | 6271 | '\V' |
cce855bc | 6272 | The release of Bash, version + patchlevel (e.g., 2.00.0) |
8a0829e9 CR |
6273 | '\w' |
6274 | The current working directory, with '$HOME' abbreviated with a | |
6275 | tilde (uses the '$PROMPT_DIRTRIM' variable). | |
6276 | '\W' | |
6277 | The basename of '$PWD', with '$HOME' abbreviated with a tilde. | |
6278 | '\!' | |
cce855bc | 6279 | The history number of this command. |
8a0829e9 | 6280 | '\#' |
cce855bc | 6281 | The command number of this command. |
8a0829e9 CR |
6282 | '\$' |
6283 | If the effective uid is 0, '#', otherwise '$'. | |
6284 | '\NNN' | |
cce855bc | 6285 | The character whose ASCII code is the octal value NNN. |
8a0829e9 | 6286 | '\\' |
cce855bc | 6287 | A backslash. |
8a0829e9 | 6288 | '\[' |
cce855bc | 6289 | Begin a sequence of non-printing characters. This could be used to |
ccc6cda3 | 6290 | embed a terminal control sequence into the prompt. |
8a0829e9 | 6291 | '\]' |
cce855bc | 6292 | End a sequence of non-printing characters. |
ccc6cda3 | 6293 | |
bb70624e JA |
6294 | The command number and the history number are usually different: the |
6295 | history number of a command is its position in the history list, which | |
6296 | may include commands restored from the history file (*note Bash History | |
28ef6c31 JA |
6297 | Facilities::), while the command number is the position in the sequence |
6298 | of commands executed during the current shell session. | |
bb70624e JA |
6299 | |
6300 | After the string is decoded, it is expanded via parameter expansion, | |
6301 | command substitution, arithmetic expansion, and quote removal, subject | |
8a0829e9 | 6302 | to the value of the 'promptvars' shell option (*note Bash Builtins::). |
bb70624e | 6303 | |
ccc6cda3 | 6304 | \1f |
122f603c | 6305 | File: bashref.info, Node: The Restricted Shell, Next: Bash POSIX Mode, Prev: Controlling the Prompt, Up: Bash Features |
ccc6cda3 | 6306 | |
37c41ab1 CR |
6307 | 6.10 The Restricted Shell |
6308 | ========================= | |
ccc6cda3 | 6309 | |
8a0829e9 | 6310 | If Bash is started with the name 'rbash', or the '--restricted' or '-r' |
37c41ab1 | 6311 | option is supplied at invocation, the shell becomes restricted. A |
ccc6cda3 | 6312 | restricted shell is used to set up an environment more controlled than |
8a0829e9 | 6313 | the standard shell. A restricted shell behaves identically to 'bash' |
7117c2d2 JA |
6314 | with the exception that the following are disallowed or not performed: |
6315 | ||
8a0829e9 CR |
6316 | * Changing directories with the 'cd' builtin. |
6317 | * Setting or unsetting the values of the 'SHELL', 'PATH', 'ENV', or | |
6318 | 'BASH_ENV' variables. | |
ccc6cda3 | 6319 | * Specifying command names containing slashes. |
8a0829e9 | 6320 | * Specifying a filename containing a slash as an argument to the '.' |
ccc6cda3 | 6321 | builtin command. |
8a0829e9 CR |
6322 | * Specifying a filename containing a slash as an argument to the '-p' |
6323 | option to the 'hash' builtin command. | |
ccc6cda3 JA |
6324 | * Importing function definitions from the shell environment at |
6325 | startup. | |
8a0829e9 | 6326 | * Parsing the value of 'SHELLOPTS' from the shell environment at |
cce855bc | 6327 | startup. |
8a0829e9 | 6328 | * Redirecting output using the '>', '>|', '<>', '>&', '&>', and '>>' |
ccc6cda3 | 6329 | redirection operators. |
8a0829e9 CR |
6330 | * Using the 'exec' builtin to replace the shell with another command. |
6331 | * Adding or deleting builtin commands with the '-f' and '-d' options | |
6332 | to the 'enable' builtin. | |
6333 | * Using the 'enable' builtin command to enable disabled shell | |
7117c2d2 | 6334 | builtins. |
8a0829e9 CR |
6335 | * Specifying the '-p' option to the 'command' builtin. |
6336 | * Turning off restricted mode with 'set +r' or 'set +o restricted'. | |
ccc6cda3 | 6337 | |
7117c2d2 JA |
6338 | These restrictions are enforced after any startup files are read. |
6339 | ||
6340 | When a command that is found to be a shell script is executed (*note | |
8a0829e9 | 6341 | Shell Scripts::), 'rbash' turns off any restrictions in the shell |
7117c2d2 JA |
6342 | spawned to execute the script. |
6343 | ||
ccc6cda3 JA |
6344 | \1f |
6345 | File: bashref.info, Node: Bash POSIX Mode, Prev: The Restricted Shell, Up: Bash Features | |
6346 | ||
37c41ab1 CR |
6347 | 6.11 Bash POSIX Mode |
6348 | ==================== | |
ccc6cda3 | 6349 | |
8a0829e9 | 6350 | Starting Bash with the '--posix' command-line option or executing 'set |
37c41ab1 | 6351 | -o posix' while Bash is running will cause Bash to conform more closely |
ac18b312 CR |
6352 | to the POSIX standard by changing the behavior to match that specified |
6353 | by POSIX in areas where the Bash default differs. | |
ccc6cda3 | 6354 | |
8a0829e9 | 6355 | When invoked as 'sh', Bash enters POSIX mode after reading the |
7117c2d2 JA |
6356 | startup files. |
6357 | ||
8a0829e9 | 6358 | The following list is what's changed when 'POSIX mode' is in effect: |
ccc6cda3 JA |
6359 | |
6360 | 1. When a command in the hash table no longer exists, Bash will | |
8a0829e9 CR |
6361 | re-search '$PATH' to find the new location. This is also available |
6362 | with 'shopt -s checkhash'. | |
ccc6cda3 | 6363 | |
28ef6c31 | 6364 | 2. The message printed by the job control code and builtins when a job |
8a0829e9 | 6365 | exits with a non-zero status is 'Done(status)'. |
ccc6cda3 JA |
6366 | |
6367 | 3. The message printed by the job control code and builtins when a job | |
8a0829e9 CR |
6368 | is stopped is 'Stopped(SIGNAME)', where SIGNAME is, for example, |
6369 | 'SIGTSTP'. | |
ccc6cda3 | 6370 | |
690150f9 | 6371 | 4. Alias expansion is always enabled, even in non-interactive shells. |
1c72c0cd CR |
6372 | |
6373 | 5. Reserved words appearing in a context where reserved words are | |
3ee6b87d | 6374 | recognized do not undergo alias expansion. |
ccc6cda3 | 6375 | |
8a0829e9 CR |
6376 | 6. The POSIX 'PS1' and 'PS2' expansions of '!' to the history number |
6377 | and '!!' to '!' are enabled, and parameter expansion is performed | |
6378 | on the values of 'PS1' and 'PS2' regardless of the setting of the | |
6379 | 'promptvars' option. | |
ccc6cda3 | 6380 | |
8a0829e9 | 6381 | 7. The POSIX startup files are executed ('$ENV') rather than the |
ac18b312 | 6382 | normal Bash files. |
ccc6cda3 | 6383 | |
1c72c0cd | 6384 | 8. Tilde expansion is only performed on assignments preceding a |
ccc6cda3 JA |
6385 | command name, rather than on all assignment statements on the line. |
6386 | ||
690150f9 | 6387 | 9. The default history file is '~/.sh_history' (this is the default |
8a0829e9 | 6388 | value of '$HISTFILE'). |
ccc6cda3 | 6389 | |
690150f9 | 6390 | 10. Redirection operators do not perform filename expansion on the |
8a0829e9 | 6391 | word in the redirection unless the shell is interactive. |
ccc6cda3 | 6392 | |
690150f9 | 6393 | 11. Redirection operators do not perform word splitting on the word in |
bb70624e JA |
6394 | the redirection. |
6395 | ||
690150f9 | 6396 | 12. Function names must be valid shell 'name's. That is, they may not |
ccc6cda3 | 6397 | contain characters other than letters, digits, and underscores, and |
cce855bc | 6398 | may not start with a digit. Declaring a function with an invalid |
ccc6cda3 JA |
6399 | name causes a fatal syntax error in non-interactive shells. |
6400 | ||
690150f9 | 6401 | 13. Function names may not be the same as one of the POSIX special |
122f603c CR |
6402 | builtins. |
6403 | ||
690150f9 | 6404 | 14. POSIX special builtins are found before shell functions during |
ac18b312 | 6405 | command lookup. |
ccc6cda3 | 6406 | |
690150f9 | 6407 | 15. Literal tildes that appear as the first character in elements of |
8a0829e9 CR |
6408 | the 'PATH' variable are not expanded as described above under *note |
6409 | Tilde Expansion::. | |
fc527055 | 6410 | |
690150f9 | 6411 | 16. The 'time' reserved word may be used by itself as a command. When |
220537f2 | 6412 | used in this way, it displays timing statistics for the shell and |
8a0829e9 | 6413 | its completed children. The 'TIMEFORMAT' variable controls the |
220537f2 CR |
6414 | format of the timing information. |
6415 | ||
690150f9 | 6416 | 17. When parsing and expanding a ${...} expansion that appears within |
220537f2 CR |
6417 | double quotes, single quotes are no longer special and cannot be |
6418 | used to quote a closing brace or other special character, unless | |
6419 | the operator is one of those defined to perform pattern removal. | |
6420 | In this case, they do not have to appear as matched pairs. | |
6421 | ||
690150f9 | 6422 | 18. The parser does not recognize 'time' as a reserved word if the |
8a0829e9 | 6423 | next token begins with a '-'. |
9ec5ed66 | 6424 | |
690150f9 CR |
6425 | 19. The '!' character does not introduce history expansion within a |
6426 | double-quoted string, even if the 'histexpand' option is enabled. | |
6427 | ||
6428 | 20. If a POSIX special builtin returns an error status, a | |
ccc6cda3 | 6429 | non-interactive shell exits. The fatal errors are those listed in |
ac18b312 | 6430 | the POSIX standard, and include things like passing incorrect |
ccc6cda3 JA |
6431 | options, redirection errors, variable assignment errors for |
6432 | assignments preceding the command name, and so on. | |
6433 | ||
690150f9 | 6434 | 21. A non-interactive shell exits with an error status if a variable |
ccc6cda3 JA |
6435 | assignment error occurs when no command name follows the assignment |
6436 | statements. A variable assignment error occurs, for example, when | |
cce855bc | 6437 | trying to assign a value to a readonly variable. |
ccc6cda3 | 6438 | |
690150f9 | 6439 | 22. A non-interactive shell exits with an error status if a variable |
e05be32d CR |
6440 | assignment error occurs in an assignment statement preceding a |
6441 | special builtin, but not with any other simple command. | |
6442 | ||
690150f9 | 6443 | 23. A non-interactive shell exits with an error status if the |
8a0829e9 CR |
6444 | iteration variable in a 'for' statement or the selection variable |
6445 | in a 'select' statement is a readonly variable. | |
ccc6cda3 | 6446 | |
690150f9 CR |
6447 | 24. Non-interactive shells exit if FILENAME in '.' FILENAME is not |
6448 | found. | |
6449 | ||
6450 | 25. Non-interactive shells exit if a syntax error in an arithmetic | |
6451 | expansion results in an invalid expression. | |
6452 | ||
6453 | 26. Non-interactive shells exit on word expansion errors. | |
ccc6cda3 | 6454 | |
690150f9 CR |
6455 | 27. Non-interactive shells exit if there is a syntax error in a script |
6456 | read with the '.' or 'source' builtins, or in a string processed by | |
6457 | the 'eval' builtin. | |
6458 | ||
6459 | 28. Process substitution is not available. | |
6460 | ||
6461 | 29. While variable indirection is available, it may not be applied to | |
8a0829e9 | 6462 | the '#' and '?' special parameters. |
74d0116b | 6463 | |
690150f9 | 6464 | 30. Assignment statements preceding POSIX special builtins persist in |
ac18b312 | 6465 | the shell environment after the builtin completes. |
ccc6cda3 | 6466 | |
690150f9 | 6467 | 31. Assignment statements preceding shell function calls persist in |
8a0829e9 | 6468 | the shell environment after the function returns, as if a POSIX |
28ef6c31 JA |
6469 | special builtin command had been executed. |
6470 | ||
690150f9 CR |
6471 | 32. The 'command' builtin does not prevent builtins that take |
6472 | assignment statements as arguments from expanding them as | |
6473 | assignment statements; when not in POSIX mode, assignment builtins | |
6474 | lose their assignment statement expansion properties when preceded | |
6475 | by 'command'. | |
6476 | ||
6477 | 33. The 'bg' builtin uses the required format to describe each job | |
6478 | placed in the background, which does not include an indication of | |
6479 | whether the job is the current or previous job. | |
6480 | ||
6481 | 34. The output of 'kill -l' prints all the signal names on a single | |
6482 | line, separated by spaces, without the 'SIG' prefix. | |
6483 | ||
6484 | 35. The 'kill' builtin does not accept signal names with a 'SIG' | |
6485 | prefix. | |
6486 | ||
6487 | 36. The 'export' and 'readonly' builtin commands display their output | |
ac18b312 | 6488 | in the format required by POSIX. |
d166f048 | 6489 | |
690150f9 | 6490 | 37. The 'trap' builtin displays signal names without the leading |
8a0829e9 | 6491 | 'SIG'. |
28ef6c31 | 6492 | |
690150f9 | 6493 | 38. The 'trap' builtin doesn't check the first argument for a possible |
d3a24ed2 | 6494 | signal specification and revert the signal handling to the original |
8a9c66f6 CR |
6495 | disposition if it is, unless that argument consists solely of |
6496 | digits and is a valid signal number. If users want to reset the | |
8a0829e9 CR |
6497 | handler for a given signal to the original disposition, they should |
6498 | use '-' as the first argument. | |
d3a24ed2 | 6499 | |
690150f9 | 6500 | 39. The '.' and 'source' builtins do not search the current directory |
8a0829e9 | 6501 | for the filename argument if it is not found by searching 'PATH'. |
28ef6c31 | 6502 | |
690150f9 CR |
6503 | 40. Enabling POSIX mode has the effect of setting the |
6504 | 'inherit_errexit' option, so subshells spawned to execute command | |
6505 | substitutions inherit the value of the '-e' option from the parent | |
6506 | shell. When the 'inherit_errexit' option is not enabled, Bash | |
6507 | clears the '-e' option in such subshells. | |
28ef6c31 | 6508 | |
690150f9 | 6509 | 41. When the 'alias' builtin displays alias definitions, it does not |
8a0829e9 | 6510 | display them with a leading 'alias ' unless the '-p' option is |
d3a24ed2 CR |
6511 | supplied. |
6512 | ||
690150f9 | 6513 | 42. When the 'set' builtin is invoked without options, it does not |
28ef6c31 JA |
6514 | display shell function names and definitions. |
6515 | ||
690150f9 | 6516 | 43. When the 'set' builtin is invoked without options, it displays |
f73dda09 JA |
6517 | variable values without quotes, unless they contain shell |
6518 | metacharacters, even if the result contains nonprinting characters. | |
ccc6cda3 | 6519 | |
690150f9 | 6520 | 44. When the 'cd' builtin is invoked in LOGICAL mode, and the pathname |
8a0829e9 CR |
6521 | constructed from '$PWD' and the directory name supplied as an |
6522 | argument does not refer to an existing directory, 'cd' will fail | |
7117c2d2 JA |
6523 | instead of falling back to PHYSICAL mode. |
6524 | ||
690150f9 | 6525 | 45. The 'pwd' builtin verifies that the value it prints is the same as |
1c72c0cd | 6526 | the current directory, even if it is not asked to check the file |
8a0829e9 | 6527 | system with the '-P' option. |
1c72c0cd | 6528 | |
690150f9 | 6529 | 46. When listing the history, the 'fc' builtin does not include an |
8a9c66f6 CR |
6530 | indication of whether or not a history entry has been modified. |
6531 | ||
690150f9 | 6532 | 47. The default editor used by 'fc' is 'ed'. |
8a9c66f6 | 6533 | |
690150f9 | 6534 | 48. The 'type' and 'command' builtins will not report a non-executable |
8a0829e9 CR |
6535 | file as having been found, though the shell will attempt to execute |
6536 | such a file if it is the only so-named file found in '$PATH'. | |
37c41ab1 | 6537 | |
690150f9 | 6538 | 49. The 'vi' editing mode will invoke the 'vi' editor directly when |
8a0829e9 CR |
6539 | the 'v' command is run, instead of checking '$VISUAL' and |
6540 | '$EDITOR'. | |
1c72c0cd | 6541 | |
690150f9 | 6542 | 50. When the 'xpg_echo' option is enabled, Bash does not attempt to |
8a0829e9 | 6543 | interpret any arguments to 'echo' as options. Each argument is |
37c41ab1 CR |
6544 | displayed, after escape characters are converted. |
6545 | ||
690150f9 | 6546 | 51. The 'ulimit' builtin uses a block size of 512 bytes for the '-c' |
8a0829e9 | 6547 | and '-f' options. |
09767ff0 | 6548 | |
690150f9 | 6549 | 52. The arrival of 'SIGCHLD' when a trap is set on 'SIGCHLD' does not |
8a0829e9 | 6550 | interrupt the 'wait' builtin and cause it to return immediately. |
d5362af8 CR |
6551 | The trap command is run once for each child that exits. |
6552 | ||
690150f9 | 6553 | 53. The 'read' builtin may be interrupted by a signal for which a trap |
abe2eb5b | 6554 | has been set. If Bash receives a trapped signal while executing |
8a0829e9 CR |
6555 | 'read', the trap handler executes and 'read' returns an exit status |
6556 | greater than 128. | |
ccc6cda3 | 6557 | |
8a0829e9 CR |
6558 | There is other POSIX behavior that Bash does not implement by default |
6559 | even when in POSIX mode. Specifically: | |
ccc6cda3 | 6560 | |
8a0829e9 CR |
6561 | 1. The 'fc' builtin checks '$EDITOR' as a program to edit history |
6562 | entries if 'FCEDIT' is unset, rather than defaulting directly to | |
6563 | 'ed'. 'fc' uses 'ed' if 'EDITOR' is unset. | |
28ef6c31 | 6564 | |
8a0829e9 CR |
6565 | 2. As noted above, Bash requires the 'xpg_echo' option to be enabled |
6566 | for the 'echo' builtin to be fully conformant. | |
28ef6c31 | 6567 | |
1c72c0cd | 6568 | Bash can be configured to be POSIX-conformant by default, by |
8a0829e9 | 6569 | specifying the '--enable-strict-posix-default' to 'configure' when |
1c72c0cd | 6570 | building (*note Optional Features::). |
28ef6c31 | 6571 | |
ccc6cda3 | 6572 | \1f |
c2a47ea9 | 6573 | File: bashref.info, Node: Job Control, Next: Command Line Editing, Prev: Bash Features, Up: Top |
ccc6cda3 | 6574 | |
37c41ab1 CR |
6575 | 7 Job Control |
6576 | ************* | |
ccc6cda3 | 6577 | |
37c41ab1 CR |
6578 | This chapter discusses what job control is, how it works, and how Bash |
6579 | allows you to access its facilities. | |
ccc6cda3 JA |
6580 | |
6581 | * Menu: | |
6582 | ||
6583 | * Job Control Basics:: How job control works. | |
6584 | * Job Control Builtins:: Bash builtin commands used to interact | |
6585 | with job control. | |
6586 | * Job Control Variables:: Variables Bash uses to customize job | |
6587 | control. | |
6588 | ||
6589 | \1f | |
6590 | File: bashref.info, Node: Job Control Basics, Next: Job Control Builtins, Up: Job Control | |
6591 | ||
37c41ab1 CR |
6592 | 7.1 Job Control Basics |
6593 | ====================== | |
ccc6cda3 | 6594 | |
37c41ab1 | 6595 | Job control refers to the ability to selectively stop (suspend) the |
ccc6cda3 JA |
6596 | execution of processes and continue (resume) their execution at a later |
6597 | point. A user typically employs this facility via an interactive | |
602bb739 CR |
6598 | interface supplied jointly by the operating system kernel's terminal |
6599 | driver and Bash. | |
ccc6cda3 JA |
6600 | |
6601 | The shell associates a JOB with each pipeline. It keeps a table of | |
8a0829e9 | 6602 | currently executing jobs, which may be listed with the 'jobs' command. |
cce855bc | 6603 | When Bash starts a job asynchronously, it prints a line that looks like: |
ccc6cda3 | 6604 | [1] 25647 |
8a0829e9 CR |
6605 | indicating that this job is job number 1 and that the process ID of the |
6606 | last process in the pipeline associated with this job is 25647. All of | |
6607 | the processes in a single pipeline are members of the same job. Bash | |
6608 | uses the JOB abstraction as the basis for job control. | |
ccc6cda3 JA |
6609 | |
6610 | To facilitate the implementation of the user interface to job | |
bb70624e JA |
6611 | control, the operating system maintains the notion of a current terminal |
6612 | process group ID. Members of this process group (processes whose | |
6613 | process group ID is equal to the current terminal process group ID) | |
8a0829e9 | 6614 | receive keyboard-generated signals such as 'SIGINT'. These processes |
bb70624e JA |
6615 | are said to be in the foreground. Background processes are those whose |
6616 | process group ID differs from the terminal's; such processes are immune | |
8a0829e9 CR |
6617 | to keyboard-generated signals. Only foreground processes are allowed to |
6618 | read from or, if the user so specifies with 'stty tostop', write to the | |
6619 | terminal. Background processes which attempt to read from (write to | |
6620 | when 'stty tostop' is in effect) the terminal are sent a 'SIGTTIN' | |
6621 | ('SIGTTOU') signal by the kernel's terminal driver, which, unless | |
602bb739 | 6622 | caught, suspends the process. |
ccc6cda3 JA |
6623 | |
6624 | If the operating system on which Bash is running supports job | |
cce855bc | 6625 | control, Bash contains facilities to use it. Typing the SUSPEND |
8a0829e9 | 6626 | character (typically '^Z', Control-Z) while a process is running causes |
cce855bc | 6627 | that process to be stopped and returns control to Bash. Typing the |
8a0829e9 CR |
6628 | DELAYED SUSPEND character (typically '^Y', Control-Y) causes the process |
6629 | to be stopped when it attempts to read input from the terminal, and | |
6630 | control to be returned to Bash. The user then manipulates the state of | |
6631 | this job, using the 'bg' command to continue it in the background, the | |
6632 | 'fg' command to continue it in the foreground, or the 'kill' command to | |
6633 | kill it. A '^Z' takes effect immediately, and has the additional side | |
6634 | effect of causing pending output and typeahead to be discarded. | |
ccc6cda3 JA |
6635 | |
6636 | There are a number of ways to refer to a job in the shell. The | |
8a0829e9 CR |
6637 | character '%' introduces a job specification (JOBSPEC). |
6638 | ||
6639 | Job number 'n' may be referred to as '%n'. The symbols '%%' and '%+' | |
6640 | refer to the shell's notion of the current job, which is the last job | |
6641 | stopped while it was in the foreground or started in the background. A | |
6642 | single '%' (with no accompanying job specification) also refers to the | |
6643 | current job. The previous job may be referenced using '%-'. If there | |
6644 | is only a single job, '%+' and '%-' can both be used to refer to that | |
6645 | job. In output pertaining to jobs (e.g., the output of the 'jobs' | |
6646 | command), the current job is always flagged with a '+', and the previous | |
6647 | job with a '-'. | |
bb70624e JA |
6648 | |
6649 | A job may also be referred to using a prefix of the name used to | |
6650 | start it, or using a substring that appears in its command line. For | |
8a0829e9 CR |
6651 | example, '%ce' refers to a stopped 'ce' job. Using '%?ce', on the other |
6652 | hand, refers to any job containing the string 'ce' in its command line. | |
6653 | If the prefix or substring matches more than one job, Bash reports an | |
6654 | error. | |
6655 | ||
6656 | Simply naming a job can be used to bring it into the foreground: '%1' | |
6657 | is a synonym for 'fg %1', bringing job 1 from the background into the | |
6658 | foreground. Similarly, '%1 &' resumes job 1 in the background, | |
6659 | equivalent to 'bg %1' | |
6660 | ||
6661 | The shell learns immediately whenever a job changes state. Normally, | |
6662 | Bash waits until it is about to print a prompt before reporting changes | |
6663 | in a job's status so as to not interrupt any other output. If the '-b' | |
6664 | option to the 'set' builtin is enabled, Bash reports such changes | |
6665 | immediately (*note The Set Builtin::). Any trap on 'SIGCHLD' is | |
6666 | executed for each child process that exits. | |
ccc6cda3 | 6667 | |
d3ad40de | 6668 | If an attempt to exit Bash is made while jobs are stopped, (or |
8a0829e9 CR |
6669 | running, if the 'checkjobs' option is enabled - see *note The Shopt |
6670 | Builtin::), the shell prints a warning message, and if the 'checkjobs' | |
6671 | option is enabled, lists the jobs and their statuses. The 'jobs' | |
cce855bc JA |
6672 | command may then be used to inspect their status. If a second attempt |
6673 | to exit is made without an intervening command, Bash does not print | |
d3ad40de | 6674 | another warning, and any stopped jobs are terminated. |
ccc6cda3 JA |
6675 | |
6676 | \1f | |
6677 | File: bashref.info, Node: Job Control Builtins, Next: Job Control Variables, Prev: Job Control Basics, Up: Job Control | |
6678 | ||
37c41ab1 CR |
6679 | 7.2 Job Control Builtins |
6680 | ======================== | |
ccc6cda3 | 6681 | |
8a0829e9 | 6682 | 'bg' |
37c41ab1 | 6683 | bg [JOBSPEC ...] |
122f603c | 6684 | |
37c41ab1 | 6685 | Resume each suspended job JOBSPEC in the background, as if it had |
8a0829e9 CR |
6686 | been started with '&'. If JOBSPEC is not supplied, the current job |
6687 | is used. The return status is zero unless it is run when job | |
1c72c0cd CR |
6688 | control is not enabled, or, when run with job control enabled, any |
6689 | JOBSPEC was not found or specifies a job that was started without | |
6690 | job control. | |
ccc6cda3 | 6691 | |
8a0829e9 | 6692 | 'fg' |
ccc6cda3 | 6693 | fg [JOBSPEC] |
122f603c | 6694 | |
cce855bc JA |
6695 | Resume the job JOBSPEC in the foreground and make it the current |
6696 | job. If JOBSPEC is not supplied, the current job is used. The | |
8a0829e9 CR |
6697 | return status is that of the command placed into the foreground, or |
6698 | non-zero if run when job control is disabled or, when run with job | |
6699 | control enabled, JOBSPEC does not specify a valid job or JOBSPEC | |
6700 | specifies a job that was started without job control. | |
ccc6cda3 | 6701 | |
8a0829e9 | 6702 | 'jobs' |
bb70624e | 6703 | jobs [-lnprs] [JOBSPEC] |
cce855bc | 6704 | jobs -x COMMAND [ARGUMENTS] |
ccc6cda3 JA |
6705 | |
6706 | The first form lists the active jobs. The options have the | |
6707 | following meanings: | |
6708 | ||
8a0829e9 | 6709 | '-l' |
cce855bc | 6710 | List process IDs in addition to the normal information. |
ccc6cda3 | 6711 | |
8a0829e9 | 6712 | '-n' |
ccc6cda3 | 6713 | Display information only about jobs that have changed status |
cce855bc | 6714 | since the user was last notified of their status. |
ccc6cda3 | 6715 | |
8a0829e9 | 6716 | '-p' |
ccc6cda3 JA |
6717 | List only the process ID of the job's process group leader. |
6718 | ||
8a0829e9 | 6719 | '-r' |
122f603c | 6720 | Display only running jobs. |
ccc6cda3 | 6721 | |
8a0829e9 | 6722 | '-s' |
122f603c | 6723 | Display only stopped jobs. |
ccc6cda3 | 6724 | |
8a0829e9 CR |
6725 | If JOBSPEC is given, output is restricted to information about that |
6726 | job. If JOBSPEC is not supplied, the status of all jobs is listed. | |
ccc6cda3 | 6727 | |
8a0829e9 | 6728 | If the '-x' option is supplied, 'jobs' replaces any JOBSPEC found |
ccc6cda3 JA |
6729 | in COMMAND or ARGUMENTS with the corresponding process group ID, |
6730 | and executes COMMAND, passing it ARGUMENTs, returning its exit | |
6731 | status. | |
6732 | ||
8a0829e9 | 6733 | 'kill' |
cce855bc | 6734 | kill [-s SIGSPEC] [-n SIGNUM] [-SIGSPEC] JOBSPEC or PID |
54a5fbe1 | 6735 | kill -l|-L [EXIT_STATUS] |
122f603c | 6736 | |
ccc6cda3 | 6737 | Send a signal specified by SIGSPEC or SIGNUM to the process named |
cce855bc | 6738 | by job specification JOBSPEC or process ID PID. SIGSPEC is either |
8a0829e9 CR |
6739 | a case-insensitive signal name such as 'SIGINT' (with or without |
6740 | the 'SIG' prefix) or a signal number; SIGNUM is a signal number. | |
6741 | If SIGSPEC and SIGNUM are not present, 'SIGTERM' is used. The '-l' | |
6742 | option lists the signal names. If any arguments are supplied when | |
6743 | '-l' is given, the names of the signals corresponding to the | |
9f422431 CR |
6744 | arguments are listed, and the return status is zero. EXIT_STATUS |
6745 | is a number specifying a signal number or the exit status of a | |
54a5fbe1 CR |
6746 | process terminated by a signal. The '-L' option is equivalent to |
6747 | '-l'. The return status is zero if at least one signal was | |
6748 | successfully sent, or non-zero if an error occurs or an invalid | |
6749 | option is encountered. | |
ccc6cda3 | 6750 | |
8a0829e9 | 6751 | 'wait' |
1101193a | 6752 | wait [-n] [JOBSPEC or PID ...] |
122f603c | 6753 | |
eb2bb562 CR |
6754 | Wait until the child process specified by each process ID PID or |
6755 | job specification JOBSPEC exits and return the exit status of the | |
6756 | last command waited for. If a job spec is given, all processes in | |
6757 | the job are waited for. If no arguments are given, all currently | |
cce855bc | 6758 | active child processes are waited for, and the return status is |
8a0829e9 | 6759 | zero. If the '-n' option is supplied, 'wait' waits for any job to |
ad4aef08 CR |
6760 | terminate and returns its exit status. If neither JOBSPEC nor PID |
6761 | specifies an active child process of the shell, the return status | |
6762 | is 127. | |
ccc6cda3 | 6763 | |
8a0829e9 | 6764 | 'disown' |
690150f9 | 6765 | disown [-ar] [-h] [JOBSPEC ... | PID ... ] |
122f603c CR |
6766 | |
6767 | Without options, remove each JOBSPEC from the table of active jobs. | |
8a0829e9 CR |
6768 | If the '-h' option is given, the job is not removed from the table, |
6769 | but is marked so that 'SIGHUP' is not sent to the job if the shell | |
6770 | receives a 'SIGHUP'. If JOBSPEC is not present, and neither the | |
6771 | '-a' nor the '-r' option is supplied, the current job is used. If | |
6772 | no JOBSPEC is supplied, the '-a' option means to remove or mark all | |
6773 | jobs; the '-r' option without a JOBSPEC argument restricts | |
122f603c | 6774 | operation to running jobs. |
ccc6cda3 | 6775 | |
8a0829e9 | 6776 | 'suspend' |
ccc6cda3 | 6777 | suspend [-f] |
122f603c | 6778 | |
8a0829e9 CR |
6779 | Suspend the execution of this shell until it receives a 'SIGCONT' |
6780 | signal. A login shell cannot be suspended; the '-f' option can be | |
09767ff0 | 6781 | used to override this and force the suspension. |
ccc6cda3 | 6782 | |
8a0829e9 CR |
6783 | When job control is not active, the 'kill' and 'wait' builtins do not |
6784 | accept JOBSPEC arguments. They must be supplied process IDs. | |
ccc6cda3 JA |
6785 | |
6786 | \1f | |
6787 | File: bashref.info, Node: Job Control Variables, Prev: Job Control Builtins, Up: Job Control | |
6788 | ||
37c41ab1 CR |
6789 | 7.3 Job Control Variables |
6790 | ========================= | |
ccc6cda3 | 6791 | |
8a0829e9 | 6792 | 'auto_resume' |
ccc6cda3 JA |
6793 | This variable controls how the shell interacts with the user and |
6794 | job control. If this variable exists then single word simple | |
cce855bc JA |
6795 | commands without redirections are treated as candidates for |
6796 | resumption of an existing job. There is no ambiguity allowed; if | |
6797 | there is more than one job beginning with the string typed, then | |
6798 | the most recently accessed job will be selected. The name of a | |
8a0829e9 CR |
6799 | stopped job, in this context, is the command line used to start it. |
6800 | If this variable is set to the value 'exact', the string supplied | |
6801 | must match the name of a stopped job exactly; if set to | |
6802 | 'substring', the string supplied needs to match a substring of the | |
6803 | name of a stopped job. The 'substring' value provides | |
6804 | functionality analogous to the '%?' job ID (*note Job Control | |
28ef6c31 JA |
6805 | Basics::). If set to any other value, the supplied string must be |
6806 | a prefix of a stopped job's name; this provides functionality | |
8a0829e9 | 6807 | analogous to the '%' job ID. |
761783bf | 6808 | |
ccc6cda3 | 6809 | \1f |
c2a47ea9 | 6810 | File: bashref.info, Node: Command Line Editing, Next: Using History Interactively, Prev: Job Control, Up: Top |
ccc6cda3 | 6811 | |
37c41ab1 CR |
6812 | 8 Command Line Editing |
6813 | ********************** | |
ccc6cda3 | 6814 | |
37c41ab1 | 6815 | This chapter describes the basic features of the GNU command line |
bb70624e JA |
6816 | editing interface. Command line editing is provided by the Readline |
6817 | library, which is used by several different programs, including Bash. | |
a9fac3b2 | 6818 | Command line editing is enabled by default when using an interactive |
8a0829e9 CR |
6819 | shell, unless the '--noediting' option is supplied at shell invocation. |
6820 | Line editing is also used when using the '-e' option to the 'read' | |
a9fac3b2 | 6821 | builtin command (*note Bash Builtins::). By default, the line editing |
e05be32d | 6822 | commands are similar to those of Emacs. A vi-style line editing |
a9fac3b2 | 6823 | interface is also available. Line editing can be enabled at any time |
8a0829e9 CR |
6824 | using the '-o emacs' or '-o vi' options to the 'set' builtin command |
6825 | (*note The Set Builtin::), or disabled using the '+o emacs' or '+o vi' | |
6826 | options to 'set'. | |
ccc6cda3 JA |
6827 | |
6828 | * Menu: | |
6829 | ||
bb70624e JA |
6830 | * Introduction and Notation:: Notation used in this text. |
6831 | * Readline Interaction:: The minimum set of commands for editing a line. | |
6832 | * Readline Init File:: Customizing Readline from a user's view. | |
6833 | * Bindable Readline Commands:: A description of most of the Readline commands | |
6834 | available for binding | |
6835 | * Readline vi Mode:: A short description of how to make Readline | |
6836 | behave like the vi editor. | |
bb70624e JA |
6837 | * Programmable Completion:: How to specify the possible completions for |
6838 | a specific command. | |
6839 | * Programmable Completion Builtins:: Builtin commands to specify how to | |
6840 | complete arguments for a particular command. | |
45c0f7f8 CR |
6841 | * A Programmable Completion Example:: An example shell function for |
6842 | generating possible completions. | |
ccc6cda3 JA |
6843 | |
6844 | \1f | |
bb70624e | 6845 | File: bashref.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing |
ccc6cda3 | 6846 | |
37c41ab1 CR |
6847 | 8.1 Introduction to Line Editing |
6848 | ================================ | |
ccc6cda3 | 6849 | |
37c41ab1 | 6850 | The following paragraphs describe the notation used to represent |
bb70624e | 6851 | keystrokes. |
ccc6cda3 | 6852 | |
8a0829e9 | 6853 | The text 'C-k' is read as 'Control-K' and describes the character |
bb70624e | 6854 | produced when the <k> key is pressed while the Control key is depressed. |
ccc6cda3 | 6855 | |
8a0829e9 | 6856 | The text 'M-k' is read as 'Meta-K' and describes the character |
bb70624e JA |
6857 | produced when the Meta key (if you have one) is depressed, and the <k> |
6858 | key is pressed. The Meta key is labeled <ALT> on many keyboards. On | |
6859 | keyboards with two keys labeled <ALT> (usually to either side of the | |
6860 | space bar), the <ALT> on the left side is generally set to work as a | |
6861 | Meta key. The <ALT> key on the right may also be configured to work as | |
6862 | a Meta key or may be configured as some other modifier, such as a | |
6863 | Compose key for typing accented characters. | |
6864 | ||
6865 | If you do not have a Meta or <ALT> key, or another key working as a | |
6866 | Meta key, the identical keystroke can be generated by typing <ESC> | |
28ef6c31 JA |
6867 | _first_, and then typing <k>. Either process is known as "metafying" |
6868 | the <k> key. | |
bb70624e | 6869 | |
8a0829e9 CR |
6870 | The text 'M-C-k' is read as 'Meta-Control-k' and describes the |
6871 | character produced by "metafying" 'C-k'. | |
bb70624e | 6872 | |
8a0829e9 CR |
6873 | In addition, several keys have their own names. Specifically, <DEL>, |
6874 | <ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves when seen | |
6875 | in this text, or in an init file (*note Readline Init File::). If your | |
6876 | keyboard lacks a <LFD> key, typing <C-j> will produce the desired | |
6877 | character. The <RET> key may be labeled <Return> or <Enter> on some | |
6878 | keyboards. | |
ccc6cda3 JA |
6879 | |
6880 | \1f | |
bb70624e | 6881 | File: bashref.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing |
cce855bc | 6882 | |
37c41ab1 CR |
6883 | 8.2 Readline Interaction |
6884 | ======================== | |
cce855bc | 6885 | |
37c41ab1 | 6886 | Often during an interactive session you type in a long line of text, |
bb70624e JA |
6887 | only to notice that the first word on the line is misspelled. The |
6888 | Readline library gives you a set of commands for manipulating the text | |
6889 | as you type it in, allowing you to just fix your typo, and not forcing | |
6890 | you to retype the majority of the line. Using these editing commands, | |
6891 | you move the cursor to the place that needs correction, and delete or | |
6892 | insert the text of the corrections. Then, when you are satisfied with | |
28ef6c31 JA |
6893 | the line, you simply press <RET>. You do not have to be at the end of |
6894 | the line to press <RET>; the entire line is accepted regardless of the | |
6895 | location of the cursor within the line. | |
cce855bc | 6896 | |
bb70624e | 6897 | * Menu: |
cce855bc | 6898 | |
bb70624e JA |
6899 | * Readline Bare Essentials:: The least you need to know about Readline. |
6900 | * Readline Movement Commands:: Moving about the input line. | |
6901 | * Readline Killing Commands:: How to delete text, and how to get it back! | |
6902 | * Readline Arguments:: Giving numeric arguments to commands. | |
6903 | * Searching:: Searching through previous lines. | |
cce855bc | 6904 | |
bb70624e JA |
6905 | \1f |
6906 | File: bashref.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction | |
cce855bc | 6907 | |
37c41ab1 CR |
6908 | 8.2.1 Readline Bare Essentials |
6909 | ------------------------------ | |
cce855bc | 6910 | |
37c41ab1 CR |
6911 | In order to enter characters into the line, simply type them. The typed |
6912 | character appears where the cursor was, and then the cursor moves one | |
6913 | space to the right. If you mistype a character, you can use your erase | |
6914 | character to back up and delete the mistyped character. | |
cce855bc | 6915 | |
8a0829e9 CR |
6916 | Sometimes you may mistype a character, and not notice the error until |
6917 | you have typed several other characters. In that case, you can type | |
6918 | 'C-b' to move the cursor to the left, and then correct your mistake. | |
6919 | Afterwards, you can move the cursor to the right with 'C-f'. | |
cce855bc | 6920 | |
bb70624e | 6921 | When you add text in the middle of a line, you will notice that |
8a0829e9 CR |
6922 | characters to the right of the cursor are 'pushed over' to make room for |
6923 | the text that you have inserted. Likewise, when you delete text behind | |
6924 | the cursor, characters to the right of the cursor are 'pulled back' to | |
6925 | fill in the blank space created by the removal of the text. A list of | |
6926 | the bare essentials for editing the text of an input line follows. | |
cce855bc | 6927 | |
8a0829e9 CR |
6928 | 'C-b' |
6929 | Move back one character. | |
6930 | 'C-f' | |
bb70624e | 6931 | Move forward one character. |
bb70624e JA |
6932 | <DEL> or <Backspace> |
6933 | Delete the character to the left of the cursor. | |
8a0829e9 | 6934 | 'C-d' |
bb70624e | 6935 | Delete the character underneath the cursor. |
bb70624e JA |
6936 | Printing characters |
6937 | Insert the character into the line at the cursor. | |
8a0829e9 | 6938 | 'C-_' or 'C-x C-u' |
bb70624e JA |
6939 | Undo the last editing command. You can undo all the way back to an |
6940 | empty line. | |
cce855bc | 6941 | |
bb70624e JA |
6942 | (Depending on your configuration, the <Backspace> key be set to delete |
6943 | the character to the left of the cursor and the <DEL> key set to delete | |
8a0829e9 | 6944 | the character underneath the cursor, like 'C-d', rather than the |
bb70624e | 6945 | character to the left of the cursor.) |
cce855bc JA |
6946 | |
6947 | \1f | |
bb70624e | 6948 | File: bashref.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction |
ccc6cda3 | 6949 | |
37c41ab1 CR |
6950 | 8.2.2 Readline Movement Commands |
6951 | -------------------------------- | |
ccc6cda3 | 6952 | |
37c41ab1 | 6953 | The above table describes the most basic keystrokes that you need in |
8a0829e9 CR |
6954 | order to do editing of the input line. For your convenience, many other |
6955 | commands have been added in addition to 'C-b', 'C-f', 'C-d', and <DEL>. | |
6956 | Here are some commands for moving more rapidly about the line. | |
ccc6cda3 | 6957 | |
8a0829e9 | 6958 | 'C-a' |
bb70624e | 6959 | Move to the start of the line. |
8a0829e9 | 6960 | 'C-e' |
bb70624e | 6961 | Move to the end of the line. |
8a0829e9 | 6962 | 'M-f' |
bb70624e JA |
6963 | Move forward a word, where a word is composed of letters and |
6964 | digits. | |
8a0829e9 | 6965 | 'M-b' |
bb70624e | 6966 | Move backward a word. |
8a0829e9 | 6967 | 'C-l' |
bb70624e | 6968 | Clear the screen, reprinting the current line at the top. |
ccc6cda3 | 6969 | |
8a0829e9 CR |
6970 | Notice how 'C-f' moves forward a character, while 'M-f' moves forward |
6971 | a word. It is a loose convention that control keystrokes operate on | |
6972 | characters while meta keystrokes operate on words. | |
ccc6cda3 JA |
6973 | |
6974 | \1f | |
bb70624e | 6975 | File: bashref.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction |
ccc6cda3 | 6976 | |
37c41ab1 CR |
6977 | 8.2.3 Readline Killing Commands |
6978 | ------------------------------- | |
ccc6cda3 | 6979 | |
37c41ab1 | 6980 | "Killing" text means to delete the text from the line, but to save it |
8a0829e9 CR |
6981 | away for later use, usually by "yanking" (re-inserting) it back into the |
6982 | line. ('Cut' and 'paste' are more recent jargon for 'kill' and 'yank'.) | |
ccc6cda3 | 6983 | |
8a0829e9 | 6984 | If the description for a command says that it 'kills' text, then you |
bb70624e JA |
6985 | can be sure that you can get the text back in a different (or the same) |
6986 | place later. | |
ccc6cda3 | 6987 | |
8a0829e9 CR |
6988 | When you use a kill command, the text is saved in a "kill-ring". Any |
6989 | number of consecutive kills save all of the killed text together, so | |
bb70624e JA |
6990 | that when you yank it back, you get it all. The kill ring is not line |
6991 | specific; the text that you killed on a previously typed line is | |
8a0829e9 | 6992 | available to be yanked back later, when you are typing another line. |
ccc6cda3 | 6993 | |
bb70624e | 6994 | Here is the list of commands for killing text. |
ccc6cda3 | 6995 | |
8a0829e9 | 6996 | 'C-k' |
bb70624e JA |
6997 | Kill the text from the current cursor position to the end of the |
6998 | line. | |
ccc6cda3 | 6999 | |
8a0829e9 | 7000 | 'M-d' |
bb70624e JA |
7001 | Kill from the cursor to the end of the current word, or, if between |
7002 | words, to the end of the next word. Word boundaries are the same | |
8a0829e9 | 7003 | as those used by 'M-f'. |
ccc6cda3 | 7004 | |
8a0829e9 | 7005 | 'M-<DEL>' |
f73dda09 | 7006 | Kill from the cursor the start of the current word, or, if between |
bb70624e | 7007 | words, to the start of the previous word. Word boundaries are the |
8a0829e9 | 7008 | same as those used by 'M-b'. |
ccc6cda3 | 7009 | |
8a0829e9 CR |
7010 | 'C-w' |
7011 | Kill from the cursor to the previous whitespace. This is different | |
7012 | than 'M-<DEL>' because the word boundaries differ. | |
761783bf | 7013 | |
cce855bc JA |
7014 | Here is how to "yank" the text back into the line. Yanking means to |
7015 | copy the most-recently-killed text from the kill buffer. | |
ccc6cda3 | 7016 | |
8a0829e9 | 7017 | 'C-y' |
ccc6cda3 JA |
7018 | Yank the most recently killed text back into the buffer at the |
7019 | cursor. | |
7020 | ||
8a0829e9 | 7021 | 'M-y' |
ccc6cda3 | 7022 | Rotate the kill-ring, and yank the new top. You can only do this |
8a0829e9 | 7023 | if the prior command is 'C-y' or 'M-y'. |
ccc6cda3 JA |
7024 | |
7025 | \1f | |
7026 | File: bashref.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction | |
7027 | ||
37c41ab1 CR |
7028 | 8.2.4 Readline Arguments |
7029 | ------------------------ | |
ccc6cda3 | 7030 | |
37c41ab1 | 7031 | You can pass numeric arguments to Readline commands. Sometimes the |
ccc6cda3 JA |
7032 | argument acts as a repeat count, other times it is the sign of the |
7033 | argument that is significant. If you pass a negative argument to a | |
7034 | command which normally acts in a forward direction, that command will | |
7035 | act in a backward direction. For example, to kill text back to the | |
8a0829e9 | 7036 | start of the line, you might type 'M-- C-k'. |
ccc6cda3 JA |
7037 | |
7038 | The general way to pass numeric arguments to a command is to type | |
8a0829e9 CR |
7039 | meta digits before the command. If the first 'digit' typed is a minus |
7040 | sign ('-'), then the sign of the argument will be negative. Once you | |
cce855bc | 7041 | have typed one meta digit to get the argument started, you can type the |
8a0829e9 CR |
7042 | remainder of the digits, and then the command. For example, to give the |
7043 | 'C-d' command an argument of 10, you could type 'M-1 0 C-d', which will | |
7044 | delete the next ten characters on the input line. | |
ccc6cda3 JA |
7045 | |
7046 | \1f | |
7047 | File: bashref.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction | |
7048 | ||
37c41ab1 CR |
7049 | 8.2.5 Searching for Commands in the History |
7050 | ------------------------------------------- | |
ccc6cda3 | 7051 | |
37c41ab1 | 7052 | Readline provides commands for searching through the command history |
28ef6c31 | 7053 | (*note Bash History Facilities::) for lines containing a specified |
8a0829e9 | 7054 | string. There are two search modes: "incremental" and |
28ef6c31 | 7055 | "non-incremental". |
ccc6cda3 JA |
7056 | |
7057 | Incremental searches begin before the user has finished typing the | |
7058 | search string. As each character of the search string is typed, | |
cce855bc | 7059 | Readline displays the next entry from the history matching the string |
8a0829e9 CR |
7060 | typed so far. An incremental search requires only as many characters as |
7061 | needed to find the desired history entry. To search backward in the | |
7062 | history for a particular string, type 'C-r'. Typing 'C-s' searches | |
7063 | forward through the history. The characters present in the value of the | |
7064 | 'isearch-terminators' variable are used to terminate an incremental | |
bb70624e | 7065 | search. If that variable has not been assigned a value, the <ESC> and |
8a0829e9 CR |
7066 | 'C-J' characters will terminate an incremental search. 'C-g' will abort |
7067 | an incremental search and restore the original line. When the search is | |
7068 | terminated, the history entry containing the search string becomes the | |
7069 | current line. | |
7070 | ||
7071 | To find other matching entries in the history list, type 'C-r' or | |
7072 | 'C-s' as appropriate. This will search backward or forward in the | |
7073 | history for the next entry matching the search string typed so far. Any | |
7074 | other key sequence bound to a Readline command will terminate the search | |
7075 | and execute that command. For instance, a <RET> will terminate the | |
7076 | search and accept the line, thereby executing the command from the | |
28ef6c31 JA |
7077 | history list. A movement command will terminate the search, make the |
7078 | last line found the current line, and begin editing. | |
ccc6cda3 | 7079 | |
8a0829e9 CR |
7080 | Readline remembers the last incremental search string. If two 'C-r's |
7081 | are typed without any intervening characters defining a new search | |
7082 | string, any remembered search string is used. | |
f73dda09 | 7083 | |
ccc6cda3 JA |
7084 | Non-incremental searches read the entire search string before |
7085 | starting to search for matching history lines. The search string may be | |
cce855bc | 7086 | typed by the user or be part of the contents of the current line. |
ccc6cda3 JA |
7087 | |
7088 | \1f | |
7089 | File: bashref.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing | |
7090 | ||
37c41ab1 CR |
7091 | 8.3 Readline Init File |
7092 | ====================== | |
ccc6cda3 | 7093 | |
8a0829e9 CR |
7094 | Although the Readline library comes with a set of Emacs-like keybindings |
7095 | installed by default, it is possible to use a different set of | |
7096 | keybindings. Any user can customize programs that use Readline by | |
bb70624e JA |
7097 | putting commands in an "inputrc" file, conventionally in his home |
7098 | directory. The name of this file is taken from the value of the shell | |
8a0829e9 CR |
7099 | variable 'INPUTRC'. If that variable is unset, the default is |
7100 | '~/.inputrc'. If that file does not exist or cannot be read, the | |
7101 | ultimate default is '/etc/inputrc'. | |
ccc6cda3 JA |
7102 | |
7103 | When a program which uses the Readline library starts up, the init | |
7104 | file is read, and the key bindings are set. | |
7105 | ||
8a0829e9 | 7106 | In addition, the 'C-x C-r' command re-reads this init file, thus |
ccc6cda3 JA |
7107 | incorporating any changes that you might have made to it. |
7108 | ||
7109 | * Menu: | |
7110 | ||
7111 | * Readline Init File Syntax:: Syntax for the commands in the inputrc file. | |
7112 | ||
7113 | * Conditional Init Constructs:: Conditional key bindings in the inputrc file. | |
7114 | ||
7115 | * Sample Init File:: An example inputrc file. | |
7116 | ||
7117 | \1f | |
7118 | File: bashref.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File | |
7119 | ||
37c41ab1 CR |
7120 | 8.3.1 Readline Init File Syntax |
7121 | ------------------------------- | |
ccc6cda3 | 7122 | |
8a0829e9 CR |
7123 | There are only a few basic constructs allowed in the Readline init file. |
7124 | Blank lines are ignored. Lines beginning with a '#' are comments. | |
7125 | Lines beginning with a '$' indicate conditional constructs (*note | |
7126 | Conditional Init Constructs::). Other lines denote variable settings | |
7127 | and key bindings. | |
ccc6cda3 JA |
7128 | |
7129 | Variable Settings | |
cce855bc | 7130 | You can modify the run-time behavior of Readline by altering the |
8a0829e9 | 7131 | values of variables in Readline using the 'set' command within the |
28ef6c31 JA |
7132 | init file. The syntax is simple: |
7133 | ||
7134 | set VARIABLE VALUE | |
7135 | ||
8a0829e9 CR |
7136 | Here, for example, is how to change from the default Emacs-like key |
7137 | binding to use 'vi' line editing commands: | |
ccc6cda3 JA |
7138 | |
7139 | set editing-mode vi | |
7140 | ||
28ef6c31 | 7141 | Variable names and values, where appropriate, are recognized |
1c72c0cd CR |
7142 | without regard to case. Unrecognized variable names are ignored. |
7143 | ||
7144 | Boolean variables (those that can be set to on or off) are set to | |
8a0829e9 CR |
7145 | on if the value is null or empty, ON (case-insensitive), or 1. Any |
7146 | other value results in the variable being set to off. | |
28ef6c31 | 7147 | |
8a0829e9 CR |
7148 | The 'bind -V' command lists the current Readline variable names and |
7149 | values. *Note Bash Builtins::. | |
bb70624e | 7150 | |
cce855bc JA |
7151 | A great deal of run-time behavior is changeable with the following |
7152 | variables. | |
ccc6cda3 | 7153 | |
8a0829e9 CR |
7154 | 'bell-style' |
7155 | Controls what happens when Readline wants to ring the terminal | |
7156 | bell. If set to 'none', Readline never rings the bell. If | |
7157 | set to 'visible', Readline uses a visible bell if one is | |
7158 | available. If set to 'audible' (the default), Readline | |
7159 | attempts to ring the terminal's bell. | |
ccc6cda3 | 7160 | |
8a0829e9 CR |
7161 | 'bind-tty-special-chars' |
7162 | If set to 'on' (the default), Readline attempts to bind the | |
7163 | control characters treated specially by the kernel's terminal | |
7164 | driver to their Readline equivalents. | |
fc527055 | 7165 | |
8a0829e9 CR |
7166 | 'blink-matching-paren' |
7167 | If set to 'on', Readline attempts to briefly move the cursor | |
0385211b | 7168 | to an opening parenthesis when a closing parenthesis is |
8a0829e9 | 7169 | inserted. The default is 'off'. |
eb2bb562 | 7170 | |
8a0829e9 CR |
7171 | 'colored-completion-prefix' |
7172 | If set to 'on', when listing completions, Readline displays | |
7173 | the common prefix of the set of possible completions using a | |
7174 | different color. The color definitions are taken from the | |
7175 | value of the 'LS_COLORS' environment variable. The default is | |
7176 | 'off'. | |
7177 | ||
7178 | 'colored-stats' | |
7179 | If set to 'on', Readline displays possible completions using | |
abe2eb5b | 7180 | different colors to indicate their file type. The color |
8a0829e9 CR |
7181 | definitions are taken from the value of the 'LS_COLORS' |
7182 | environment variable. The default is 'off'. | |
abe2eb5b | 7183 | |
8a0829e9 | 7184 | 'comment-begin' |
ccc6cda3 | 7185 | The string to insert at the beginning of the line when the |
8a0829e9 CR |
7186 | 'insert-comment' command is executed. The default value is |
7187 | '"#"'. | |
ccc6cda3 | 7188 | |
8a0829e9 | 7189 | 'completion-display-width' |
eb0b2ad8 CR |
7190 | The number of screen columns used to display possible matches |
7191 | when performing completion. The value is ignored if it is | |
7192 | less than 0 or greater than the terminal screen width. A | |
7193 | value of 0 will cause matches to be displayed one per line. | |
7194 | The default value is -1. | |
7195 | ||
8a0829e9 CR |
7196 | 'completion-ignore-case' |
7197 | If set to 'on', Readline performs filename matching and | |
cce855bc | 7198 | completion in a case-insensitive fashion. The default value |
8a0829e9 | 7199 | is 'off'. |
cce855bc | 7200 | |
8a0829e9 CR |
7201 | 'completion-map-case' |
7202 | If set to 'on', and COMPLETION-IGNORE-CASE is enabled, | |
7203 | Readline treats hyphens ('-') and underscores ('_') as | |
220537f2 CR |
7204 | equivalent when performing case-insensitive filename matching |
7205 | and completion. | |
7206 | ||
8a0829e9 | 7207 | 'completion-prefix-display-length' |
ed35cb4a CR |
7208 | The length in characters of the common prefix of a list of |
7209 | possible completions that is displayed without modification. | |
7210 | When set to a value greater than zero, common prefixes longer | |
7211 | than this value are replaced with an ellipsis when displaying | |
7212 | possible completions. | |
7213 | ||
8a0829e9 | 7214 | 'completion-query-items' |
ccc6cda3 | 7215 | The number of possible completions that determines when the |
d3a24ed2 CR |
7216 | user is asked whether the list of possibilities should be |
7217 | displayed. If the number of possible completions is greater | |
7218 | than this value, Readline will ask the user whether or not he | |
7219 | wishes to view them; otherwise, they are simply listed. This | |
8a0829e9 CR |
7220 | variable must be set to an integer value greater than or equal |
7221 | to 0. A negative value means Readline should never ask. The | |
7222 | default limit is '100'. | |
ccc6cda3 | 7223 | |
8a0829e9 CR |
7224 | 'convert-meta' |
7225 | If set to 'on', Readline will convert characters with the | |
cce855bc | 7226 | eighth bit set to an ASCII key sequence by stripping the |
bb70624e | 7227 | eighth bit and prefixing an <ESC> character, converting them |
8a0829e9 | 7228 | to a meta-prefixed key sequence. The default value is 'on'. |
ccc6cda3 | 7229 | |
8a0829e9 CR |
7230 | 'disable-completion' |
7231 | If set to 'On', Readline will inhibit word completion. | |
7232 | Completion characters will be inserted into the line as if | |
7233 | they had been mapped to 'self-insert'. The default is 'off'. | |
ccc6cda3 | 7234 | |
8a0829e9 CR |
7235 | 'editing-mode' |
7236 | The 'editing-mode' variable controls which default set of key | |
cce855bc JA |
7237 | bindings is used. By default, Readline starts up in Emacs |
7238 | editing mode, where the keystrokes are most similar to Emacs. | |
8a0829e9 CR |
7239 | This variable can be set to either 'emacs' or 'vi'. |
7240 | ||
7241 | 'emacs-mode-string' | |
7242 | This string is displayed immediately before the last line of | |
7243 | the primary prompt when emacs editing mode is active. The | |
7244 | value is expanded like a key binding, so the standard set of | |
7245 | meta- and control prefixes and backslash escape sequences is | |
7246 | available. Use the '\1' and '\2' escapes to begin and end | |
7247 | sequences of non-printing characters, which can be used to | |
7248 | embed a terminal control sequence into the mode string. The | |
7249 | default is '@'. | |
7250 | ||
7251 | 'echo-control-characters' | |
7252 | When set to 'on', on operating systems that indicate they | |
a8fd3f3e | 7253 | support it, readline echoes a character corresponding to a |
8a0829e9 CR |
7254 | signal generated from the keyboard. The default is 'on'. |
7255 | ||
7256 | 'enable-bracketed-paste' | |
7257 | When set to 'On', Readline will configure the terminal in a | |
7258 | way that will enable it to insert each paste into the editing | |
7259 | buffer as a single string of characters, instead of treating | |
7260 | each character as if it had been read from the keyboard. This | |
7261 | can prevent pasted characters from being interpreted as | |
7262 | editing commands. The default is 'off'. | |
7263 | ||
7264 | 'enable-keypad' | |
7265 | When set to 'on', Readline will try to enable the application | |
ccc6cda3 | 7266 | keypad when it is called. Some systems need this to enable |
8a0829e9 | 7267 | the arrow keys. The default is 'off'. |
ccc6cda3 | 7268 | |
8a0829e9 CR |
7269 | 'enable-meta-key' |
7270 | When set to 'on', Readline will try to enable any meta | |
7271 | modifier key the terminal claims to support when it is called. | |
7272 | On many terminals, the meta key is used to send eight-bit | |
7273 | characters. The default is 'on'. | |
d5362af8 | 7274 | |
8a0829e9 CR |
7275 | 'expand-tilde' |
7276 | If set to 'on', tilde expansion is performed when Readline | |
7277 | attempts word completion. The default is 'off'. | |
ccc6cda3 | 7278 | |
8a0829e9 CR |
7279 | 'history-preserve-point' |
7280 | If set to 'on', the history code attempts to place the point | |
d7f49990 | 7281 | (the current cursor position) at the same location on each |
8a0829e9 CR |
7282 | history line retrieved with 'previous-history' or |
7283 | 'next-history'. The default is 'off'. | |
7284 | ||
7285 | 'history-size' | |
7286 | Set the maximum number of history entries saved in the history | |
7287 | list. If set to zero, any existing history entries are | |
7288 | deleted and no new entries are saved. If set to a value less | |
7289 | than zero, the number of history entries is not limited. By | |
7290 | default, the number of history entries is not limited. | |
7291 | ||
7292 | 'horizontal-scroll-mode' | |
7293 | This variable can be set to either 'on' or 'off'. Setting it | |
7294 | to 'on' means that the text of the lines being edited will | |
ccc6cda3 JA |
7295 | scroll horizontally on a single screen line when they are |
7296 | longer than the width of the screen, instead of wrapping onto | |
8a0829e9 | 7297 | a new screen line. By default, this variable is set to 'off'. |
ccc6cda3 | 7298 | |
8a0829e9 CR |
7299 | 'input-meta' |
7300 | If set to 'on', Readline will enable eight-bit input (it will | |
28ef6c31 | 7301 | not clear the eighth bit in the characters it reads), |
b72432fd | 7302 | regardless of what the terminal claims it can support. The |
8a0829e9 CR |
7303 | default value is 'off'. The name 'meta-flag' is a synonym for |
7304 | this variable. | |
b72432fd | 7305 | |
8a0829e9 | 7306 | 'isearch-terminators' |
b72432fd JA |
7307 | The string of characters that should terminate an incremental |
7308 | search without subsequently executing the character as a | |
28ef6c31 | 7309 | command (*note Searching::). If this variable has not been |
8a0829e9 | 7310 | given a value, the characters <ESC> and 'C-J' will terminate |
b72432fd JA |
7311 | an incremental search. |
7312 | ||
8a0829e9 | 7313 | 'keymap' |
ccc6cda3 | 7314 | Sets Readline's idea of the current keymap for key binding |
8a0829e9 CR |
7315 | commands. Acceptable 'keymap' names are 'emacs', |
7316 | 'emacs-standard', 'emacs-meta', 'emacs-ctlx', 'vi', 'vi-move', | |
7317 | 'vi-command', and 'vi-insert'. 'vi' is equivalent to | |
690150f9 CR |
7318 | 'vi-command' ('vi-move' is also a synonym); 'emacs' is |
7319 | equivalent to 'emacs-standard'. The default value is 'emacs'. | |
7320 | The value of the 'editing-mode' variable also affects the | |
7321 | default keymap. | |
ccc6cda3 | 7322 | |
8a0829e9 CR |
7323 | 'keyseq-timeout' |
7324 | Specifies the duration Readline will wait for a character when | |
7325 | reading an ambiguous key sequence (one that can form a | |
7326 | complete key sequence using the input read so far, or can take | |
7327 | additional input to complete a longer key sequence). If no | |
7328 | input is received within the timeout, Readline will use the | |
7329 | shorter but complete key sequence. Readline uses this value | |
7330 | to determine whether or not input is available on the current | |
7331 | input source ('rl_instream' by default). The value is | |
7332 | specified in milliseconds, so a value of 1000 means that | |
278286c9 CR |
7333 | Readline will wait one second for additional input. If this |
7334 | variable is set to a value less than or equal to zero, or to a | |
7335 | non-numeric value, Readline will wait until another key is | |
8a0829e9 CR |
7336 | pressed to decide which key sequence to complete. The default |
7337 | value is '500'. | |
278286c9 | 7338 | |
8a0829e9 CR |
7339 | 'mark-directories' |
7340 | If set to 'on', completed directory names have a slash | |
7341 | appended. The default is 'on'. | |
ccc6cda3 | 7342 | |
8a0829e9 CR |
7343 | 'mark-modified-lines' |
7344 | This variable, when set to 'on', causes Readline to display an | |
7345 | asterisk ('*') at the start of history lines which have been | |
7346 | modified. This variable is 'off' by default. | |
ccc6cda3 | 7347 | |
8a0829e9 CR |
7348 | 'mark-symlinked-directories' |
7349 | If set to 'on', completed names which are symbolic links to | |
7117c2d2 | 7350 | directories have a slash appended (subject to the value of |
8a0829e9 | 7351 | 'mark-directories'). The default is 'off'. |
7117c2d2 | 7352 | |
8a0829e9 CR |
7353 | 'match-hidden-files' |
7354 | This variable, when set to 'on', causes Readline to match | |
7355 | files whose names begin with a '.' (hidden files) when | |
7356 | performing filename completion. If set to 'off', the leading | |
7357 | '.' must be supplied by the user in the filename to be | |
7358 | completed. This variable is 'on' by default. | |
f73dda09 | 7359 | |
8a0829e9 CR |
7360 | 'menu-complete-display-prefix' |
7361 | If set to 'on', menu completion displays the common prefix of | |
e05be32d | 7362 | the list of possible completions (which may be empty) before |
8a0829e9 | 7363 | cycling through the list. The default is 'off'. |
e05be32d | 7364 | |
8a0829e9 CR |
7365 | 'output-meta' |
7366 | If set to 'on', Readline will display characters with the | |
ccc6cda3 | 7367 | eighth bit set directly rather than as a meta-prefixed escape |
8a0829e9 | 7368 | sequence. The default is 'off'. |
ccc6cda3 | 7369 | |
8a0829e9 CR |
7370 | 'page-completions' |
7371 | If set to 'on', Readline uses an internal 'more'-like pager to | |
7372 | display a screenful of possible completions at a time. This | |
7373 | variable is 'on' by default. | |
7117c2d2 | 7374 | |
8a0829e9 CR |
7375 | 'print-completions-horizontally' |
7376 | If set to 'on', Readline will display completions with matches | |
cce855bc | 7377 | sorted horizontally in alphabetical order, rather than down |
8a0829e9 | 7378 | the screen. The default is 'off'. |
cce855bc | 7379 | |
8a0829e9 CR |
7380 | 'revert-all-at-newline' |
7381 | If set to 'on', Readline will undo all changes to history | |
7382 | lines before returning when 'accept-line' is executed. By | |
ed35cb4a | 7383 | default, history lines may be modified and retain individual |
8a0829e9 | 7384 | undo lists across calls to 'readline'. The default is 'off'. |
ed35cb4a | 7385 | |
8a0829e9 | 7386 | 'show-all-if-ambiguous' |
ccc6cda3 | 7387 | This alters the default behavior of the completion functions. |
8a0829e9 | 7388 | If set to 'on', words which have more than one possible |
ccc6cda3 | 7389 | completion cause the matches to be listed immediately instead |
8a0829e9 | 7390 | of ringing the bell. The default value is 'off'. |
ccc6cda3 | 7391 | |
8a0829e9 | 7392 | 'show-all-if-unmodified' |
d3a24ed2 CR |
7393 | This alters the default behavior of the completion functions |
7394 | in a fashion similar to SHOW-ALL-IF-AMBIGUOUS. If set to | |
8a0829e9 | 7395 | 'on', words which have more than one possible completion |
d3a24ed2 CR |
7396 | without any possible partial completion (the possible |
7397 | completions don't share a common prefix) cause the matches to | |
7398 | be listed immediately instead of ringing the bell. The | |
8a0829e9 CR |
7399 | default value is 'off'. |
7400 | ||
7401 | 'show-mode-in-prompt' | |
7402 | If set to 'on', add a character to the beginning of the prompt | |
7403 | indicating the editing mode: emacs, vi command, or vi | |
7404 | insertion. The mode strings are user-settable. The default | |
7405 | value is 'off'. | |
7406 | ||
7407 | 'skip-completed-text' | |
7408 | If set to 'on', this alters the default completion behavior | |
7409 | when inserting a single match into the line. It's only active | |
7410 | when performing completion in the middle of a word. If | |
7411 | enabled, readline does not insert characters from the | |
7412 | completion that match characters after point in the word being | |
7413 | completed, so portions of the word following the cursor are | |
7414 | not duplicated. For instance, if this is enabled, attempting | |
7415 | completion when the cursor is after the 'e' in 'Makefile' will | |
7416 | result in 'Makefile' rather than 'Makefilefile', assuming | |
7417 | there is a single possible completion. The default value is | |
7418 | 'off'. | |
7419 | ||
7420 | 'vi-cmd-mode-string' | |
7421 | This string is displayed immediately before the last line of | |
7422 | the primary prompt when vi editing mode is active and in | |
7423 | command mode. The value is expanded like a key binding, so | |
7424 | the standard set of meta- and control prefixes and backslash | |
7425 | escape sequences is available. Use the '\1' and '\2' escapes | |
7426 | to begin and end sequences of non-printing characters, which | |
7427 | can be used to embed a terminal control sequence into the mode | |
7428 | string. The default is '(cmd)'. | |
7429 | ||
7430 | 'vi-ins-mode-string' | |
7431 | This string is displayed immediately before the last line of | |
7432 | the primary prompt when vi editing mode is active and in | |
7433 | insertion mode. The value is expanded like a key binding, so | |
7434 | the standard set of meta- and control prefixes and backslash | |
7435 | escape sequences is available. Use the '\1' and '\2' escapes | |
7436 | to begin and end sequences of non-printing characters, which | |
7437 | can be used to embed a terminal control sequence into the mode | |
7438 | string. The default is '(ins)'. | |
7439 | ||
7440 | 'visible-stats' | |
7441 | If set to 'on', a character denoting a file's type is appended | |
7442 | to the filename when listing possible completions. The | |
7443 | default is 'off'. | |
761783bf | 7444 | |
ccc6cda3 | 7445 | Key Bindings |
8a0829e9 CR |
7446 | The syntax for controlling key bindings in the init file is simple. |
7447 | First you need to find the name of the command that you want to | |
7448 | change. The following sections contain tables of the command name, | |
7449 | the default keybinding, if any, and a short description of what the | |
7450 | command does. | |
ccc6cda3 | 7451 | |
28ef6c31 JA |
7452 | Once you know the name of the command, simply place on a line in |
7453 | the init file the name of the key you wish to bind the command to, | |
d3ad40de CR |
7454 | a colon, and then the name of the command. There can be no space |
7455 | between the key name and the colon - that will be interpreted as | |
7456 | part of the key name. The name of the key can be expressed in | |
7457 | different ways, depending on what you find most comfortable. | |
28ef6c31 | 7458 | |
8a0829e9 CR |
7459 | In addition to command names, readline allows keys to be bound to a |
7460 | string that is inserted when the key is pressed (a MACRO). | |
ccc6cda3 | 7461 | |
8a0829e9 CR |
7462 | The 'bind -p' command displays Readline function names and bindings |
7463 | in a format that can put directly into an initialization file. | |
7464 | *Note Bash Builtins::. | |
bb70624e | 7465 | |
8a0829e9 | 7466 | KEYNAME: FUNCTION-NAME or MACRO |
ccc6cda3 JA |
7467 | KEYNAME is the name of a key spelled out in English. For |
7468 | example: | |
7469 | Control-u: universal-argument | |
7470 | Meta-Rubout: backward-kill-word | |
7471 | Control-o: "> output" | |
7472 | ||
8a0829e9 CR |
7473 | In the above example, 'C-u' is bound to the function |
7474 | 'universal-argument', 'M-DEL' is bound to the function | |
7475 | 'backward-kill-word', and 'C-o' is bound to run the macro | |
ccc6cda3 | 7476 | expressed on the right hand side (that is, to insert the text |
8a0829e9 | 7477 | '> output' into the line). |
ccc6cda3 | 7478 | |
28ef6c31 JA |
7479 | A number of symbolic character names are recognized while |
7480 | processing this key binding syntax: DEL, ESC, ESCAPE, LFD, | |
7481 | NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB. | |
7482 | ||
8a0829e9 | 7483 | "KEYSEQ": FUNCTION-NAME or MACRO |
ccc6cda3 JA |
7484 | KEYSEQ differs from KEYNAME above in that strings denoting an |
7485 | entire key sequence can be specified, by placing the key | |
7486 | sequence in double quotes. Some GNU Emacs style key escapes | |
7487 | can be used, as in the following example, but the special | |
7488 | character names are not recognized. | |
7489 | ||
7490 | "\C-u": universal-argument | |
7491 | "\C-x\C-r": re-read-init-file | |
7492 | "\e[11~": "Function Key 1" | |
7493 | ||
8a0829e9 CR |
7494 | In the above example, 'C-u' is again bound to the function |
7495 | 'universal-argument' (just as it was in the first example), | |
7496 | ''C-x' 'C-r'' is bound to the function 're-read-init-file', | |
7497 | and '<ESC> <[> <1> <1> <~>' is bound to insert the text | |
7498 | 'Function Key 1'. | |
761783bf | 7499 | |
cce855bc JA |
7500 | The following GNU Emacs style escape sequences are available when |
7501 | specifying key sequences: | |
7502 | ||
8a0829e9 | 7503 | '\C-' |
cce855bc | 7504 | control prefix |
8a0829e9 | 7505 | '\M-' |
cce855bc | 7506 | meta prefix |
8a0829e9 | 7507 | '\e' |
cce855bc | 7508 | an escape character |
8a0829e9 | 7509 | '\\' |
cce855bc | 7510 | backslash |
8a0829e9 | 7511 | '\"' |
bb70624e | 7512 | <">, a double quotation mark |
8a0829e9 | 7513 | '\'' |
bb70624e | 7514 | <'>, a single quote or apostrophe |
cce855bc JA |
7515 | |
7516 | In addition to the GNU Emacs style escape sequences, a second set | |
7517 | of backslash escapes is available: | |
ccc6cda3 | 7518 | |
8a0829e9 | 7519 | '\a' |
cce855bc | 7520 | alert (bell) |
8a0829e9 | 7521 | '\b' |
cce855bc | 7522 | backspace |
8a0829e9 | 7523 | '\d' |
cce855bc | 7524 | delete |
8a0829e9 | 7525 | '\f' |
cce855bc | 7526 | form feed |
8a0829e9 | 7527 | '\n' |
cce855bc | 7528 | newline |
8a0829e9 | 7529 | '\r' |
cce855bc | 7530 | carriage return |
8a0829e9 | 7531 | '\t' |
cce855bc | 7532 | horizontal tab |
8a0829e9 | 7533 | '\v' |
cce855bc | 7534 | vertical tab |
8a0829e9 | 7535 | '\NNN' |
f73dda09 | 7536 | the eight-bit character whose value is the octal value NNN |
cce855bc | 7537 | (one to three digits) |
8a0829e9 | 7538 | '\xHH' |
f73dda09 JA |
7539 | the eight-bit character whose value is the hexadecimal value |
7540 | HH (one or two hex digits) | |
7541 | ||
cce855bc JA |
7542 | When entering the text of a macro, single or double quotes must be |
7543 | used to indicate a macro definition. Unquoted text is assumed to | |
7544 | be a function name. In the macro body, the backslash escapes | |
7545 | described above are expanded. Backslash will quote any other | |
8a0829e9 CR |
7546 | character in the macro text, including '"' and '''. For example, |
7547 | the following binding will make ''C-x' \' insert a single '\' into | |
cce855bc JA |
7548 | the line: |
7549 | "\C-x\\": "\\" | |
ccc6cda3 JA |
7550 | |
7551 | \1f | |
7552 | File: bashref.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File | |
7553 | ||
37c41ab1 CR |
7554 | 8.3.2 Conditional Init Constructs |
7555 | --------------------------------- | |
ccc6cda3 | 7556 | |
37c41ab1 | 7557 | Readline implements a facility similar in spirit to the conditional |
8a0829e9 CR |
7558 | compilation features of the C preprocessor which allows key bindings and |
7559 | variable settings to be performed as the result of tests. There are | |
7560 | four parser directives used. | |
7561 | ||
7562 | '$if' | |
7563 | The '$if' construct allows bindings to be made based on the editing | |
7564 | mode, the terminal being used, or the application using Readline. | |
7565 | The text of the test extends to the end of the line; no characters | |
7566 | are required to isolate it. | |
7567 | ||
7568 | 'mode' | |
7569 | The 'mode=' form of the '$if' directive is used to test | |
7570 | whether Readline is in 'emacs' or 'vi' mode. This may be used | |
7571 | in conjunction with the 'set keymap' command, for instance, to | |
7572 | set bindings in the 'emacs-standard' and 'emacs-ctlx' keymaps | |
7573 | only if Readline is starting out in 'emacs' mode. | |
7574 | ||
7575 | 'term' | |
7576 | The 'term=' form may be used to include terminal-specific key | |
ccc6cda3 JA |
7577 | bindings, perhaps to bind the key sequences output by the |
7578 | terminal's function keys. The word on the right side of the | |
8a0829e9 CR |
7579 | '=' is tested against both the full name of the terminal and |
7580 | the portion of the terminal name before the first '-'. This | |
7581 | allows 'sun' to match both 'sun' and 'sun-cmd', for instance. | |
ccc6cda3 | 7582 | |
8a0829e9 | 7583 | 'application' |
ccc6cda3 JA |
7584 | The APPLICATION construct is used to include |
7585 | application-specific settings. Each program using the | |
7586 | Readline library sets the APPLICATION NAME, and you can test | |
28ef6c31 JA |
7587 | for a particular value. This could be used to bind key |
7588 | sequences to functions useful for a specific program. For | |
7589 | instance, the following command adds a key sequence that | |
7590 | quotes the current or previous word in Bash: | |
ccc6cda3 JA |
7591 | $if Bash |
7592 | # Quote the current or previous word | |
7593 | "\C-xq": "\eb\"\ef\"" | |
7594 | $endif | |
7595 | ||
8a0829e9 CR |
7596 | '$endif' |
7597 | This command, as seen in the previous example, terminates an '$if' | |
cce855bc | 7598 | command. |
ccc6cda3 | 7599 | |
8a0829e9 CR |
7600 | '$else' |
7601 | Commands in this branch of the '$if' directive are executed if the | |
ccc6cda3 JA |
7602 | test fails. |
7603 | ||
8a0829e9 | 7604 | '$include' |
cce855bc | 7605 | This directive takes a single filename as an argument and reads |
28ef6c31 | 7606 | commands and bindings from that file. For example, the following |
8a0829e9 | 7607 | directive reads from '/etc/inputrc': |
cce855bc JA |
7608 | $include /etc/inputrc |
7609 | ||
ccc6cda3 JA |
7610 | \1f |
7611 | File: bashref.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File | |
7612 | ||
37c41ab1 CR |
7613 | 8.3.3 Sample Init File |
7614 | ---------------------- | |
ccc6cda3 | 7615 | |
37c41ab1 CR |
7616 | Here is an example of an INPUTRC file. This illustrates key binding, |
7617 | variable assignment, and conditional syntax. | |
ccc6cda3 | 7618 | |
ccc6cda3 | 7619 | # This file controls the behaviour of line input editing for |
7117c2d2 JA |
7620 | # programs that use the GNU Readline library. Existing |
7621 | # programs include FTP, Bash, and GDB. | |
ccc6cda3 JA |
7622 | # |
7623 | # You can re-read the inputrc file with C-x C-r. | |
7624 | # Lines beginning with '#' are comments. | |
cce855bc | 7625 | # |
d76edd30 | 7626 | # First, include any system-wide bindings and variable |
7117c2d2 | 7627 | # assignments from /etc/Inputrc |
cce855bc | 7628 | $include /etc/Inputrc |
37c41ab1 | 7629 | |
ccc6cda3 JA |
7630 | # |
7631 | # Set various bindings for emacs mode. | |
37c41ab1 | 7632 | |
ccc6cda3 | 7633 | set editing-mode emacs |
37c41ab1 | 7634 | |
ccc6cda3 | 7635 | $if mode=emacs |
37c41ab1 | 7636 | |
ccc6cda3 | 7637 | Meta-Control-h: backward-kill-word Text after the function name is ignored |
37c41ab1 | 7638 | |
ccc6cda3 JA |
7639 | # |
7640 | # Arrow keys in keypad mode | |
7641 | # | |
d166f048 JA |
7642 | #"\M-OD": backward-char |
7643 | #"\M-OC": forward-char | |
7644 | #"\M-OA": previous-history | |
7645 | #"\M-OB": next-history | |
ccc6cda3 JA |
7646 | # |
7647 | # Arrow keys in ANSI mode | |
7648 | # | |
d166f048 JA |
7649 | "\M-[D": backward-char |
7650 | "\M-[C": forward-char | |
7651 | "\M-[A": previous-history | |
7652 | "\M-[B": next-history | |
ccc6cda3 JA |
7653 | # |
7654 | # Arrow keys in 8 bit keypad mode | |
7655 | # | |
d166f048 JA |
7656 | #"\M-\C-OD": backward-char |
7657 | #"\M-\C-OC": forward-char | |
7658 | #"\M-\C-OA": previous-history | |
7659 | #"\M-\C-OB": next-history | |
ccc6cda3 JA |
7660 | # |
7661 | # Arrow keys in 8 bit ANSI mode | |
7662 | # | |
d166f048 JA |
7663 | #"\M-\C-[D": backward-char |
7664 | #"\M-\C-[C": forward-char | |
7665 | #"\M-\C-[A": previous-history | |
7666 | #"\M-\C-[B": next-history | |
37c41ab1 | 7667 | |
ccc6cda3 | 7668 | C-q: quoted-insert |
37c41ab1 | 7669 | |
ccc6cda3 | 7670 | $endif |
37c41ab1 | 7671 | |
ccc6cda3 JA |
7672 | # An old-style binding. This happens to be the default. |
7673 | TAB: complete | |
37c41ab1 | 7674 | |
ccc6cda3 JA |
7675 | # Macros that are convenient for shell interaction |
7676 | $if Bash | |
7677 | # edit the path | |
7678 | "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f" | |
7117c2d2 JA |
7679 | # prepare to type a quoted word -- |
7680 | # insert open and close double quotes | |
ccc6cda3 JA |
7681 | # and move to just after the open quote |
7682 | "\C-x\"": "\"\"\C-b" | |
7117c2d2 JA |
7683 | # insert a backslash (testing backslash escapes |
7684 | # in sequences and macros) | |
ccc6cda3 JA |
7685 | "\C-x\\": "\\" |
7686 | # Quote the current or previous word | |
7687 | "\C-xq": "\eb\"\ef\"" | |
7688 | # Add a binding to refresh the line, which is unbound | |
7689 | "\C-xr": redraw-current-line | |
7690 | # Edit variable on current line. | |
7691 | "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y=" | |
7692 | $endif | |
37c41ab1 | 7693 | |
ccc6cda3 JA |
7694 | # use a visible bell if one is available |
7695 | set bell-style visible | |
37c41ab1 | 7696 | |
ccc6cda3 JA |
7697 | # don't strip characters to 7 bits when reading |
7698 | set input-meta on | |
37c41ab1 | 7699 | |
7117c2d2 JA |
7700 | # allow iso-latin1 characters to be inserted rather |
7701 | # than converted to prefix-meta sequences | |
ccc6cda3 | 7702 | set convert-meta off |
37c41ab1 | 7703 | |
7117c2d2 JA |
7704 | # display characters with the eighth bit set directly |
7705 | # rather than as meta-prefixed characters | |
ccc6cda3 | 7706 | set output-meta on |
37c41ab1 | 7707 | |
7117c2d2 JA |
7708 | # if there are more than 150 possible completions for |
7709 | # a word, ask the user if he wants to see all of them | |
ccc6cda3 | 7710 | set completion-query-items 150 |
37c41ab1 | 7711 | |
ccc6cda3 JA |
7712 | # For FTP |
7713 | $if Ftp | |
7714 | "\C-xg": "get \M-?" | |
7715 | "\C-xt": "put \M-?" | |
7716 | "\M-.": yank-last-arg | |
7717 | $endif | |
7718 | ||
7719 | \1f | |
bb70624e JA |
7720 | File: bashref.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing |
7721 | ||
37c41ab1 CR |
7722 | 8.4 Bindable Readline Commands |
7723 | ============================== | |
bb70624e JA |
7724 | |
7725 | * Menu: | |
7726 | ||
7727 | * Commands For Moving:: Moving about the line. | |
7728 | * Commands For History:: Getting at previous lines. | |
7729 | * Commands For Text:: Commands for changing text. | |
7730 | * Commands For Killing:: Commands for killing and yanking. | |
7731 | * Numeric Arguments:: Specifying numeric arguments, repeat counts. | |
7732 | * Commands For Completion:: Getting Readline to do the typing for you. | |
7733 | * Keyboard Macros:: Saving and re-executing typed characters | |
7734 | * Miscellaneous Commands:: Other miscellaneous commands. | |
7735 | ||
8a0829e9 CR |
7736 | This section describes Readline commands that may be bound to key |
7737 | sequences. You can list your key bindings by executing 'bind -P' or, | |
7738 | for a more terse format, suitable for an INPUTRC file, 'bind -p'. | |
28ef6c31 JA |
7739 | (*Note Bash Builtins::.) Command names without an accompanying key |
7740 | sequence are unbound by default. | |
bb70624e | 7741 | |
28ef6c31 | 7742 | In the following descriptions, "point" refers to the current cursor |
8a0829e9 CR |
7743 | position, and "mark" refers to a cursor position saved by the 'set-mark' |
7744 | command. The text between the point and mark is referred to as the | |
7745 | "region". | |
bb70624e JA |
7746 | |
7747 | \1f | |
7748 | File: bashref.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands | |
7749 | ||
37c41ab1 CR |
7750 | 8.4.1 Commands For Moving |
7751 | ------------------------- | |
bb70624e | 7752 | |
8a0829e9 | 7753 | 'beginning-of-line (C-a)' |
bb70624e JA |
7754 | Move to the start of the current line. |
7755 | ||
8a0829e9 | 7756 | 'end-of-line (C-e)' |
bb70624e JA |
7757 | Move to the end of the line. |
7758 | ||
8a0829e9 | 7759 | 'forward-char (C-f)' |
bb70624e JA |
7760 | Move forward a character. |
7761 | ||
8a0829e9 | 7762 | 'backward-char (C-b)' |
bb70624e JA |
7763 | Move back a character. |
7764 | ||
8a0829e9 | 7765 | 'forward-word (M-f)' |
bb70624e JA |
7766 | Move forward to the end of the next word. Words are composed of |
7767 | letters and digits. | |
7768 | ||
8a0829e9 | 7769 | 'backward-word (M-b)' |
bb70624e JA |
7770 | Move back to the start of the current or previous word. Words are |
7771 | composed of letters and digits. | |
7772 | ||
8a0829e9 | 7773 | 'shell-forward-word ()' |
a9fac3b2 CR |
7774 | Move forward to the end of the next word. Words are delimited by |
7775 | non-quoted shell metacharacters. | |
7776 | ||
8a0829e9 | 7777 | 'shell-backward-word ()' |
a9fac3b2 CR |
7778 | Move back to the start of the current or previous word. Words are |
7779 | delimited by non-quoted shell metacharacters. | |
7780 | ||
8a0829e9 | 7781 | 'clear-screen (C-l)' |
bb70624e JA |
7782 | Clear the screen and redraw the current line, leaving the current |
7783 | line at the top of the screen. | |
7784 | ||
8a0829e9 | 7785 | 'redraw-current-line ()' |
bb70624e JA |
7786 | Refresh the current line. By default, this is unbound. |
7787 | ||
7788 | \1f | |
7789 | File: bashref.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands | |
7790 | ||
37c41ab1 CR |
7791 | 8.4.2 Commands For Manipulating The History |
7792 | ------------------------------------------- | |
bb70624e | 7793 | |
8a0829e9 | 7794 | 'accept-line (Newline or Return)' |
bb70624e JA |
7795 | Accept the line regardless of where the cursor is. If this line is |
7796 | non-empty, add it to the history list according to the setting of | |
8a0829e9 | 7797 | the 'HISTCONTROL' and 'HISTIGNORE' variables. If this line is a |
28ef6c31 JA |
7798 | modified history line, then restore the history line to its |
7799 | original state. | |
bb70624e | 7800 | |
8a0829e9 CR |
7801 | 'previous-history (C-p)' |
7802 | Move 'back' through the history list, fetching the previous | |
28ef6c31 | 7803 | command. |
bb70624e | 7804 | |
8a0829e9 CR |
7805 | 'next-history (C-n)' |
7806 | Move 'forward' through the history list, fetching the next command. | |
bb70624e | 7807 | |
8a0829e9 | 7808 | 'beginning-of-history (M-<)' |
bb70624e JA |
7809 | Move to the first line in the history. |
7810 | ||
8a0829e9 | 7811 | 'end-of-history (M->)' |
bb70624e JA |
7812 | Move to the end of the input history, i.e., the line currently |
7813 | being entered. | |
7814 | ||
8a0829e9 CR |
7815 | 'reverse-search-history (C-r)' |
7816 | Search backward starting at the current line and moving 'up' | |
bb70624e JA |
7817 | through the history as necessary. This is an incremental search. |
7818 | ||
8a0829e9 CR |
7819 | 'forward-search-history (C-s)' |
7820 | Search forward starting at the current line and moving 'down' | |
fc527055 | 7821 | through the history as necessary. This is an incremental search. |
bb70624e | 7822 | |
8a0829e9 CR |
7823 | 'non-incremental-reverse-search-history (M-p)' |
7824 | Search backward starting at the current line and moving 'up' | |
7825 | through the history as necessary using a non-incremental search for | |
7826 | a string supplied by the user. The search string may match | |
fc527055 | 7827 | anywhere in a history line. |
bb70624e | 7828 | |
8a0829e9 CR |
7829 | 'non-incremental-forward-search-history (M-n)' |
7830 | Search forward starting at the current line and moving 'down' | |
7831 | through the history as necessary using a non-incremental search for | |
7832 | a string supplied by the user. The search string may match | |
fc527055 | 7833 | anywhere in a history line. |
bb70624e | 7834 | |
8a0829e9 | 7835 | 'history-search-forward ()' |
bb70624e | 7836 | Search forward through the history for the string of characters |
74d0116b CR |
7837 | between the start of the current line and the point. The search |
7838 | string must match at the beginning of a history line. This is a | |
bb70624e JA |
7839 | non-incremental search. By default, this command is unbound. |
7840 | ||
8a0829e9 | 7841 | 'history-search-backward ()' |
bb70624e | 7842 | Search backward through the history for the string of characters |
74d0116b CR |
7843 | between the start of the current line and the point. The search |
7844 | string must match at the beginning of a history line. This is a | |
7845 | non-incremental search. By default, this command is unbound. | |
7846 | ||
8a0829e9 | 7847 | 'history-substr-search-forward ()' |
74d0116b CR |
7848 | Search forward through the history for the string of characters |
7849 | between the start of the current line and the point. The search | |
7850 | string may match anywhere in a history line. This is a | |
7851 | non-incremental search. By default, this command is unbound. | |
7852 | ||
8a0829e9 | 7853 | 'history-substr-search-backward ()' |
74d0116b CR |
7854 | Search backward through the history for the string of characters |
7855 | between the start of the current line and the point. The search | |
7856 | string may match anywhere in a history line. This is a | |
bb70624e JA |
7857 | non-incremental search. By default, this command is unbound. |
7858 | ||
8a0829e9 | 7859 | 'yank-nth-arg (M-C-y)' |
bb70624e | 7860 | Insert the first argument to the previous command (usually the |
28ef6c31 JA |
7861 | second word on the previous line) at point. With an argument N, |
7862 | insert the Nth word from the previous command (the words in the | |
7863 | previous command begin with word 0). A negative argument inserts | |
eb2bb562 | 7864 | the Nth word from the end of the previous command. Once the |
8a0829e9 | 7865 | argument N is computed, the argument is extracted as if the '!N' |
eb2bb562 | 7866 | history expansion had been specified. |
bb70624e | 7867 | |
8a0829e9 | 7868 | 'yank-last-arg (M-. or M-_)' |
bb70624e | 7869 | Insert last argument to the previous command (the last word of the |
510e20a2 | 7870 | previous history entry). With a numeric argument, behave exactly |
8a0829e9 CR |
7871 | like 'yank-nth-arg'. Successive calls to 'yank-last-arg' move back |
7872 | through the history list, inserting the last word (or the word | |
7873 | specified by the argument to the first call) of each line in turn. | |
7874 | Any numeric argument supplied to these successive calls determines | |
7875 | the direction to move through the history. A negative argument | |
7876 | switches the direction through the history (back or forward). The | |
7877 | history expansion facilities are used to extract the last argument, | |
7878 | as if the '!$' history expansion had been specified. | |
761783bf | 7879 | |
bb70624e JA |
7880 | \1f |
7881 | File: bashref.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands | |
7882 | ||
37c41ab1 CR |
7883 | 8.4.3 Commands For Changing Text |
7884 | -------------------------------- | |
bb70624e | 7885 | |
8a0829e9 | 7886 | 'end-of-file (usually C-d)' |
c61bfbfd | 7887 | The character indicating end-of-file as set, for example, by |
8a0829e9 | 7888 | 'stty'. If this character is read when there are no characters on |
c61bfbfd CR |
7889 | the line, and point is at the beginning of the line, Readline |
7890 | interprets it as the end of input and returns EOF. | |
7891 | ||
8a0829e9 | 7892 | 'delete-char (C-d)' |
c61bfbfd | 7893 | Delete the character at point. If this function is bound to the |
8a0829e9 | 7894 | same character as the tty EOF character, as 'C-d' commonly is, see |
c61bfbfd | 7895 | above for the effects. |
bb70624e | 7896 | |
8a0829e9 | 7897 | 'backward-delete-char (Rubout)' |
bb70624e JA |
7898 | Delete the character behind the cursor. A numeric argument means |
7899 | to kill the characters instead of deleting them. | |
7900 | ||
8a0829e9 | 7901 | 'forward-backward-delete-char ()' |
bb70624e JA |
7902 | Delete the character under the cursor, unless the cursor is at the |
7903 | end of the line, in which case the character behind the cursor is | |
7904 | deleted. By default, this is not bound to a key. | |
7905 | ||
8a0829e9 | 7906 | 'quoted-insert (C-q or C-v)' |
bb70624e | 7907 | Add the next character typed to the line verbatim. This is how to |
8a0829e9 | 7908 | insert key sequences like 'C-q', for example. |
bb70624e | 7909 | |
8a0829e9 | 7910 | 'self-insert (a, b, A, 1, !, ...)' |
bb70624e JA |
7911 | Insert yourself. |
7912 | ||
8a0829e9 CR |
7913 | 'bracketed-paste-begin ()' |
7914 | This function is intended to be bound to the "bracketed paste" | |
7915 | escape sequence sent by some terminals, and such a binding is | |
7916 | assigned by default. It allows Readline to insert the pasted text | |
7917 | as a single unit without treating each character as if it had been | |
7918 | read from the keyboard. The characters are inserted as if each one | |
7919 | was bound to 'self-insert') instead of executing any editing | |
7920 | commands. | |
7921 | ||
7922 | 'transpose-chars (C-t)' | |
bb70624e JA |
7923 | Drag the character before the cursor forward over the character at |
7924 | the cursor, moving the cursor forward as well. If the insertion | |
7925 | point is at the end of the line, then this transposes the last two | |
7926 | characters of the line. Negative arguments have no effect. | |
7927 | ||
8a0829e9 | 7928 | 'transpose-words (M-t)' |
bb70624e | 7929 | Drag the word before point past the word after point, moving point |
f73dda09 JA |
7930 | past that word as well. If the insertion point is at the end of |
7931 | the line, this transposes the last two words on the line. | |
bb70624e | 7932 | |
8a0829e9 | 7933 | 'upcase-word (M-u)' |
bb70624e JA |
7934 | Uppercase the current (or following) word. With a negative |
7935 | argument, uppercase the previous word, but do not move the cursor. | |
7936 | ||
8a0829e9 | 7937 | 'downcase-word (M-l)' |
bb70624e JA |
7938 | Lowercase the current (or following) word. With a negative |
7939 | argument, lowercase the previous word, but do not move the cursor. | |
7940 | ||
8a0829e9 | 7941 | 'capitalize-word (M-c)' |
bb70624e JA |
7942 | Capitalize the current (or following) word. With a negative |
7943 | argument, capitalize the previous word, but do not move the cursor. | |
7944 | ||
8a0829e9 | 7945 | 'overwrite-mode ()' |
7117c2d2 JA |
7946 | Toggle overwrite mode. With an explicit positive numeric argument, |
7947 | switches to overwrite mode. With an explicit non-positive numeric | |
7948 | argument, switches to insert mode. This command affects only | |
8a0829e9 CR |
7949 | 'emacs' mode; 'vi' mode does overwrite differently. Each call to |
7950 | 'readline()' starts in insert mode. | |
7117c2d2 | 7951 | |
8a0829e9 | 7952 | In overwrite mode, characters bound to 'self-insert' replace the |
7117c2d2 | 7953 | text at point rather than pushing the text to the right. |
8a0829e9 | 7954 | Characters bound to 'backward-delete-char' replace the character |
7117c2d2 JA |
7955 | before point with a space. |
7956 | ||
7957 | By default, this command is unbound. | |
7958 | ||
bb70624e JA |
7959 | \1f |
7960 | File: bashref.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands | |
7961 | ||
37c41ab1 CR |
7962 | 8.4.4 Killing And Yanking |
7963 | ------------------------- | |
bb70624e | 7964 | |
8a0829e9 | 7965 | 'kill-line (C-k)' |
bb70624e JA |
7966 | Kill the text from point to the end of the line. |
7967 | ||
8a0829e9 | 7968 | 'backward-kill-line (C-x Rubout)' |
fc527055 | 7969 | Kill backward from the cursor to the beginning of the current line. |
bb70624e | 7970 | |
8a0829e9 | 7971 | 'unix-line-discard (C-u)' |
bb70624e JA |
7972 | Kill backward from the cursor to the beginning of the current line. |
7973 | ||
8a0829e9 | 7974 | 'kill-whole-line ()' |
28ef6c31 JA |
7975 | Kill all characters on the current line, no matter where point is. |
7976 | By default, this is unbound. | |
bb70624e | 7977 | |
8a0829e9 | 7978 | 'kill-word (M-d)' |
bb70624e JA |
7979 | Kill from point to the end of the current word, or if between |
7980 | words, to the end of the next word. Word boundaries are the same | |
8a0829e9 | 7981 | as 'forward-word'. |
bb70624e | 7982 | |
8a0829e9 | 7983 | 'backward-kill-word (M-<DEL>)' |
bb70624e | 7984 | Kill the word behind point. Word boundaries are the same as |
8a0829e9 | 7985 | 'backward-word'. |
bb70624e | 7986 | |
8a0829e9 | 7987 | 'shell-kill-word ()' |
a9fac3b2 CR |
7988 | Kill from point to the end of the current word, or if between |
7989 | words, to the end of the next word. Word boundaries are the same | |
8a0829e9 | 7990 | as 'shell-forward-word'. |
a9fac3b2 | 7991 | |
8a0829e9 | 7992 | 'shell-backward-kill-word ()' |
a9fac3b2 | 7993 | Kill the word behind point. Word boundaries are the same as |
8a0829e9 | 7994 | 'shell-backward-word'. |
a9fac3b2 | 7995 | |
8a0829e9 | 7996 | 'unix-word-rubout (C-w)' |
bb70624e JA |
7997 | Kill the word behind point, using white space as a word boundary. |
7998 | The killed text is saved on the kill-ring. | |
7999 | ||
8a0829e9 | 8000 | 'unix-filename-rubout ()' |
113d85a4 CR |
8001 | Kill the word behind point, using white space and the slash |
8002 | character as the word boundaries. The killed text is saved on the | |
8003 | kill-ring. | |
8004 | ||
8a0829e9 | 8005 | 'delete-horizontal-space ()' |
bb70624e JA |
8006 | Delete all spaces and tabs around point. By default, this is |
8007 | unbound. | |
8008 | ||
8a0829e9 | 8009 | 'kill-region ()' |
bb70624e JA |
8010 | Kill the text in the current region. By default, this command is |
8011 | unbound. | |
8012 | ||
8a0829e9 | 8013 | 'copy-region-as-kill ()' |
bb70624e JA |
8014 | Copy the text in the region to the kill buffer, so it can be yanked |
8015 | right away. By default, this command is unbound. | |
8016 | ||
8a0829e9 CR |
8017 | 'copy-backward-word ()' |
8018 | Copy the word before point to the kill buffer. The word boundaries | |
8019 | are the same as 'backward-word'. By default, this command is | |
8020 | unbound. | |
bb70624e | 8021 | |
8a0829e9 | 8022 | 'copy-forward-word ()' |
bb70624e | 8023 | Copy the word following point to the kill buffer. The word |
8a0829e9 | 8024 | boundaries are the same as 'forward-word'. By default, this |
bb70624e JA |
8025 | command is unbound. |
8026 | ||
8a0829e9 | 8027 | 'yank (C-y)' |
28ef6c31 | 8028 | Yank the top of the kill ring into the buffer at point. |
bb70624e | 8029 | |
8a0829e9 | 8030 | 'yank-pop (M-y)' |
bb70624e | 8031 | Rotate the kill-ring, and yank the new top. You can only do this |
8a0829e9 | 8032 | if the prior command is 'yank' or 'yank-pop'. |
bb70624e JA |
8033 | |
8034 | \1f | |
8035 | File: bashref.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands | |
8036 | ||
37c41ab1 CR |
8037 | 8.4.5 Specifying Numeric Arguments |
8038 | ---------------------------------- | |
bb70624e | 8039 | |
8a0829e9 | 8040 | 'digit-argument (M-0, M-1, ... M--)' |
bb70624e | 8041 | Add this digit to the argument already accumulating, or start a new |
8a0829e9 | 8042 | argument. 'M--' starts a negative argument. |
bb70624e | 8043 | |
8a0829e9 | 8044 | 'universal-argument ()' |
bb70624e JA |
8045 | This is another way to specify an argument. If this command is |
8046 | followed by one or more digits, optionally with a leading minus | |
8a0829e9 CR |
8047 | sign, those digits define the argument. If the command is followed |
8048 | by digits, executing 'universal-argument' again ends the numeric | |
8049 | argument, but is otherwise ignored. As a special case, if this | |
8050 | command is immediately followed by a character that is neither a | |
8051 | digit nor minus sign, the argument count for the next command is | |
8052 | multiplied by four. The argument count is initially one, so | |
8053 | executing this function the first time makes the argument count | |
8054 | four, a second time makes the argument count sixteen, and so on. | |
8055 | By default, this is not bound to a key. | |
bb70624e JA |
8056 | |
8057 | \1f | |
8058 | File: bashref.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands | |
8059 | ||
37c41ab1 CR |
8060 | 8.4.6 Letting Readline Type For You |
8061 | ----------------------------------- | |
bb70624e | 8062 | |
8a0829e9 CR |
8063 | 'complete (<TAB>)' |
8064 | Attempt to perform completion on the text before point. The actual | |
8065 | completion performed is application-specific. Bash attempts | |
8066 | completion treating the text as a variable (if the text begins with | |
8067 | '$'), username (if the text begins with '~'), hostname (if the text | |
8068 | begins with '@'), or command (including aliases and functions) in | |
8069 | turn. If none of these produces a match, filename completion is | |
8070 | attempted. | |
bb70624e | 8071 | |
8a0829e9 | 8072 | 'possible-completions (M-?)' |
eb0b2ad8 CR |
8073 | List the possible completions of the text before point. When |
8074 | displaying completions, Readline sets the number of columns used | |
8a0829e9 CR |
8075 | for display to the value of 'completion-display-width', the value |
8076 | of the environment variable 'COLUMNS', or the screen width, in that | |
8077 | order. | |
bb70624e | 8078 | |
8a0829e9 | 8079 | 'insert-completions (M-*)' |
bb70624e | 8080 | Insert all completions of the text before point that would have |
8a0829e9 | 8081 | been generated by 'possible-completions'. |
bb70624e | 8082 | |
8a0829e9 CR |
8083 | 'menu-complete ()' |
8084 | Similar to 'complete', but replaces the word to be completed with a | |
8085 | single match from the list of possible completions. Repeated | |
8086 | execution of 'menu-complete' steps through the list of possible | |
bb70624e | 8087 | completions, inserting each match in turn. At the end of the list |
28ef6c31 | 8088 | of completions, the bell is rung (subject to the setting of |
8a0829e9 | 8089 | 'bell-style') and the original text is restored. An argument of N |
28ef6c31 JA |
8090 | moves N positions forward in the list of matches; a negative |
8091 | argument may be used to move backward through the list. This | |
8092 | command is intended to be bound to <TAB>, but is unbound by | |
bb70624e JA |
8093 | default. |
8094 | ||
8a0829e9 CR |
8095 | 'menu-complete-backward ()' |
8096 | Identical to 'menu-complete', but moves backward through the list | |
8097 | of possible completions, as if 'menu-complete' had been given a | |
3eb2d94a CR |
8098 | negative argument. |
8099 | ||
8a0829e9 | 8100 | 'delete-char-or-list ()' |
bb70624e | 8101 | Deletes the character under the cursor if not at the beginning or |
8a0829e9 CR |
8102 | end of the line (like 'delete-char'). If at the end of the line, |
8103 | behaves identically to 'possible-completions'. This command is | |
bb70624e JA |
8104 | unbound by default. |
8105 | ||
8a0829e9 | 8106 | 'complete-filename (M-/)' |
bb70624e JA |
8107 | Attempt filename completion on the text before point. |
8108 | ||
8a0829e9 CR |
8109 | 'possible-filename-completions (C-x /)' |
8110 | List the possible completions of the text before point, treating it | |
8111 | as a filename. | |
bb70624e | 8112 | |
8a0829e9 | 8113 | 'complete-username (M-~)' |
bb70624e JA |
8114 | Attempt completion on the text before point, treating it as a |
8115 | username. | |
8116 | ||
8a0829e9 CR |
8117 | 'possible-username-completions (C-x ~)' |
8118 | List the possible completions of the text before point, treating it | |
8119 | as a username. | |
bb70624e | 8120 | |
8a0829e9 CR |
8121 | 'complete-variable (M-$)' |
8122 | Attempt completion on the text before point, treating it as a shell | |
8123 | variable. | |
bb70624e | 8124 | |
8a0829e9 CR |
8125 | 'possible-variable-completions (C-x $)' |
8126 | List the possible completions of the text before point, treating it | |
8127 | as a shell variable. | |
bb70624e | 8128 | |
8a0829e9 | 8129 | 'complete-hostname (M-@)' |
bb70624e JA |
8130 | Attempt completion on the text before point, treating it as a |
8131 | hostname. | |
8132 | ||
8a0829e9 CR |
8133 | 'possible-hostname-completions (C-x @)' |
8134 | List the possible completions of the text before point, treating it | |
8135 | as a hostname. | |
bb70624e | 8136 | |
8a0829e9 | 8137 | 'complete-command (M-!)' |
bb70624e JA |
8138 | Attempt completion on the text before point, treating it as a |
8139 | command name. Command completion attempts to match the text | |
8140 | against aliases, reserved words, shell functions, shell builtins, | |
8141 | and finally executable filenames, in that order. | |
8142 | ||
8a0829e9 CR |
8143 | 'possible-command-completions (C-x !)' |
8144 | List the possible completions of the text before point, treating it | |
8145 | as a command name. | |
bb70624e | 8146 | |
8a0829e9 | 8147 | 'dynamic-complete-history (M-<TAB>)' |
bb70624e JA |
8148 | Attempt completion on the text before point, comparing the text |
8149 | against lines from the history list for possible completion | |
8150 | matches. | |
8151 | ||
8a0829e9 | 8152 | 'dabbrev-expand ()' |
ed35cb4a CR |
8153 | Attempt menu completion on the text before point, comparing the |
8154 | text against lines from the history list for possible completion | |
8155 | matches. | |
8156 | ||
8a0829e9 | 8157 | 'complete-into-braces (M-{)' |
bb70624e JA |
8158 | Perform filename completion and insert the list of possible |
8159 | completions enclosed within braces so the list is available to the | |
28ef6c31 | 8160 | shell (*note Brace Expansion::). |
bb70624e JA |
8161 | |
8162 | \1f | |
8163 | File: bashref.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands | |
8164 | ||
37c41ab1 CR |
8165 | 8.4.7 Keyboard Macros |
8166 | --------------------- | |
bb70624e | 8167 | |
8a0829e9 | 8168 | 'start-kbd-macro (C-x ()' |
bb70624e JA |
8169 | Begin saving the characters typed into the current keyboard macro. |
8170 | ||
8a0829e9 | 8171 | 'end-kbd-macro (C-x ))' |
bb70624e JA |
8172 | Stop saving the characters typed into the current keyboard macro |
8173 | and save the definition. | |
8174 | ||
8a0829e9 | 8175 | 'call-last-kbd-macro (C-x e)' |
bb70624e JA |
8176 | Re-execute the last keyboard macro defined, by making the |
8177 | characters in the macro appear as if typed at the keyboard. | |
8178 | ||
8a0829e9 | 8179 | 'print-last-kbd-macro ()' |
45c0f7f8 CR |
8180 | Print the last keboard macro defined in a format suitable for the |
8181 | INPUTRC file. | |
8182 | ||
bb70624e JA |
8183 | \1f |
8184 | File: bashref.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands | |
8185 | ||
37c41ab1 CR |
8186 | 8.4.8 Some Miscellaneous Commands |
8187 | --------------------------------- | |
bb70624e | 8188 | |
8a0829e9 | 8189 | 're-read-init-file (C-x C-r)' |
bb70624e JA |
8190 | Read in the contents of the INPUTRC file, and incorporate any |
8191 | bindings or variable assignments found there. | |
8192 | ||
8a0829e9 | 8193 | 'abort (C-g)' |
bb70624e | 8194 | Abort the current editing command and ring the terminal's bell |
8a0829e9 | 8195 | (subject to the setting of 'bell-style'). |
bb70624e | 8196 | |
8a0829e9 | 8197 | 'do-uppercase-version (M-a, M-b, M-X, ...)' |
bb70624e JA |
8198 | If the metafied character X is lowercase, run the command that is |
8199 | bound to the corresponding uppercase character. | |
8200 | ||
8a0829e9 | 8201 | 'prefix-meta (<ESC>)' |
28ef6c31 | 8202 | Metafy the next character typed. This is for keyboards without a |
8a0829e9 | 8203 | meta key. Typing '<ESC> f' is equivalent to typing 'M-f'. |
bb70624e | 8204 | |
8a0829e9 | 8205 | 'undo (C-_ or C-x C-u)' |
bb70624e JA |
8206 | Incremental undo, separately remembered for each line. |
8207 | ||
8a0829e9 | 8208 | 'revert-line (M-r)' |
bb70624e | 8209 | Undo all changes made to this line. This is like executing the |
8a0829e9 | 8210 | 'undo' command enough times to get back to the beginning. |
bb70624e | 8211 | |
8a0829e9 | 8212 | 'tilde-expand (M-&)' |
bb70624e JA |
8213 | Perform tilde expansion on the current word. |
8214 | ||
8a0829e9 | 8215 | 'set-mark (C-@)' |
28ef6c31 JA |
8216 | Set the mark to the point. If a numeric argument is supplied, the |
8217 | mark is set to that position. | |
bb70624e | 8218 | |
8a0829e9 | 8219 | 'exchange-point-and-mark (C-x C-x)' |
bb70624e JA |
8220 | Swap the point with the mark. The current cursor position is set |
8221 | to the saved position, and the old cursor position is saved as the | |
8222 | mark. | |
8223 | ||
8a0829e9 | 8224 | 'character-search (C-])' |
bb70624e JA |
8225 | A character is read and point is moved to the next occurrence of |
8226 | that character. A negative count searches for previous | |
8227 | occurrences. | |
8228 | ||
8a0829e9 | 8229 | 'character-search-backward (M-C-])' |
bb70624e JA |
8230 | A character is read and point is moved to the previous occurrence |
8231 | of that character. A negative count searches for subsequent | |
8232 | occurrences. | |
8233 | ||
8a0829e9 | 8234 | 'skip-csi-sequence ()' |
8f714a7c CR |
8235 | Read enough characters to consume a multi-key sequence such as |
8236 | those defined for keys like Home and End. Such sequences begin | |
8237 | with a Control Sequence Indicator (CSI), usually ESC-[. If this | |
8a0829e9 CR |
8238 | sequence is bound to "\e[", keys producing such sequences will have |
8239 | no effect unless explicitly bound to a readline command, instead of | |
8240 | inserting stray characters into the editing buffer. This is | |
8241 | unbound by default, but usually bound to ESC-[. | |
8f714a7c | 8242 | |
8a0829e9 CR |
8243 | 'insert-comment (M-#)' |
8244 | Without a numeric argument, the value of the 'comment-begin' | |
7117c2d2 | 8245 | variable is inserted at the beginning of the current line. If a |
8a0829e9 CR |
8246 | numeric argument is supplied, this command acts as a toggle: if the |
8247 | characters at the beginning of the line do not match the value of | |
8248 | 'comment-begin', the value is inserted, otherwise the characters in | |
8249 | 'comment-begin' are deleted from the beginning of the line. In | |
8250 | either case, the line is accepted as if a newline had been typed. | |
8251 | The default value of 'comment-begin' causes this command to make | |
8252 | the current line a shell comment. If a numeric argument causes the | |
8253 | comment character to be removed, the line will be executed by the | |
8254 | shell. | |
8255 | ||
8256 | 'dump-functions ()' | |
bb70624e JA |
8257 | Print all of the functions and their key bindings to the Readline |
8258 | output stream. If a numeric argument is supplied, the output is | |
8259 | formatted in such a way that it can be made part of an INPUTRC | |
8260 | file. This command is unbound by default. | |
8261 | ||
8a0829e9 | 8262 | 'dump-variables ()' |
bb70624e JA |
8263 | Print all of the settable variables and their values to the |
8264 | Readline output stream. If a numeric argument is supplied, the | |
8265 | output is formatted in such a way that it can be made part of an | |
8266 | INPUTRC file. This command is unbound by default. | |
8267 | ||
8a0829e9 | 8268 | 'dump-macros ()' |
bb70624e | 8269 | Print all of the Readline key sequences bound to macros and the |
8a0829e9 CR |
8270 | strings they output. If a numeric argument is supplied, the output |
8271 | is formatted in such a way that it can be made part of an INPUTRC | |
8272 | file. This command is unbound by default. | |
bb70624e | 8273 | |
8a0829e9 | 8274 | 'glob-complete-word (M-g)' |
7117c2d2 JA |
8275 | The word before point is treated as a pattern for pathname |
8276 | expansion, with an asterisk implicitly appended. This pattern is | |
8277 | used to generate a list of matching file names for possible | |
8278 | completions. | |
8279 | ||
8a0829e9 | 8280 | 'glob-expand-word (C-x *)' |
bb70624e JA |
8281 | The word before point is treated as a pattern for pathname |
8282 | expansion, and the list of matching file names is inserted, | |
8a0829e9 | 8283 | replacing the word. If a numeric argument is supplied, a '*' is |
7117c2d2 | 8284 | appended before pathname expansion. |
bb70624e | 8285 | |
8a0829e9 | 8286 | 'glob-list-expansions (C-x g)' |
bb70624e | 8287 | The list of expansions that would have been generated by |
8a0829e9 CR |
8288 | 'glob-expand-word' is displayed, and the line is redrawn. If a |
8289 | numeric argument is supplied, a '*' is appended before pathname | |
7117c2d2 | 8290 | expansion. |
bb70624e | 8291 | |
8a0829e9 | 8292 | 'display-shell-version (C-x C-v)' |
bb70624e JA |
8293 | Display version information about the current instance of Bash. |
8294 | ||
8a0829e9 CR |
8295 | 'shell-expand-line (M-C-e)' |
8296 | Expand the line as the shell does. This performs alias and history | |
8297 | expansion as well as all of the shell word expansions (*note Shell | |
8298 | Expansions::). | |
bb70624e | 8299 | |
8a0829e9 | 8300 | 'history-expand-line (M-^)' |
bb70624e JA |
8301 | Perform history expansion on the current line. |
8302 | ||
8a0829e9 | 8303 | 'magic-space ()' |
bb70624e | 8304 | Perform history expansion on the current line and insert a space |
28ef6c31 | 8305 | (*note History Interaction::). |
bb70624e | 8306 | |
8a0829e9 | 8307 | 'alias-expand-line ()' |
28ef6c31 | 8308 | Perform alias expansion on the current line (*note Aliases::). |
bb70624e | 8309 | |
8a0829e9 | 8310 | 'history-and-alias-expand-line ()' |
bb70624e JA |
8311 | Perform history and alias expansion on the current line. |
8312 | ||
8a0829e9 CR |
8313 | 'insert-last-argument (M-. or M-_)' |
8314 | A synonym for 'yank-last-arg'. | |
bb70624e | 8315 | |
8a0829e9 | 8316 | 'operate-and-get-next (C-o)' |
bb70624e JA |
8317 | Accept the current line for execution and fetch the next line |
8318 | relative to the current line from the history for editing. Any | |
8319 | argument is ignored. | |
8320 | ||
8a0829e9 | 8321 | 'edit-and-execute-command (C-xC-e)' |
7117c2d2 | 8322 | Invoke an editor on the current command line, and execute the |
8a0829e9 CR |
8323 | result as shell commands. Bash attempts to invoke '$VISUAL', |
8324 | '$EDITOR', and 'emacs' as the editor, in that order. | |
761783bf | 8325 | |
bb70624e JA |
8326 | \1f |
8327 | File: bashref.info, Node: Readline vi Mode, Next: Programmable Completion, Prev: Bindable Readline Commands, Up: Command Line Editing | |
8328 | ||
37c41ab1 CR |
8329 | 8.5 Readline vi Mode |
8330 | ==================== | |
bb70624e | 8331 | |
8a0829e9 | 8332 | While the Readline library does not have a full set of 'vi' editing |
bb70624e | 8333 | functions, it does contain enough to allow simple editing of the line. |
8a0829e9 | 8334 | The Readline 'vi' mode behaves as specified in the POSIX standard. |
bb70624e | 8335 | |
8a0829e9 CR |
8336 | In order to switch interactively between 'emacs' and 'vi' editing |
8337 | modes, use the 'set -o emacs' and 'set -o vi' commands (*note The Set | |
8338 | Builtin::). The Readline default is 'emacs' mode. | |
bb70624e | 8339 | |
8a0829e9 CR |
8340 | When you enter a line in 'vi' mode, you are already placed in |
8341 | 'insertion' mode, as if you had typed an 'i'. Pressing <ESC> switches | |
8342 | you into 'command' mode, where you can edit the text of the line with | |
8343 | the standard 'vi' movement keys, move to previous history lines with 'k' | |
8344 | and subsequent lines with 'j', and so forth. | |
bb70624e JA |
8345 | |
8346 | \1f | |
8347 | File: bashref.info, Node: Programmable Completion, Next: Programmable Completion Builtins, Prev: Readline vi Mode, Up: Command Line Editing | |
8348 | ||
37c41ab1 CR |
8349 | 8.6 Programmable Completion |
8350 | =========================== | |
bb70624e | 8351 | |
8a0829e9 CR |
8352 | When word completion is attempted for an argument to a command for which |
8353 | a completion specification (a COMPSPEC) has been defined using the | |
8354 | 'complete' builtin (*note Programmable Completion Builtins::), the | |
bb70624e JA |
8355 | programmable completion facilities are invoked. |
8356 | ||
8357 | First, the command name is identified. If a compspec has been | |
8358 | defined for that command, the compspec is used to generate the list of | |
8f714a7c CR |
8359 | possible completions for the word. If the command word is the empty |
8360 | string (completion attempted at the beginning of an empty line), any | |
8a0829e9 | 8361 | compspec defined with the '-E' option to 'complete' is used. If the |
8f714a7c CR |
8362 | command word is a full pathname, a compspec for the full pathname is |
8363 | searched for first. If no compspec is found for the full pathname, an | |
8364 | attempt is made to find a compspec for the portion following the final | |
8365 | slash. If those searches do not result in a compspec, any compspec | |
8a0829e9 | 8366 | defined with the '-D' option to 'complete' is used as the default. |
bb70624e JA |
8367 | |
8368 | Once a compspec has been found, it is used to generate the list of | |
8369 | matching words. If a compspec is not found, the default Bash completion | |
28ef6c31 | 8370 | described above (*note Commands For Completion::) is performed. |
bb70624e JA |
8371 | |
8372 | First, the actions specified by the compspec are used. Only matches | |
8373 | which are prefixed by the word being completed are returned. When the | |
8a0829e9 CR |
8374 | '-f' or '-d' option is used for filename or directory name completion, |
8375 | the shell variable 'FIGNORE' is used to filter the matches. *Note Bash | |
8376 | Variables::, for a description of 'FIGNORE'. | |
8377 | ||
8378 | Any completions specified by a filename expansion pattern to the '-G' | |
8379 | option are generated next. The words generated by the pattern need not | |
8380 | match the word being completed. The 'GLOBIGNORE' shell variable is not | |
8381 | used to filter the matches, but the 'FIGNORE' shell variable is used. | |
8382 | ||
8383 | Next, the string specified as the argument to the '-W' option is | |
8384 | considered. The string is first split using the characters in the 'IFS' | |
8385 | special variable as delimiters. Shell quoting is honored. Each word is | |
8386 | then expanded using brace expansion, tilde expansion, parameter and | |
2206f89a | 8387 | variable expansion, command substitution, and arithmetic expansion, as |
8a0829e9 CR |
8388 | described above (*note Shell Expansions::). The results are split using |
8389 | the rules described above (*note Word Splitting::). The results of the | |
8390 | expansion are prefix-matched against the word being completed, and the | |
8391 | matching words become the possible completions. | |
bb70624e JA |
8392 | |
8393 | After these matches have been generated, any shell function or | |
8a0829e9 CR |
8394 | command specified with the '-F' and '-C' options is invoked. When the |
8395 | command or function is invoked, the 'COMP_LINE', 'COMP_POINT', | |
8396 | 'COMP_KEY', and 'COMP_TYPE' variables are assigned values as described | |
d3ad40de | 8397 | above (*note Bash Variables::). If a shell function is being invoked, |
8a0829e9 | 8398 | the 'COMP_WORDS' and 'COMP_CWORD' variables are also set. When the |
45c0f7f8 CR |
8399 | function or command is invoked, the first argument ($1) is the name of |
8400 | the command whose arguments are being completed, the second argument | |
8401 | ($2) is the word being completed, and the third argument ($3) is the | |
8a0829e9 CR |
8402 | word preceding the word being completed on the current command line. No |
8403 | filtering of the generated completions against the word being completed | |
8404 | is performed; the function or command has complete freedom in generating | |
8405 | the matches. | |
bb70624e | 8406 | |
8a0829e9 CR |
8407 | Any function specified with '-F' is invoked first. The function may |
8408 | use any of the shell facilities, including the 'compgen' and 'compopt' | |
6a8fd0ed CR |
8409 | builtins described below (*note Programmable Completion Builtins::), to |
8410 | generate the matches. It must put the possible completions in the | |
8a0829e9 | 8411 | 'COMPREPLY' array variable, one per array element. |
bb70624e | 8412 | |
8a0829e9 | 8413 | Next, any command specified with the '-C' option is invoked in an |
bb70624e JA |
8414 | environment equivalent to command substitution. It should print a list |
8415 | of completions, one per line, to the standard output. Backslash may be | |
8416 | used to escape a newline, if necessary. | |
8417 | ||
8418 | After all of the possible completions are generated, any filter | |
8a0829e9 CR |
8419 | specified with the '-X' option is applied to the list. The filter is a |
8420 | pattern as used for pathname expansion; a '&' in the pattern is replaced | |
8421 | with the text of the word being completed. A literal '&' may be escaped | |
8422 | with a backslash; the backslash is removed before attempting a match. | |
8423 | Any completion that matches the pattern will be removed from the list. | |
8424 | A leading '!' negates the pattern; in this case any completion not | |
8425 | matching the pattern will be removed. If the 'nocasematch' shell option | |
8426 | (see the description of 'shopt' in *note The Shopt Builtin::) is | |
8427 | enabled, the match is performed without regard to the case of alphabetic | |
8428 | characters. | |
8429 | ||
8430 | Finally, any prefix and suffix specified with the '-P' and '-S' | |
bb70624e JA |
8431 | options are added to each member of the completion list, and the result |
8432 | is returned to the Readline completion code as the list of possible | |
8433 | completions. | |
8434 | ||
28ef6c31 | 8435 | If the previously-applied actions do not generate any matches, and |
8a0829e9 | 8436 | the '-o dirnames' option was supplied to 'complete' when the compspec |
28ef6c31 JA |
8437 | was defined, directory name completion is attempted. |
8438 | ||
8a0829e9 | 8439 | If the '-o plusdirs' option was supplied to 'complete' when the |
d3a24ed2 CR |
8440 | compspec was defined, directory name completion is attempted and any |
8441 | matches are added to the results of the other actions. | |
8442 | ||
8a0829e9 CR |
8443 | By default, if a compspec is found, whatever it generates is returned |
8444 | to the completion code as the full set of possible completions. The | |
8445 | default Bash completions are not attempted, and the Readline default of | |
8446 | filename completion is disabled. If the '-o bashdefault' option was | |
8447 | supplied to 'complete' when the compspec was defined, the default Bash | |
d3a24ed2 | 8448 | completions are attempted if the compspec generates no matches. If the |
8a0829e9 CR |
8449 | '-o default' option was supplied to 'complete' when the compspec was |
8450 | defined, Readline's default completion will be performed if the compspec | |
8451 | (and, if attempted, the default Bash completions) generate no matches. | |
bb70624e | 8452 | |
7117c2d2 JA |
8453 | When a compspec indicates that directory name completion is desired, |
8454 | the programmable completion functions force Readline to append a slash | |
8455 | to completed names which are symbolic links to directories, subject to | |
8456 | the value of the MARK-DIRECTORIES Readline variable, regardless of the | |
8457 | setting of the MARK-SYMLINKED-DIRECTORIES Readline variable. | |
8458 | ||
8f714a7c CR |
8459 | There is some support for dynamically modifying completions. This is |
8460 | most useful when used in combination with a default completion specified | |
8a0829e9 | 8461 | with '-D'. It's possible for shell functions executed as completion |
8f714a7c CR |
8462 | handlers to indicate that completion should be retried by returning an |
8463 | exit status of 124. If a shell function returns 124, and changes the | |
8464 | compspec associated with the command on which completion is being | |
8465 | attempted (supplied as the first argument when the function is | |
8466 | executed), programmable completion restarts from the beginning, with an | |
eb0b2ad8 | 8467 | attempt to find a new compspec for that command. This allows a set of |
8f714a7c CR |
8468 | completions to be built dynamically as completion is attempted, rather |
8469 | than being loaded all at once. | |
8470 | ||
8471 | For instance, assuming that there is a library of compspecs, each | |
8472 | kept in a file corresponding to the name of the command, the following | |
8473 | default completion function would load completions dynamically: | |
8474 | ||
8475 | _completion_loader() | |
8476 | { | |
45c0f7f8 | 8477 | . "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124 |
8f714a7c | 8478 | } |
1101193a | 8479 | complete -D -F _completion_loader -o bashdefault -o default |
8f714a7c | 8480 | |
bb70624e | 8481 | \1f |
45c0f7f8 | 8482 | File: bashref.info, Node: Programmable Completion Builtins, Next: A Programmable Completion Example, Prev: Programmable Completion, Up: Command Line Editing |
bb70624e | 8483 | |
37c41ab1 CR |
8484 | 8.7 Programmable Completion Builtins |
8485 | ==================================== | |
bb70624e | 8486 | |
45c0f7f8 CR |
8487 | Three builtin commands are available to manipulate the programmable |
8488 | completion facilities: one to specify how the arguments to a particular | |
8489 | command are to be completed, and two to modify the completion as it is | |
8490 | happening. | |
bb70624e | 8491 | |
8a0829e9 CR |
8492 | 'compgen' |
8493 | compgen [OPTION] [WORD] | |
bb70624e JA |
8494 | |
8495 | Generate possible completion matches for WORD according to the | |
8a0829e9 CR |
8496 | OPTIONs, which may be any option accepted by the 'complete' builtin |
8497 | with the exception of '-p' and '-r', and write the matches to the | |
8498 | standard output. When using the '-F' or '-C' options, the various | |
8499 | shell variables set by the programmable completion facilities, | |
8500 | while available, will not have useful values. | |
bb70624e JA |
8501 | |
8502 | The matches will be generated in the same way as if the | |
8503 | programmable completion code had generated them directly from a | |
8504 | completion specification with the same flags. If WORD is | |
8505 | specified, only those completions matching WORD will be displayed. | |
8506 | ||
8507 | The return value is true unless an invalid option is supplied, or | |
8508 | no matches were generated. | |
8509 | ||
8a0829e9 CR |
8510 | 'complete' |
8511 | complete [-abcdefgjksuv] [-o COMP-OPTION] [-DE] [-A ACTION] [-G GLOBPAT] [-W WORDLIST] | |
d3ad40de | 8512 | [-F FUNCTION] [-C COMMAND] [-X FILTERPAT] |
8a0829e9 CR |
8513 | [-P PREFIX] [-S SUFFIX] NAME [NAME ...] |
8514 | complete -pr [-DE] [NAME ...] | |
bb70624e JA |
8515 | |
8516 | Specify how arguments to each NAME should be completed. If the | |
8a0829e9 | 8517 | '-p' option is supplied, or if no options are supplied, existing |
bb70624e | 8518 | completion specifications are printed in a way that allows them to |
8a0829e9 | 8519 | be reused as input. The '-r' option removes a completion |
bb70624e | 8520 | specification for each NAME, or, if no NAMEs are supplied, all |
8a0829e9 CR |
8521 | completion specifications. The '-D' option indicates that the |
8522 | remaining options and actions should apply to the "default" command | |
8523 | completion; that is, completion attempted on a command for which no | |
8524 | completion has previously been defined. The '-E' option indicates | |
8525 | that the remaining options and actions should apply to "empty" | |
8526 | command completion; that is, completion attempted on a blank line. | |
bb70624e JA |
8527 | |
8528 | The process of applying these completion specifications when word | |
8529 | completion is attempted is described above (*note Programmable | |
8a0829e9 | 8530 | Completion::). The '-D' option takes precedence over '-E'. |
bb70624e JA |
8531 | |
8532 | Other options, if specified, have the following meanings. The | |
8a0829e9 CR |
8533 | arguments to the '-G', '-W', and '-X' options (and, if necessary, |
8534 | the '-P' and '-S' options) should be quoted to protect them from | |
8535 | expansion before the 'complete' builtin is invoked. | |
bb70624e | 8536 | |
8a0829e9 | 8537 | '-o COMP-OPTION' |
28ef6c31 JA |
8538 | The COMP-OPTION controls several aspects of the compspec's |
8539 | behavior beyond the simple generation of completions. | |
8540 | COMP-OPTION may be one of: | |
8541 | ||
8a0829e9 | 8542 | 'bashdefault' |
d3a24ed2 CR |
8543 | Perform the rest of the default Bash completions if the |
8544 | compspec generates no matches. | |
8545 | ||
8a0829e9 | 8546 | 'default' |
7117c2d2 JA |
8547 | Use Readline's default filename completion if the |
8548 | compspec generates no matches. | |
28ef6c31 | 8549 | |
8a0829e9 | 8550 | 'dirnames' |
28ef6c31 JA |
8551 | Perform directory name completion if the compspec |
8552 | generates no matches. | |
8553 | ||
8a0829e9 | 8554 | 'filenames' |
28ef6c31 | 8555 | Tell Readline that the compspec generates filenames, so |
d3a24ed2 | 8556 | it can perform any filename-specific processing (like |
a9fac3b2 | 8557 | adding a slash to directory names quoting special |
8a0829e9 CR |
8558 | characters, or suppressing trailing spaces). This option |
8559 | is intended to be used with shell functions specified | |
8560 | with '-F'. | |
28ef6c31 | 8561 | |
8a0829e9 | 8562 | 'noquote' |
45c0f7f8 CR |
8563 | Tell Readline not to quote the completed words if they |
8564 | are filenames (quoting filenames is the default). | |
8565 | ||
8a0829e9 CR |
8566 | 'nosort' |
8567 | Tell Readline not to sort the list of possible | |
8568 | completions alphabetically. | |
8569 | ||
8570 | 'nospace' | |
7117c2d2 JA |
8571 | Tell Readline not to append a space (the default) to |
8572 | words completed at the end of the line. | |
8573 | ||
8a0829e9 | 8574 | 'plusdirs' |
22e63b05 CR |
8575 | After any matches defined by the compspec are generated, |
8576 | directory name completion is attempted and any matches | |
8577 | are added to the results of the other actions. | |
8578 | ||
8a0829e9 | 8579 | '-A ACTION' |
bb70624e JA |
8580 | The ACTION may be one of the following to generate a list of |
8581 | possible completions: | |
8582 | ||
8a0829e9 CR |
8583 | 'alias' |
8584 | Alias names. May also be specified as '-a'. | |
bb70624e | 8585 | |
8a0829e9 | 8586 | 'arrayvar' |
bb70624e JA |
8587 | Array variable names. |
8588 | ||
8a0829e9 | 8589 | 'binding' |
bb70624e | 8590 | Readline key binding names (*note Bindable Readline |
28ef6c31 | 8591 | Commands::). |
bb70624e | 8592 | |
8a0829e9 | 8593 | 'builtin' |
bb70624e | 8594 | Names of shell builtin commands. May also be specified |
8a0829e9 | 8595 | as '-b'. |
bb70624e | 8596 | |
8a0829e9 CR |
8597 | 'command' |
8598 | Command names. May also be specified as '-c'. | |
bb70624e | 8599 | |
8a0829e9 CR |
8600 | 'directory' |
8601 | Directory names. May also be specified as '-d'. | |
bb70624e | 8602 | |
8a0829e9 | 8603 | 'disabled' |
bb70624e JA |
8604 | Names of disabled shell builtins. |
8605 | ||
8a0829e9 | 8606 | 'enabled' |
bb70624e JA |
8607 | Names of enabled shell builtins. |
8608 | ||
8a0829e9 CR |
8609 | 'export' |
8610 | Names of exported shell variables. May also be specified | |
8611 | as '-e'. | |
bb70624e | 8612 | |
8a0829e9 CR |
8613 | 'file' |
8614 | File names. May also be specified as '-f'. | |
bb70624e | 8615 | |
8a0829e9 | 8616 | 'function' |
bb70624e JA |
8617 | Names of shell functions. |
8618 | ||
8a0829e9 CR |
8619 | 'group' |
8620 | Group names. May also be specified as '-g'. | |
f73dda09 | 8621 | |
8a0829e9 CR |
8622 | 'helptopic' |
8623 | Help topics as accepted by the 'help' builtin (*note Bash | |
8624 | Builtins::). | |
bb70624e | 8625 | |
8a0829e9 | 8626 | 'hostname' |
bb70624e | 8627 | Hostnames, as taken from the file specified by the |
8a0829e9 | 8628 | 'HOSTFILE' shell variable (*note Bash Variables::). |
bb70624e | 8629 | |
8a0829e9 | 8630 | 'job' |
bb70624e | 8631 | Job names, if job control is active. May also be |
8a0829e9 | 8632 | specified as '-j'. |
bb70624e | 8633 | |
8a0829e9 CR |
8634 | 'keyword' |
8635 | Shell reserved words. May also be specified as '-k'. | |
bb70624e | 8636 | |
8a0829e9 | 8637 | 'running' |
bb70624e JA |
8638 | Names of running jobs, if job control is active. |
8639 | ||
8a0829e9 CR |
8640 | 'service' |
8641 | Service names. May also be specified as '-s'. | |
7117c2d2 | 8642 | |
8a0829e9 CR |
8643 | 'setopt' |
8644 | Valid arguments for the '-o' option to the 'set' builtin | |
28ef6c31 | 8645 | (*note The Set Builtin::). |
bb70624e | 8646 | |
8a0829e9 CR |
8647 | 'shopt' |
8648 | Shell option names as accepted by the 'shopt' builtin | |
28ef6c31 | 8649 | (*note Bash Builtins::). |
bb70624e | 8650 | |
8a0829e9 | 8651 | 'signal' |
bb70624e JA |
8652 | Signal names. |
8653 | ||
8a0829e9 | 8654 | 'stopped' |
bb70624e JA |
8655 | Names of stopped jobs, if job control is active. |
8656 | ||
8a0829e9 CR |
8657 | 'user' |
8658 | User names. May also be specified as '-u'. | |
bb70624e | 8659 | |
8a0829e9 | 8660 | 'variable' |
bb70624e | 8661 | Names of all shell variables. May also be specified as |
8a0829e9 | 8662 | '-v'. |
bb70624e | 8663 | |
8a0829e9 | 8664 | '-C COMMAND' |
bb70624e JA |
8665 | COMMAND is executed in a subshell environment, and its output |
8666 | is used as the possible completions. | |
8667 | ||
8a0829e9 | 8668 | '-F FUNCTION' |
bb70624e | 8669 | The shell function FUNCTION is executed in the current shell |
45c0f7f8 CR |
8670 | environment. When it is executed, $1 is the name of the |
8671 | command whose arguments are being completed, $2 is the word | |
8672 | being completed, and $3 is the word preceding the word being | |
8673 | completed, as described above (*note Programmable | |
8a0829e9 CR |
8674 | Completion::). When it finishes, the possible completions are |
8675 | retrieved from the value of the 'COMPREPLY' array variable. | |
bb70624e | 8676 | |
8a0829e9 | 8677 | '-G GLOBPAT' |
5cdaaf76 CR |
8678 | The filename expansion pattern GLOBPAT is expanded to generate |
8679 | the possible completions. | |
bb70624e | 8680 | |
8a0829e9 | 8681 | '-P PREFIX' |
bb70624e JA |
8682 | PREFIX is added at the beginning of each possible completion |
8683 | after all other options have been applied. | |
8684 | ||
8a0829e9 CR |
8685 | '-S SUFFIX' |
8686 | SUFFIX is appended to each possible completion after all other | |
8687 | options have been applied. | |
bb70624e | 8688 | |
8a0829e9 CR |
8689 | '-W WORDLIST' |
8690 | The WORDLIST is split using the characters in the 'IFS' | |
5cdaaf76 CR |
8691 | special variable as delimiters, and each resultant word is |
8692 | expanded. The possible completions are the members of the | |
8693 | resultant list which match the word being completed. | |
8694 | ||
8a0829e9 | 8695 | '-X FILTERPAT' |
5cdaaf76 CR |
8696 | FILTERPAT is a pattern as used for filename expansion. It is |
8697 | applied to the list of possible completions generated by the | |
8698 | preceding options and arguments, and each completion matching | |
8a0829e9 | 8699 | FILTERPAT is removed from the list. A leading '!' in |
5cdaaf76 CR |
8700 | FILTERPAT negates the pattern; in this case, any completion |
8701 | not matching FILTERPAT is removed. | |
8702 | ||
bb70624e | 8703 | The return value is true unless an invalid option is supplied, an |
8a0829e9 CR |
8704 | option other than '-p' or '-r' is supplied without a NAME argument, |
8705 | an attempt is made to remove a completion specification for a NAME | |
8706 | for which no specification exists, or an error occurs adding a | |
8707 | completion specification. | |
bb70624e | 8708 | |
8a0829e9 CR |
8709 | 'compopt' |
8710 | compopt [-o OPTION] [-DE] [+o OPTION] [NAME] | |
6a8fd0ed | 8711 | Modify completion options for each NAME according to the OPTIONs, |
5cdaaf76 | 8712 | or for the currently-executing completion if no NAMEs are supplied. |
6a8fd0ed CR |
8713 | If no OPTIONs are given, display the completion options for each |
8714 | NAME or the current completion. The possible values of OPTION are | |
8a0829e9 | 8715 | those valid for the 'complete' builtin described above. The '-D' |
3eb2d94a CR |
8716 | option indicates that the remaining options should apply to the |
8717 | "default" command completion; that is, completion attempted on a | |
8718 | command for which no completion has previously been defined. The | |
8a0829e9 | 8719 | '-E' option indicates that the remaining options should apply to |
3eb2d94a CR |
8720 | "empty" command completion; that is, completion attempted on a |
8721 | blank line. | |
6a8fd0ed | 8722 | |
8a0829e9 | 8723 | The '-D' option takes precedence over '-E'. |
8f714a7c | 8724 | |
6a8fd0ed CR |
8725 | The return value is true unless an invalid option is supplied, an |
8726 | attempt is made to modify the options for a NAME for which no | |
8727 | completion specification exists, or an output error occurs. | |
8728 | ||
45c0f7f8 CR |
8729 | \1f |
8730 | File: bashref.info, Node: A Programmable Completion Example, Prev: Programmable Completion Builtins, Up: Command Line Editing | |
8731 | ||
8732 | 8.8 A Programmable Completion Example | |
8733 | ===================================== | |
8734 | ||
8735 | The most common way to obtain additional completion functionality beyond | |
8a0829e9 CR |
8736 | the default actions 'complete' and 'compgen' provide is to use a shell |
8737 | function and bind it to a particular command using 'complete -F'. | |
45c0f7f8 | 8738 | |
8a0829e9 CR |
8739 | The following function provides completions for the 'cd' builtin. It |
8740 | is a reasonably good example of what shell functions must do when used | |
8741 | for completion. This function uses the word passsed as '$2' to | |
45c0f7f8 | 8742 | determine the directory name to complete. You can also use the |
8a0829e9 CR |
8743 | 'COMP_WORDS' array variable; the current word is indexed by the |
8744 | 'COMP_CWORD' variable. | |
45c0f7f8 | 8745 | |
8a0829e9 CR |
8746 | The function relies on the 'complete' and 'compgen' builtins to do |
8747 | much of the work, adding only the things that the Bash 'cd' does beyond | |
45c0f7f8 CR |
8748 | accepting basic directory names: tilde expansion (*note Tilde |
8749 | Expansion::), searching directories in $CDPATH, which is described above | |
8a0829e9 CR |
8750 | (*note Bourne Shell Builtins::), and basic support for the 'cdable_vars' |
8751 | shell option (*note The Shopt Builtin::). '_comp_cd' modifies the value | |
8752 | of IFS so that it contains only a newline to accommodate file names | |
8753 | containing spaces and tabs - 'compgen' prints the possible completions | |
8754 | it generates one per line. | |
45c0f7f8 CR |
8755 | |
8756 | Possible completions go into the COMPREPLY array variable, one | |
8757 | completion per array element. The programmable completion system | |
8758 | retrieves the completions from there when the function returns. | |
8759 | ||
8760 | # A completion function for the cd builtin | |
8761 | # based on the cd completion function from the bash_completion package | |
8762 | _comp_cd() | |
8763 | { | |
8764 | local IFS=$' \t\n' # normalize IFS | |
8765 | local cur _skipdot _cdpath | |
8766 | local i j k | |
8767 | ||
8768 | # Tilde expansion, with side effect of expanding tilde to full pathname | |
8769 | case "$2" in | |
8770 | \~*) eval cur="$2" ;; | |
8771 | *) cur=$2 ;; | |
8772 | esac | |
8773 | ||
8774 | # no cdpath or absolute pathname -- straight directory completion | |
8775 | if [[ -z "${CDPATH:-}" ]] || [[ "$cur" == @(./*|../*|/*) ]]; then | |
8776 | # compgen prints paths one per line; could also use while loop | |
8777 | IFS=$'\n' | |
8778 | COMPREPLY=( $(compgen -d -- "$cur") ) | |
8779 | IFS=$' \t\n' | |
8780 | # CDPATH+directories in the current directory if not in CDPATH | |
8781 | else | |
8782 | IFS=$'\n' | |
8783 | _skipdot=false | |
8784 | # preprocess CDPATH to convert null directory names to . | |
8785 | _cdpath=${CDPATH/#:/.:} | |
8786 | _cdpath=${_cdpath//::/:.:} | |
8787 | _cdpath=${_cdpath/%:/:.} | |
8788 | for i in ${_cdpath//:/$'\n'}; do | |
8789 | if [[ $i -ef . ]]; then _skipdot=true; fi | |
8790 | k="${#COMPREPLY[@]}" | |
8791 | for j in $( compgen -d -- "$i/$cur" ); do | |
8792 | COMPREPLY[k++]=${j#$i/} # cut off directory | |
8793 | done | |
8794 | done | |
8795 | $_skipdot || COMPREPLY+=( $(compgen -d -- "$cur") ) | |
8796 | IFS=$' \t\n' | |
8797 | fi | |
8798 | ||
8799 | # variable names if appropriate shell option set and no completions | |
8800 | if shopt -q cdable_vars && [[ ${#COMPREPLY[@]} -eq 0 ]]; then | |
8801 | COMPREPLY=( $(compgen -v -- "$cur") ) | |
8802 | fi | |
8803 | ||
8804 | return 0 | |
8805 | } | |
8806 | ||
8a0829e9 CR |
8807 | We install the completion function using the '-F' option to |
8808 | 'complete': | |
45c0f7f8 CR |
8809 | |
8810 | # Tell readline to quote appropriate and append slashes to directories; | |
8811 | # use the bash default completion for other arguments | |
8812 | complete -o filenames -o nospace -o bashdefault -F _comp_cd cd | |
8813 | ||
8814 | Since we'd like Bash and Readline to take care of some of the other | |
8815 | details for us, we use several other options to tell Bash and Readline | |
8a0829e9 | 8816 | what to do. The '-o filenames' option tells Readline that the possible |
45c0f7f8 CR |
8817 | completions should be treated as filenames, and quoted appropriately. |
8818 | That option will also cause Readline to append a slash to filenames it | |
8819 | can determine are directories (which is why we might want to extend | |
8a0829e9 CR |
8820 | '_comp_cd' to append a slash if we're using directories found via |
8821 | CDPATH: Readline can't tell those completions are directories). The '-o | |
8822 | nospace' option tells Readline to not append a space character to the | |
8823 | directory name, in case we want to append to it. The '-o bashdefault' | |
8824 | option brings in the rest of the "Bash default" completions - possible | |
8825 | completion that Bash adds to the default Readline set. These include | |
8826 | things like command name completion, variable completion for words | |
8827 | beginning with '{', completions containing pathname expansion patterns | |
8828 | (*note Filename Expansion::), and so on. | |
8829 | ||
8830 | Once installed using 'complete', '_comp_cd' will be called every time | |
8831 | we attempt word completion for a 'cd' command. | |
45c0f7f8 CR |
8832 | |
8833 | Many more examples - an extensive collection of completions for most | |
8834 | of the common GNU, Unix, and Linux commands - are available as part of | |
8835 | the bash_completion project. This is installed by default on many | |
8836 | GNU/Linux distributions. Originally written by Ian Macdonald, the | |
8a0829e9 CR |
8837 | project now lives at <http://bash-completion.alioth.debian.org/>. There |
8838 | are ports for other systems such as Solaris and Mac OS X. | |
45c0f7f8 CR |
8839 | |
8840 | An older version of the bash_completion package is distributed with | |
8a0829e9 | 8841 | bash in the 'examples/complete' subdirectory. |
45c0f7f8 | 8842 | |
bb70624e | 8843 | \1f |
c2a47ea9 | 8844 | File: bashref.info, Node: Using History Interactively, Next: Installing Bash, Prev: Command Line Editing, Up: Top |
bb70624e | 8845 | |
37c41ab1 CR |
8846 | 9 Using History Interactively |
8847 | ***************************** | |
bb70624e | 8848 | |
8a0829e9 CR |
8849 | This chapter describes how to use the GNU History Library interactively, |
8850 | from a user's standpoint. It should be considered a user's guide. For | |
8851 | information on using the GNU History Library in other programs, see the | |
8852 | GNU Readline Library Manual. | |
bb70624e JA |
8853 | |
8854 | * Menu: | |
8855 | ||
8856 | * Bash History Facilities:: How Bash lets you manipulate your command | |
8857 | history. | |
8858 | * Bash History Builtins:: The Bash builtin commands that manipulate | |
8859 | the command history. | |
8860 | * History Interaction:: What it feels like using History as a user. | |
8861 | ||
8862 | \1f | |
8863 | File: bashref.info, Node: Bash History Facilities, Next: Bash History Builtins, Up: Using History Interactively | |
8864 | ||
37c41ab1 CR |
8865 | 9.1 Bash History Facilities |
8866 | =========================== | |
bb70624e | 8867 | |
8a0829e9 | 8868 | When the '-o history' option to the 'set' builtin is enabled (*note The |
37c41ab1 | 8869 | Set Builtin::), the shell provides access to the "command history", the |
8a0829e9 | 8870 | list of commands previously typed. The value of the 'HISTSIZE' shell |
37c41ab1 | 8871 | variable is used as the number of commands to save in a history list. |
8a0829e9 | 8872 | The text of the last '$HISTSIZE' commands (default 500) is saved. The |
37c41ab1 CR |
8873 | shell stores each command in the history list prior to parameter and |
8874 | variable expansion but after history expansion is performed, subject to | |
8a0829e9 | 8875 | the values of the shell variables 'HISTIGNORE' and 'HISTCONTROL'. |
bb70624e JA |
8876 | |
8877 | When the shell starts up, the history is initialized from the file | |
8a0829e9 CR |
8878 | named by the 'HISTFILE' variable (default '~/.bash_history'). The file |
8879 | named by the value of 'HISTFILE' is truncated, if necessary, to contain | |
bb70624e | 8880 | no more than the number of lines specified by the value of the |
8a0829e9 CR |
8881 | 'HISTFILESIZE' variable. When a shell with history enabled exits, the |
8882 | last '$HISTSIZE' lines are copied from the history list to the file | |
8883 | named by '$HISTFILE'. If the 'histappend' shell option is set (*note | |
9f178efb | 8884 | Bash Builtins::), the lines are appended to the history file, otherwise |
8a0829e9 | 8885 | the history file is overwritten. If 'HISTFILE' is unset, or if the |
9f178efb | 8886 | history file is unwritable, the history is not saved. After saving the |
bb70624e | 8887 | history, the history file is truncated to contain no more than |
8a0829e9 | 8888 | '$HISTFILESIZE' lines. If 'HISTFILESIZE' is unset, or set to null, a |
45c0f7f8 CR |
8889 | non-numeric value, or a numeric value less than zero, the history file |
8890 | is not truncated. | |
bb70624e | 8891 | |
8a0829e9 CR |
8892 | If the 'HISTTIMEFORMAT' is set, the time stamp information associated |
8893 | with each history entry is written to the history file, marked with the | |
8894 | history comment character. When the history file is read, lines | |
8895 | beginning with the history comment character followed immediately by a | |
690150f9 | 8896 | digit are interpreted as timestamps for the following history entry. |
d3a24ed2 | 8897 | |
8a0829e9 CR |
8898 | The builtin command 'fc' may be used to list or edit and re-execute a |
8899 | portion of the history list. The 'history' builtin may be used to | |
bb70624e JA |
8900 | display or modify the history list and manipulate the history file. |
8901 | When using command-line editing, search commands are available in each | |
8a0829e9 CR |
8902 | editing mode that provide access to the history list (*note Commands For |
8903 | History::). | |
bb70624e JA |
8904 | |
8905 | The shell allows control over which commands are saved on the history | |
8a0829e9 CR |
8906 | list. The 'HISTCONTROL' and 'HISTIGNORE' variables may be set to cause |
8907 | the shell to save only a subset of the commands entered. The 'cmdhist' | |
bb70624e JA |
8908 | shell option, if enabled, causes the shell to attempt to save each line |
8909 | of a multi-line command in the same history entry, adding semicolons | |
8a0829e9 | 8910 | where necessary to preserve syntactic correctness. The 'lithist' shell |
bb70624e | 8911 | option causes the shell to save the command with embedded newlines |
8a0829e9 CR |
8912 | instead of semicolons. The 'shopt' builtin is used to set these |
8913 | options. *Note Bash Builtins::, for a description of 'shopt'. | |
bb70624e JA |
8914 | |
8915 | \1f | |
8916 | File: bashref.info, Node: Bash History Builtins, Next: History Interaction, Prev: Bash History Facilities, Up: Using History Interactively | |
8917 | ||
37c41ab1 CR |
8918 | 9.2 Bash History Builtins |
8919 | ========================= | |
bb70624e | 8920 | |
8a0829e9 CR |
8921 | Bash provides two builtin commands which manipulate the history list and |
8922 | history file. | |
bb70624e | 8923 | |
8a0829e9 CR |
8924 | 'fc' |
8925 | fc [-e ENAME] [-lnr] [FIRST] [LAST] | |
8926 | fc -s [PAT=REP] [COMMAND] | |
bb70624e | 8927 | |
122f603c CR |
8928 | The first form selects a range of commands from FIRST to LAST from |
8929 | the history list and displays or edits and re-executes them. Both | |
8930 | FIRST and LAST may be specified as a string (to locate the most | |
8a0829e9 CR |
8931 | recent command beginning with that string) or as a number (an index |
8932 | into the history list, where a negative number is used as an offset | |
8933 | from the current command number). If LAST is not specified it is | |
8934 | set to FIRST. If FIRST is not specified it is set to the previous | |
8935 | command for editing and -16 for listing. If the '-l' flag is | |
8936 | given, the commands are listed on standard output. The '-n' flag | |
8937 | suppresses the command numbers when listing. The '-r' flag | |
8938 | reverses the order of the listing. Otherwise, the editor given by | |
8939 | ENAME is invoked on a file containing those commands. If ENAME is | |
8940 | not given, the value of the following variable expansion is used: | |
8941 | '${FCEDIT:-${EDITOR:-vi}}'. This says to use the value of the | |
8942 | 'FCEDIT' variable if set, or the value of the 'EDITOR' variable if | |
8943 | that is set, or 'vi' if neither is set. When editing is complete, | |
8944 | the edited commands are echoed and executed. | |
bb70624e JA |
8945 | |
8946 | In the second form, COMMAND is re-executed after each instance of | |
122f603c CR |
8947 | PAT in the selected command is replaced by REP. COMMAND is |
8948 | intepreted the same as FIRST above. | |
bb70624e | 8949 | |
8a0829e9 CR |
8950 | A useful alias to use with the 'fc' command is 'r='fc -s'', so that |
8951 | typing 'r cc' runs the last command beginning with 'cc' and typing | |
8952 | 'r' re-executes the last command (*note Aliases::). | |
bb70624e | 8953 | |
8a0829e9 | 8954 | 'history' |
bb70624e JA |
8955 | history [N] |
8956 | history -c | |
8957 | history -d OFFSET | |
8958 | history [-anrw] [FILENAME] | |
8959 | history -ps ARG | |
8960 | ||
8a0829e9 CR |
8961 | With no options, display the history list with line numbers. Lines |
8962 | prefixed with a '*' have been modified. An argument of N lists | |
8963 | only the last N lines. If the shell variable 'HISTTIMEFORMAT' is | |
8964 | set and not null, it is used as a format string for STRFTIME to | |
8965 | display the time stamp associated with each displayed history | |
8966 | entry. No intervening blank is printed between the formatted time | |
8967 | stamp and the history line. | |
d3a24ed2 CR |
8968 | |
8969 | Options, if supplied, have the following meanings: | |
bb70624e | 8970 | |
8a0829e9 | 8971 | '-c' |
bb70624e JA |
8972 | Clear the history list. This may be combined with the other |
8973 | options to replace the history list completely. | |
8974 | ||
8a0829e9 CR |
8975 | '-d OFFSET' |
8976 | Delete the history entry at position OFFSET. OFFSET should be | |
8977 | specified as it appears when the history is displayed. | |
bb70624e | 8978 | |
8a0829e9 | 8979 | '-a' |
eac8fb1b CR |
8980 | Append the new history lines to the history file. These are |
8981 | history lines entered since the beginning of the current Bash | |
8982 | session, but not already appended to the history file. | |
bb70624e | 8983 | |
8a0829e9 | 8984 | '-n' |
bb70624e | 8985 | Append the history lines not already read from the history |
8a0829e9 CR |
8986 | file to the current history list. These are lines appended to |
8987 | the history file since the beginning of the current Bash | |
bb70624e JA |
8988 | session. |
8989 | ||
8a0829e9 | 8990 | '-r' |
122f603c CR |
8991 | Read the history file and append its contents to the history |
8992 | list. | |
bb70624e | 8993 | |
8a0829e9 | 8994 | '-w' |
122f603c | 8995 | Write out the current history list to the history file. |
bb70624e | 8996 | |
8a0829e9 | 8997 | '-p' |
bb70624e JA |
8998 | Perform history substitution on the ARGs and display the |
8999 | result on the standard output, without storing the results in | |
9000 | the history list. | |
9001 | ||
8a0829e9 | 9002 | '-s' |
bb70624e JA |
9003 | The ARGs are added to the end of the history list as a single |
9004 | entry. | |
9005 | ||
8a0829e9 | 9006 | When any of the '-w', '-r', '-a', or '-n' options is used, if |
bb70624e | 9007 | FILENAME is given, then it is used as the history file. If not, |
8a0829e9 | 9008 | then the value of the 'HISTFILE' variable is used. |
761783bf | 9009 | |
bb70624e JA |
9010 | \1f |
9011 | File: bashref.info, Node: History Interaction, Prev: Bash History Builtins, Up: Using History Interactively | |
ccc6cda3 | 9012 | |
37c41ab1 CR |
9013 | 9.3 History Expansion |
9014 | ===================== | |
ccc6cda3 | 9015 | |
37c41ab1 | 9016 | The History library provides a history expansion feature that is similar |
8a0829e9 | 9017 | to the history expansion provided by 'csh'. This section describes the |
37c41ab1 | 9018 | syntax used to manipulate the history information. |
ccc6cda3 | 9019 | |
bb70624e | 9020 | History expansions introduce words from the history list into the |
8a0829e9 CR |
9021 | input stream, making it easy to repeat commands, insert the arguments to |
9022 | a previous command into the current input line, or fix errors in | |
bb70624e | 9023 | previous commands quickly. |
ccc6cda3 | 9024 | |
54a5fbe1 CR |
9025 | History expansion is performed immediately after a complete line is |
9026 | read, before the shell breaks it into words. | |
9027 | ||
bb70624e JA |
9028 | History expansion takes place in two parts. The first is to |
9029 | determine which line from the history list should be used during | |
9030 | substitution. The second is to select portions of that line for | |
9031 | inclusion into the current one. The line selected from the history is | |
9032 | called the "event", and the portions of that line that are acted upon | |
8a0829e9 CR |
9033 | are called "words". Various "modifiers" are available to manipulate the |
9034 | selected words. The line is broken into words in the same fashion that | |
9035 | Bash does, so that several words surrounded by quotes are considered one | |
9036 | word. History expansions are introduced by the appearance of the | |
9037 | history expansion character, which is '!' by default. Only '\' and ''' | |
54a5fbe1 CR |
9038 | may be used to escape the history expansion character, but the history |
9039 | expansion character is also treated as quoted if it immediately precedes | |
9040 | the closing double quote in a double-quoted string. | |
8a0829e9 CR |
9041 | |
9042 | Several shell options settable with the 'shopt' builtin (*note Bash | |
9043 | Builtins::) may be used to tailor the behavior of history expansion. If | |
9044 | the 'histverify' shell option is enabled, and Readline is being used, | |
9045 | history substitutions are not immediately passed to the shell parser. | |
9046 | Instead, the expanded line is reloaded into the Readline editing buffer | |
9047 | for further modification. If Readline is being used, and the | |
9048 | 'histreedit' shell option is enabled, a failed history expansion will be | |
9049 | reloaded into the Readline editing buffer for correction. The '-p' | |
9050 | option to the 'history' builtin command may be used to see what a | |
9051 | history expansion will do before using it. The '-s' option to the | |
9052 | 'history' builtin may be used to add commands to the end of the history | |
9053 | list without actually executing them, so that they are available for | |
9054 | subsequent recall. This is most useful in conjunction with Readline. | |
bb70624e JA |
9055 | |
9056 | The shell allows control of the various characters used by the | |
8a0829e9 | 9057 | history expansion mechanism with the 'histchars' variable, as explained |
d3ad40de CR |
9058 | above (*note Bash Variables::). The shell uses the history comment |
9059 | character to mark history timestamps when writing the history file. | |
bb70624e JA |
9060 | |
9061 | * Menu: | |
9062 | ||
9063 | * Event Designators:: How to specify which history line to use. | |
9064 | * Word Designators:: Specifying which words are of interest. | |
9065 | * Modifiers:: Modifying the results of substitution. | |
ccc6cda3 JA |
9066 | |
9067 | \1f | |
bb70624e | 9068 | File: bashref.info, Node: Event Designators, Next: Word Designators, Up: History Interaction |
ccc6cda3 | 9069 | |
37c41ab1 CR |
9070 | 9.3.1 Event Designators |
9071 | ----------------------- | |
ccc6cda3 | 9072 | |
37c41ab1 | 9073 | An event designator is a reference to a command line entry in the |
e05be32d | 9074 | history list. Unless the reference is absolute, events are relative to |
8a0829e9 | 9075 | the current position in the history list. |
ccc6cda3 | 9076 | |
8a0829e9 | 9077 | '!' |
bb70624e | 9078 | Start a history substitution, except when followed by a space, tab, |
8a0829e9 CR |
9079 | the end of the line, '=' or '(' (when the 'extglob' shell option is |
9080 | enabled using the 'shopt' builtin). | |
ccc6cda3 | 9081 | |
8a0829e9 | 9082 | '!N' |
bb70624e | 9083 | Refer to command line N. |
ccc6cda3 | 9084 | |
8a0829e9 | 9085 | '!-N' |
bb70624e | 9086 | Refer to the command N lines back. |
ccc6cda3 | 9087 | |
8a0829e9 CR |
9088 | '!!' |
9089 | Refer to the previous command. This is a synonym for '!-1'. | |
ccc6cda3 | 9090 | |
8a0829e9 | 9091 | '!STRING' |
e05be32d CR |
9092 | Refer to the most recent command preceding the current position in |
9093 | the history list starting with STRING. | |
ccc6cda3 | 9094 | |
8a0829e9 | 9095 | '!?STRING[?]' |
e05be32d | 9096 | Refer to the most recent command preceding the current position in |
8a0829e9 | 9097 | the history list containing STRING. The trailing '?' may be |
e05be32d | 9098 | omitted if the STRING is followed immediately by a newline. |
ccc6cda3 | 9099 | |
8a0829e9 | 9100 | '^STRING1^STRING2^' |
bb70624e | 9101 | Quick Substitution. Repeat the last command, replacing STRING1 |
8a0829e9 | 9102 | with STRING2. Equivalent to '!!:s/STRING1/STRING2/'. |
bb70624e | 9103 | |
8a0829e9 | 9104 | '!#' |
bb70624e | 9105 | The entire command line typed so far. |
ccc6cda3 JA |
9106 | |
9107 | \1f | |
bb70624e | 9108 | File: bashref.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction |
ccc6cda3 | 9109 | |
37c41ab1 CR |
9110 | 9.3.2 Word Designators |
9111 | ---------------------- | |
ccc6cda3 | 9112 | |
8a0829e9 CR |
9113 | Word designators are used to select desired words from the event. A ':' |
9114 | separates the event specification from the word designator. It may be | |
9115 | omitted if the word designator begins with a '^', '$', '*', '-', or '%'. | |
9116 | Words are numbered from the beginning of the line, with the first word | |
9117 | being denoted by 0 (zero). Words are inserted into the current line | |
9118 | separated by single spaces. | |
ccc6cda3 | 9119 | |
bb70624e | 9120 | For example, |
ccc6cda3 | 9121 | |
8a0829e9 | 9122 | '!!' |
bb70624e JA |
9123 | designates the preceding command. When you type this, the |
9124 | preceding command is repeated in toto. | |
ccc6cda3 | 9125 | |
8a0829e9 | 9126 | '!!:$' |
bb70624e | 9127 | designates the last argument of the preceding command. This may be |
8a0829e9 | 9128 | shortened to '!$'. |
ccc6cda3 | 9129 | |
8a0829e9 | 9130 | '!fi:2' |
bb70624e | 9131 | designates the second argument of the most recent command starting |
8a0829e9 | 9132 | with the letters 'fi'. |
ccc6cda3 | 9133 | |
bb70624e | 9134 | Here are the word designators: |
ccc6cda3 | 9135 | |
8a0829e9 CR |
9136 | '0 (zero)' |
9137 | The '0'th word. For many applications, this is the command word. | |
ccc6cda3 | 9138 | |
8a0829e9 | 9139 | 'N' |
bb70624e | 9140 | The Nth word. |
ccc6cda3 | 9141 | |
8a0829e9 | 9142 | '^' |
bb70624e | 9143 | The first argument; that is, word 1. |
ccc6cda3 | 9144 | |
8a0829e9 | 9145 | '$' |
bb70624e | 9146 | The last argument. |
ccc6cda3 | 9147 | |
8a0829e9 CR |
9148 | '%' |
9149 | The word matched by the most recent '?STRING?' search. | |
ccc6cda3 | 9150 | |
8a0829e9 CR |
9151 | 'X-Y' |
9152 | A range of words; '-Y' abbreviates '0-Y'. | |
ccc6cda3 | 9153 | |
8a0829e9 CR |
9154 | '*' |
9155 | All of the words, except the '0'th. This is a synonym for '1-$'. | |
9156 | It is not an error to use '*' if there is just one word in the | |
bb70624e JA |
9157 | event; the empty string is returned in that case. |
9158 | ||
8a0829e9 CR |
9159 | 'X*' |
9160 | Abbreviates 'X-$' | |
bb70624e | 9161 | |
8a0829e9 CR |
9162 | 'X-' |
9163 | Abbreviates 'X-$' like 'X*', but omits the last word. | |
761783bf | 9164 | |
bb70624e JA |
9165 | If a word designator is supplied without an event specification, the |
9166 | previous command is used as the event. | |
ccc6cda3 JA |
9167 | |
9168 | \1f | |
bb70624e | 9169 | File: bashref.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction |
ccc6cda3 | 9170 | |
37c41ab1 CR |
9171 | 9.3.3 Modifiers |
9172 | --------------- | |
ccc6cda3 | 9173 | |
37c41ab1 | 9174 | After the optional word designator, you can add a sequence of one or |
8a0829e9 | 9175 | more of the following modifiers, each preceded by a ':'. |
ccc6cda3 | 9176 | |
8a0829e9 | 9177 | 'h' |
bb70624e | 9178 | Remove a trailing pathname component, leaving only the head. |
ccc6cda3 | 9179 | |
8a0829e9 | 9180 | 't' |
d3ad40de | 9181 | Remove all leading pathname components, leaving the tail. |
bb70624e | 9182 | |
8a0829e9 CR |
9183 | 'r' |
9184 | Remove a trailing suffix of the form '.SUFFIX', leaving the | |
bb70624e JA |
9185 | basename. |
9186 | ||
8a0829e9 | 9187 | 'e' |
bb70624e JA |
9188 | Remove all but the trailing suffix. |
9189 | ||
8a0829e9 | 9190 | 'p' |
bb70624e JA |
9191 | Print the new command but do not execute it. |
9192 | ||
8a0829e9 | 9193 | 'q' |
bb70624e JA |
9194 | Quote the substituted words, escaping further substitutions. |
9195 | ||
8a0829e9 CR |
9196 | 'x' |
9197 | Quote the substituted words as with 'q', but break into words at | |
bb70624e JA |
9198 | spaces, tabs, and newlines. |
9199 | ||
8a0829e9 | 9200 | 's/OLD/NEW/' |
bb70624e | 9201 | Substitute NEW for the first occurrence of OLD in the event line. |
8a0829e9 CR |
9202 | Any delimiter may be used in place of '/'. The delimiter may be |
9203 | quoted in OLD and NEW with a single backslash. If '&' appears in | |
9204 | NEW, it is replaced by OLD. A single backslash will quote the '&'. | |
9205 | The final delimiter is optional if it is the last character on the | |
9206 | input line. | |
bb70624e | 9207 | |
8a0829e9 | 9208 | '&' |
bb70624e JA |
9209 | Repeat the previous substitution. |
9210 | ||
8a0829e9 CR |
9211 | 'g' |
9212 | 'a' | |
bb70624e | 9213 | Cause changes to be applied over the entire event line. Used in |
8a0829e9 | 9214 | conjunction with 's', as in 'gs/OLD/NEW/', or with '&'. |
d3a24ed2 | 9215 | |
8a0829e9 CR |
9216 | 'G' |
9217 | Apply the following 's' modifier once to each word in the event. | |
761783bf | 9218 | |
bb70624e | 9219 | \1f |
c2a47ea9 | 9220 | File: bashref.info, Node: Installing Bash, Next: Reporting Bugs, Prev: Using History Interactively, Up: Top |
bb70624e | 9221 | |
37c41ab1 CR |
9222 | 10 Installing Bash |
9223 | ****************** | |
b72432fd | 9224 | |
37c41ab1 | 9225 | This chapter provides basic instructions for installing Bash on the |
bb70624e JA |
9226 | various supported platforms. The distribution supports the GNU |
9227 | operating systems, nearly every version of Unix, and several non-Unix | |
9228 | systems such as BeOS and Interix. Other independent ports exist for | |
d3a24ed2 | 9229 | MS-DOS, OS/2, and Windows platforms. |
ccc6cda3 | 9230 | |
bb70624e | 9231 | * Menu: |
ccc6cda3 | 9232 | |
bb70624e | 9233 | * Basic Installation:: Installation instructions. |
bb70624e JA |
9234 | * Compilers and Options:: How to set special options for various |
9235 | systems. | |
bb70624e JA |
9236 | * Compiling For Multiple Architectures:: How to compile Bash for more |
9237 | than one kind of system from | |
9238 | the same source tree. | |
bb70624e | 9239 | * Installation Names:: How to set the various paths used by the installation. |
bb70624e | 9240 | * Specifying the System Type:: How to configure Bash for a particular system. |
bb70624e JA |
9241 | * Sharing Defaults:: How to share default configuration values among GNU |
9242 | programs. | |
bb70624e | 9243 | * Operation Controls:: Options recognized by the configuration program. |
bb70624e JA |
9244 | * Optional Features:: How to enable and disable optional features when |
9245 | building Bash. | |
ccc6cda3 | 9246 | |
bb70624e JA |
9247 | \1f |
9248 | File: bashref.info, Node: Basic Installation, Next: Compilers and Options, Up: Installing Bash | |
ccc6cda3 | 9249 | |
37c41ab1 CR |
9250 | 10.1 Basic Installation |
9251 | ======================= | |
ccc6cda3 | 9252 | |
37c41ab1 | 9253 | These are installation instructions for Bash. |
ccc6cda3 | 9254 | |
bb70624e | 9255 | The simplest way to compile Bash is: |
ccc6cda3 | 9256 | |
8a0829e9 CR |
9257 | 1. 'cd' to the directory containing the source code and type |
9258 | './configure' to configure Bash for your system. If you're using | |
9259 | 'csh' on an old version of System V, you might need to type 'sh | |
9260 | ./configure' instead to prevent 'csh' from trying to execute | |
9261 | 'configure' itself. | |
ccc6cda3 | 9262 | |
8a0829e9 | 9263 | Running 'configure' takes some time. While running, it prints |
bb70624e | 9264 | messages telling which features it is checking for. |
ccc6cda3 | 9265 | |
8a0829e9 | 9266 | 2. Type 'make' to compile Bash and build the 'bashbug' bug reporting |
bb70624e | 9267 | script. |
ccc6cda3 | 9268 | |
8a0829e9 | 9269 | 3. Optionally, type 'make tests' to run the Bash test suite. |
ccc6cda3 | 9270 | |
8a0829e9 | 9271 | 4. Type 'make install' to install 'bash' and 'bashbug'. This will |
bb70624e | 9272 | also install the manual pages and Info file. |
ccc6cda3 | 9273 | |
8a0829e9 | 9274 | The 'configure' shell script attempts to guess correct values for |
bb70624e | 9275 | various system-dependent variables used during compilation. It uses |
8a0829e9 CR |
9276 | those values to create a 'Makefile' in each directory of the package |
9277 | (the top directory, the 'builtins', 'doc', and 'support' directories, | |
9278 | each directory under 'lib', and several others). It also creates a | |
9279 | 'config.h' file containing system-dependent definitions. Finally, it | |
9280 | creates a shell script named 'config.status' that you can run in the | |
9281 | future to recreate the current configuration, a file 'config.cache' that | |
9282 | saves the results of its tests to speed up reconfiguring, and a file | |
9283 | 'config.log' containing compiler output (useful mainly for debugging | |
9284 | 'configure'). If at some point 'config.cache' contains results you | |
9285 | don't want to keep, you may remove or edit it. | |
9286 | ||
9287 | To find out more about the options and arguments that the 'configure' | |
9288 | script understands, type | |
ccc6cda3 | 9289 | |
bb70624e | 9290 | bash-2.04$ ./configure --help |
ccc6cda3 | 9291 | |
bb70624e | 9292 | at the Bash prompt in your Bash source directory. |
ccc6cda3 | 9293 | |
bb70624e | 9294 | If you need to do unusual things to compile Bash, please try to |
8a0829e9 | 9295 | figure out how 'configure' could check whether or not to do them, and |
bb70624e JA |
9296 | mail diffs or instructions to <bash-maintainers@gnu.org> so they can be |
9297 | considered for the next release. | |
ccc6cda3 | 9298 | |
8a0829e9 CR |
9299 | The file 'configure.ac' is used to create 'configure' by a program |
9300 | called Autoconf. You only need 'configure.ac' if you want to change it | |
9301 | or regenerate 'configure' using a newer version of Autoconf. If you do | |
f73dda09 | 9302 | this, make sure you are using Autoconf version 2.50 or newer. |
ccc6cda3 | 9303 | |
bb70624e | 9304 | You can remove the program binaries and object files from the source |
8a0829e9 CR |
9305 | code directory by typing 'make clean'. To also remove the files that |
9306 | 'configure' created (so you can compile Bash for a different kind of | |
9307 | computer), type 'make distclean'. | |
ccc6cda3 | 9308 | |
bb70624e JA |
9309 | \1f |
9310 | File: bashref.info, Node: Compilers and Options, Next: Compiling For Multiple Architectures, Prev: Basic Installation, Up: Installing Bash | |
ccc6cda3 | 9311 | |
37c41ab1 CR |
9312 | 10.2 Compilers and Options |
9313 | ========================== | |
ccc6cda3 | 9314 | |
8a0829e9 CR |
9315 | Some systems require unusual options for compilation or linking that the |
9316 | 'configure' script does not know about. You can give 'configure' | |
bb70624e JA |
9317 | initial values for variables by setting them in the environment. Using |
9318 | a Bourne-compatible shell, you can do that on the command line like | |
9319 | this: | |
ccc6cda3 | 9320 | |
bb70624e | 9321 | CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure |
ccc6cda3 | 9322 | |
8a0829e9 | 9323 | On systems that have the 'env' program, you can do it like this: |
cce855bc | 9324 | |
bb70624e | 9325 | env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure |
b72432fd | 9326 | |
bb70624e | 9327 | The configuration process uses GCC to build Bash if it is available. |
ccc6cda3 | 9328 | |
bb70624e JA |
9329 | \1f |
9330 | File: bashref.info, Node: Compiling For Multiple Architectures, Next: Installation Names, Prev: Compilers and Options, Up: Installing Bash | |
ccc6cda3 | 9331 | |
37c41ab1 CR |
9332 | 10.3 Compiling For Multiple Architectures |
9333 | ========================================= | |
ccc6cda3 | 9334 | |
37c41ab1 | 9335 | You can compile Bash for more than one kind of computer at the same |
bb70624e | 9336 | time, by placing the object files for each architecture in their own |
8a0829e9 CR |
9337 | directory. To do this, you must use a version of 'make' that supports |
9338 | the 'VPATH' variable, such as GNU 'make'. 'cd' to the directory where | |
9339 | you want the object files and executables to go and run the 'configure' | |
bb70624e | 9340 | script from the source directory. You may need to supply the |
8a0829e9 CR |
9341 | '--srcdir=PATH' argument to tell 'configure' where the source files are. |
9342 | 'configure' automatically checks for the source code in the directory | |
9343 | that 'configure' is in and in '..'. | |
ccc6cda3 | 9344 | |
8a0829e9 | 9345 | If you have to use a 'make' that does not supports the 'VPATH' |
bb70624e JA |
9346 | variable, you can compile Bash for one architecture at a time in the |
9347 | source code directory. After you have installed Bash for one | |
8a0829e9 | 9348 | architecture, use 'make distclean' before reconfiguring for another |
bb70624e | 9349 | architecture. |
ccc6cda3 | 9350 | |
bb70624e | 9351 | Alternatively, if your system supports symbolic links, you can use |
8a0829e9 CR |
9352 | the 'support/mkclone' script to create a build tree which has symbolic |
9353 | links back to each file in the source directory. Here's an example that | |
9354 | creates a build directory in the current directory from a source | |
9355 | directory '/usr/gnu/src/bash-2.0': | |
ccc6cda3 | 9356 | |
bb70624e | 9357 | bash /usr/gnu/src/bash-2.0/support/mkclone -s /usr/gnu/src/bash-2.0 . |
ccc6cda3 | 9358 | |
8a0829e9 | 9359 | The 'mkclone' script requires Bash, so you must have already built Bash |
bb70624e JA |
9360 | for at least one architecture before you can create build directories |
9361 | for other architectures. | |
ccc6cda3 | 9362 | |
bb70624e JA |
9363 | \1f |
9364 | File: bashref.info, Node: Installation Names, Next: Specifying the System Type, Prev: Compiling For Multiple Architectures, Up: Installing Bash | |
ccc6cda3 | 9365 | |
37c41ab1 CR |
9366 | 10.4 Installation Names |
9367 | ======================= | |
ccc6cda3 | 9368 | |
8a0829e9 CR |
9369 | By default, 'make install' will install into '/usr/local/bin', |
9370 | '/usr/local/man', etc. You can specify an installation prefix other | |
9371 | than '/usr/local' by giving 'configure' the option '--prefix=PATH', or | |
9372 | by specifying a value for the 'DESTDIR' 'make' variable when running | |
9373 | 'make install'. | |
ccc6cda3 | 9374 | |
bb70624e JA |
9375 | You can specify separate installation prefixes for |
9376 | architecture-specific files and architecture-independent files. If you | |
8a0829e9 | 9377 | give 'configure' the option '--exec-prefix=PATH', 'make install' will |
bb70624e JA |
9378 | use PATH as the prefix for installing programs and libraries. |
9379 | Documentation and other data files will still use the regular prefix. | |
ccc6cda3 JA |
9380 | |
9381 | \1f | |
bb70624e | 9382 | File: bashref.info, Node: Specifying the System Type, Next: Sharing Defaults, Prev: Installation Names, Up: Installing Bash |
ccc6cda3 | 9383 | |
37c41ab1 CR |
9384 | 10.5 Specifying the System Type |
9385 | =============================== | |
ccc6cda3 | 9386 | |
8a0829e9 CR |
9387 | There may be some features 'configure' can not figure out automatically, |
9388 | but need to determine by the type of host Bash will run on. Usually | |
9389 | 'configure' can figure that out, but if it prints a message saying it | |
9390 | can not guess the host type, give it the '--host=TYPE' option. 'TYPE' | |
9391 | can either be a short name for the system type, such as 'sun4', or a | |
9392 | canonical name with three fields: 'CPU-COMPANY-SYSTEM' (e.g., | |
9393 | 'i386-unknown-freebsd4.2'). | |
ccc6cda3 | 9394 | |
8a0829e9 | 9395 | See the file 'support/config.sub' for the possible values of each |
bb70624e | 9396 | field. |
ccc6cda3 | 9397 | |
bb70624e JA |
9398 | \1f |
9399 | File: bashref.info, Node: Sharing Defaults, Next: Operation Controls, Prev: Specifying the System Type, Up: Installing Bash | |
9400 | ||
37c41ab1 CR |
9401 | 10.6 Sharing Defaults |
9402 | ===================== | |
bb70624e | 9403 | |
8a0829e9 CR |
9404 | If you want to set default values for 'configure' scripts to share, you |
9405 | can create a site shell script called 'config.site' that gives default | |
9406 | values for variables like 'CC', 'cache_file', and 'prefix'. 'configure' | |
9407 | looks for 'PREFIX/share/config.site' if it exists, then | |
9408 | 'PREFIX/etc/config.site' if it exists. Or, you can set the | |
9409 | 'CONFIG_SITE' environment variable to the location of the site script. | |
9410 | A warning: the Bash 'configure' looks for a site script, but not all | |
9411 | 'configure' scripts do. | |
ccc6cda3 JA |
9412 | |
9413 | \1f | |
bb70624e | 9414 | File: bashref.info, Node: Operation Controls, Next: Optional Features, Prev: Sharing Defaults, Up: Installing Bash |
ccc6cda3 | 9415 | |
37c41ab1 CR |
9416 | 10.7 Operation Controls |
9417 | ======================= | |
ccc6cda3 | 9418 | |
8a0829e9 | 9419 | 'configure' recognizes the following options to control how it operates. |
ccc6cda3 | 9420 | |
8a0829e9 | 9421 | '--cache-file=FILE' |
bb70624e | 9422 | Use and save the results of the tests in FILE instead of |
8a0829e9 CR |
9423 | './config.cache'. Set FILE to '/dev/null' to disable caching, for |
9424 | debugging 'configure'. | |
ccc6cda3 | 9425 | |
8a0829e9 CR |
9426 | '--help' |
9427 | Print a summary of the options to 'configure', and exit. | |
ccc6cda3 | 9428 | |
8a0829e9 CR |
9429 | '--quiet' |
9430 | '--silent' | |
9431 | '-q' | |
bb70624e | 9432 | Do not print messages saying which checks are being made. |
ccc6cda3 | 9433 | |
8a0829e9 | 9434 | '--srcdir=DIR' |
bb70624e | 9435 | Look for the Bash source code in directory DIR. Usually |
8a0829e9 | 9436 | 'configure' can determine that directory automatically. |
ccc6cda3 | 9437 | |
8a0829e9 CR |
9438 | '--version' |
9439 | Print the version of Autoconf used to generate the 'configure' | |
bb70624e | 9440 | script, and exit. |
ccc6cda3 | 9441 | |
8a0829e9 CR |
9442 | 'configure' also accepts some other, not widely used, boilerplate |
9443 | options. 'configure --help' prints the complete list. | |
ccc6cda3 | 9444 | |
bb70624e JA |
9445 | \1f |
9446 | File: bashref.info, Node: Optional Features, Prev: Operation Controls, Up: Installing Bash | |
ccc6cda3 | 9447 | |
37c41ab1 CR |
9448 | 10.8 Optional Features |
9449 | ====================== | |
ccc6cda3 | 9450 | |
8a0829e9 | 9451 | The Bash 'configure' has a number of '--enable-FEATURE' options, where |
37c41ab1 | 9452 | FEATURE indicates an optional part of Bash. There are also several |
8a0829e9 CR |
9453 | '--with-PACKAGE' options, where PACKAGE is something like 'bash-malloc' |
9454 | or 'purify'. To turn off the default use of a package, use | |
9455 | '--without-PACKAGE'. To configure Bash without a feature that is | |
9456 | enabled by default, use '--disable-FEATURE'. | |
ccc6cda3 | 9457 | |
8a0829e9 CR |
9458 | Here is a complete list of the '--enable-' and '--with-' options that |
9459 | the Bash 'configure' recognizes. | |
ccc6cda3 | 9460 | |
8a0829e9 | 9461 | '--with-afs' |
bb70624e | 9462 | Define if you are using the Andrew File System from Transarc. |
ccc6cda3 | 9463 | |
8a0829e9 CR |
9464 | '--with-bash-malloc' |
9465 | Use the Bash version of 'malloc' in the directory 'lib/malloc'. | |
9466 | This is not the same 'malloc' that appears in GNU libc, but an | |
9467 | older version originally derived from the 4.2 BSD 'malloc'. This | |
9468 | 'malloc' is very fast, but wastes some space on each allocation. | |
9469 | This option is enabled by default. The 'NOTES' file contains a | |
1c72c0cd | 9470 | list of systems for which this should be turned off, and |
8a0829e9 | 9471 | 'configure' disables this option automatically for a number of |
1c72c0cd | 9472 | systems. |
ccc6cda3 | 9473 | |
8a0829e9 | 9474 | '--with-curses' |
bb70624e JA |
9475 | Use the curses library instead of the termcap library. This should |
9476 | be supplied if your system has an inadequate or incomplete termcap | |
9477 | database. | |
ccc6cda3 | 9478 | |
8a0829e9 CR |
9479 | '--with-gnu-malloc' |
9480 | A synonym for '--with-bash-malloc'. | |
ccc6cda3 | 9481 | |
8a0829e9 | 9482 | '--with-installed-readline[=PREFIX]' |
bb70624e | 9483 | Define this to make Bash link with a locally-installed version of |
8a0829e9 CR |
9484 | Readline rather than the version in 'lib/readline'. This works |
9485 | only with Readline 5.0 and later versions. If PREFIX is 'yes' or | |
9486 | not supplied, 'configure' uses the values of the make variables | |
9487 | 'includedir' and 'libdir', which are subdirectories of 'prefix' by | |
f73dda09 JA |
9488 | default, to find the installed version of Readline if it is not in |
9489 | the standard system include and library directories. If PREFIX is | |
8a0829e9 CR |
9490 | 'no', Bash links with the version in 'lib/readline'. If PREFIX is |
9491 | set to any other value, 'configure' treats it as a directory | |
f73dda09 | 9492 | pathname and looks for the installed version of Readline in |
8a0829e9 CR |
9493 | subdirectories of that directory (include files in PREFIX/'include' |
9494 | and the library in PREFIX/'lib'). | |
ccc6cda3 | 9495 | |
8a0829e9 | 9496 | '--with-purify' |
bb70624e JA |
9497 | Define this to use the Purify memory allocation checker from |
9498 | Rational Software. | |
ccc6cda3 | 9499 | |
8a0829e9 | 9500 | '--enable-minimal-config' |
bb70624e JA |
9501 | This produces a shell with minimal features, close to the |
9502 | historical Bourne shell. | |
ccc6cda3 | 9503 | |
8a0829e9 CR |
9504 | There are several '--enable-' options that alter how Bash is compiled |
9505 | and linked, rather than changing run-time features. | |
ccc6cda3 | 9506 | |
8a0829e9 | 9507 | '--enable-largefile' |
f73dda09 JA |
9508 | Enable support for large files |
9509 | (http://www.sas.com/standards/large_file/x_open.20Mar96.html) if | |
9510 | the operating system requires special compiler options to build | |
8a0829e9 CR |
9511 | programs which can access large files. This is enabled by default, |
9512 | if the operating system provides large file support. | |
f73dda09 | 9513 | |
8a0829e9 | 9514 | '--enable-profiling' |
bb70624e | 9515 | This builds a Bash binary that produces profiling information to be |
8a0829e9 | 9516 | processed by 'gprof' each time it is executed. |
cce855bc | 9517 | |
8a0829e9 CR |
9518 | '--enable-static-link' |
9519 | This causes Bash to be linked statically, if 'gcc' is being used. | |
bb70624e | 9520 | This could be used to build a version to use as root's shell. |
d166f048 | 9521 | |
8a0829e9 | 9522 | The 'minimal-config' option can be used to disable all of the |
bb70624e | 9523 | following options, but it is processed first, so individual options may |
8a0829e9 | 9524 | be enabled using 'enable-FEATURE'. |
d166f048 | 9525 | |
8a0829e9 CR |
9526 | All of the following options except for 'disabled-builtins', |
9527 | 'direxpand-default', and 'xpg-echo-default' are enabled by default, | |
ad4aef08 | 9528 | unless the operating system does not provide the necessary support. |
ccc6cda3 | 9529 | |
8a0829e9 CR |
9530 | '--enable-alias' |
9531 | Allow alias expansion and include the 'alias' and 'unalias' | |
28ef6c31 | 9532 | builtins (*note Aliases::). |
ccc6cda3 | 9533 | |
8a0829e9 CR |
9534 | '--enable-arith-for-command' |
9535 | Include support for the alternate form of the 'for' command that | |
9536 | behaves like the C language 'for' statement (*note Looping | |
28ef6c31 | 9537 | Constructs::). |
ccc6cda3 | 9538 | |
8a0829e9 | 9539 | '--enable-array-variables' |
bb70624e | 9540 | Include support for one-dimensional array shell variables (*note |
28ef6c31 | 9541 | Arrays::). |
ccc6cda3 | 9542 | |
8a0829e9 CR |
9543 | '--enable-bang-history' |
9544 | Include support for 'csh'-like history substitution (*note History | |
28ef6c31 | 9545 | Interaction::). |
ccc6cda3 | 9546 | |
8a0829e9 CR |
9547 | '--enable-brace-expansion' |
9548 | Include 'csh'-like brace expansion ( 'b{a,b}c' ==> 'bac bbc' ). | |
6a8fd0ed | 9549 | See *note Brace Expansion::, for a complete description. |
ccc6cda3 | 9550 | |
8a0829e9 CR |
9551 | '--enable-casemod-attributes' |
9552 | Include support for case-modifying attributes in the 'declare' | |
09767ff0 CR |
9553 | builtin and assignment statements. Variables with the UPPERCASE |
9554 | attribute, for example, will have their values converted to | |
9555 | uppercase upon assignment. | |
9556 | ||
8a0829e9 | 9557 | '--enable-casemod-expansion' |
09767ff0 CR |
9558 | Include support for case-modifying word expansions. |
9559 | ||
8a0829e9 CR |
9560 | '--enable-command-timing' |
9561 | Include support for recognizing 'time' as a reserved word and for | |
9562 | displaying timing statistics for the pipeline following 'time' | |
28ef6c31 | 9563 | (*note Pipelines::). This allows pipelines as well as shell |
bb70624e | 9564 | builtins and functions to be timed. |
ccc6cda3 | 9565 | |
8a0829e9 CR |
9566 | '--enable-cond-command' |
9567 | Include support for the '[[' conditional command. (*note | |
5e13499c CR |
9568 | Conditional Constructs::). |
9569 | ||
8a0829e9 | 9570 | '--enable-cond-regexp' |
5e13499c | 9571 | Include support for matching POSIX regular expressions using the |
8a0829e9 | 9572 | '=~' binary operator in the '[[' conditional command. (*note |
28ef6c31 | 9573 | Conditional Constructs::). |
ccc6cda3 | 9574 | |
8a0829e9 CR |
9575 | '--enable-coprocesses' |
9576 | Include support for coprocesses and the 'coproc' reserved word | |
8e1a6eaa CR |
9577 | (*note Pipelines::). |
9578 | ||
8a0829e9 | 9579 | '--enable-debugger' |
01ed5ba4 CR |
9580 | Include support for the bash debugger (distributed separately). |
9581 | ||
8a0829e9 CR |
9582 | '--enable-direxpand-default' |
9583 | Cause the 'direxpand' shell option (*note The Shopt Builtin::) to | |
ad4aef08 CR |
9584 | be enabled by default when the shell starts. It is normally |
9585 | disabled by default. | |
9586 | ||
8a0829e9 CR |
9587 | '--enable-directory-stack' |
9588 | Include support for a 'csh'-like directory stack and the 'pushd', | |
9589 | 'popd', and 'dirs' builtins (*note The Directory Stack::). | |
ccc6cda3 | 9590 | |
8a0829e9 CR |
9591 | '--enable-disabled-builtins' |
9592 | Allow builtin commands to be invoked via 'builtin xxx' even after | |
9593 | 'xxx' has been disabled using 'enable -n xxx'. See *note Bash | |
9594 | Builtins::, for details of the 'builtin' and 'enable' builtin | |
bb70624e | 9595 | commands. |
ccc6cda3 | 9596 | |
8a0829e9 CR |
9597 | '--enable-dparen-arithmetic' |
9598 | Include support for the '((...))' command (*note Conditional | |
28ef6c31 | 9599 | Constructs::). |
ccc6cda3 | 9600 | |
8a0829e9 | 9601 | '--enable-extended-glob' |
bb70624e | 9602 | Include support for the extended pattern matching features |
6a8fd0ed | 9603 | described above under *note Pattern Matching::. |
ccc6cda3 | 9604 | |
8a0829e9 | 9605 | '--enable-extended-glob-default' |
8f714a7c CR |
9606 | Set the default value of the EXTGLOB shell option described above |
9607 | under *note The Shopt Builtin:: to be enabled. | |
9608 | ||
8a0829e9 CR |
9609 | '--enable-function-import' |
9610 | Include support for importing function definitions exported by | |
9611 | another instance of the shell from the environment. This option is | |
9612 | enabled by default. | |
9613 | ||
9614 | '--enable-glob-asciirange-default' | |
1101193a | 9615 | Set the default value of the GLOBASCIIRANGES shell option described |
8a0829e9 CR |
9616 | above under *note The Shopt Builtin:: to be enabled. This controls |
9617 | the behavior of character ranges when used in pattern matching | |
9618 | bracket expressions. | |
1101193a | 9619 | |
8a0829e9 CR |
9620 | '--enable-help-builtin' |
9621 | Include the 'help' builtin, which displays help on shell builtins | |
28ef6c31 | 9622 | and variables (*note Bash Builtins::). |
ccc6cda3 | 9623 | |
8a0829e9 CR |
9624 | '--enable-history' |
9625 | Include command history and the 'fc' and 'history' builtin commands | |
9626 | (*note Bash History Facilities::). | |
ccc6cda3 | 9627 | |
8a0829e9 CR |
9628 | '--enable-job-control' |
9629 | This enables the job control features (*note Job Control::), if the | |
9630 | operating system supports them. | |
ccc6cda3 | 9631 | |
8a0829e9 | 9632 | '--enable-multibyte' |
d3a24ed2 CR |
9633 | This enables support for multibyte characters if the operating |
9634 | system provides the necessary support. | |
9635 | ||
8a0829e9 | 9636 | '--enable-net-redirections' |
bb70624e | 9637 | This enables the special handling of filenames of the form |
8a0829e9 | 9638 | '/dev/tcp/HOST/PORT' and '/dev/udp/HOST/PORT' when used in |
28ef6c31 | 9639 | redirections (*note Redirections::). |
ccc6cda3 | 9640 | |
8a0829e9 | 9641 | '--enable-process-substitution' |
28ef6c31 JA |
9642 | This enables process substitution (*note Process Substitution::) if |
9643 | the operating system provides the necessary support. | |
ccc6cda3 | 9644 | |
8a0829e9 | 9645 | '--enable-progcomp' |
01ed5ba4 CR |
9646 | Enable the programmable completion facilities (*note Programmable |
9647 | Completion::). If Readline is not enabled, this option has no | |
9648 | effect. | |
9649 | ||
8a0829e9 | 9650 | '--enable-prompt-string-decoding' |
bb70624e | 9651 | Turn on the interpretation of a number of backslash-escaped |
8a0829e9 | 9652 | characters in the '$PS1', '$PS2', '$PS3', and '$PS4' prompt |
122f603c CR |
9653 | strings. See *note Controlling the Prompt::, for a complete list |
9654 | of prompt string escape sequences. | |
ccc6cda3 | 9655 | |
8a0829e9 | 9656 | '--enable-readline' |
bb70624e | 9657 | Include support for command-line editing and history with the Bash |
28ef6c31 | 9658 | version of the Readline library (*note Command Line Editing::). |
ccc6cda3 | 9659 | |
8a0829e9 | 9660 | '--enable-restricted' |
bb70624e | 9661 | Include support for a "restricted shell". If this is enabled, |
8a0829e9 | 9662 | Bash, when called as 'rbash', enters a restricted mode. See *note |
bb70624e | 9663 | The Restricted Shell::, for a description of restricted mode. |
ccc6cda3 | 9664 | |
8a0829e9 CR |
9665 | '--enable-select' |
9666 | Include the 'select' compound command, which allows the generation | |
54a1fa7c | 9667 | of simple menus (*note Conditional Constructs::). |
ccc6cda3 | 9668 | |
8a0829e9 CR |
9669 | '--enable-separate-helpfiles' |
9670 | Use external files for the documentation displayed by the 'help' | |
01ed5ba4 CR |
9671 | builtin instead of storing the text internally. |
9672 | ||
8a0829e9 CR |
9673 | '--enable-single-help-strings' |
9674 | Store the text displayed by the 'help' builtin as a single string | |
01ed5ba4 | 9675 | for each help topic. This aids in translating the text to |
8a0829e9 CR |
9676 | different languages. You may need to disable this if your compiler |
9677 | cannot handle very long string literals. | |
01ed5ba4 | 9678 | |
8a0829e9 | 9679 | '--enable-strict-posix-default' |
1c72c0cd CR |
9680 | Make Bash POSIX-conformant by default (*note Bash POSIX Mode::). |
9681 | ||
8a0829e9 CR |
9682 | '--enable-usg-echo-default' |
9683 | A synonym for '--enable-xpg-echo-default'. | |
ccc6cda3 | 9684 | |
8a0829e9 CR |
9685 | '--enable-xpg-echo-default' |
9686 | Make the 'echo' builtin expand backslash-escaped characters by | |
9687 | default, without requiring the '-e' option. This sets the default | |
9688 | value of the 'xpg_echo' shell option to 'on', which makes the Bash | |
9689 | 'echo' behave more like the version specified in the Single Unix | |
9690 | Specification, version 3. *Note Bash Builtins::, for a description | |
9691 | of the escape sequences that 'echo' recognizes. | |
ccc6cda3 | 9692 | |
8a0829e9 CR |
9693 | The file 'config-top.h' contains C Preprocessor '#define' statements |
9694 | for options which are not settable from 'configure'. Some of these are | |
9695 | not meant to be changed; beware of the consequences if you do. Read the | |
9696 | comments associated with each definition for more information about its | |
9697 | effect. | |
ccc6cda3 | 9698 | |
bb70624e JA |
9699 | \1f |
9700 | File: bashref.info, Node: Reporting Bugs, Next: Major Differences From The Bourne Shell, Prev: Installing Bash, Up: Top | |
d166f048 | 9701 | |
37c41ab1 CR |
9702 | Appendix A Reporting Bugs |
9703 | ************************* | |
ccc6cda3 | 9704 | |
37c41ab1 | 9705 | Please report all bugs you find in Bash. But first, you should make |
bb70624e | 9706 | sure that it really is a bug, and that it appears in the latest version |
d3a24ed2 | 9707 | of Bash. The latest version of Bash is always available for FTP from |
8a0829e9 | 9708 | <ftp://ftp.gnu.org/pub/gnu/bash/>. |
ccc6cda3 | 9709 | |
bb70624e | 9710 | Once you have determined that a bug actually exists, use the |
8a0829e9 CR |
9711 | 'bashbug' command to submit a bug report. If you have a fix, you are |
9712 | encouraged to mail that as well! Suggestions and 'philosophical' bug | |
bb70624e | 9713 | reports may be mailed to <bug-bash@gnu.org> or posted to the Usenet |
8a0829e9 | 9714 | newsgroup 'gnu.bash.bug'. |
ccc6cda3 | 9715 | |
bb70624e JA |
9716 | All bug reports should include: |
9717 | * The version number of Bash. | |
bb70624e | 9718 | * The hardware and operating system. |
bb70624e | 9719 | * The compiler used to compile Bash. |
bb70624e | 9720 | * A description of the bug behaviour. |
8a0829e9 | 9721 | * A short script or 'recipe' which exercises the bug and may be used |
bb70624e | 9722 | to reproduce it. |
ccc6cda3 | 9723 | |
8a0829e9 | 9724 | 'bashbug' inserts the first three items automatically into the template |
bb70624e JA |
9725 | it provides for filing a bug report. |
9726 | ||
ad4aef08 | 9727 | Please send all reports concerning this manual to <bug-bash@gnu.org>. |
ccc6cda3 JA |
9728 | |
9729 | \1f | |
c2a47ea9 | 9730 | File: bashref.info, Node: Major Differences From The Bourne Shell, Next: GNU Free Documentation License, Prev: Reporting Bugs, Up: Top |
ccc6cda3 | 9731 | |
37c41ab1 CR |
9732 | Appendix B Major Differences From The Bourne Shell |
9733 | ************************************************** | |
ccc6cda3 | 9734 | |
37c41ab1 | 9735 | Bash implements essentially the same grammar, parameter and variable |
bb70624e | 9736 | expansion, redirection, and quoting as the Bourne Shell. Bash uses the |
ac18b312 CR |
9737 | POSIX standard as the specification of how these features are to be |
9738 | implemented. There are some differences between the traditional Bourne | |
9739 | shell and Bash; this section quickly details the differences of | |
bb70624e | 9740 | significance. A number of these differences are explained in greater |
8a0829e9 | 9741 | depth in previous sections. This section uses the version of 'sh' |
1c72c0cd CR |
9742 | included in SVR4.2 (the last version of the historical Bourne shell) as |
9743 | the baseline reference. | |
ccc6cda3 | 9744 | |
bb70624e | 9745 | * Bash is POSIX-conformant, even where the POSIX specification |
8a0829e9 | 9746 | differs from traditional 'sh' behavior (*note Bash POSIX Mode::). |
ccc6cda3 | 9747 | |
bb70624e | 9748 | * Bash has multi-character invocation options (*note Invoking |
28ef6c31 | 9749 | Bash::). |
ccc6cda3 | 9750 | |
28ef6c31 | 9751 | * Bash has command-line editing (*note Command Line Editing::) and |
8a0829e9 | 9752 | the 'bind' builtin. |
ccc6cda3 | 9753 | |
bb70624e | 9754 | * Bash provides a programmable word completion mechanism (*note |
8a0829e9 CR |
9755 | Programmable Completion::), and builtin commands 'complete', |
9756 | 'compgen', and 'compopt', to manipulate it. | |
ccc6cda3 | 9757 | |
28ef6c31 | 9758 | * Bash has command history (*note Bash History Facilities::) and the |
8a0829e9 | 9759 | 'history' and 'fc' builtins to manipulate it. The Bash history |
5e13499c | 9760 | list maintains timestamp information and uses the value of the |
8a0829e9 | 9761 | 'HISTTIMEFORMAT' variable to display it. |
ccc6cda3 | 9762 | |
8a0829e9 | 9763 | * Bash implements 'csh'-like history expansion (*note History |
28ef6c31 | 9764 | Interaction::). |
ccc6cda3 | 9765 | |
28ef6c31 | 9766 | * Bash has one-dimensional array variables (*note Arrays::), and the |
bb70624e JA |
9767 | appropriate variable expansions and assignment syntax to use them. |
9768 | Several of the Bash builtins take options to act on arrays. Bash | |
9769 | provides a number of built-in array variables. | |
ccc6cda3 | 9770 | |
8a0829e9 CR |
9771 | * The '$'...'' quoting syntax, which expands ANSI-C backslash-escaped |
9772 | characters in the text between the single quotes, is supported | |
9773 | (*note ANSI-C Quoting::). | |
ccc6cda3 | 9774 | |
8a0829e9 CR |
9775 | * Bash supports the '$"..."' quoting syntax to do locale-specific |
9776 | translation of the characters between the double quotes. The '-D', | |
9777 | '--dump-strings', and '--dump-po-strings' invocation options list | |
9778 | the translatable strings found in a script (*note Locale | |
28ef6c31 | 9779 | Translation::). |
ccc6cda3 | 9780 | |
8a0829e9 CR |
9781 | * Bash implements the '!' keyword to negate the return value of a |
9782 | pipeline (*note Pipelines::). Very useful when an 'if' statement | |
9783 | needs to act only if a test fails. The Bash '-o pipefail' option | |
9784 | to 'set' will cause a pipeline to return a failure status if any | |
1c72c0cd | 9785 | command fails. |
ccc6cda3 | 9786 | |
8a0829e9 | 9787 | * Bash has the 'time' reserved word and command timing (*note |
28ef6c31 | 9788 | Pipelines::). The display of the timing statistics may be |
8a0829e9 | 9789 | controlled with the 'TIMEFORMAT' variable. |
ccc6cda3 | 9790 | |
8a0829e9 | 9791 | * Bash implements the 'for (( EXPR1 ; EXPR2 ; EXPR3 ))' arithmetic |
bb70624e | 9792 | for command, similar to the C language (*note Looping |
28ef6c31 | 9793 | Constructs::). |
ccc6cda3 | 9794 | |
8a0829e9 | 9795 | * Bash includes the 'select' compound command, which allows the |
28ef6c31 | 9796 | generation of simple menus (*note Conditional Constructs::). |
ccc6cda3 | 9797 | |
8a0829e9 CR |
9798 | * Bash includes the '[[' compound command, which makes conditional |
9799 | testing part of the shell grammar (*note Conditional Constructs::), | |
9800 | including optional regular expression matching. | |
1c72c0cd | 9801 | |
8a0829e9 CR |
9802 | * Bash provides optional case-insensitive matching for the 'case' and |
9803 | '[[' constructs. | |
ccc6cda3 | 9804 | |
28ef6c31 JA |
9805 | * Bash includes brace expansion (*note Brace Expansion::) and tilde |
9806 | expansion (*note Tilde Expansion::). | |
ccc6cda3 | 9807 | |
8a0829e9 | 9808 | * Bash implements command aliases and the 'alias' and 'unalias' |
28ef6c31 | 9809 | builtins (*note Aliases::). |
ccc6cda3 | 9810 | |
8a0829e9 | 9811 | * Bash provides shell arithmetic, the '((' compound command (*note |
28ef6c31 JA |
9812 | Conditional Constructs::), and arithmetic expansion (*note Shell |
9813 | Arithmetic::). | |
ccc6cda3 | 9814 | |
bb70624e JA |
9815 | * Variables present in the shell's initial environment are |
9816 | automatically exported to child processes. The Bourne shell does | |
9817 | not normally do this unless the variables are explicitly marked | |
8a0829e9 | 9818 | using the 'export' command. |
ccc6cda3 | 9819 | |
8a0829e9 | 9820 | * Bash supports the '+=' assignment operator, which appends to the |
1c72c0cd CR |
9821 | value of the variable named on the left hand side. |
9822 | ||
8a0829e9 | 9823 | * Bash includes the POSIX pattern removal '%', '#', '%%' and '##' |
bb70624e | 9824 | expansions to remove leading or trailing substrings from variable |
28ef6c31 | 9825 | values (*note Shell Parameter Expansion::). |
ccc6cda3 | 9826 | |
8a0829e9 | 9827 | * The expansion '${#xx}', which returns the length of '${xx}', is |
28ef6c31 | 9828 | supported (*note Shell Parameter Expansion::). |
ccc6cda3 | 9829 | |
8a0829e9 CR |
9830 | * The expansion '${var:'OFFSET'[:'LENGTH']}', which expands to the |
9831 | substring of 'var''s value of length LENGTH, beginning at OFFSET, | |
28ef6c31 | 9832 | is present (*note Shell Parameter Expansion::). |
ccc6cda3 | 9833 | |
8a0829e9 CR |
9834 | * The expansion '${var/[/]'PATTERN'[/'REPLACEMENT']}', which matches |
9835 | PATTERN and replaces it with REPLACEMENT in the value of 'var', is | |
28ef6c31 | 9836 | available (*note Shell Parameter Expansion::). |
ccc6cda3 | 9837 | |
8a0829e9 | 9838 | * The expansion '${!PREFIX*}' expansion, which expands to the names |
bb70624e | 9839 | of all shell variables whose names begin with PREFIX, is available |
28ef6c31 | 9840 | (*note Shell Parameter Expansion::). |
ccc6cda3 | 9841 | |
8a0829e9 | 9842 | * Bash has INDIRECT variable expansion using '${!word}' (*note Shell |
28ef6c31 | 9843 | Parameter Expansion::). |
ccc6cda3 | 9844 | |
8a0829e9 | 9845 | * Bash can expand positional parameters beyond '$9' using '${NUM}'. |
ccc6cda3 | 9846 | |
8a0829e9 CR |
9847 | * The POSIX '$()' form of command substitution is implemented (*note |
9848 | Command Substitution::), and preferred to the Bourne shell's '``' | |
bb70624e | 9849 | (which is also implemented for backwards compatibility). |
ccc6cda3 | 9850 | |
28ef6c31 | 9851 | * Bash has process substitution (*note Process Substitution::). |
ccc6cda3 | 9852 | |
8a0829e9 CR |
9853 | * Bash automatically assigns variables that provide information about |
9854 | the current user ('UID', 'EUID', and 'GROUPS'), the current host | |
9855 | ('HOSTTYPE', 'OSTYPE', 'MACHTYPE', and 'HOSTNAME'), and the | |
9856 | instance of Bash that is running ('BASH', 'BASH_VERSION', and | |
9857 | 'BASH_VERSINFO'). *Note Bash Variables::, for details. | |
ccc6cda3 | 9858 | |
8a0829e9 CR |
9859 | * The 'IFS' variable is used to split only the results of expansion, |
9860 | not all words (*note Word Splitting::). This closes a longstanding | |
9861 | shell security hole. | |
ccc6cda3 | 9862 | |
8a0829e9 | 9863 | * The filename expansion bracket expression code uses '!' and '^' to |
ad4aef08 | 9864 | negate the set of characters between the brackets. The Bourne |
8a0829e9 | 9865 | shell uses only '!'. |
ad4aef08 | 9866 | |
ac18b312 CR |
9867 | * Bash implements the full set of POSIX filename expansion operators, |
9868 | including CHARACTER CLASSES, EQUIVALENCE CLASSES, and COLLATING | |
9869 | SYMBOLS (*note Filename Expansion::). | |
ccc6cda3 | 9870 | |
bb70624e | 9871 | * Bash implements extended pattern matching features when the |
8a0829e9 | 9872 | 'extglob' shell option is enabled (*note Pattern Matching::). |
ccc6cda3 | 9873 | |
bb70624e | 9874 | * It is possible to have a variable and a function with the same |
8a0829e9 | 9875 | name; 'sh' does not separate the two name spaces. |
ccc6cda3 | 9876 | |
bb70624e | 9877 | * Bash functions are permitted to have local variables using the |
8a0829e9 | 9878 | 'local' builtin, and thus useful recursive functions may be written |
28ef6c31 | 9879 | (*note Bash Builtins::). |
ccc6cda3 | 9880 | |
bb70624e | 9881 | * Variable assignments preceding commands affect only that command, |
8a0829e9 | 9882 | even builtins and functions (*note Environment::). In 'sh', all |
bb70624e JA |
9883 | variable assignments preceding commands are global unless the |
9884 | command is executed from the file system. | |
ccc6cda3 | 9885 | |
bb70624e | 9886 | * Bash performs filename expansion on filenames specified as operands |
28ef6c31 | 9887 | to input and output redirection operators (*note Redirections::). |
ccc6cda3 | 9888 | |
8a0829e9 CR |
9889 | * Bash contains the '<>' redirection operator, allowing a file to be |
9890 | opened for both reading and writing, and the '&>' redirection | |
bb70624e | 9891 | operator, for directing standard output and standard error to the |
28ef6c31 | 9892 | same file (*note Redirections::). |
d166f048 | 9893 | |
8a0829e9 | 9894 | * Bash includes the '<<<' redirection operator, allowing a string to |
1c72c0cd CR |
9895 | be used as the standard input to a command. |
9896 | ||
8a0829e9 | 9897 | * Bash implements the '[n]<&WORD' and '[n]>&WORD' redirection |
1c72c0cd CR |
9898 | operators, which move one file descriptor to another. |
9899 | ||
bb70624e | 9900 | * Bash treats a number of filenames specially when they are used in |
28ef6c31 | 9901 | redirection operators (*note Redirections::). |
ccc6cda3 | 9902 | |
bb70624e | 9903 | * Bash can open network connections to arbitrary machines and |
28ef6c31 | 9904 | services with the redirection operators (*note Redirections::). |
ccc6cda3 | 9905 | |
8a0829e9 CR |
9906 | * The 'noclobber' option is available to avoid overwriting existing |
9907 | files with output redirection (*note The Set Builtin::). The '>|' | |
9908 | redirection operator may be used to override 'noclobber'. | |
ccc6cda3 | 9909 | |
8a0829e9 CR |
9910 | * The Bash 'cd' and 'pwd' builtins (*note Bourne Shell Builtins::) |
9911 | each take '-L' and '-P' options to switch between logical and | |
bb70624e | 9912 | physical modes. |
b72432fd | 9913 | |
bb70624e JA |
9914 | * Bash allows a function to override a builtin with the same name, |
9915 | and provides access to that builtin's functionality within the | |
8a0829e9 | 9916 | function via the 'builtin' and 'command' builtins (*note Bash |
28ef6c31 | 9917 | Builtins::). |
ccc6cda3 | 9918 | |
8a0829e9 | 9919 | * The 'command' builtin allows selective disabling of functions when |
28ef6c31 | 9920 | command lookup is performed (*note Bash Builtins::). |
ccc6cda3 | 9921 | |
8a0829e9 | 9922 | * Individual builtins may be enabled or disabled using the 'enable' |
28ef6c31 | 9923 | builtin (*note Bash Builtins::). |
cce855bc | 9924 | |
8a0829e9 | 9925 | * The Bash 'exec' builtin takes additional options that allow users |
bb70624e JA |
9926 | to control the contents of the environment passed to the executed |
9927 | command, and what the zeroth argument to the command is to be | |
28ef6c31 | 9928 | (*note Bourne Shell Builtins::). |
cce855bc | 9929 | |
bb70624e | 9930 | * Shell functions may be exported to children via the environment |
8a0829e9 | 9931 | using 'export -f' (*note Shell Functions::). |
cce855bc | 9932 | |
8a0829e9 CR |
9933 | * The Bash 'export', 'readonly', and 'declare' builtins can take a |
9934 | '-f' option to act on shell functions, a '-p' option to display | |
bb70624e | 9935 | variables with various attributes set in a format that can be used |
8a0829e9 CR |
9936 | as shell input, a '-n' option to remove various variable |
9937 | attributes, and 'name=value' arguments to set variable attributes | |
bb70624e | 9938 | and values simultaneously. |
ccc6cda3 | 9939 | |
8a0829e9 | 9940 | * The Bash 'hash' builtin allows a name to be associated with an |
bb70624e | 9941 | arbitrary filename, even when that filename cannot be found by |
8a0829e9 | 9942 | searching the '$PATH', using 'hash -p' (*note Bourne Shell |
28ef6c31 | 9943 | Builtins::). |
ccc6cda3 | 9944 | |
8a0829e9 | 9945 | * Bash includes a 'help' builtin for quick reference to shell |
28ef6c31 | 9946 | facilities (*note Bash Builtins::). |
ccc6cda3 | 9947 | |
8a0829e9 | 9948 | * The 'printf' builtin is available to display formatted output |
28ef6c31 | 9949 | (*note Bash Builtins::). |
ccc6cda3 | 9950 | |
8a0829e9 CR |
9951 | * The Bash 'read' builtin (*note Bash Builtins::) will read a line |
9952 | ending in '\' with the '-r' option, and will use the 'REPLY' | |
9953 | variable as a default if no non-option arguments are supplied. The | |
9954 | Bash 'read' builtin also accepts a prompt string with the '-p' | |
9955 | option and will use Readline to obtain the line when given the '-e' | |
9956 | option. The 'read' builtin also has additional options to control | |
9957 | input: the '-s' option will turn off echoing of input characters as | |
9958 | they are read, the '-t' option will allow 'read' to time out if | |
9959 | input does not arrive within a specified number of seconds, the | |
9960 | '-n' option will allow reading only a specified number of | |
9961 | characters rather than a full line, and the '-d' option will read | |
9962 | until a particular character rather than newline. | |
9963 | ||
9964 | * The 'return' builtin may be used to abort execution of scripts | |
9965 | executed with the '.' or 'source' builtins (*note Bourne Shell | |
28ef6c31 | 9966 | Builtins::). |
d166f048 | 9967 | |
8a0829e9 CR |
9968 | * Bash includes the 'shopt' builtin, for finer control of shell |
9969 | optional capabilities (*note The Shopt Builtin::), and allows these | |
9970 | options to be set and unset at shell invocation (*note Invoking | |
9971 | Bash::). | |
d166f048 | 9972 | |
8a0829e9 | 9973 | * Bash has much more optional behavior controllable with the 'set' |
28ef6c31 | 9974 | builtin (*note The Set Builtin::). |
cce855bc | 9975 | |
8a0829e9 | 9976 | * The '-x' ('xtrace') option displays commands other than simple |
5e13499c CR |
9977 | commands when performing an execution trace (*note The Set |
9978 | Builtin::). | |
9979 | ||
8a0829e9 | 9980 | * The 'test' builtin (*note Bourne Shell Builtins::) is slightly |
bb70624e JA |
9981 | different, as it implements the POSIX algorithm, which specifies |
9982 | the behavior based on the number of arguments. | |
ccc6cda3 | 9983 | |
8a0829e9 | 9984 | * Bash includes the 'caller' builtin, which displays the context of |
5e13499c | 9985 | any active subroutine call (a shell function or a script executed |
8a0829e9 | 9986 | with the '.' or 'source' builtins). This supports the bash |
5e13499c CR |
9987 | debugger. |
9988 | ||
8a0829e9 CR |
9989 | * The 'trap' builtin (*note Bourne Shell Builtins::) allows a 'DEBUG' |
9990 | pseudo-signal specification, similar to 'EXIT'. Commands specified | |
9991 | with a 'DEBUG' trap are executed before every simple command, 'for' | |
9992 | command, 'case' command, 'select' command, every arithmetic 'for' | |
9993 | command, and before the first command executes in a shell function. | |
9994 | The 'DEBUG' trap is not inherited by shell functions unless the | |
9995 | function has been given the 'trace' attribute or the 'functrace' | |
9996 | option has been enabled using the 'shopt' builtin. The 'extdebug' | |
9997 | shell option has additional effects on the 'DEBUG' trap. | |
9998 | ||
9999 | The 'trap' builtin (*note Bourne Shell Builtins::) allows an 'ERR' | |
10000 | pseudo-signal specification, similar to 'EXIT' and 'DEBUG'. | |
10001 | Commands specified with an 'ERR' trap are executed after a simple | |
10002 | command fails, with a few exceptions. The 'ERR' trap is not | |
10003 | inherited by shell functions unless the '-o errtrace' option to the | |
10004 | 'set' builtin is enabled. | |
10005 | ||
10006 | The 'trap' builtin (*note Bourne Shell Builtins::) allows a | |
10007 | 'RETURN' pseudo-signal specification, similar to 'EXIT' and | |
10008 | 'DEBUG'. Commands specified with an 'RETURN' trap are executed | |
d3a24ed2 | 10009 | before execution resumes after a shell function or a shell script |
8a0829e9 CR |
10010 | executed with '.' or 'source' returns. The 'RETURN' trap is not |
10011 | inherited by shell functions unless the function has been given the | |
10012 | 'trace' attribute or the 'functrace' option has been enabled using | |
10013 | the 'shopt' builtin. | |
f73dda09 | 10014 | |
8a0829e9 | 10015 | * The Bash 'type' builtin is more extensive and gives more |
28ef6c31 | 10016 | information about the names it finds (*note Bash Builtins::). |
cce855bc | 10017 | |
8a0829e9 CR |
10018 | * The Bash 'umask' builtin permits a '-p' option to cause the output |
10019 | to be displayed in the form of a 'umask' command that may be reused | |
10020 | as input (*note Bourne Shell Builtins::). | |
d166f048 | 10021 | |
8a0829e9 CR |
10022 | * Bash implements a 'csh'-like directory stack, and provides the |
10023 | 'pushd', 'popd', and 'dirs' builtins to manipulate it (*note The | |
10024 | Directory Stack::). Bash also makes the directory stack visible as | |
10025 | the value of the 'DIRSTACK' shell variable. | |
d166f048 | 10026 | |
bb70624e | 10027 | * Bash interprets special backslash-escaped characters in the prompt |
122f603c | 10028 | strings when interactive (*note Controlling the Prompt::). |
d166f048 | 10029 | |
bb70624e | 10030 | * The Bash restricted mode is more useful (*note The Restricted |
28ef6c31 | 10031 | Shell::); the SVR4.2 shell restricted mode is too limited. |
ccc6cda3 | 10032 | |
8a0829e9 | 10033 | * The 'disown' builtin can remove a job from the internal shell job |
28ef6c31 | 10034 | table (*note Job Control Builtins::) or suppress the sending of |
8a0829e9 | 10035 | 'SIGHUP' to a job when the shell exits as the result of a 'SIGHUP'. |
ccc6cda3 | 10036 | |
1c72c0cd CR |
10037 | * Bash includes a number of features to support a separate debugger |
10038 | for shell scripts. | |
10039 | ||
8a0829e9 CR |
10040 | * The SVR4.2 shell has two privilege-related builtins ('mldmode' and |
10041 | 'priv') not present in Bash. | |
ccc6cda3 | 10042 | |
8a0829e9 | 10043 | * Bash does not have the 'stop' or 'newgrp' builtins. |
d166f048 | 10044 | |
8a0829e9 | 10045 | * Bash does not use the 'SHACCT' variable or perform shell |
bb70624e | 10046 | accounting. |
d166f048 | 10047 | |
8a0829e9 | 10048 | * The SVR4.2 'sh' uses a 'TIMEOUT' variable like Bash uses 'TMOUT'. |
28ef6c31 | 10049 | |
6a8fd0ed | 10050 | More features unique to Bash may be found in *note Bash Features::. |
ccc6cda3 | 10051 | |
37c41ab1 CR |
10052 | B.1 Implementation Differences From The SVR4.2 Shell |
10053 | ==================================================== | |
ccc6cda3 | 10054 | |
37c41ab1 CR |
10055 | Since Bash is a completely new implementation, it does not suffer from |
10056 | many of the limitations of the SVR4.2 shell. For instance: | |
ccc6cda3 | 10057 | |
bb70624e | 10058 | * Bash does not fork a subshell when redirecting into or out of a |
8a0829e9 | 10059 | shell control structure such as an 'if' or 'while' statement. |
ccc6cda3 | 10060 | |
bb70624e | 10061 | * Bash does not allow unbalanced quotes. The SVR4.2 shell will |
8a0829e9 | 10062 | silently insert a needed closing quote at 'EOF' under certain |
bb70624e | 10063 | circumstances. This can be the cause of some hard-to-find errors. |
ccc6cda3 | 10064 | |
bb70624e | 10065 | * The SVR4.2 shell uses a baroque memory management scheme based on |
8a0829e9 CR |
10066 | trapping 'SIGSEGV'. If the shell is started from a process with |
10067 | 'SIGSEGV' blocked (e.g., by using the 'system()' C library function | |
10068 | call), it misbehaves badly. | |
ccc6cda3 | 10069 | |
bb70624e | 10070 | * In a questionable attempt at security, the SVR4.2 shell, when |
8a0829e9 | 10071 | invoked without the '-p' option, will alter its real and effective |
bb70624e JA |
10072 | UID and GID if they are less than some magic threshold value, |
10073 | commonly 100. This can lead to unexpected results. | |
ccc6cda3 | 10074 | |
8a0829e9 CR |
10075 | * The SVR4.2 shell does not allow users to trap 'SIGSEGV', 'SIGALRM', |
10076 | or 'SIGCHLD'. | |
ccc6cda3 | 10077 | |
8a0829e9 CR |
10078 | * The SVR4.2 shell does not allow the 'IFS', 'MAILCHECK', 'PATH', |
10079 | 'PS1', or 'PS2' variables to be unset. | |
ccc6cda3 | 10080 | |
8a0829e9 | 10081 | * The SVR4.2 shell treats '^' as the undocumented equivalent of '|'. |
ccc6cda3 | 10082 | |
8a0829e9 CR |
10083 | * Bash allows multiple option arguments when it is invoked ('-x -v'); |
10084 | the SVR4.2 shell allows only one option argument ('-xv'). In fact, | |
10085 | some versions of the shell dump core if the second argument begins | |
10086 | with a '-'. | |
ccc6cda3 | 10087 | |
bb70624e | 10088 | * The SVR4.2 shell exits a script if any builtin fails; Bash exits a |
ac18b312 CR |
10089 | script only if one of the POSIX special builtins fails, and only |
10090 | for certain failures, as enumerated in the POSIX standard. | |
ccc6cda3 | 10091 | |
8a0829e9 | 10092 | * The SVR4.2 shell behaves differently when invoked as 'jsh' (it |
bb70624e | 10093 | turns on job control). |
ccc6cda3 JA |
10094 | |
10095 | \1f | |
c2a47ea9 | 10096 | File: bashref.info, Node: GNU Free Documentation License, Next: Indexes, Prev: Major Differences From The Bourne Shell, Up: Top |
d3a24ed2 | 10097 | |
c2a47ea9 CR |
10098 | Appendix C GNU Free Documentation License |
10099 | ***************************************** | |
d3a24ed2 | 10100 | |
1231ac47 | 10101 | Version 1.3, 3 November 2008 |
37c41ab1 | 10102 | |
1231ac47 | 10103 | Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. |
8a0829e9 | 10104 | <http://fsf.org/> |
37c41ab1 | 10105 | |
d3a24ed2 CR |
10106 | Everyone is permitted to copy and distribute verbatim copies |
10107 | of this license document, but changing it is not allowed. | |
10108 | ||
10109 | 0. PREAMBLE | |
10110 | ||
10111 | The purpose of this License is to make a manual, textbook, or other | |
10112 | functional and useful document "free" in the sense of freedom: to | |
10113 | assure everyone the effective freedom to copy and redistribute it, | |
10114 | with or without modifying it, either commercially or | |
10115 | noncommercially. Secondarily, this License preserves for the | |
10116 | author and publisher a way to get credit for their work, while not | |
10117 | being considered responsible for modifications made by others. | |
10118 | ||
10119 | This License is a kind of "copyleft", which means that derivative | |
10120 | works of the document must themselves be free in the same sense. | |
10121 | It complements the GNU General Public License, which is a copyleft | |
10122 | license designed for free software. | |
10123 | ||
10124 | We have designed this License in order to use it for manuals for | |
10125 | free software, because free software needs free documentation: a | |
10126 | free program should come with manuals providing the same freedoms | |
10127 | that the software does. But this License is not limited to | |
10128 | software manuals; it can be used for any textual work, regardless | |
8a0829e9 CR |
10129 | of subject matter or whether it is published as a printed book. We |
10130 | recommend this License principally for works whose purpose is | |
d3a24ed2 CR |
10131 | instruction or reference. |
10132 | ||
10133 | 1. APPLICABILITY AND DEFINITIONS | |
10134 | ||
10135 | This License applies to any manual or other work, in any medium, | |
8a0829e9 CR |
10136 | that contains a notice placed by the copyright holder saying it can |
10137 | be distributed under the terms of this License. Such a notice | |
d3a24ed2 CR |
10138 | grants a world-wide, royalty-free license, unlimited in duration, |
10139 | to use that work under the conditions stated herein. The | |
10140 | "Document", below, refers to any such manual or work. Any member | |
8a0829e9 CR |
10141 | of the public is a licensee, and is addressed as "you". You accept |
10142 | the license if you copy, modify or distribute the work in a way | |
10143 | requiring permission under copyright law. | |
d3a24ed2 CR |
10144 | |
10145 | A "Modified Version" of the Document means any work containing the | |
10146 | Document or a portion of it, either copied verbatim, or with | |
10147 | modifications and/or translated into another language. | |
10148 | ||
10149 | A "Secondary Section" is a named appendix or a front-matter section | |
10150 | of the Document that deals exclusively with the relationship of the | |
10151 | publishers or authors of the Document to the Document's overall | |
10152 | subject (or to related matters) and contains nothing that could | |
10153 | fall directly within that overall subject. (Thus, if the Document | |
10154 | is in part a textbook of mathematics, a Secondary Section may not | |
10155 | explain any mathematics.) The relationship could be a matter of | |
10156 | historical connection with the subject or with related matters, or | |
10157 | of legal, commercial, philosophical, ethical or political position | |
10158 | regarding them. | |
10159 | ||
10160 | The "Invariant Sections" are certain Secondary Sections whose | |
8a0829e9 CR |
10161 | titles are designated, as being those of Invariant Sections, in the |
10162 | notice that says that the Document is released under this License. | |
10163 | If a section does not fit the above definition of Secondary then it | |
10164 | is not allowed to be designated as Invariant. The Document may | |
10165 | contain zero Invariant Sections. If the Document does not identify | |
10166 | any Invariant Sections then there are none. | |
d3a24ed2 CR |
10167 | |
10168 | The "Cover Texts" are certain short passages of text that are | |
10169 | listed, as Front-Cover Texts or Back-Cover Texts, in the notice | |
10170 | that says that the Document is released under this License. A | |
10171 | Front-Cover Text may be at most 5 words, and a Back-Cover Text may | |
10172 | be at most 25 words. | |
10173 | ||
10174 | A "Transparent" copy of the Document means a machine-readable copy, | |
10175 | represented in a format whose specification is available to the | |
10176 | general public, that is suitable for revising the document | |
8a0829e9 CR |
10177 | straightforwardly with generic text editors or (for images composed |
10178 | of pixels) generic paint programs or (for drawings) some widely | |
10179 | available drawing editor, and that is suitable for input to text | |
10180 | formatters or for automatic translation to a variety of formats | |
10181 | suitable for input to text formatters. A copy made in an otherwise | |
10182 | Transparent file format whose markup, or absence of markup, has | |
10183 | been arranged to thwart or discourage subsequent modification by | |
10184 | readers is not Transparent. An image format is not Transparent if | |
10185 | used for any substantial amount of text. A copy that is not | |
10186 | "Transparent" is called "Opaque". | |
d3a24ed2 CR |
10187 | |
10188 | Examples of suitable formats for Transparent copies include plain | |
10189 | ASCII without markup, Texinfo input format, LaTeX input format, | |
8a0829e9 CR |
10190 | SGML or XML using a publicly available DTD, and standard-conforming |
10191 | simple HTML, PostScript or PDF designed for human modification. | |
10192 | Examples of transparent image formats include PNG, XCF and JPG. | |
10193 | Opaque formats include proprietary formats that can be read and | |
10194 | edited only by proprietary word processors, SGML or XML for which | |
10195 | the DTD and/or processing tools are not generally available, and | |
10196 | the machine-generated HTML, PostScript or PDF produced by some word | |
10197 | processors for output purposes only. | |
d3a24ed2 CR |
10198 | |
10199 | The "Title Page" means, for a printed book, the title page itself, | |
10200 | plus such following pages as are needed to hold, legibly, the | |
10201 | material this License requires to appear in the title page. For | |
10202 | works in formats which do not have any title page as such, "Title | |
10203 | Page" means the text near the most prominent appearance of the | |
10204 | work's title, preceding the beginning of the body of the text. | |
10205 | ||
1231ac47 CR |
10206 | The "publisher" means any person or entity that distributes copies |
10207 | of the Document to the public. | |
10208 | ||
d3a24ed2 CR |
10209 | A section "Entitled XYZ" means a named subunit of the Document |
10210 | whose title either is precisely XYZ or contains XYZ in parentheses | |
10211 | following text that translates XYZ in another language. (Here XYZ | |
10212 | stands for a specific section name mentioned below, such as | |
10213 | "Acknowledgements", "Dedications", "Endorsements", or "History".) | |
10214 | To "Preserve the Title" of such a section when you modify the | |
10215 | Document means that it remains a section "Entitled XYZ" according | |
10216 | to this definition. | |
10217 | ||
10218 | The Document may include Warranty Disclaimers next to the notice | |
10219 | which states that this License applies to the Document. These | |
10220 | Warranty Disclaimers are considered to be included by reference in | |
10221 | this License, but only as regards disclaiming warranties: any other | |
10222 | implication that these Warranty Disclaimers may have is void and | |
10223 | has no effect on the meaning of this License. | |
10224 | ||
10225 | 2. VERBATIM COPYING | |
10226 | ||
10227 | You may copy and distribute the Document in any medium, either | |
10228 | commercially or noncommercially, provided that this License, the | |
10229 | copyright notices, and the license notice saying this License | |
10230 | applies to the Document are reproduced in all copies, and that you | |
10231 | add no other conditions whatsoever to those of this License. You | |
10232 | may not use technical measures to obstruct or control the reading | |
10233 | or further copying of the copies you make or distribute. However, | |
10234 | you may accept compensation in exchange for copies. If you | |
8a0829e9 CR |
10235 | distribute a large enough number of copies you must also follow the |
10236 | conditions in section 3. | |
d3a24ed2 CR |
10237 | |
10238 | You may also lend copies, under the same conditions stated above, | |
10239 | and you may publicly display copies. | |
10240 | ||
10241 | 3. COPYING IN QUANTITY | |
10242 | ||
10243 | If you publish printed copies (or copies in media that commonly | |
10244 | have printed covers) of the Document, numbering more than 100, and | |
10245 | the Document's license notice requires Cover Texts, you must | |
10246 | enclose the copies in covers that carry, clearly and legibly, all | |
10247 | these Cover Texts: Front-Cover Texts on the front cover, and | |
10248 | Back-Cover Texts on the back cover. Both covers must also clearly | |
10249 | and legibly identify you as the publisher of these copies. The | |
8a0829e9 CR |
10250 | front cover must present the full title with all words of the title |
10251 | equally prominent and visible. You may add other material on the | |
10252 | covers in addition. Copying with changes limited to the covers, as | |
10253 | long as they preserve the title of the Document and satisfy these | |
10254 | conditions, can be treated as verbatim copying in other respects. | |
d3a24ed2 CR |
10255 | |
10256 | If the required texts for either cover are too voluminous to fit | |
10257 | legibly, you should put the first ones listed (as many as fit | |
10258 | reasonably) on the actual cover, and continue the rest onto | |
10259 | adjacent pages. | |
10260 | ||
10261 | If you publish or distribute Opaque copies of the Document | |
8a0829e9 CR |
10262 | numbering more than 100, you must either include a machine-readable |
10263 | Transparent copy along with each Opaque copy, or state in or with | |
10264 | each Opaque copy a computer-network location from which the general | |
10265 | network-using public has access to download using public-standard | |
10266 | network protocols a complete Transparent copy of the Document, free | |
10267 | of added material. If you use the latter option, you must take | |
10268 | reasonably prudent steps, when you begin distribution of Opaque | |
10269 | copies in quantity, to ensure that this Transparent copy will | |
10270 | remain thus accessible at the stated location until at least one | |
10271 | year after the last time you distribute an Opaque copy (directly or | |
10272 | through your agents or retailers) of that edition to the public. | |
d3a24ed2 CR |
10273 | |
10274 | It is requested, but not required, that you contact the authors of | |
8a0829e9 CR |
10275 | the Document well before redistributing any large number of copies, |
10276 | to give them a chance to provide you with an updated version of the | |
10277 | Document. | |
d3a24ed2 CR |
10278 | |
10279 | 4. MODIFICATIONS | |
10280 | ||
10281 | You may copy and distribute a Modified Version of the Document | |
10282 | under the conditions of sections 2 and 3 above, provided that you | |
8a0829e9 CR |
10283 | release the Modified Version under precisely this License, with the |
10284 | Modified Version filling the role of the Document, thus licensing | |
10285 | distribution and modification of the Modified Version to whoever | |
10286 | possesses a copy of it. In addition, you must do these things in | |
10287 | the Modified Version: | |
d3a24ed2 CR |
10288 | |
10289 | A. Use in the Title Page (and on the covers, if any) a title | |
8a0829e9 CR |
10290 | distinct from that of the Document, and from those of previous |
10291 | versions (which should, if there were any, be listed in the | |
10292 | History section of the Document). You may use the same title | |
10293 | as a previous version if the original publisher of that | |
10294 | version gives permission. | |
d3a24ed2 CR |
10295 | |
10296 | B. List on the Title Page, as authors, one or more persons or | |
10297 | entities responsible for authorship of the modifications in | |
10298 | the Modified Version, together with at least five of the | |
10299 | principal authors of the Document (all of its principal | |
10300 | authors, if it has fewer than five), unless they release you | |
10301 | from this requirement. | |
10302 | ||
10303 | C. State on the Title page the name of the publisher of the | |
10304 | Modified Version, as the publisher. | |
10305 | ||
10306 | D. Preserve all the copyright notices of the Document. | |
10307 | ||
10308 | E. Add an appropriate copyright notice for your modifications | |
10309 | adjacent to the other copyright notices. | |
10310 | ||
10311 | F. Include, immediately after the copyright notices, a license | |
10312 | notice giving the public permission to use the Modified | |
10313 | Version under the terms of this License, in the form shown in | |
10314 | the Addendum below. | |
10315 | ||
10316 | G. Preserve in that license notice the full lists of Invariant | |
10317 | Sections and required Cover Texts given in the Document's | |
10318 | license notice. | |
10319 | ||
10320 | H. Include an unaltered copy of this License. | |
10321 | ||
10322 | I. Preserve the section Entitled "History", Preserve its Title, | |
10323 | and add to it an item stating at least the title, year, new | |
8a0829e9 CR |
10324 | authors, and publisher of the Modified Version as given on the |
10325 | Title Page. If there is no section Entitled "History" in the | |
10326 | Document, create one stating the title, year, authors, and | |
10327 | publisher of the Document as given on its Title Page, then add | |
10328 | an item describing the Modified Version as stated in the | |
10329 | previous sentence. | |
d3a24ed2 CR |
10330 | |
10331 | J. Preserve the network location, if any, given in the Document | |
10332 | for public access to a Transparent copy of the Document, and | |
10333 | likewise the network locations given in the Document for | |
8a0829e9 CR |
10334 | previous versions it was based on. These may be placed in the |
10335 | "History" section. You may omit a network location for a work | |
10336 | that was published at least four years before the Document | |
10337 | itself, or if the original publisher of the version it refers | |
10338 | to gives permission. | |
d3a24ed2 CR |
10339 | |
10340 | K. For any section Entitled "Acknowledgements" or "Dedications", | |
8a0829e9 CR |
10341 | Preserve the Title of the section, and preserve in the section |
10342 | all the substance and tone of each of the contributor | |
d3a24ed2 CR |
10343 | acknowledgements and/or dedications given therein. |
10344 | ||
8a0829e9 CR |
10345 | L. Preserve all the Invariant Sections of the Document, unaltered |
10346 | in their text and in their titles. Section numbers or the | |
10347 | equivalent are not considered part of the section titles. | |
d3a24ed2 CR |
10348 | |
10349 | M. Delete any section Entitled "Endorsements". Such a section | |
10350 | may not be included in the Modified Version. | |
10351 | ||
10352 | N. Do not retitle any existing section to be Entitled | |
10353 | "Endorsements" or to conflict in title with any Invariant | |
10354 | Section. | |
10355 | ||
10356 | O. Preserve any Warranty Disclaimers. | |
10357 | ||
10358 | If the Modified Version includes new front-matter sections or | |
10359 | appendices that qualify as Secondary Sections and contain no | |
8a0829e9 CR |
10360 | material copied from the Document, you may at your option designate |
10361 | some or all of these sections as invariant. To do this, add their | |
10362 | titles to the list of Invariant Sections in the Modified Version's | |
10363 | license notice. These titles must be distinct from any other | |
10364 | section titles. | |
d3a24ed2 CR |
10365 | |
10366 | You may add a section Entitled "Endorsements", provided it contains | |
10367 | nothing but endorsements of your Modified Version by various | |
10368 | parties--for example, statements of peer review or that the text | |
10369 | has been approved by an organization as the authoritative | |
10370 | definition of a standard. | |
10371 | ||
10372 | You may add a passage of up to five words as a Front-Cover Text, | |
8a0829e9 CR |
10373 | and a passage of up to 25 words as a Back-Cover Text, to the end of |
10374 | the list of Cover Texts in the Modified Version. Only one passage | |
10375 | of Front-Cover Text and one of Back-Cover Text may be added by (or | |
10376 | through arrangements made by) any one entity. If the Document | |
10377 | already includes a cover text for the same cover, previously added | |
10378 | by you or by arrangement made by the same entity you are acting on | |
10379 | behalf of, you may not add another; but you may replace the old | |
10380 | one, on explicit permission from the previous publisher that added | |
10381 | the old one. | |
d3a24ed2 CR |
10382 | |
10383 | The author(s) and publisher(s) of the Document do not by this | |
10384 | License give permission to use their names for publicity for or to | |
10385 | assert or imply endorsement of any Modified Version. | |
10386 | ||
10387 | 5. COMBINING DOCUMENTS | |
10388 | ||
10389 | You may combine the Document with other documents released under | |
10390 | this License, under the terms defined in section 4 above for | |
8a0829e9 CR |
10391 | modified versions, provided that you include in the combination all |
10392 | of the Invariant Sections of all of the original documents, | |
d3a24ed2 CR |
10393 | unmodified, and list them all as Invariant Sections of your |
10394 | combined work in its license notice, and that you preserve all | |
10395 | their Warranty Disclaimers. | |
10396 | ||
10397 | The combined work need only contain one copy of this License, and | |
10398 | multiple identical Invariant Sections may be replaced with a single | |
10399 | copy. If there are multiple Invariant Sections with the same name | |
10400 | but different contents, make the title of each such section unique | |
10401 | by adding at the end of it, in parentheses, the name of the | |
10402 | original author or publisher of that section if known, or else a | |
10403 | unique number. Make the same adjustment to the section titles in | |
10404 | the list of Invariant Sections in the license notice of the | |
10405 | combined work. | |
10406 | ||
10407 | In the combination, you must combine any sections Entitled | |
10408 | "History" in the various original documents, forming one section | |
10409 | Entitled "History"; likewise combine any sections Entitled | |
10410 | "Acknowledgements", and any sections Entitled "Dedications". You | |
10411 | must delete all sections Entitled "Endorsements." | |
10412 | ||
10413 | 6. COLLECTIONS OF DOCUMENTS | |
10414 | ||
10415 | You may make a collection consisting of the Document and other | |
10416 | documents released under this License, and replace the individual | |
10417 | copies of this License in the various documents with a single copy | |
10418 | that is included in the collection, provided that you follow the | |
8a0829e9 CR |
10419 | rules of this License for verbatim copying of each of the documents |
10420 | in all other respects. | |
d3a24ed2 CR |
10421 | |
10422 | You may extract a single document from such a collection, and | |
10423 | distribute it individually under this License, provided you insert | |
8a0829e9 CR |
10424 | a copy of this License into the extracted document, and follow this |
10425 | License in all other respects regarding verbatim copying of that | |
10426 | document. | |
d3a24ed2 CR |
10427 | |
10428 | 7. AGGREGATION WITH INDEPENDENT WORKS | |
10429 | ||
10430 | A compilation of the Document or its derivatives with other | |
8a0829e9 CR |
10431 | separate and independent documents or works, in or on a volume of a |
10432 | storage or distribution medium, is called an "aggregate" if the | |
d3a24ed2 CR |
10433 | copyright resulting from the compilation is not used to limit the |
10434 | legal rights of the compilation's users beyond what the individual | |
c2a47ea9 | 10435 | works permit. When the Document is included in an aggregate, this |
d3a24ed2 CR |
10436 | License does not apply to the other works in the aggregate which |
10437 | are not themselves derivative works of the Document. | |
10438 | ||
10439 | If the Cover Text requirement of section 3 is applicable to these | |
10440 | copies of the Document, then if the Document is less than one half | |
10441 | of the entire aggregate, the Document's Cover Texts may be placed | |
10442 | on covers that bracket the Document within the aggregate, or the | |
10443 | electronic equivalent of covers if the Document is in electronic | |
10444 | form. Otherwise they must appear on printed covers that bracket | |
10445 | the whole aggregate. | |
10446 | ||
10447 | 8. TRANSLATION | |
10448 | ||
10449 | Translation is considered a kind of modification, so you may | |
10450 | distribute translations of the Document under the terms of section | |
10451 | 4. Replacing Invariant Sections with translations requires special | |
10452 | permission from their copyright holders, but you may include | |
10453 | translations of some or all Invariant Sections in addition to the | |
10454 | original versions of these Invariant Sections. You may include a | |
10455 | translation of this License, and all the license notices in the | |
10456 | Document, and any Warranty Disclaimers, provided that you also | |
10457 | include the original English version of this License and the | |
10458 | original versions of those notices and disclaimers. In case of a | |
10459 | disagreement between the translation and the original version of | |
10460 | this License or a notice or disclaimer, the original version will | |
10461 | prevail. | |
10462 | ||
10463 | If a section in the Document is Entitled "Acknowledgements", | |
10464 | "Dedications", or "History", the requirement (section 4) to | |
10465 | Preserve its Title (section 1) will typically require changing the | |
10466 | actual title. | |
10467 | ||
10468 | 9. TERMINATION | |
10469 | ||
10470 | You may not copy, modify, sublicense, or distribute the Document | |
1231ac47 CR |
10471 | except as expressly provided under this License. Any attempt |
10472 | otherwise to copy, modify, sublicense, or distribute it is void, | |
10473 | and will automatically terminate your rights under this License. | |
10474 | ||
10475 | However, if you cease all violation of this License, then your | |
10476 | license from a particular copyright holder is reinstated (a) | |
8a0829e9 CR |
10477 | provisionally, unless and until the copyright holder explicitly and |
10478 | finally terminates your license, and (b) permanently, if the | |
1231ac47 CR |
10479 | copyright holder fails to notify you of the violation by some |
10480 | reasonable means prior to 60 days after the cessation. | |
10481 | ||
10482 | Moreover, your license from a particular copyright holder is | |
10483 | reinstated permanently if the copyright holder notifies you of the | |
10484 | violation by some reasonable means, this is the first time you have | |
10485 | received notice of violation of this License (for any work) from | |
10486 | that copyright holder, and you cure the violation prior to 30 days | |
10487 | after your receipt of the notice. | |
10488 | ||
10489 | Termination of your rights under this section does not terminate | |
8a0829e9 CR |
10490 | the licenses of parties who have received copies or rights from you |
10491 | under this License. If your rights have been terminated and not | |
10492 | permanently reinstated, receipt of a copy of some or all of the | |
10493 | same material does not give you any rights to use it. | |
d3a24ed2 | 10494 | |
8a0829e9 | 10495 | 10. FUTURE REVISIONS OF THIS LICENSE |
d3a24ed2 CR |
10496 | |
10497 | The Free Software Foundation may publish new, revised versions of | |
10498 | the GNU Free Documentation License from time to time. Such new | |
10499 | versions will be similar in spirit to the present version, but may | |
10500 | differ in detail to address new problems or concerns. See | |
8a0829e9 | 10501 | <http://www.gnu.org/copyleft/>. |
d3a24ed2 CR |
10502 | |
10503 | Each version of the License is given a distinguishing version | |
10504 | number. If the Document specifies that a particular numbered | |
10505 | version of this License "or any later version" applies to it, you | |
10506 | have the option of following the terms and conditions either of | |
10507 | that specified version or of any later version that has been | |
8a0829e9 CR |
10508 | published (not as a draft) by the Free Software Foundation. If the |
10509 | Document does not specify a version number of this License, you may | |
10510 | choose any version ever published (not as a draft) by the Free | |
10511 | Software Foundation. If the Document specifies that a proxy can | |
10512 | decide which future versions of this License can be used, that | |
1231ac47 CR |
10513 | proxy's public statement of acceptance of a version permanently |
10514 | authorizes you to choose that version for the Document. | |
10515 | ||
8a0829e9 | 10516 | 11. RELICENSING |
1231ac47 CR |
10517 | |
10518 | "Massive Multiauthor Collaboration Site" (or "MMC Site") means any | |
10519 | World Wide Web server that publishes copyrightable works and also | |
10520 | provides prominent facilities for anybody to edit those works. A | |
10521 | public wiki that anybody can edit is an example of such a server. | |
10522 | A "Massive Multiauthor Collaboration" (or "MMC") contained in the | |
10523 | site means any set of copyrightable works thus published on the MMC | |
10524 | site. | |
10525 | ||
10526 | "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 | |
10527 | license published by Creative Commons Corporation, a not-for-profit | |
10528 | corporation with a principal place of business in San Francisco, | |
10529 | California, as well as future copyleft versions of that license | |
10530 | published by that same organization. | |
10531 | ||
10532 | "Incorporate" means to publish or republish a Document, in whole or | |
10533 | in part, as part of another Document. | |
10534 | ||
10535 | An MMC is "eligible for relicensing" if it is licensed under this | |
10536 | License, and if all works that were first published under this | |
10537 | License somewhere other than this MMC, and subsequently | |
10538 | incorporated in whole or in part into the MMC, (1) had no cover | |
10539 | texts or invariant sections, and (2) were thus incorporated prior | |
10540 | to November 1, 2008. | |
10541 | ||
10542 | The operator of an MMC Site may republish an MMC contained in the | |
10543 | site under CC-BY-SA on the same site at any time before August 1, | |
10544 | 2009, provided the MMC is eligible for relicensing. | |
10545 | ||
c2a47ea9 CR |
10546 | ADDENDUM: How to use this License for your documents |
10547 | ==================================================== | |
d3a24ed2 | 10548 | |
37c41ab1 | 10549 | To use this License in a document you have written, include a copy of |
d3a24ed2 CR |
10550 | the License in the document and put the following copyright and license |
10551 | notices just after the title page: | |
10552 | ||
10553 | Copyright (C) YEAR YOUR NAME. | |
10554 | Permission is granted to copy, distribute and/or modify this document | |
1231ac47 | 10555 | under the terms of the GNU Free Documentation License, Version 1.3 |
d3a24ed2 | 10556 | or any later version published by the Free Software Foundation; |
c2a47ea9 CR |
10557 | with no Invariant Sections, no Front-Cover Texts, and no Back-Cover |
10558 | Texts. A copy of the license is included in the section entitled ``GNU | |
d3a24ed2 CR |
10559 | Free Documentation License''. |
10560 | ||
10561 | If you have Invariant Sections, Front-Cover Texts and Back-Cover | |
8a0829e9 | 10562 | Texts, replace the "with...Texts." line with this: |
d3a24ed2 CR |
10563 | |
10564 | with the Invariant Sections being LIST THEIR TITLES, with | |
10565 | the Front-Cover Texts being LIST, and with the Back-Cover Texts | |
10566 | being LIST. | |
10567 | ||
10568 | If you have Invariant Sections without Cover Texts, or some other | |
10569 | combination of the three, merge those two alternatives to suit the | |
10570 | situation. | |
10571 | ||
10572 | If your document contains nontrivial examples of program code, we | |
8a0829e9 CR |
10573 | recommend releasing these examples in parallel under your choice of free |
10574 | software license, such as the GNU General Public License, to permit | |
10575 | their use in free software. | |
d3a24ed2 CR |
10576 | |
10577 | \1f | |
c2a47ea9 | 10578 | File: bashref.info, Node: Indexes, Prev: GNU Free Documentation License, Up: Top |
d3ad40de CR |
10579 | |
10580 | Appendix D Indexes | |
10581 | ****************** | |
10582 | ||
10583 | * Menu: | |
10584 | ||
10585 | * Builtin Index:: Index of Bash builtin commands. | |
10586 | * Reserved Word Index:: Index of Bash reserved words. | |
10587 | * Variable Index:: Quick reference helps you find the | |
10588 | variable you want. | |
10589 | * Function Index:: Index of bindable Readline functions. | |
10590 | * Concept Index:: General index for concepts described in | |
10591 | this manual. | |
10592 | ||
10593 | \1f | |
10594 | File: bashref.info, Node: Builtin Index, Next: Reserved Word Index, Up: Indexes | |
5cfe250d | 10595 | |
d3ad40de CR |
10596 | D.1 Index of Shell Builtin Commands |
10597 | =================================== | |
ccc6cda3 | 10598 | |
37c41ab1 | 10599 | \0\b[index\0\b] |
ccc6cda3 JA |
10600 | * Menu: |
10601 | ||
e8ce775d | 10602 | * .: Bourne Shell Builtins. |
122f603c | 10603 | (line 17) |
e8ce775d | 10604 | * :: Bourne Shell Builtins. |
37c41ab1 | 10605 | (line 11) |
e8ce775d | 10606 | * [: Bourne Shell Builtins. |
eac8fb1b | 10607 | (line 268) |
37c41ab1 | 10608 | * alias: Bash Builtins. (line 11) |
e8ce775d | 10609 | * bg: Job Control Builtins. |
37c41ab1 CR |
10610 | (line 7) |
10611 | * bind: Bash Builtins. (line 21) | |
e8ce775d | 10612 | * break: Bourne Shell Builtins. |
eac8fb1b | 10613 | (line 36) |
690150f9 CR |
10614 | * builtin: Bash Builtins. (line 102) |
10615 | * caller: Bash Builtins. (line 111) | |
e8ce775d | 10616 | * cd: Bourne Shell Builtins. |
eac8fb1b | 10617 | (line 44) |
690150f9 | 10618 | * command: Bash Builtins. (line 128) |
bb70624e | 10619 | * compgen: Programmable Completion Builtins. |
45c0f7f8 | 10620 | (line 12) |
bb70624e | 10621 | * complete: Programmable Completion Builtins. |
45c0f7f8 | 10622 | (line 30) |
6a8fd0ed | 10623 | * compopt: Programmable Completion Builtins. |
8a0829e9 | 10624 | (line 229) |
e8ce775d | 10625 | * continue: Bourne Shell Builtins. |
eac8fb1b | 10626 | (line 85) |
690150f9 | 10627 | * declare: Bash Builtins. (line 148) |
bb70624e | 10628 | * dirs: Directory Stack Builtins. |
37c41ab1 | 10629 | (line 7) |
e8ce775d | 10630 | * disown: Job Control Builtins. |
54a5fbe1 | 10631 | (line 89) |
690150f9 CR |
10632 | * echo: Bash Builtins. (line 245) |
10633 | * enable: Bash Builtins. (line 294) | |
e8ce775d | 10634 | * eval: Bourne Shell Builtins. |
eac8fb1b | 10635 | (line 94) |
e8ce775d | 10636 | * exec: Bourne Shell Builtins. |
eac8fb1b | 10637 | (line 102) |
e8ce775d | 10638 | * exit: Bourne Shell Builtins. |
eac8fb1b | 10639 | (line 119) |
e8ce775d | 10640 | * export: Bourne Shell Builtins. |
eac8fb1b | 10641 | (line 126) |
cce855bc | 10642 | * fc: Bash History Builtins. |
37c41ab1 | 10643 | (line 10) |
e8ce775d | 10644 | * fg: Job Control Builtins. |
122f603c | 10645 | (line 17) |
e8ce775d | 10646 | * getopts: Bourne Shell Builtins. |
eac8fb1b | 10647 | (line 142) |
e8ce775d | 10648 | * hash: Bourne Shell Builtins. |
eac8fb1b | 10649 | (line 185) |
690150f9 | 10650 | * help: Bash Builtins. (line 323) |
cce855bc | 10651 | * history: Bash History Builtins. |
122f603c | 10652 | (line 40) |
e8ce775d | 10653 | * jobs: Job Control Builtins. |
122f603c | 10654 | (line 27) |
e8ce775d | 10655 | * kill: Job Control Builtins. |
8a0829e9 | 10656 | (line 58) |
690150f9 CR |
10657 | * let: Bash Builtins. (line 342) |
10658 | * local: Bash Builtins. (line 350) | |
10659 | * logout: Bash Builtins. (line 364) | |
10660 | * mapfile: Bash Builtins. (line 369) | |
bb70624e | 10661 | * popd: Directory Stack Builtins. |
54a5fbe1 | 10662 | (line 35) |
690150f9 | 10663 | * printf: Bash Builtins. (line 414) |
bb70624e | 10664 | * pushd: Directory Stack Builtins. |
54a5fbe1 | 10665 | (line 53) |
e8ce775d | 10666 | * pwd: Bourne Shell Builtins. |
eac8fb1b | 10667 | (line 205) |
8a0829e9 | 10668 | * read: Bash Builtins. (line 458) |
690150f9 | 10669 | * readarray: Bash Builtins. (line 550) |
e8ce775d | 10670 | * readonly: Bourne Shell Builtins. |
eac8fb1b | 10671 | (line 215) |
e8ce775d | 10672 | * return: Bourne Shell Builtins. |
eac8fb1b | 10673 | (line 234) |
d3ad40de | 10674 | * set: The Set Builtin. (line 11) |
e8ce775d | 10675 | * shift: Bourne Shell Builtins. |
eac8fb1b | 10676 | (line 255) |
d3ad40de | 10677 | * shopt: The Shopt Builtin. (line 9) |
690150f9 | 10678 | * source: Bash Builtins. (line 559) |
e8ce775d | 10679 | * suspend: Job Control Builtins. |
54a5fbe1 | 10680 | (line 101) |
e8ce775d | 10681 | * test: Bourne Shell Builtins. |
eac8fb1b | 10682 | (line 268) |
e8ce775d | 10683 | * times: Bourne Shell Builtins. |
eac8fb1b | 10684 | (line 343) |
e8ce775d | 10685 | * trap: Bourne Shell Builtins. |
eac8fb1b | 10686 | (line 349) |
690150f9 CR |
10687 | * type: Bash Builtins. (line 564) |
10688 | * typeset: Bash Builtins. (line 596) | |
10689 | * ulimit: Bash Builtins. (line 602) | |
e8ce775d | 10690 | * umask: Bourne Shell Builtins. |
eac8fb1b | 10691 | (line 398) |
690150f9 | 10692 | * unalias: Bash Builtins. (line 701) |
e8ce775d | 10693 | * unset: Bourne Shell Builtins. |
eac8fb1b | 10694 | (line 416) |
e8ce775d | 10695 | * wait: Job Control Builtins. |
54a5fbe1 | 10696 | (line 76) |
ccc6cda3 JA |
10697 | |
10698 | \1f | |
d3ad40de | 10699 | File: bashref.info, Node: Reserved Word Index, Next: Variable Index, Prev: Builtin Index, Up: Indexes |
ccc6cda3 | 10700 | |
d3ad40de CR |
10701 | D.2 Index of Shell Reserved Words |
10702 | ================================= | |
ccc6cda3 | 10703 | |
37c41ab1 | 10704 | \0\b[index\0\b] |
ccc6cda3 JA |
10705 | * Menu: |
10706 | ||
ed35cb4a | 10707 | * !: Pipelines. (line 9) |
cce855bc | 10708 | * [[: Conditional Constructs. |
8a0829e9 | 10709 | (line 120) |
cce855bc | 10710 | * ]]: Conditional Constructs. |
8a0829e9 CR |
10711 | (line 120) |
10712 | * {: Command Grouping. (line 21) | |
10713 | * }: Command Grouping. (line 21) | |
e8ce775d | 10714 | * case: Conditional Constructs. |
37c41ab1 CR |
10715 | (line 28) |
10716 | * do: Looping Constructs. (line 12) | |
10717 | * done: Looping Constructs. (line 12) | |
e8ce775d | 10718 | * elif: Conditional Constructs. |
37c41ab1 | 10719 | (line 7) |
e8ce775d | 10720 | * else: Conditional Constructs. |
37c41ab1 | 10721 | (line 7) |
e8ce775d | 10722 | * esac: Conditional Constructs. |
37c41ab1 | 10723 | (line 28) |
e8ce775d | 10724 | * fi: Conditional Constructs. |
37c41ab1 | 10725 | (line 7) |
122f603c | 10726 | * for: Looping Constructs. (line 32) |
37c41ab1 | 10727 | * function: Shell Functions. (line 13) |
e8ce775d | 10728 | * if: Conditional Constructs. |
37c41ab1 | 10729 | (line 7) |
e8ce775d | 10730 | * in: Conditional Constructs. |
37c41ab1 | 10731 | (line 28) |
cce855bc | 10732 | * select: Conditional Constructs. |
9f178efb | 10733 | (line 78) |
e8ce775d | 10734 | * then: Conditional Constructs. |
37c41ab1 | 10735 | (line 7) |
ed35cb4a | 10736 | * time: Pipelines. (line 9) |
37c41ab1 | 10737 | * until: Looping Constructs. (line 12) |
122f603c | 10738 | * while: Looping Constructs. (line 22) |
ccc6cda3 JA |
10739 | |
10740 | \1f | |
d3ad40de | 10741 | File: bashref.info, Node: Variable Index, Next: Function Index, Prev: Reserved Word Index, Up: Indexes |
ccc6cda3 | 10742 | |
d3ad40de CR |
10743 | D.3 Parameter and Variable Index |
10744 | ================================ | |
ccc6cda3 | 10745 | |
37c41ab1 | 10746 | \0\b[index\0\b] |
ccc6cda3 JA |
10747 | * Menu: |
10748 | ||
595e3e69 CR |
10749 | * !: Special Parameters. (line 50) |
10750 | * #: Special Parameters. (line 33) | |
10751 | * $: Special Parameters. (line 45) | |
10752 | * $!: Special Parameters. (line 51) | |
10753 | * $#: Special Parameters. (line 34) | |
10754 | * $$: Special Parameters. (line 46) | |
6e51e0d0 | 10755 | * $*: Special Parameters. (line 10) |
595e3e69 CR |
10756 | * $-: Special Parameters. (line 41) |
10757 | * $0: Special Parameters. (line 56) | |
10758 | * $?: Special Parameters. (line 37) | |
10759 | * $@: Special Parameters. (line 23) | |
10760 | * $_: Special Parameters. (line 65) | |
37c41ab1 | 10761 | * *: Special Parameters. (line 9) |
595e3e69 CR |
10762 | * -: Special Parameters. (line 40) |
10763 | * 0: Special Parameters. (line 55) | |
10764 | * ?: Special Parameters. (line 36) | |
10765 | * @: Special Parameters. (line 22) | |
10766 | * _: Special Parameters. (line 64) | |
e8ce775d | 10767 | * auto_resume: Job Control Variables. |
37c41ab1 CR |
10768 | (line 6) |
10769 | * BASH: Bash Variables. (line 13) | |
8a0829e9 CR |
10770 | * BASHOPTS: Bash Variables. (line 16) |
10771 | * BASHPID: Bash Variables. (line 25) | |
8f714a7c | 10772 | * BASH_ALIASES: Bash Variables. (line 30) |
690150f9 CR |
10773 | * BASH_ARGC: Bash Variables. (line 39) |
10774 | * BASH_ARGV: Bash Variables. (line 49) | |
10775 | * BASH_CMDS: Bash Variables. (line 59) | |
10776 | * BASH_COMMAND: Bash Variables. (line 68) | |
10777 | * BASH_COMPAT: Bash Variables. (line 73) | |
10778 | * BASH_ENV: Bash Variables. (line 88) | |
10779 | * BASH_EXECUTION_STRING: Bash Variables. (line 94) | |
10780 | * BASH_LINENO: Bash Variables. (line 97) | |
10781 | * BASH_LOADABLES_PATH: Bash Variables. (line 105) | |
10782 | * BASH_REMATCH: Bash Variables. (line 109) | |
10783 | * BASH_SOURCE: Bash Variables. (line 117) | |
10784 | * BASH_SUBSHELL: Bash Variables. (line 124) | |
10785 | * BASH_VERSINFO: Bash Variables. (line 129) | |
10786 | * BASH_VERSION: Bash Variables. (line 152) | |
10787 | * BASH_XTRACEFD: Bash Variables. (line 155) | |
e8ce775d | 10788 | * bell-style: Readline Init File Syntax. |
1c72c0cd | 10789 | (line 38) |
eb2bb562 | 10790 | * bind-tty-special-chars: Readline Init File Syntax. |
1c72c0cd | 10791 | (line 45) |
fc527055 CR |
10792 | * blink-matching-paren: Readline Init File Syntax. |
10793 | (line 50) | |
e8ce775d | 10794 | * CDPATH: Bourne Shell Variables. |
37c41ab1 | 10795 | (line 9) |
690150f9 | 10796 | * CHILD_MAX: Bash Variables. (line 166) |
8a0829e9 | 10797 | * colored-completion-prefix: Readline Init File Syntax. |
fc527055 | 10798 | (line 55) |
8a0829e9 CR |
10799 | * colored-stats: Readline Init File Syntax. |
10800 | (line 62) | |
690150f9 | 10801 | * COLUMNS: Bash Variables. (line 173) |
e8ce775d | 10802 | * comment-begin: Readline Init File Syntax. |
8a0829e9 CR |
10803 | (line 68) |
10804 | * completion-display-width: Readline Init File Syntax. | |
10805 | (line 73) | |
10806 | * completion-ignore-case: Readline Init File Syntax. | |
10807 | (line 80) | |
10808 | * completion-map-case: Readline Init File Syntax. | |
10809 | (line 85) | |
10810 | * completion-prefix-display-length: Readline Init File Syntax. | |
10811 | (line 91) | |
10812 | * completion-query-items: Readline Init File Syntax. | |
10813 | (line 98) | |
690150f9 CR |
10814 | * COMPREPLY: Bash Variables. (line 225) |
10815 | * COMP_CWORD: Bash Variables. (line 179) | |
10816 | * COMP_KEY: Bash Variables. (line 208) | |
10817 | * COMP_LINE: Bash Variables. (line 185) | |
10818 | * COMP_POINT: Bash Variables. (line 190) | |
10819 | * COMP_TYPE: Bash Variables. (line 198) | |
10820 | * COMP_WORDBREAKS: Bash Variables. (line 212) | |
10821 | * COMP_WORDS: Bash Variables. (line 218) | |
e8ce775d | 10822 | * convert-meta: Readline Init File Syntax. |
8a0829e9 | 10823 | (line 108) |
690150f9 CR |
10824 | * COPROC: Bash Variables. (line 231) |
10825 | * DIRSTACK: Bash Variables. (line 235) | |
e8ce775d | 10826 | * disable-completion: Readline Init File Syntax. |
8a0829e9 CR |
10827 | (line 114) |
10828 | * echo-control-characters: Readline Init File Syntax. | |
10829 | (line 135) | |
fc527055 | 10830 | * editing-mode: Readline Init File Syntax. |
8a0829e9 | 10831 | (line 119) |
690150f9 | 10832 | * EMACS: Bash Variables. (line 245) |
8a0829e9 CR |
10833 | * emacs-mode-string: Readline Init File Syntax. |
10834 | (line 125) | |
10835 | * enable-bracketed-paste: Readline Init File Syntax. | |
10836 | (line 140) | |
e8ce775d | 10837 | * enable-keypad: Readline Init File Syntax. |
8a0829e9 | 10838 | (line 148) |
690150f9 CR |
10839 | * ENV: Bash Variables. (line 250) |
10840 | * EUID: Bash Variables. (line 254) | |
10841 | * EXECIGNORE: Bash Variables. (line 258) | |
e8ce775d | 10842 | * expand-tilde: Readline Init File Syntax. |
8a0829e9 | 10843 | (line 159) |
690150f9 CR |
10844 | * FCEDIT: Bash Variables. (line 269) |
10845 | * FIGNORE: Bash Variables. (line 273) | |
10846 | * FUNCNAME: Bash Variables. (line 279) | |
10847 | * FUNCNEST: Bash Variables. (line 296) | |
10848 | * GLOBIGNORE: Bash Variables. (line 301) | |
10849 | * GROUPS: Bash Variables. (line 308) | |
10850 | * histchars: Bash Variables. (line 314) | |
10851 | * HISTCMD: Bash Variables. (line 329) | |
10852 | * HISTCONTROL: Bash Variables. (line 334) | |
10853 | * HISTFILE: Bash Variables. (line 350) | |
10854 | * HISTFILESIZE: Bash Variables. (line 354) | |
10855 | * HISTIGNORE: Bash Variables. (line 365) | |
f73dda09 | 10856 | * history-preserve-point: Readline Init File Syntax. |
8a0829e9 | 10857 | (line 163) |
abe2eb5b | 10858 | * history-size: Readline Init File Syntax. |
8a0829e9 | 10859 | (line 169) |
690150f9 CR |
10860 | * HISTSIZE: Bash Variables. (line 385) |
10861 | * HISTTIMEFORMAT: Bash Variables. (line 392) | |
e8ce775d | 10862 | * HOME: Bourne Shell Variables. |
37c41ab1 | 10863 | (line 13) |
e8ce775d | 10864 | * horizontal-scroll-mode: Readline Init File Syntax. |
8a0829e9 | 10865 | (line 176) |
690150f9 CR |
10866 | * HOSTFILE: Bash Variables. (line 400) |
10867 | * HOSTNAME: Bash Variables. (line 411) | |
10868 | * HOSTTYPE: Bash Variables. (line 414) | |
e8ce775d | 10869 | * IFS: Bourne Shell Variables. |
37c41ab1 | 10870 | (line 18) |
690150f9 | 10871 | * IGNOREEOF: Bash Variables. (line 417) |
e8ce775d | 10872 | * input-meta: Readline Init File Syntax. |
8a0829e9 | 10873 | (line 183) |
690150f9 | 10874 | * INPUTRC: Bash Variables. (line 427) |
b72432fd | 10875 | * isearch-terminators: Readline Init File Syntax. |
8a0829e9 | 10876 | (line 190) |
eb0b2ad8 | 10877 | * keymap: Readline Init File Syntax. |
8a0829e9 | 10878 | (line 197) |
690150f9 CR |
10879 | * LANG: Bash Variables. (line 431) |
10880 | * LC_ALL: Bash Variables. (line 435) | |
10881 | * LC_COLLATE: Bash Variables. (line 439) | |
10882 | * LC_CTYPE: Bash Variables. (line 446) | |
8a0829e9 | 10883 | * LC_MESSAGES: Locale Translation. (line 11) |
690150f9 CR |
10884 | * LC_MESSAGES <1>: Bash Variables. (line 451) |
10885 | * LC_NUMERIC: Bash Variables. (line 455) | |
10886 | * LC_TIME: Bash Variables. (line 459) | |
10887 | * LINENO: Bash Variables. (line 463) | |
10888 | * LINES: Bash Variables. (line 467) | |
10889 | * MACHTYPE: Bash Variables. (line 473) | |
e8ce775d | 10890 | * MAIL: Bourne Shell Variables. |
37c41ab1 | 10891 | (line 22) |
690150f9 | 10892 | * MAILCHECK: Bash Variables. (line 477) |
e8ce775d | 10893 | * MAILPATH: Bourne Shell Variables. |
37c41ab1 | 10894 | (line 27) |
690150f9 | 10895 | * MAPFILE: Bash Variables. (line 485) |
e8ce775d | 10896 | * mark-modified-lines: Readline Init File Syntax. |
690150f9 | 10897 | (line 227) |
fc527055 | 10898 | * mark-symlinked-directories: Readline Init File Syntax. |
690150f9 | 10899 | (line 232) |
fc527055 | 10900 | * match-hidden-files: Readline Init File Syntax. |
690150f9 | 10901 | (line 237) |
e05be32d | 10902 | * menu-complete-display-prefix: Readline Init File Syntax. |
690150f9 | 10903 | (line 244) |
e8ce775d | 10904 | * meta-flag: Readline Init File Syntax. |
8a0829e9 | 10905 | (line 183) |
690150f9 | 10906 | * OLDPWD: Bash Variables. (line 489) |
e8ce775d | 10907 | * OPTARG: Bourne Shell Variables. |
37c41ab1 | 10908 | (line 34) |
690150f9 | 10909 | * OPTERR: Bash Variables. (line 492) |
e8ce775d | 10910 | * OPTIND: Bourne Shell Variables. |
37c41ab1 | 10911 | (line 38) |
690150f9 | 10912 | * OSTYPE: Bash Variables. (line 496) |
e8ce775d | 10913 | * output-meta: Readline Init File Syntax. |
690150f9 | 10914 | (line 249) |
fc527055 | 10915 | * page-completions: Readline Init File Syntax. |
690150f9 | 10916 | (line 254) |
e8ce775d | 10917 | * PATH: Bourne Shell Variables. |
37c41ab1 | 10918 | (line 42) |
690150f9 CR |
10919 | * PIPESTATUS: Bash Variables. (line 499) |
10920 | * POSIXLY_CORRECT: Bash Variables. (line 504) | |
10921 | * PPID: Bash Variables. (line 513) | |
10922 | * PROMPT_COMMAND: Bash Variables. (line 517) | |
10923 | * PROMPT_DIRTRIM: Bash Variables. (line 521) | |
10924 | * PS0: Bash Variables. (line 527) | |
e8ce775d | 10925 | * PS1: Bourne Shell Variables. |
37c41ab1 | 10926 | (line 48) |
e8ce775d | 10927 | * PS2: Bourne Shell Variables. |
37c41ab1 | 10928 | (line 53) |
690150f9 CR |
10929 | * PS3: Bash Variables. (line 532) |
10930 | * PS4: Bash Variables. (line 537) | |
10931 | * PWD: Bash Variables. (line 543) | |
10932 | * RANDOM: Bash Variables. (line 546) | |
10933 | * READLINE_LINE: Bash Variables. (line 551) | |
10934 | * READLINE_POINT: Bash Variables. (line 555) | |
10935 | * REPLY: Bash Variables. (line 559) | |
ed35cb4a | 10936 | * revert-all-at-newline: Readline Init File Syntax. |
690150f9 CR |
10937 | (line 264) |
10938 | * SECONDS: Bash Variables. (line 562) | |
10939 | * SHELL: Bash Variables. (line 568) | |
10940 | * SHELLOPTS: Bash Variables. (line 573) | |
10941 | * SHLVL: Bash Variables. (line 582) | |
220537f2 | 10942 | * show-all-if-ambiguous: Readline Init File Syntax. |
690150f9 | 10943 | (line 270) |
abe2eb5b | 10944 | * show-all-if-unmodified: Readline Init File Syntax. |
690150f9 | 10945 | (line 276) |
ad4aef08 | 10946 | * show-mode-in-prompt: Readline Init File Syntax. |
690150f9 | 10947 | (line 285) |
fc527055 | 10948 | * skip-completed-text: Readline Init File Syntax. |
690150f9 | 10949 | (line 291) |
37c41ab1 CR |
10950 | * TEXTDOMAIN: Locale Translation. (line 11) |
10951 | * TEXTDOMAINDIR: Locale Translation. (line 11) | |
690150f9 CR |
10952 | * TIMEFORMAT: Bash Variables. (line 587) |
10953 | * TMOUT: Bash Variables. (line 625) | |
10954 | * TMPDIR: Bash Variables. (line 637) | |
10955 | * UID: Bash Variables. (line 641) | |
8a0829e9 | 10956 | * vi-cmd-mode-string: Readline Init File Syntax. |
690150f9 | 10957 | (line 304) |
8a0829e9 | 10958 | * vi-ins-mode-string: Readline Init File Syntax. |
690150f9 | 10959 | (line 314) |
e8ce775d | 10960 | * visible-stats: Readline Init File Syntax. |
690150f9 | 10961 | (line 324) |
ccc6cda3 JA |
10962 | |
10963 | \1f | |
d3ad40de | 10964 | File: bashref.info, Node: Function Index, Next: Concept Index, Prev: Variable Index, Up: Indexes |
ccc6cda3 | 10965 | |
d3ad40de CR |
10966 | D.4 Function Index |
10967 | ================== | |
ccc6cda3 | 10968 | |
37c41ab1 | 10969 | \0\b[index\0\b] |
ccc6cda3 JA |
10970 | * Menu: |
10971 | ||
e8ce775d | 10972 | * abort (C-g): Miscellaneous Commands. |
8a0829e9 CR |
10973 | (line 10) |
10974 | * accept-line (Newline or Return): Commands For History. | |
10975 | (line 6) | |
10976 | * alias-expand-line (): Miscellaneous Commands. | |
10977 | (line 124) | |
10978 | * backward-char (C-b): Commands For Moving. (line 15) | |
10979 | * backward-delete-char (Rubout): Commands For Text. (line 17) | |
10980 | * backward-kill-line (C-x Rubout): Commands For Killing. | |
10981 | (line 9) | |
10982 | * backward-kill-word (M-<DEL>): Commands For Killing. | |
10983 | (line 24) | |
10984 | * backward-word (M-b): Commands For Moving. (line 22) | |
10985 | * beginning-of-history (M-<): Commands For History. | |
10986 | (line 20) | |
10987 | * beginning-of-line (C-a): Commands For Moving. (line 6) | |
10988 | * bracketed-paste-begin (): Commands For Text. (line 33) | |
10989 | * call-last-kbd-macro (C-x e): Keyboard Macros. (line 13) | |
10990 | * capitalize-word (M-c): Commands For Text. (line 61) | |
e8ce775d | 10991 | * character-search (C-]): Miscellaneous Commands. |
8a0829e9 | 10992 | (line 41) |
e8ce775d | 10993 | * character-search-backward (M-C-]): Miscellaneous Commands. |
8a0829e9 CR |
10994 | (line 46) |
10995 | * clear-screen (C-l): Commands For Moving. (line 34) | |
28ef6c31 | 10996 | * complete (<TAB>): Commands For Completion. |
8a0829e9 CR |
10997 | (line 6) |
10998 | * complete-command (M-!): Commands For Completion. | |
10999 | (line 80) | |
11000 | * complete-filename (M-/): Commands For Completion. | |
11001 | (line 49) | |
11002 | * complete-hostname (M-@): Commands For Completion. | |
11003 | (line 72) | |
11004 | * complete-into-braces (M-{): Commands For Completion. | |
11005 | (line 100) | |
11006 | * complete-username (M-~): Commands For Completion. | |
11007 | (line 56) | |
11008 | * complete-variable (M-$): Commands For Completion. | |
11009 | (line 64) | |
11010 | * copy-backward-word (): Commands For Killing. | |
11011 | (line 58) | |
11012 | * copy-forward-word (): Commands For Killing. | |
11013 | (line 63) | |
11014 | * copy-region-as-kill (): Commands For Killing. | |
11015 | (line 54) | |
11016 | * dabbrev-expand (): Commands For Completion. | |
11017 | (line 95) | |
11018 | * delete-char (C-d): Commands For Text. (line 12) | |
b72432fd | 11019 | * delete-char-or-list (): Commands For Completion. |
8a0829e9 CR |
11020 | (line 43) |
11021 | * delete-horizontal-space (): Commands For Killing. | |
11022 | (line 46) | |
11023 | * digit-argument ('M-0', 'M-1', ... 'M--'): Numeric Arguments. | |
11024 | (line 6) | |
11025 | * display-shell-version (C-x C-v): Miscellaneous Commands. | |
11026 | (line 109) | |
ccc6cda3 | 11027 | * do-uppercase-version (M-a, M-b, M-X, ...): Miscellaneous Commands. |
8a0829e9 CR |
11028 | (line 14) |
11029 | * downcase-word (M-l): Commands For Text. (line 57) | |
e8ce775d | 11030 | * dump-functions (): Miscellaneous Commands. |
8a0829e9 | 11031 | (line 73) |
e8ce775d | 11032 | * dump-macros (): Miscellaneous Commands. |
8a0829e9 | 11033 | (line 85) |
e8ce775d | 11034 | * dump-variables (): Miscellaneous Commands. |
8a0829e9 CR |
11035 | (line 79) |
11036 | * dynamic-complete-history (M-<TAB>): Commands For Completion. | |
11037 | (line 90) | |
11038 | * edit-and-execute-command (C-xC-e): Miscellaneous Commands. | |
11039 | (line 138) | |
11040 | * end-kbd-macro (C-x )): Keyboard Macros. (line 9) | |
11041 | * end-of-file (usually C-d): Commands For Text. (line 6) | |
11042 | * end-of-history (M->): Commands For History. | |
11043 | (line 23) | |
11044 | * end-of-line (C-e): Commands For Moving. (line 9) | |
e8ce775d | 11045 | * exchange-point-and-mark (C-x C-x): Miscellaneous Commands. |
8a0829e9 CR |
11046 | (line 36) |
11047 | * forward-backward-delete-char (): Commands For Text. (line 21) | |
11048 | * forward-char (C-f): Commands For Moving. (line 12) | |
11049 | * forward-search-history (C-s): Commands For History. | |
11050 | (line 31) | |
11051 | * forward-word (M-f): Commands For Moving. (line 18) | |
11052 | * glob-complete-word (M-g): Miscellaneous Commands. | |
11053 | (line 91) | |
11054 | * glob-expand-word (C-x *): Miscellaneous Commands. | |
11055 | (line 97) | |
11056 | * glob-list-expansions (C-x g): Miscellaneous Commands. | |
11057 | (line 103) | |
11058 | * history-and-alias-expand-line (): Miscellaneous Commands. | |
11059 | (line 127) | |
11060 | * history-expand-line (M-^): Miscellaneous Commands. | |
11061 | (line 117) | |
11062 | * history-search-backward (): Commands For History. | |
11063 | (line 53) | |
11064 | * history-search-forward (): Commands For History. | |
11065 | (line 47) | |
11066 | * history-substr-search-backward (): Commands For History. | |
11067 | (line 65) | |
11068 | * history-substr-search-forward (): Commands For History. | |
11069 | (line 59) | |
e8ce775d | 11070 | * insert-comment (M-#): Miscellaneous Commands. |
8a0829e9 | 11071 | (line 60) |
e8ce775d | 11072 | * insert-completions (M-*): Commands For Completion. |
8a0829e9 CR |
11073 | (line 22) |
11074 | * insert-last-argument (M-. or M-_): Miscellaneous Commands. | |
11075 | (line 130) | |
11076 | * kill-line (C-k): Commands For Killing. | |
11077 | (line 6) | |
11078 | * kill-region (): Commands For Killing. | |
11079 | (line 50) | |
11080 | * kill-whole-line (): Commands For Killing. | |
11081 | (line 15) | |
11082 | * kill-word (M-d): Commands For Killing. | |
11083 | (line 19) | |
11084 | * magic-space (): Miscellaneous Commands. | |
11085 | (line 120) | |
cce855bc | 11086 | * menu-complete (): Commands For Completion. |
8a0829e9 | 11087 | (line 26) |
3eb2d94a | 11088 | * menu-complete-backward (): Commands For Completion. |
8a0829e9 CR |
11089 | (line 38) |
11090 | * next-history (C-n): Commands For History. | |
11091 | (line 17) | |
ccc6cda3 | 11092 | * non-incremental-forward-search-history (M-n): Commands For History. |
8a0829e9 | 11093 | (line 41) |
ccc6cda3 | 11094 | * non-incremental-reverse-search-history (M-p): Commands For History. |
8a0829e9 CR |
11095 | (line 35) |
11096 | * operate-and-get-next (C-o): Miscellaneous Commands. | |
11097 | (line 133) | |
11098 | * overwrite-mode (): Commands For Text. (line 65) | |
11099 | * possible-command-completions (C-x !): Commands For Completion. | |
11100 | (line 86) | |
e8ce775d | 11101 | * possible-completions (M-?): Commands For Completion. |
8a0829e9 CR |
11102 | (line 15) |
11103 | * possible-filename-completions (C-x /): Commands For Completion. | |
11104 | (line 52) | |
11105 | * possible-hostname-completions (C-x @): Commands For Completion. | |
11106 | (line 76) | |
11107 | * possible-username-completions (C-x ~): Commands For Completion. | |
11108 | (line 60) | |
11109 | * possible-variable-completions (C-x $): Commands For Completion. | |
11110 | (line 68) | |
28ef6c31 | 11111 | * prefix-meta (<ESC>): Miscellaneous Commands. |
8a0829e9 CR |
11112 | (line 18) |
11113 | * previous-history (C-p): Commands For History. | |
11114 | (line 13) | |
11115 | * print-last-kbd-macro (): Keyboard Macros. (line 17) | |
11116 | * quoted-insert (C-q or C-v): Commands For Text. (line 26) | |
e8ce775d | 11117 | * re-read-init-file (C-x C-r): Miscellaneous Commands. |
8a0829e9 CR |
11118 | (line 6) |
11119 | * redraw-current-line (): Commands For Moving. (line 38) | |
11120 | * reverse-search-history (C-r): Commands For History. | |
11121 | (line 27) | |
e8ce775d | 11122 | * revert-line (M-r): Miscellaneous Commands. |
8a0829e9 CR |
11123 | (line 25) |
11124 | * self-insert (a, b, A, 1, !, ...): Commands For Text. (line 30) | |
e8ce775d | 11125 | * set-mark (C-@): Miscellaneous Commands. |
8a0829e9 CR |
11126 | (line 32) |
11127 | * shell-backward-kill-word (): Commands For Killing. | |
11128 | (line 33) | |
11129 | * shell-backward-word (): Commands For Moving. (line 30) | |
11130 | * shell-expand-line (M-C-e): Miscellaneous Commands. | |
11131 | (line 112) | |
11132 | * shell-forward-word (): Commands For Moving. (line 26) | |
11133 | * shell-kill-word (): Commands For Killing. | |
11134 | (line 28) | |
8f714a7c | 11135 | * skip-csi-sequence (): Miscellaneous Commands. |
8a0829e9 CR |
11136 | (line 51) |
11137 | * start-kbd-macro (C-x (): Keyboard Macros. (line 6) | |
11138 | * tilde-expand (M-&): Miscellaneous Commands. | |
11139 | (line 29) | |
11140 | * transpose-chars (C-t): Commands For Text. (line 42) | |
11141 | * transpose-words (M-t): Commands For Text. (line 48) | |
28ef6c31 | 11142 | * undo (C-_ or C-x C-u): Miscellaneous Commands. |
8a0829e9 CR |
11143 | (line 22) |
11144 | * universal-argument (): Numeric Arguments. (line 10) | |
11145 | * unix-filename-rubout (): Commands For Killing. | |
11146 | (line 41) | |
11147 | * unix-line-discard (C-u): Commands For Killing. | |
11148 | (line 12) | |
11149 | * unix-word-rubout (C-w): Commands For Killing. | |
11150 | (line 37) | |
11151 | * upcase-word (M-u): Commands For Text. (line 53) | |
11152 | * yank (C-y): Commands For Killing. | |
11153 | (line 68) | |
11154 | * yank-last-arg (M-. or M-_): Commands For History. | |
11155 | (line 80) | |
11156 | * yank-nth-arg (M-C-y): Commands For History. | |
11157 | (line 71) | |
11158 | * yank-pop (M-y): Commands For Killing. | |
11159 | (line 71) | |
ccc6cda3 JA |
11160 | |
11161 | \1f | |
d3ad40de | 11162 | File: bashref.info, Node: Concept Index, Prev: Function Index, Up: Indexes |
ccc6cda3 | 11163 | |
d3ad40de CR |
11164 | D.5 Concept Index |
11165 | ================= | |
ccc6cda3 | 11166 | |
37c41ab1 | 11167 | \0\b[index\0\b] |
ccc6cda3 JA |
11168 | * Menu: |
11169 | ||
37c41ab1 CR |
11170 | * alias expansion: Aliases. (line 6) |
11171 | * arithmetic evaluation: Shell Arithmetic. (line 6) | |
e8ce775d | 11172 | * arithmetic expansion: Arithmetic Expansion. |
37c41ab1 CR |
11173 | (line 6) |
11174 | * arithmetic, shell: Shell Arithmetic. (line 6) | |
11175 | * arrays: Arrays. (line 6) | |
11176 | * background: Job Control Basics. (line 6) | |
11177 | * Bash configuration: Basic Installation. (line 6) | |
11178 | * Bash installation: Basic Installation. (line 6) | |
e8ce775d | 11179 | * Bourne shell: Basic Shell Features. |
37c41ab1 CR |
11180 | (line 6) |
11181 | * brace expansion: Brace Expansion. (line 6) | |
ac18b312 | 11182 | * builtin: Definitions. (line 17) |
e8ce775d | 11183 | * command editing: Readline Bare Essentials. |
37c41ab1 | 11184 | (line 6) |
e8ce775d | 11185 | * command execution: Command Search and Execution. |
37c41ab1 | 11186 | (line 6) |
cce855bc | 11187 | * command expansion: Simple Command Expansion. |
37c41ab1 | 11188 | (line 6) |
e8ce775d | 11189 | * command history: Bash History Facilities. |
37c41ab1 | 11190 | (line 6) |
e8ce775d | 11191 | * command search: Command Search and Execution. |
37c41ab1 | 11192 | (line 6) |
e8ce775d | 11193 | * command substitution: Command Substitution. |
37c41ab1 | 11194 | (line 6) |
ed35cb4a | 11195 | * command timing: Pipelines. (line 9) |
37c41ab1 | 11196 | * commands, compound: Compound Commands. (line 6) |
e8ce775d | 11197 | * commands, conditional: Conditional Constructs. |
37c41ab1 CR |
11198 | (line 6) |
11199 | * commands, grouping: Command Grouping. (line 6) | |
11200 | * commands, lists: Lists. (line 6) | |
11201 | * commands, looping: Looping Constructs. (line 6) | |
11202 | * commands, pipelines: Pipelines. (line 6) | |
11203 | * commands, shell: Shell Commands. (line 6) | |
11204 | * commands, simple: Simple Commands. (line 6) | |
11205 | * comments, shell: Comments. (line 6) | |
bb70624e | 11206 | * completion builtins: Programmable Completion Builtins. |
37c41ab1 CR |
11207 | (line 6) |
11208 | * configuration: Basic Installation. (line 6) | |
ac18b312 | 11209 | * control operator: Definitions. (line 21) |
8e1a6eaa | 11210 | * coprocess: Coprocesses. (line 6) |
37c41ab1 | 11211 | * directory stack: The Directory Stack. (line 6) |
e8ce775d | 11212 | * editing command lines: Readline Bare Essentials. |
37c41ab1 CR |
11213 | (line 6) |
11214 | * environment: Environment. (line 6) | |
11215 | * evaluation, arithmetic: Shell Arithmetic. (line 6) | |
11216 | * event designators: Event Designators. (line 6) | |
cce855bc | 11217 | * execution environment: Command Execution Environment. |
37c41ab1 | 11218 | (line 6) |
ed35cb4a | 11219 | * exit status: Definitions. (line 26) |
8a0829e9 | 11220 | * exit status <1>: Exit Status. (line 6) |
37c41ab1 | 11221 | * expansion: Shell Expansions. (line 6) |
e8ce775d | 11222 | * expansion, arithmetic: Arithmetic Expansion. |
37c41ab1 CR |
11223 | (line 6) |
11224 | * expansion, brace: Brace Expansion. (line 6) | |
11225 | * expansion, filename: Filename Expansion. (line 9) | |
e8ce775d | 11226 | * expansion, parameter: Shell Parameter Expansion. |
37c41ab1 CR |
11227 | (line 6) |
11228 | * expansion, pathname: Filename Expansion. (line 9) | |
11229 | * expansion, tilde: Tilde Expansion. (line 6) | |
11230 | * expressions, arithmetic: Shell Arithmetic. (line 6) | |
e8ce775d | 11231 | * expressions, conditional: Bash Conditional Expressions. |
37c41ab1 | 11232 | (line 6) |
ed35cb4a CR |
11233 | * field: Definitions. (line 30) |
11234 | * filename: Definitions. (line 35) | |
37c41ab1 CR |
11235 | * filename expansion: Filename Expansion. (line 9) |
11236 | * foreground: Job Control Basics. (line 6) | |
11237 | * functions, shell: Shell Functions. (line 6) | |
cce855bc | 11238 | * history builtins: Bash History Builtins. |
37c41ab1 | 11239 | (line 6) |
e05be32d | 11240 | * history events: Event Designators. (line 8) |
37c41ab1 | 11241 | * history expansion: History Interaction. (line 6) |
e8ce775d | 11242 | * history list: Bash History Facilities. |
37c41ab1 | 11243 | (line 6) |
45c0f7f8 CR |
11244 | * History, how to use: A Programmable Completion Example. |
11245 | (line 114) | |
ed35cb4a | 11246 | * identifier: Definitions. (line 51) |
37c41ab1 CR |
11247 | * initialization file, readline: Readline Init File. (line 6) |
11248 | * installation: Basic Installation. (line 6) | |
e8ce775d | 11249 | * interaction, readline: Readline Interaction. |
37c41ab1 | 11250 | (line 6) |
fc527055 | 11251 | * interactive shell: Invoking Bash. (line 128) |
8a0829e9 | 11252 | * interactive shell <1>: Interactive Shells. (line 6) |
37c41ab1 | 11253 | * internationalization: Locale Translation. (line 6) |
ed35cb4a | 11254 | * job: Definitions. (line 38) |
ed35cb4a | 11255 | * job control: Definitions. (line 42) |
8a0829e9 | 11256 | * job control <1>: Job Control Basics. (line 6) |
e8ce775d | 11257 | * kill ring: Readline Killing Commands. |
8a0829e9 | 11258 | (line 18) |
e8ce775d | 11259 | * killing text: Readline Killing Commands. |
37c41ab1 CR |
11260 | (line 6) |
11261 | * localization: Locale Translation. (line 6) | |
fc527055 | 11262 | * login shell: Invoking Bash. (line 125) |
37c41ab1 | 11263 | * matching, pattern: Pattern Matching. (line 6) |
ed35cb4a CR |
11264 | * metacharacter: Definitions. (line 46) |
11265 | * name: Definitions. (line 51) | |
37c41ab1 | 11266 | * native languages: Locale Translation. (line 6) |
e8ce775d | 11267 | * notation, readline: Readline Bare Essentials. |
37c41ab1 | 11268 | (line 6) |
ed35cb4a | 11269 | * operator, shell: Definitions. (line 57) |
e8ce775d | 11270 | * parameter expansion: Shell Parameter Expansion. |
37c41ab1 CR |
11271 | (line 6) |
11272 | * parameters: Shell Parameters. (line 6) | |
e8ce775d | 11273 | * parameters, positional: Positional Parameters. |
37c41ab1 CR |
11274 | (line 6) |
11275 | * parameters, special: Special Parameters. (line 6) | |
11276 | * pathname expansion: Filename Expansion. (line 9) | |
11277 | * pattern matching: Pattern Matching. (line 6) | |
11278 | * pipeline: Pipelines. (line 6) | |
11279 | * POSIX: Definitions. (line 9) | |
11280 | * POSIX Mode: Bash POSIX Mode. (line 6) | |
a9fac3b2 CR |
11281 | * process group: Definitions. (line 62) |
11282 | * process group ID: Definitions. (line 66) | |
e8ce775d | 11283 | * process substitution: Process Substitution. |
37c41ab1 | 11284 | (line 6) |
bb70624e | 11285 | * programmable completion: Programmable Completion. |
37c41ab1 | 11286 | (line 6) |
122f603c CR |
11287 | * prompting: Controlling the Prompt. |
11288 | (line 6) | |
37c41ab1 CR |
11289 | * quoting: Quoting. (line 6) |
11290 | * quoting, ANSI: ANSI-C Quoting. (line 6) | |
bb70624e | 11291 | * Readline, how to use: Job Control Variables. |
8a0829e9 | 11292 | (line 23) |
37c41ab1 | 11293 | * redirection: Redirections. (line 6) |
a9fac3b2 | 11294 | * reserved word: Definitions. (line 70) |
e8ce775d | 11295 | * restricted shell: The Restricted Shell. |
37c41ab1 | 11296 | (line 6) |
a9fac3b2 | 11297 | * return status: Definitions. (line 75) |
37c41ab1 CR |
11298 | * shell arithmetic: Shell Arithmetic. (line 6) |
11299 | * shell function: Shell Functions. (line 6) | |
11300 | * shell script: Shell Scripts. (line 6) | |
11301 | * shell variable: Shell Parameters. (line 6) | |
11302 | * shell, interactive: Interactive Shells. (line 6) | |
a9fac3b2 | 11303 | * signal: Definitions. (line 78) |
37c41ab1 | 11304 | * signal handling: Signals. (line 6) |
a9fac3b2 | 11305 | * special builtin: Definitions. (line 82) |
8a0829e9 | 11306 | * special builtin <1>: Special Builtins. (line 6) |
37c41ab1 CR |
11307 | * startup files: Bash Startup Files. (line 6) |
11308 | * suspending jobs: Job Control Basics. (line 6) | |
11309 | * tilde expansion: Tilde Expansion. (line 6) | |
a9fac3b2 | 11310 | * token: Definitions. (line 86) |
37c41ab1 CR |
11311 | * translation, native languages: Locale Translation. (line 6) |
11312 | * variable, shell: Shell Parameters. (line 6) | |
28ef6c31 | 11313 | * variables, readline: Readline Init File Syntax. |
1c72c0cd | 11314 | (line 37) |
a9fac3b2 | 11315 | * word: Definitions. (line 90) |
37c41ab1 | 11316 | * word splitting: Word Splitting. (line 6) |
e8ce775d | 11317 | * yanking text: Readline Killing Commands. |
37c41ab1 | 11318 | (line 6) |
ccc6cda3 JA |
11319 | |
11320 | ||
11321 | \1f | |
11322 | Tag Table: | |
690150f9 CR |
11323 | Node: Top\7f895 |
11324 | Node: Introduction\7f2813 | |
11325 | Node: What is Bash?\7f3029 | |
11326 | Node: What is a shell?\7f4143 | |
11327 | Node: Definitions\7f6681 | |
11328 | Node: Basic Shell Features\7f9632 | |
11329 | Node: Shell Syntax\7f10851 | |
11330 | Node: Shell Operation\7f11877 | |
11331 | Node: Quoting\7f13170 | |
11332 | Node: Escape Character\7f14470 | |
11333 | Node: Single Quotes\7f14955 | |
11334 | Node: Double Quotes\7f15303 | |
11335 | Node: ANSI-C Quoting\7f16581 | |
11336 | Node: Locale Translation\7f17834 | |
11337 | Node: Comments\7f18730 | |
11338 | Node: Shell Commands\7f19348 | |
11339 | Node: Simple Commands\7f20220 | |
11340 | Node: Pipelines\7f20851 | |
11341 | Node: Lists\7f23594 | |
11342 | Node: Compound Commands\7f25323 | |
11343 | Node: Looping Constructs\7f26326 | |
11344 | Node: Conditional Constructs\7f28789 | |
11345 | Node: Command Grouping\7f39710 | |
11346 | Node: Coprocesses\7f41189 | |
11347 | Node: GNU Parallel\7f43021 | |
11348 | Node: Shell Functions\7f46994 | |
11349 | Node: Shell Parameters\7f52200 | |
11350 | Node: Positional Parameters\7f56602 | |
11351 | Node: Special Parameters\7f57502 | |
11352 | Node: Shell Expansions\7f60839 | |
11353 | Node: Brace Expansion\7f62776 | |
11354 | Node: Tilde Expansion\7f65557 | |
11355 | Node: Shell Parameter Expansion\7f67905 | |
11356 | Node: Command Substitution\7f82037 | |
11357 | Node: Arithmetic Expansion\7f83392 | |
11358 | Node: Process Substitution\7f84324 | |
11359 | Node: Word Splitting\7f85444 | |
11360 | Node: Filename Expansion\7f87388 | |
11361 | Node: Pattern Matching\7f89672 | |
11362 | Node: Quote Removal\7f93370 | |
11363 | Node: Redirections\7f93665 | |
11364 | Node: Executing Commands\7f102914 | |
11365 | Node: Simple Command Expansion\7f103584 | |
11366 | Node: Command Search and Execution\7f105514 | |
11367 | Node: Command Execution Environment\7f107850 | |
11368 | Node: Environment\7f110834 | |
11369 | Node: Exit Status\7f112493 | |
11370 | Node: Signals\7f114163 | |
11371 | Node: Shell Scripts\7f116130 | |
11372 | Node: Shell Builtin Commands\7f118645 | |
11373 | Node: Bourne Shell Builtins\7f120679 | |
11374 | Node: Bash Builtins\7f141281 | |
11375 | Node: Modifying Shell Behavior\7f169911 | |
11376 | Node: The Set Builtin\7f170256 | |
11377 | Node: The Shopt Builtin\7f180669 | |
11378 | Node: Special Builtins\7f196289 | |
11379 | Node: Shell Variables\7f197268 | |
11380 | Node: Bourne Shell Variables\7f197705 | |
11381 | Node: Bash Variables\7f199736 | |
11382 | Node: Bash Features\7f228000 | |
11383 | Node: Invoking Bash\7f228899 | |
11384 | Node: Bash Startup Files\7f234848 | |
11385 | Node: Interactive Shells\7f239951 | |
11386 | Node: What is an Interactive Shell?\7f240361 | |
11387 | Node: Is this Shell Interactive?\7f241010 | |
11388 | Node: Interactive Shell Behavior\7f241825 | |
11389 | Node: Bash Conditional Expressions\7f245200 | |
11390 | Node: Shell Arithmetic\7f249201 | |
11391 | Node: Aliases\7f251978 | |
11392 | Node: Arrays\7f254526 | |
11393 | Node: The Directory Stack\7f259610 | |
11394 | Node: Directory Stack Builtins\7f260394 | |
11395 | Node: Controlling the Prompt\7f263362 | |
11396 | Node: The Restricted Shell\7f266108 | |
11397 | Node: Bash POSIX Mode\7f267933 | |
11398 | Node: Job Control\7f277845 | |
11399 | Node: Job Control Basics\7f278305 | |
11400 | Node: Job Control Builtins\7f283024 | |
11401 | Node: Job Control Variables\7f287554 | |
11402 | Node: Command Line Editing\7f288710 | |
11403 | Node: Introduction and Notation\7f290381 | |
11404 | Node: Readline Interaction\7f292004 | |
11405 | Node: Readline Bare Essentials\7f293195 | |
11406 | Node: Readline Movement Commands\7f294978 | |
11407 | Node: Readline Killing Commands\7f295938 | |
11408 | Node: Readline Arguments\7f297856 | |
11409 | Node: Searching\7f298900 | |
11410 | Node: Readline Init File\7f301086 | |
11411 | Node: Readline Init File Syntax\7f302233 | |
11412 | Node: Conditional Init Constructs\7f321997 | |
11413 | Node: Sample Init File\7f324522 | |
11414 | Node: Bindable Readline Commands\7f327639 | |
11415 | Node: Commands For Moving\7f328843 | |
11416 | Node: Commands For History\7f329986 | |
11417 | Node: Commands For Text\7f334275 | |
11418 | Node: Commands For Killing\7f337664 | |
11419 | Node: Numeric Arguments\7f340145 | |
11420 | Node: Commands For Completion\7f341284 | |
11421 | Node: Keyboard Macros\7f345475 | |
11422 | Node: Miscellaneous Commands\7f346162 | |
11423 | Node: Readline vi Mode\7f351966 | |
11424 | Node: Programmable Completion\7f352873 | |
11425 | Node: Programmable Completion Builtins\7f360334 | |
11426 | Node: A Programmable Completion Example\7f370220 | |
11427 | Node: Using History Interactively\7f375472 | |
11428 | Node: Bash History Facilities\7f376156 | |
11429 | Node: Bash History Builtins\7f379157 | |
11430 | Node: History Interaction\7f383154 | |
11431 | Node: Event Designators\7f386118 | |
11432 | Node: Word Designators\7f387337 | |
11433 | Node: Modifiers\7f388974 | |
11434 | Node: Installing Bash\7f390376 | |
11435 | Node: Basic Installation\7f391513 | |
11436 | Node: Compilers and Options\7f394204 | |
11437 | Node: Compiling For Multiple Architectures\7f394945 | |
11438 | Node: Installation Names\7f396608 | |
11439 | Node: Specifying the System Type\7f397426 | |
11440 | Node: Sharing Defaults\7f398142 | |
11441 | Node: Operation Controls\7f398815 | |
11442 | Node: Optional Features\7f399773 | |
11443 | Node: Reporting Bugs\7f410030 | |
11444 | Node: Major Differences From The Bourne Shell\7f411224 | |
11445 | Node: GNU Free Documentation License\7f428076 | |
11446 | Node: Indexes\7f453253 | |
11447 | Node: Builtin Index\7f453707 | |
11448 | Node: Reserved Word Index\7f460534 | |
11449 | Node: Variable Index\7f462982 | |
11450 | Node: Function Index\7f478441 | |
11451 | Node: Concept Index\7f491661 | |
ccc6cda3 JA |
11452 | \1f |
11453 | End Tag Table |