]>
Commit | Line | Data |
---|---|---|
ccc6cda3 JA |
1 | \input texinfo.tex @c -*- texinfo -*- |
2 | @c %**start of header | |
3 | @setfilename bashref.info | |
4 | @settitle Bash Reference Manual | |
ccc6cda3 | 5 | |
b80f6443 | 6 | @include version.texi |
ac50fbac | 7 | @c %**end of header |
e8ce775d | 8 | |
b80f6443 | 9 | @copying |
ccc6cda3 | 10 | This text is a brief description of the features that are present in |
b80f6443 | 11 | the Bash shell (version @value{VERSION}, @value{UPDATED}). |
ccc6cda3 JA |
12 | |
13 | This is Edition @value{EDITION}, last updated @value{UPDATED}, | |
14 | of @cite{The GNU Bash Reference Manual}, | |
15 | for @code{Bash}, Version @value{VERSION}. | |
16 | ||
a0c0a00f | 17 | Copyright @copyright{} 1988--2016 Free Software Foundation, Inc. |
ccc6cda3 | 18 | |
b80f6443 JA |
19 | @quotation |
20 | Permission is granted to copy, distribute and/or modify this document | |
0001803f | 21 | under the terms of the GNU Free Documentation License, Version 1.3 or |
b80f6443 | 22 | any later version published by the Free Software Foundation; with no |
ac50fbac CR |
23 | Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. |
24 | A copy of the license is included in the section entitled | |
25 | ``GNU Free Documentation License''. | |
b80f6443 JA |
26 | @end quotation |
27 | @end copying | |
28 | ||
29 | @defcodeindex bt | |
30 | @defcodeindex rw | |
31 | @set BashFeatures | |
32 | ||
33 | @dircategory Basics | |
34 | @direntry | |
35 | * Bash: (bash). The GNU Bourne-Again SHell. | |
36 | @end direntry | |
37 | ||
38 | @finalout | |
ccc6cda3 JA |
39 | |
40 | @titlepage | |
41 | @title Bash Reference Manual | |
42 | @subtitle Reference Documentation for Bash | |
b72432fd | 43 | @subtitle Edition @value{EDITION}, for @code{Bash} Version @value{VERSION}. |
b80f6443 | 44 | @subtitle @value{UPDATED-MONTH} |
ccc6cda3 JA |
45 | @author Chet Ramey, Case Western Reserve University |
46 | @author Brian Fox, Free Software Foundation | |
b80f6443 | 47 | |
ccc6cda3 JA |
48 | @page |
49 | @vskip 0pt plus 1filll | |
b80f6443 | 50 | @insertcopying |
ccc6cda3 | 51 | |
ccc6cda3 JA |
52 | @end titlepage |
53 | ||
b80f6443 JA |
54 | @contents |
55 | ||
56 | @ifnottex | |
ccc6cda3 JA |
57 | @node Top, Introduction, (dir), (dir) |
58 | @top Bash Features | |
ccc6cda3 | 59 | |
ccc6cda3 | 60 | This text is a brief description of the features that are present in |
0628567a | 61 | the Bash shell (version @value{VERSION}, @value{UPDATED}). |
ac50fbac | 62 | The Bash home page is @url{http://www.gnu.org/software/bash/}. |
ccc6cda3 JA |
63 | |
64 | This is Edition @value{EDITION}, last updated @value{UPDATED}, | |
65 | of @cite{The GNU Bash Reference Manual}, | |
66 | for @code{Bash}, Version @value{VERSION}. | |
67 | ||
ccc6cda3 JA |
68 | Bash contains features that appear in other popular shells, and some |
69 | features that only appear in Bash. Some of the shells that Bash has | |
70 | borrowed concepts from are the Bourne Shell (@file{sh}), the Korn Shell | |
71 | (@file{ksh}), and the C-shell (@file{csh} and its successor, | |
ac50fbac CR |
72 | @file{tcsh}). The following menu breaks the features up into |
73 | categories, noting which features were inspired by other shells and | |
74 | which are specific to Bash. | |
ccc6cda3 JA |
75 | |
76 | This manual is meant as a brief introduction to features found in | |
77 | Bash. The Bash manual page should be used as the definitive | |
78 | reference on shell behavior. | |
79 | ||
80 | @menu | |
81 | * Introduction:: An introduction to the shell. | |
ccc6cda3 JA |
82 | * Definitions:: Some definitions used in the rest of this |
83 | manual. | |
ccc6cda3 | 84 | * Basic Shell Features:: The shell "building blocks". |
bb70624e | 85 | * Shell Builtin Commands:: Commands that are a part of the shell. |
bb70624e | 86 | * Shell Variables:: Variables used or set by Bash. |
ccc6cda3 | 87 | * Bash Features:: Features found only in Bash. |
95732b49 JA |
88 | * Job Control:: What job control is and how Bash allows you |
89 | to use it. | |
ccc6cda3 JA |
90 | * Command Line Editing:: Chapter describing the command line |
91 | editing features. | |
3185942a | 92 | * Using History Interactively:: Command History Expansion |
ccc6cda3 | 93 | * Installing Bash:: How to build and install Bash on your system. |
ccc6cda3 | 94 | * Reporting Bugs:: How to report bugs in Bash. |
bb70624e JA |
95 | * Major Differences From The Bourne Shell:: A terse list of the differences |
96 | between Bash and historical | |
97 | versions of /bin/sh. | |
3185942a JA |
98 | * GNU Free Documentation License:: Copying and sharing this documentation. |
99 | * Indexes:: Various indexes for this manual. | |
ccc6cda3 | 100 | @end menu |
b80f6443 | 101 | @end ifnottex |
ccc6cda3 JA |
102 | |
103 | @node Introduction | |
104 | @chapter Introduction | |
105 | @menu | |
106 | * What is Bash?:: A short description of Bash. | |
ccc6cda3 JA |
107 | * What is a shell?:: A brief introduction to shells. |
108 | @end menu | |
109 | ||
110 | @node What is Bash? | |
111 | @section What is Bash? | |
112 | ||
113 | Bash is the shell, or command language interpreter, | |
bb70624e | 114 | for the @sc{gnu} operating system. |
ccc6cda3 | 115 | The name is an acronym for the @samp{Bourne-Again SHell}, |
bb70624e | 116 | a pun on Stephen Bourne, the author of the direct ancestor of |
b80f6443 | 117 | the current Unix shell @code{sh}, |
ccc6cda3 JA |
118 | which appeared in the Seventh Edition Bell Labs Research version |
119 | of Unix. | |
120 | ||
bb70624e | 121 | Bash is largely compatible with @code{sh} and incorporates useful |
ccc6cda3 | 122 | features from the Korn shell @code{ksh} and the C shell @code{csh}. |
bb70624e | 123 | It is intended to be a conformant implementation of the @sc{ieee} |
0628567a JA |
124 | @sc{posix} Shell and Tools portion of the @sc{ieee} @sc{posix} |
125 | specification (@sc{ieee} Standard 1003.1). | |
cce855bc JA |
126 | It offers functional improvements over @code{sh} for both interactive and |
127 | programming use. | |
ccc6cda3 | 128 | |
bb70624e JA |
129 | While the @sc{gnu} operating system provides other shells, including |
130 | a version of @code{csh}, Bash is the default shell. | |
131 | Like other @sc{gnu} software, Bash is quite portable. It currently runs | |
ccc6cda3 | 132 | on nearly every version of Unix and a few other operating systems @minus{} |
bb70624e | 133 | independently-supported ports exist for @sc{ms-dos}, @sc{os/2}, |
b80f6443 | 134 | and Windows platforms. |
ccc6cda3 JA |
135 | |
136 | @node What is a shell? | |
137 | @section What is a shell? | |
138 | ||
139 | At its base, a shell is simply a macro processor that executes | |
b80f6443 JA |
140 | commands. The term macro processor means functionality where text |
141 | and symbols are expanded to create larger expressions. | |
142 | ||
143 | A Unix shell is both a command interpreter and a programming | |
144 | language. As a command interpreter, the shell provides the user | |
145 | interface to the rich set of @sc{gnu} utilities. The programming | |
3185942a | 146 | language features allow these utilities to be combined. |
b80f6443 | 147 | Files containing commands can be created, and become |
ccc6cda3 | 148 | commands themselves. These new commands have the same status as |
bb70624e | 149 | system commands in directories such as @file{/bin}, allowing users |
b80f6443 JA |
150 | or groups to establish custom environments to automate their common |
151 | tasks. | |
152 | ||
153 | Shells may be used interactively or non-interactively. In | |
154 | interactive mode, they accept input typed from the keyboard. | |
155 | When executing non-interactively, shells execute commands read | |
156 | from a file. | |
ccc6cda3 | 157 | |
bb70624e | 158 | A shell allows execution of @sc{gnu} commands, both synchronously and |
cce855bc JA |
159 | asynchronously. |
160 | The shell waits for synchronous commands to complete before accepting | |
161 | more input; asynchronous commands continue to execute in parallel | |
162 | with the shell while it reads and executes additional commands. | |
163 | The @dfn{redirection} constructs permit | |
bb70624e JA |
164 | fine-grained control of the input and output of those commands. |
165 | Moreover, the shell allows control over the contents of commands' | |
166 | environments. | |
bb70624e JA |
167 | |
168 | Shells also provide a small set of built-in | |
ccc6cda3 | 169 | commands (@dfn{builtins}) implementing functionality impossible |
bb70624e JA |
170 | or inconvenient to obtain via separate utilities. |
171 | For example, @code{cd}, @code{break}, @code{continue}, and | |
ac50fbac | 172 | @code{exec} cannot be implemented outside of the shell because |
bb70624e JA |
173 | they directly manipulate the shell itself. |
174 | The @code{history}, @code{getopts}, @code{kill}, or @code{pwd} | |
175 | builtins, among others, could be implemented in separate utilities, | |
176 | but they are more convenient to use as builtin commands. | |
177 | All of the shell builtins are described in | |
ccc6cda3 JA |
178 | subsequent sections. |
179 | ||
180 | While executing commands is essential, most of the power (and | |
181 | complexity) of shells is due to their embedded programming | |
182 | languages. Like any high-level language, the shell provides | |
183 | variables, flow control constructs, quoting, and functions. | |
184 | ||
bb70624e | 185 | Shells offer features geared specifically for |
ccc6cda3 JA |
186 | interactive use rather than to augment the programming language. |
187 | These interactive features include job control, command line | |
b80f6443 | 188 | editing, command history and aliases. Each of these features is |
ccc6cda3 JA |
189 | described in this manual. |
190 | ||
191 | @node Definitions | |
192 | @chapter Definitions | |
193 | These definitions are used throughout the remainder of this manual. | |
194 | ||
195 | @table @code | |
196 | ||
197 | @item POSIX | |
198 | @cindex POSIX | |
199 | A family of open system standards based on Unix. Bash | |
0628567a JA |
200 | is primarily concerned with the Shell and Utilities portion of the |
201 | @sc{posix} 1003.1 standard. | |
ccc6cda3 JA |
202 | |
203 | @item blank | |
204 | A space or tab character. | |
205 | ||
206 | @item builtin | |
207 | @cindex builtin | |
208 | A command that is implemented internally by the shell itself, rather | |
209 | than by an executable program somewhere in the file system. | |
210 | ||
211 | @item control operator | |
212 | @cindex control operator | |
3185942a | 213 | A @code{token} that performs a control function. It is a @code{newline} |
ccc6cda3 | 214 | or one of the following: |
a0c0a00f | 215 | @samp{||}, @samp{&&}, @samp{&}, @samp{;}, @samp{;;}, @samp{;&}, @samp{;;&}, |
3185942a | 216 | @samp{|}, @samp{|&}, @samp{(}, or @samp{)}. |
ccc6cda3 JA |
217 | |
218 | @item exit status | |
219 | @cindex exit status | |
f73dda09 JA |
220 | The value returned by a command to its caller. The value is restricted |
221 | to eight bits, so the maximum value is 255. | |
ccc6cda3 JA |
222 | |
223 | @item field | |
224 | @cindex field | |
225 | A unit of text that is the result of one of the shell expansions. After | |
226 | expansion, when executing a command, the resulting fields are used as | |
227 | the command name and arguments. | |
228 | ||
229 | @item filename | |
230 | @cindex filename | |
231 | A string of characters used to identify a file. | |
232 | ||
233 | @item job | |
234 | @cindex job | |
235 | A set of processes comprising a pipeline, and any processes descended | |
236 | from it, that are all in the same process group. | |
237 | ||
238 | @item job control | |
239 | @cindex job control | |
d166f048 JA |
240 | A mechanism by which users can selectively stop (suspend) and restart |
241 | (resume) execution of processes. | |
ccc6cda3 JA |
242 | |
243 | @item metacharacter | |
244 | @cindex metacharacter | |
245 | A character that, when unquoted, separates words. A metacharacter is | |
a0c0a00f | 246 | a @code{space}, @code{tab}, @code{newline}, or one of the following characters: |
ccc6cda3 JA |
247 | @samp{|}, @samp{&}, @samp{;}, @samp{(}, @samp{)}, @samp{<}, or |
248 | @samp{>}. | |
249 | ||
250 | @item name | |
251 | @cindex name | |
252 | @cindex identifier | |
253 | A @code{word} consisting solely of letters, numbers, and underscores, | |
254 | and beginning with a letter or underscore. @code{Name}s are used as | |
255 | shell variable and function names. | |
256 | Also referred to as an @code{identifier}. | |
257 | ||
258 | @item operator | |
259 | @cindex operator, shell | |
260 | A @code{control operator} or a @code{redirection operator}. | |
261 | @xref{Redirections}, for a list of redirection operators. | |
3185942a | 262 | Operators contain at least one unquoted @code{metacharacter}. |
ccc6cda3 JA |
263 | |
264 | @item process group | |
265 | @cindex process group | |
266 | A collection of related processes each having the same process | |
bb70624e | 267 | group @sc{id}. |
ccc6cda3 JA |
268 | |
269 | @item process group ID | |
270 | @cindex process group ID | |
3185942a | 271 | A unique identifier that represents a @code{process group} |
ccc6cda3 JA |
272 | during its lifetime. |
273 | ||
274 | @item reserved word | |
275 | @cindex reserved word | |
276 | A @code{word} that has a special meaning to the shell. Most reserved | |
277 | words introduce shell flow control constructs, such as @code{for} and | |
278 | @code{while}. | |
279 | ||
280 | @item return status | |
281 | @cindex return status | |
282 | A synonym for @code{exit status}. | |
283 | ||
284 | @item signal | |
285 | @cindex signal | |
bb70624e | 286 | A mechanism by which a process may be notified by the kernel |
ccc6cda3 JA |
287 | of an event occurring in the system. |
288 | ||
289 | @item special builtin | |
290 | @cindex special builtin | |
291 | A shell builtin command that has been classified as special by the | |
0628567a | 292 | @sc{posix} standard. |
ccc6cda3 JA |
293 | |
294 | @item token | |
295 | @cindex token | |
3185942a JA |
296 | A sequence of characters considered a single unit by the shell. |
297 | It is either a @code{word} or an @code{operator}. | |
ccc6cda3 JA |
298 | |
299 | @item word | |
300 | @cindex word | |
3185942a JA |
301 | A sequence of characters treated as a unit by the shell. |
302 | Words may not include unquoted @code{metacharacters}. | |
ccc6cda3 JA |
303 | @end table |
304 | ||
305 | @node Basic Shell Features | |
306 | @chapter Basic Shell Features | |
307 | @cindex Bourne shell | |
308 | ||
309 | Bash is an acronym for @samp{Bourne-Again SHell}. | |
310 | The Bourne shell is | |
311 | the traditional Unix shell originally written by Stephen Bourne. | |
312 | All of the Bourne shell builtin commands are available in Bash, | |
b80f6443 JA |
313 | The rules for evaluation and quoting are taken from the @sc{posix} |
314 | specification for the `standard' Unix shell. | |
ccc6cda3 | 315 | |
cce855bc | 316 | This chapter briefly summarizes the shell's `building blocks': |
ccc6cda3 JA |
317 | commands, control structures, shell functions, shell @i{parameters}, |
318 | shell expansions, | |
319 | @i{redirections}, which are a way to direct input and output from | |
320 | and to named files, and how the shell executes commands. | |
321 | ||
322 | @menu | |
323 | * Shell Syntax:: What your input means to the shell. | |
cce855bc | 324 | * Shell Commands:: The types of commands you can use. |
ccc6cda3 | 325 | * Shell Functions:: Grouping commands by name. |
b80f6443 JA |
326 | * Shell Parameters:: How the shell stores values. |
327 | * Shell Expansions:: How Bash expands parameters and the various | |
ccc6cda3 JA |
328 | expansions available. |
329 | * Redirections:: A way to control where input and output go. | |
330 | * Executing Commands:: What happens when you run a command. | |
331 | * Shell Scripts:: Executing files of shell commands. | |
332 | @end menu | |
333 | ||
334 | @node Shell Syntax | |
335 | @section Shell Syntax | |
336 | @menu | |
337 | * Shell Operation:: The basic operation of the shell. | |
ccc6cda3 | 338 | * Quoting:: How to remove the special meaning from characters. |
ccc6cda3 JA |
339 | * Comments:: How to specify comments. |
340 | @end menu | |
341 | ||
bb70624e JA |
342 | When the shell reads input, it proceeds through a |
343 | sequence of operations. If the input indicates the beginning of a | |
344 | comment, the shell ignores the comment symbol (@samp{#}), and the rest | |
345 | of that line. | |
346 | ||
347 | Otherwise, roughly speaking, the shell reads its input and | |
348 | divides the input into words and operators, employing the quoting rules | |
349 | to select which meanings to assign various words and characters. | |
350 | ||
351 | The shell then parses these tokens into commands and other constructs, | |
352 | removes the special meaning of certain words or characters, expands | |
353 | others, redirects input and output as needed, executes the specified | |
354 | command, waits for the command's exit status, and makes that exit status | |
355 | available for further inspection or processing. | |
356 | ||
ccc6cda3 JA |
357 | @node Shell Operation |
358 | @subsection Shell Operation | |
359 | ||
360 | The following is a brief description of the shell's operation when it | |
361 | reads and executes a command. Basically, the shell does the | |
362 | following: | |
363 | ||
364 | @enumerate | |
365 | @item | |
366 | Reads its input from a file (@pxref{Shell Scripts}), from a string | |
28ef6c31 | 367 | supplied as an argument to the @option{-c} invocation option |
ccc6cda3 JA |
368 | (@pxref{Invoking Bash}), or from the user's terminal. |
369 | ||
370 | @item | |
371 | Breaks the input into words and operators, obeying the quoting rules | |
cce855bc | 372 | described in @ref{Quoting}. These tokens are separated by |
ccc6cda3 JA |
373 | @code{metacharacters}. Alias expansion is performed by this step |
374 | (@pxref{Aliases}). | |
375 | ||
376 | @item | |
cce855bc JA |
377 | Parses the tokens into simple and compound commands |
378 | (@pxref{Shell Commands}). | |
ccc6cda3 JA |
379 | |
380 | @item | |
381 | Performs the various shell expansions (@pxref{Shell Expansions}), breaking | |
382 | the expanded tokens into lists of filenames (@pxref{Filename Expansion}) | |
383 | and commands and arguments. | |
384 | ||
385 | @item | |
386 | Performs any necessary redirections (@pxref{Redirections}) and removes | |
387 | the redirection operators and their operands from the argument list. | |
388 | ||
389 | @item | |
390 | Executes the command (@pxref{Executing Commands}). | |
391 | ||
392 | @item | |
393 | Optionally waits for the command to complete and collects its exit | |
cce855bc | 394 | status (@pxref{Exit Status}). |
ccc6cda3 JA |
395 | |
396 | @end enumerate | |
397 | ||
398 | @node Quoting | |
399 | @subsection Quoting | |
400 | @cindex quoting | |
401 | @menu | |
402 | * Escape Character:: How to remove the special meaning from a single | |
403 | character. | |
404 | * Single Quotes:: How to inhibit all interpretation of a sequence | |
405 | of characters. | |
406 | * Double Quotes:: How to suppress most of the interpretation of a | |
407 | sequence of characters. | |
408 | * ANSI-C Quoting:: How to expand ANSI-C sequences in quoted strings. | |
ccc6cda3 JA |
409 | * Locale Translation:: How to translate strings into different languages. |
410 | @end menu | |
411 | ||
412 | Quoting is used to remove the special meaning of certain | |
413 | characters or words to the shell. Quoting can be used to | |
414 | disable special treatment for special characters, to prevent | |
415 | reserved words from being recognized as such, and to prevent | |
416 | parameter expansion. | |
417 | ||
cce855bc JA |
418 | Each of the shell metacharacters (@pxref{Definitions}) |
419 | has special meaning to the shell and must be quoted if it is to | |
bb70624e | 420 | represent itself. |
95732b49 JA |
421 | When the command history expansion facilities are being used |
422 | (@pxref{History Interaction}), the | |
bb70624e | 423 | @var{history expansion} character, usually @samp{!}, must be quoted |
28ef6c31 | 424 | to prevent history expansion. @xref{Bash History Facilities}, for |
bb70624e | 425 | more details concerning history expansion. |
b80f6443 | 426 | |
bb70624e | 427 | There are three quoting mechanisms: the |
ccc6cda3 JA |
428 | @var{escape character}, single quotes, and double quotes. |
429 | ||
430 | @node Escape Character | |
431 | @subsubsection Escape Character | |
432 | A non-quoted backslash @samp{\} is the Bash escape character. | |
433 | It preserves the literal value of the next character that follows, | |
434 | with the exception of @code{newline}. If a @code{\newline} pair | |
cce855bc JA |
435 | appears, and the backslash itself is not quoted, the @code{\newline} |
436 | is treated as a line continuation (that is, it is removed from | |
437 | the input stream and effectively ignored). | |
ccc6cda3 JA |
438 | |
439 | @node Single Quotes | |
440 | @subsubsection Single Quotes | |
441 | ||
bb70624e | 442 | Enclosing characters in single quotes (@samp{'}) preserves the literal value |
ccc6cda3 JA |
443 | of each character within the quotes. A single quote may not occur |
444 | between single quotes, even when preceded by a backslash. | |
445 | ||
446 | @node Double Quotes | |
447 | @subsubsection Double Quotes | |
448 | ||
bb70624e | 449 | Enclosing characters in double quotes (@samp{"}) preserves the literal value |
ccc6cda3 | 450 | of all characters within the quotes, with the exception of |
95732b49 JA |
451 | @samp{$}, @samp{`}, @samp{\}, |
452 | and, when history expansion is enabled, @samp{!}. | |
a0c0a00f CR |
453 | When the shell is in |
454 | @sc{posix} mode (@pxref{Bash POSIX Mode}), | |
455 | the @samp{!} has no special meaning | |
456 | within double quotes, even when history expansion is enabled. | |
ccc6cda3 | 457 | The characters @samp{$} and @samp{`} |
cce855bc JA |
458 | retain their special meaning within double quotes (@pxref{Shell Expansions}). |
459 | The backslash retains its special meaning only when followed by one of | |
460 | the following characters: | |
ccc6cda3 | 461 | @samp{$}, @samp{`}, @samp{"}, @samp{\}, or @code{newline}. |
cce855bc JA |
462 | Within double quotes, backslashes that are followed by one of these |
463 | characters are removed. Backslashes preceding characters without a | |
464 | special meaning are left unmodified. | |
ccc6cda3 JA |
465 | A double quote may be quoted within double quotes by preceding it with |
466 | a backslash. | |
95732b49 JA |
467 | If enabled, history expansion will be performed unless an @samp{!} |
468 | appearing in double quotes is escaped using a backslash. | |
469 | The backslash preceding the @samp{!} is not removed. | |
ccc6cda3 JA |
470 | |
471 | The special parameters @samp{*} and @samp{@@} have special meaning | |
472 | when in double quotes (@pxref{Shell Parameter Expansion}). | |
473 | ||
474 | @node ANSI-C Quoting | |
475 | @subsubsection ANSI-C Quoting | |
476 | @cindex quoting, ANSI | |
477 | ||
478 | Words of the form @code{$'@var{string}'} are treated specially. The | |
479 | word expands to @var{string}, with backslash-escaped characters replaced | |
28ef6c31 | 480 | as specified by the ANSI C standard. Backslash escape sequences, if |
ccc6cda3 JA |
481 | present, are decoded as follows: |
482 | ||
483 | @table @code | |
484 | @item \a | |
485 | alert (bell) | |
486 | @item \b | |
487 | backspace | |
488 | @item \e | |
0001803f | 489 | @itemx \E |
ccc6cda3 JA |
490 | an escape character (not ANSI C) |
491 | @item \f | |
492 | form feed | |
493 | @item \n | |
494 | newline | |
495 | @item \r | |
496 | carriage return | |
497 | @item \t | |
498 | horizontal tab | |
499 | @item \v | |
500 | vertical tab | |
501 | @item \\ | |
502 | backslash | |
bb70624e JA |
503 | @item \' |
504 | single quote | |
0001803f CR |
505 | @item \" |
506 | double quote | |
a0c0a00f CR |
507 | @item \? |
508 | question mark | |
ccc6cda3 | 509 | @item \@var{nnn} |
f73dda09 | 510 | the eight-bit character whose value is the octal value @var{nnn} |
cce855bc | 511 | (one to three digits) |
f73dda09 JA |
512 | @item \x@var{HH} |
513 | the eight-bit character whose value is the hexadecimal value @var{HH} | |
514 | (one or two hex digits) | |
495aee44 CR |
515 | @item \u@var{HHHH} |
516 | the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value | |
517 | @var{HHHH} (one to four hex digits) | |
518 | @item \U@var{HHHHHHHH} | |
519 | the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value | |
520 | @var{HHHHHHHH} (one to eight hex digits) | |
7117c2d2 JA |
521 | @item \c@var{x} |
522 | a control-@var{x} character | |
ccc6cda3 JA |
523 | @end table |
524 | ||
525 | @noindent | |
bb70624e JA |
526 | The expanded result is single-quoted, as if the dollar sign had not |
527 | been present. | |
ccc6cda3 JA |
528 | |
529 | @node Locale Translation | |
530 | @subsubsection Locale-Specific Translation | |
531 | @cindex localization | |
f73dda09 JA |
532 | @cindex internationalization |
533 | @cindex native languages | |
534 | @cindex translation, native languages | |
ccc6cda3 JA |
535 | |
536 | A double-quoted string preceded by a dollar sign (@samp{$}) will cause | |
537 | the string to be translated according to the current locale. | |
538 | If the current locale is @code{C} or @code{POSIX}, the dollar sign | |
539 | is ignored. | |
540 | If the string is translated and replaced, the replacement is | |
541 | double-quoted. | |
542 | ||
f73dda09 JA |
543 | @vindex LC_MESSAGES |
544 | @vindex TEXTDOMAIN | |
545 | @vindex TEXTDOMAINDIR | |
28ef6c31 JA |
546 | Some systems use the message catalog selected by the @env{LC_MESSAGES} |
547 | shell variable. Others create the name of the message catalog from the | |
548 | value of the @env{TEXTDOMAIN} shell variable, possibly adding a | |
549 | suffix of @samp{.mo}. If you use the @env{TEXTDOMAIN} variable, you | |
550 | may need to set the @env{TEXTDOMAINDIR} variable to the location of | |
f73dda09 JA |
551 | the message catalog files. Still others use both variables in this |
552 | fashion: | |
553 | @env{TEXTDOMAINDIR}/@env{LC_MESSAGES}/LC_MESSAGES/@env{TEXTDOMAIN}.mo. | |
28ef6c31 | 554 | |
ccc6cda3 JA |
555 | @node Comments |
556 | @subsection Comments | |
557 | @cindex comments, shell | |
558 | ||
559 | In a non-interactive shell, or an interactive shell in which the | |
560 | @code{interactive_comments} option to the @code{shopt} | |
3185942a | 561 | builtin is enabled (@pxref{The Shopt Builtin}), |
ccc6cda3 JA |
562 | a word beginning with @samp{#} |
563 | causes that word and all remaining characters on that line to | |
564 | be ignored. An interactive shell without the @code{interactive_comments} | |
565 | option enabled does not allow comments. The @code{interactive_comments} | |
566 | option is on by default in interactive shells. | |
bb70624e | 567 | @xref{Interactive Shells}, for a description of what makes |
cce855bc JA |
568 | a shell interactive. |
569 | ||
570 | @node Shell Commands | |
571 | @section Shell Commands | |
572 | @cindex commands, shell | |
bb70624e JA |
573 | |
574 | A simple shell command such as @code{echo a b c} consists of the command | |
575 | itself followed by arguments, separated by spaces. | |
576 | ||
577 | More complex shell commands are composed of simple commands arranged together | |
578 | in a variety of ways: in a pipeline in which the output of one command | |
579 | becomes the input of a second, in a loop or conditional construct, or in | |
580 | some other grouping. | |
581 | ||
cce855bc JA |
582 | @menu |
583 | * Simple Commands:: The most common type of command. | |
584 | * Pipelines:: Connecting the input and output of several | |
585 | commands. | |
586 | * Lists:: How to execute commands sequentially. | |
b80f6443 | 587 | * Compound Commands:: Shell commands for control flow. |
3185942a | 588 | * Coprocesses:: Two-way communication between commands. |
495aee44 | 589 | * GNU Parallel:: Running commands in parallel. |
cce855bc | 590 | @end menu |
ccc6cda3 JA |
591 | |
592 | @node Simple Commands | |
cce855bc | 593 | @subsection Simple Commands |
ccc6cda3 JA |
594 | @cindex commands, simple |
595 | ||
cce855bc | 596 | A simple command is the kind of command encountered most often. |
ccc6cda3 | 597 | It's just a sequence of words separated by @code{blank}s, terminated |
cce855bc | 598 | by one of the shell's control operators (@pxref{Definitions}). The |
bb70624e JA |
599 | first word generally specifies a command to be executed, with the |
600 | rest of the words being that command's arguments. | |
ccc6cda3 JA |
601 | |
602 | The return status (@pxref{Exit Status}) of a simple command is | |
603 | its exit status as provided | |
bb70624e JA |
604 | by the @sc{posix} 1003.1 @code{waitpid} function, or 128+@var{n} if |
605 | the command was terminated by signal @var{n}. | |
ccc6cda3 JA |
606 | |
607 | @node Pipelines | |
cce855bc | 608 | @subsection Pipelines |
ccc6cda3 JA |
609 | @cindex pipeline |
610 | @cindex commands, pipelines | |
611 | ||
a0c0a00f CR |
612 | A @code{pipeline} is a sequence of one or more commands separated by |
613 | one of the control operators @samp{|} or @samp{|&}. | |
ccc6cda3 JA |
614 | |
615 | @rwindex time | |
616 | @rwindex ! | |
617 | @cindex command timing | |
618 | The format for a pipeline is | |
619 | @example | |
ac50fbac | 620 | [time [-p]] [!] @var{command1} [ | or |& @var{command2} ] @dots{} |
ccc6cda3 JA |
621 | @end example |
622 | ||
623 | @noindent | |
f73dda09 JA |
624 | The output of each command in the pipeline is connected via a pipe |
625 | to the input of the next command. | |
3185942a JA |
626 | That is, each command reads the previous command's output. This |
627 | connection is performed before any redirections specified by the | |
628 | command. | |
629 | ||
ac50fbac CR |
630 | If @samp{|&} is used, @var{command1}'s standard error, in addition to |
631 | its standard output, is connected to | |
632 | @var{command2}'s standard input through the pipe; | |
633 | it is shorthand for @code{2>&1 |}. | |
634 | This implicit redirection of the standard error to the standard output is | |
3185942a | 635 | performed after any redirections specified by the command. |
ccc6cda3 JA |
636 | |
637 | The reserved word @code{time} causes timing statistics | |
638 | to be printed for the pipeline once it finishes. | |
cce855bc JA |
639 | The statistics currently consist of elapsed (wall-clock) time and |
640 | user and system time consumed by the command's execution. | |
28ef6c31 | 641 | The @option{-p} option changes the output format to that specified |
bb70624e | 642 | by @sc{posix}. |
495aee44 CR |
643 | When the shell is in @sc{posix} mode (@pxref{Bash POSIX Mode}), |
644 | it does not recognize @code{time} as a reserved word if the next | |
645 | token begins with a @samp{-}. | |
28ef6c31 | 646 | The @env{TIMEFORMAT} variable may be set to a format string that |
ccc6cda3 JA |
647 | specifies how the timing information should be displayed. |
648 | @xref{Bash Variables}, for a description of the available formats. | |
cce855bc JA |
649 | The use of @code{time} as a reserved word permits the timing of |
650 | shell builtins, shell functions, and pipelines. An external | |
651 | @code{time} command cannot time these easily. | |
652 | ||
495aee44 CR |
653 | When the shell is in @sc{posix} mode (@pxref{Bash POSIX Mode}), @code{time} |
654 | may be followed by a newline. In this case, the shell displays the | |
655 | total user and system time consumed by the shell and its children. | |
656 | The @env{TIMEFORMAT} variable may be used to specify the format of | |
657 | the time information. | |
658 | ||
cce855bc JA |
659 | If the pipeline is not executed asynchronously (@pxref{Lists}), the |
660 | shell waits for all commands in the pipeline to complete. | |
ccc6cda3 | 661 | |
cce855bc JA |
662 | Each command in a pipeline is executed in its own subshell |
663 | (@pxref{Command Execution Environment}). The exit | |
ccc6cda3 | 664 | status of a pipeline is the exit status of the last command in the |
b80f6443 JA |
665 | pipeline, unless the @code{pipefail} option is enabled |
666 | (@pxref{The Set Builtin}). | |
667 | If @code{pipefail} is enabled, the pipeline's return status is the | |
668 | value of the last (rightmost) command to exit with a non-zero status, | |
669 | or zero if all commands exit successfully. | |
670 | If the reserved word @samp{!} precedes the pipeline, the | |
671 | exit status is the logical negation of the exit status as described | |
672 | above. | |
673 | The shell waits for all commands in the pipeline to terminate before | |
674 | returning a value. | |
ccc6cda3 JA |
675 | |
676 | @node Lists | |
cce855bc | 677 | @subsection Lists of Commands |
ccc6cda3 JA |
678 | @cindex commands, lists |
679 | ||
680 | A @code{list} is a sequence of one or more pipelines separated by one | |
681 | of the operators @samp{;}, @samp{&}, @samp{&&}, or @samp{||}, | |
682 | and optionally terminated by one of @samp{;}, @samp{&}, or a | |
683 | @code{newline}. | |
684 | ||
685 | Of these list operators, @samp{&&} and @samp{||} | |
686 | have equal precedence, followed by @samp{;} and @samp{&}, | |
687 | which have equal precedence. | |
688 | ||
7117c2d2 JA |
689 | A sequence of one or more newlines may appear in a @code{list} |
690 | to delimit commands, equivalent to a semicolon. | |
691 | ||
ccc6cda3 | 692 | If a command is terminated by the control operator @samp{&}, |
cce855bc JA |
693 | the shell executes the command asynchronously in a subshell. |
694 | This is known as executing the command in the @var{background}. | |
695 | The shell does not wait for the command to finish, and the return | |
696 | status is 0 (true). | |
bb70624e JA |
697 | When job control is not active (@pxref{Job Control}), |
698 | the standard input for asynchronous commands, in the absence of any | |
cce855bc JA |
699 | explicit redirections, is redirected from @code{/dev/null}. |
700 | ||
701 | Commands separated by a @samp{;} are executed sequentially; the shell | |
702 | waits for each command to terminate in turn. The return status is the | |
ccc6cda3 JA |
703 | exit status of the last command executed. |
704 | ||
3185942a JA |
705 | @sc{and} and @sc{or} lists are sequences of one or more pipelines |
706 | separated by the control operators @samp{&&} and @samp{||}, | |
707 | respectively. @sc{and} and @sc{or} lists are executed with left | |
708 | associativity. | |
709 | ||
bb70624e | 710 | An @sc{and} list has the form |
ccc6cda3 | 711 | @example |
bb70624e | 712 | @var{command1} && @var{command2} |
ccc6cda3 JA |
713 | @end example |
714 | ||
715 | @noindent | |
bb70624e | 716 | @var{command2} is executed if, and only if, @var{command1} |
ccc6cda3 JA |
717 | returns an exit status of zero. |
718 | ||
bb70624e | 719 | An @sc{or} list has the form |
ccc6cda3 | 720 | @example |
bb70624e | 721 | @var{command1} || @var{command2} |
ccc6cda3 JA |
722 | @end example |
723 | ||
724 | @noindent | |
bb70624e | 725 | @var{command2} is executed if, and only if, @var{command1} |
ccc6cda3 JA |
726 | returns a non-zero exit status. |
727 | ||
728 | The return status of | |
bb70624e | 729 | @sc{and} and @sc{or} lists is the exit status of the last command |
ccc6cda3 JA |
730 | executed in the list. |
731 | ||
b80f6443 JA |
732 | @node Compound Commands |
733 | @subsection Compound Commands | |
734 | @cindex commands, compound | |
735 | ||
736 | @menu | |
737 | * Looping Constructs:: Shell commands for iterative action. | |
738 | * Conditional Constructs:: Shell commands for conditional execution. | |
739 | * Command Grouping:: Ways to group commands. | |
740 | @end menu | |
741 | ||
742 | Compound commands are the shell programming constructs. | |
743 | Each construct begins with a reserved word or control operator and is | |
744 | terminated by a corresponding reserved word or operator. | |
745 | Any redirections (@pxref{Redirections}) associated with a compound command | |
746 | apply to all commands within that compound command unless explicitly overridden. | |
747 | ||
ac50fbac CR |
748 | In most cases a list of commands in a compound command's description may be |
749 | separated from the rest of the command by one or more newlines, and may be | |
750 | followed by a newline in place of a semicolon. | |
751 | ||
b80f6443 JA |
752 | Bash provides looping constructs, conditional commands, and mechanisms |
753 | to group commands and execute them as a unit. | |
754 | ||
ccc6cda3 | 755 | @node Looping Constructs |
b80f6443 | 756 | @subsubsection Looping Constructs |
ccc6cda3 JA |
757 | @cindex commands, looping |
758 | ||
ccc6cda3 JA |
759 | Bash supports the following looping constructs. |
760 | ||
bb70624e | 761 | Note that wherever a @samp{;} appears in the description of a |
cce855bc JA |
762 | command's syntax, it may be replaced with one or more newlines. |
763 | ||
ccc6cda3 JA |
764 | @table @code |
765 | @item until | |
766 | @rwindex until | |
767 | @rwindex do | |
768 | @rwindex done | |
769 | The syntax of the @code{until} command is: | |
ac50fbac | 770 | |
ccc6cda3 JA |
771 | @example |
772 | until @var{test-commands}; do @var{consequent-commands}; done | |
773 | @end example | |
ac50fbac | 774 | |
cce855bc | 775 | Execute @var{consequent-commands} as long as |
ccc6cda3 | 776 | @var{test-commands} has an exit status which is not zero. |
cce855bc JA |
777 | The return status is the exit status of the last command executed |
778 | in @var{consequent-commands}, or zero if none was executed. | |
ccc6cda3 JA |
779 | |
780 | @item while | |
781 | @rwindex while | |
782 | The syntax of the @code{while} command is: | |
ac50fbac | 783 | |
ccc6cda3 JA |
784 | @example |
785 | while @var{test-commands}; do @var{consequent-commands}; done | |
786 | @end example | |
787 | ||
cce855bc | 788 | Execute @var{consequent-commands} as long as |
ccc6cda3 | 789 | @var{test-commands} has an exit status of zero. |
cce855bc JA |
790 | The return status is the exit status of the last command executed |
791 | in @var{consequent-commands}, or zero if none was executed. | |
ccc6cda3 JA |
792 | |
793 | @item for | |
794 | @rwindex for | |
795 | The syntax of the @code{for} command is: | |
796 | ||
797 | @example | |
0001803f | 798 | for @var{name} [ [in [@var{words} @dots{}] ] ; ] do @var{commands}; done |
ccc6cda3 | 799 | @end example |
ac50fbac | 800 | |
cce855bc JA |
801 | Expand @var{words}, and execute @var{commands} once for each member |
802 | in the resultant list, with @var{name} bound to the current member. | |
bb70624e JA |
803 | If @samp{in @var{words}} is not present, the @code{for} command |
804 | executes the @var{commands} once for each positional parameter that is | |
805 | set, as if @samp{in "$@@"} had been specified | |
806 | (@pxref{Special Parameters}). | |
cce855bc JA |
807 | The return status is the exit status of the last command that executes. |
808 | If there are no items in the expansion of @var{words}, no commands are | |
809 | executed, and the return status is zero. | |
bb70624e JA |
810 | |
811 | An alternate form of the @code{for} command is also supported: | |
812 | ||
813 | @example | |
814 | for (( @var{expr1} ; @var{expr2} ; @var{expr3} )) ; do @var{commands} ; done | |
815 | @end example | |
ac50fbac | 816 | |
bb70624e JA |
817 | First, the arithmetic expression @var{expr1} is evaluated according |
818 | to the rules described below (@pxref{Shell Arithmetic}). | |
819 | The arithmetic expression @var{expr2} is then evaluated repeatedly | |
820 | until it evaluates to zero. | |
821 | Each time @var{expr2} evaluates to a non-zero value, @var{commands} are | |
822 | executed and the arithmetic expression @var{expr3} is evaluated. | |
823 | If any expression is omitted, it behaves as if it evaluates to 1. | |
495aee44 | 824 | The return value is the exit status of the last command in @var{commands} |
bb70624e | 825 | that is executed, or false if any of the expressions is invalid. |
ccc6cda3 JA |
826 | @end table |
827 | ||
828 | The @code{break} and @code{continue} builtins (@pxref{Bourne Shell Builtins}) | |
829 | may be used to control loop execution. | |
830 | ||
831 | @node Conditional Constructs | |
b80f6443 | 832 | @subsubsection Conditional Constructs |
ccc6cda3 JA |
833 | @cindex commands, conditional |
834 | ||
835 | @table @code | |
836 | @item if | |
837 | @rwindex if | |
838 | @rwindex then | |
839 | @rwindex else | |
840 | @rwindex elif | |
841 | @rwindex fi | |
842 | The syntax of the @code{if} command is: | |
843 | ||
844 | @example | |
845 | if @var{test-commands}; then | |
846 | @var{consequent-commands}; | |
847 | [elif @var{more-test-commands}; then | |
848 | @var{more-consequents};] | |
849 | [else @var{alternate-consequents};] | |
850 | fi | |
851 | @end example | |
852 | ||
cce855bc JA |
853 | The @var{test-commands} list is executed, and if its return status is zero, |
854 | the @var{consequent-commands} list is executed. | |
855 | If @var{test-commands} returns a non-zero status, each @code{elif} list | |
856 | is executed in turn, and if its exit status is zero, | |
ccc6cda3 JA |
857 | the corresponding @var{more-consequents} is executed and the |
858 | command completes. | |
859 | If @samp{else @var{alternate-consequents}} is present, and | |
860 | the final command in the final @code{if} or @code{elif} clause | |
cce855bc JA |
861 | has a non-zero exit status, then @var{alternate-consequents} is executed. |
862 | The return status is the exit status of the last command executed, or | |
863 | zero if no condition tested true. | |
ccc6cda3 JA |
864 | |
865 | @item case | |
866 | @rwindex case | |
867 | @rwindex in | |
868 | @rwindex esac | |
869 | The syntax of the @code{case} command is: | |
870 | ||
871 | @example | |
ac50fbac | 872 | case @var{word} in [ [(] @var{pattern} [| @var{pattern}]@dots{}) @var{command-list} ;;]@dots{} esac |
ccc6cda3 JA |
873 | @end example |
874 | ||
cce855bc JA |
875 | @code{case} will selectively execute the @var{command-list} corresponding to |
876 | the first @var{pattern} that matches @var{word}. | |
a0c0a00f | 877 | If the @code{nocasematch} shell option |
3185942a | 878 | (see the description of @code{shopt} in @ref{The Shopt Builtin}) |
95732b49 JA |
879 | is enabled, the match is performed without regard to the case |
880 | of alphabetic characters. | |
cce855bc JA |
881 | The @samp{|} is used to separate multiple patterns, and the @samp{)} |
882 | operator terminates a pattern list. | |
883 | A list of patterns and an associated command-list is known | |
3185942a JA |
884 | as a @var{clause}. |
885 | ||
0001803f | 886 | Each clause must be terminated with @samp{;;}, @samp{;&}, or @samp{;;&}. |
cce855bc JA |
887 | The @var{word} undergoes tilde expansion, parameter expansion, command |
888 | substitution, arithmetic expansion, and quote removal before matching is | |
889 | attempted. Each @var{pattern} undergoes tilde expansion, parameter | |
890 | expansion, command substitution, and arithmetic expansion. | |
891 | ||
892 | There may be an arbitrary number of @code{case} clauses, each terminated | |
3185942a JA |
893 | by a @samp{;;}, @samp{;&}, or @samp{;;&}. |
894 | The first pattern that matches determines the | |
cce855bc | 895 | command-list that is executed. |
ac50fbac CR |
896 | It's a common idiom to use @samp{*} as the final pattern to define the |
897 | default case, since that pattern will always match. | |
ccc6cda3 JA |
898 | |
899 | Here is an example using @code{case} in a script that could be used to | |
900 | describe one interesting feature of an animal: | |
901 | ||
902 | @example | |
903 | echo -n "Enter the name of an animal: " | |
904 | read ANIMAL | |
905 | echo -n "The $ANIMAL has " | |
906 | case $ANIMAL in | |
907 | horse | dog | cat) echo -n "four";; | |
908 | man | kangaroo ) echo -n "two";; | |
909 | *) echo -n "an unknown number of";; | |
910 | esac | |
911 | echo " legs." | |
912 | @end example | |
913 | ||
cce855bc | 914 | @noindent |
3185942a JA |
915 | |
916 | If the @samp{;;} operator is used, no subsequent matches are attempted after | |
917 | the first pattern match. | |
918 | Using @samp{;&} in place of @samp{;;} causes execution to continue with | |
919 | the @var{command-list} associated with the next clause, if any. | |
920 | Using @samp{;;&} in place of @samp{;;} causes the shell to test the patterns | |
921 | in the next clause, if any, and execute any associated @var{command-list} | |
922 | on a successful match. | |
923 | ||
cce855bc JA |
924 | The return status is zero if no @var{pattern} is matched. Otherwise, the |
925 | return status is the exit status of the @var{command-list} executed. | |
926 | ||
927 | @item select | |
928 | @rwindex select | |
929 | ||
930 | The @code{select} construct allows the easy generation of menus. | |
931 | It has almost the same syntax as the @code{for} command: | |
932 | ||
933 | @example | |
934 | select @var{name} [in @var{words} @dots{}]; do @var{commands}; done | |
935 | @end example | |
936 | ||
937 | The list of words following @code{in} is expanded, generating a list | |
938 | of items. The set of expanded words is printed on the standard | |
939 | error output stream, each preceded by a number. If the | |
940 | @samp{in @var{words}} is omitted, the positional parameters are printed, | |
3185942a | 941 | as if @samp{in "$@@"} had been specified. |
28ef6c31 | 942 | The @env{PS3} prompt is then displayed and a line is read from the |
cce855bc JA |
943 | standard input. |
944 | If the line consists of a number corresponding to one of the displayed | |
945 | words, then the value of @var{name} is set to that word. | |
946 | If the line is empty, the words and prompt are displayed again. | |
947 | If @code{EOF} is read, the @code{select} command completes. | |
948 | Any other value read causes @var{name} to be set to null. | |
28ef6c31 | 949 | The line read is saved in the variable @env{REPLY}. |
cce855bc JA |
950 | |
951 | The @var{commands} are executed after each selection until a | |
f73dda09 | 952 | @code{break} command is executed, at which |
cce855bc JA |
953 | point the @code{select} command completes. |
954 | ||
955 | Here is an example that allows the user to pick a filename from the | |
956 | current directory, and displays the name and index of the file | |
957 | selected. | |
958 | ||
959 | @example | |
960 | select fname in *; | |
961 | do | |
962 | echo you picked $fname \($REPLY\) | |
963 | break; | |
964 | done | |
965 | @end example | |
966 | ||
ccc6cda3 JA |
967 | @item ((@dots{})) |
968 | @example | |
969 | (( @var{expression} )) | |
970 | @end example | |
971 | ||
cce855bc JA |
972 | The arithmetic @var{expression} is evaluated according to the rules |
973 | described below (@pxref{Shell Arithmetic}). | |
ccc6cda3 JA |
974 | If the value of the expression is non-zero, the return status is 0; |
975 | otherwise the return status is 1. This is exactly equivalent to | |
976 | @example | |
977 | let "@var{expression}" | |
978 | @end example | |
cce855bc JA |
979 | @noindent |
980 | @xref{Bash Builtins}, for a full description of the @code{let} builtin. | |
981 | ||
982 | @item [[@dots{}]] | |
983 | @rwindex [[ | |
984 | @rwindex ]] | |
985 | @example | |
986 | [[ @var{expression} ]] | |
987 | @end example | |
988 | ||
989 | Return a status of 0 or 1 depending on the evaluation of | |
990 | the conditional expression @var{expression}. | |
991 | Expressions are composed of the primaries described below in | |
992 | @ref{Bash Conditional Expressions}. | |
993 | Word splitting and filename expansion are not performed on the words | |
ac50fbac | 994 | between the @code{[[} and @code{]]}; tilde expansion, parameter and |
cce855bc JA |
995 | variable expansion, arithmetic expansion, command substitution, process |
996 | substitution, and quote removal are performed. | |
b80f6443 JA |
997 | Conditional operators such as @samp{-f} must be unquoted to be recognized |
998 | as primaries. | |
cce855bc | 999 | |
ac50fbac | 1000 | When used with @code{[[}, the @samp{<} and @samp{>} operators sort |
0001803f CR |
1001 | lexicographically using the current locale. |
1002 | ||
cce855bc JA |
1003 | When the @samp{==} and @samp{!=} operators are used, the string to the |
1004 | right of the operator is considered a pattern and matched according | |
ac50fbac CR |
1005 | to the rules described below in @ref{Pattern Matching}, |
1006 | as if the @code{extglob} shell option were enabled. | |
1007 | The @samp{=} operator is identical to @samp{==}. | |
a0c0a00f | 1008 | If the @code{nocasematch} shell option |
3185942a | 1009 | (see the description of @code{shopt} in @ref{The Shopt Builtin}) |
95732b49 JA |
1010 | is enabled, the match is performed without regard to the case |
1011 | of alphabetic characters. | |
0628567a JA |
1012 | The return value is 0 if the string matches (@samp{==}) or does not |
1013 | match (@samp{!=})the pattern, and 1 otherwise. | |
ac50fbac CR |
1014 | Any part of the pattern may be quoted to force the quoted portion |
1015 | to be matched as a string. | |
cce855bc | 1016 | |
b80f6443 JA |
1017 | An additional binary operator, @samp{=~}, is available, with the same |
1018 | precedence as @samp{==} and @samp{!=}. | |
1019 | When it is used, the string to the right of the operator is considered | |
a0c0a00f | 1020 | an extended regular expression and matched accordingly (as in @i{regex}3)). |
b80f6443 JA |
1021 | The return value is 0 if the string matches |
1022 | the pattern, and 1 otherwise. | |
1023 | If the regular expression is syntactically incorrect, the conditional | |
1024 | expression's return value is 2. | |
a0c0a00f | 1025 | If the @code{nocasematch} shell option |
3185942a | 1026 | (see the description of @code{shopt} in @ref{The Shopt Builtin}) |
b80f6443 JA |
1027 | is enabled, the match is performed without regard to the case |
1028 | of alphabetic characters. | |
ac50fbac CR |
1029 | Any part of the pattern may be quoted to force the quoted portion |
1030 | to be matched as a string. | |
1031 | Bracket expressions in regular expressions must be treated carefully, | |
1032 | since normal quoting characters lose their meanings between brackets. | |
1033 | If the pattern is stored in a shell variable, quoting the variable | |
1034 | expansion forces the entire pattern to be matched as a string. | |
b80f6443 JA |
1035 | Substrings matched by parenthesized subexpressions within the regular |
1036 | expression are saved in the array variable @code{BASH_REMATCH}. | |
1037 | The element of @code{BASH_REMATCH} with index 0 is the portion of the string | |
1038 | matching the entire regular expression. | |
1039 | The element of @code{BASH_REMATCH} with index @var{n} is the portion of the | |
1040 | string matching the @var{n}th parenthesized subexpression. | |
1041 | ||
ac50fbac CR |
1042 | For example, the following will match a line |
1043 | (stored in the shell variable @var{line}) | |
1044 | if there is a sequence of characters in the value consisting of | |
1045 | any number, including zero, of | |
1046 | space characters, zero or one instances of @samp{a}, then a @samp{b}: | |
1047 | @example | |
1048 | [[ $line =~ [[:space:]]*(a)?b ]] | |
1049 | @end example | |
1050 | ||
1051 | @noindent | |
1052 | That means values like @samp{aab} and @samp{ aaaaaab} will match, as | |
1053 | will a line containing a @samp{b} anywhere in its value. | |
1054 | ||
1055 | Storing the regular expression in a shell variable is often a useful | |
1056 | way to avoid problems with quoting characters that are special to the | |
1057 | shell. | |
1058 | It is sometimes difficult to specify a regular expression literally | |
1059 | without using quotes, or to keep track of the quoting used by regular | |
1060 | expressions while paying attention to the shell's quote removal. | |
1061 | Using a shell variable to store the pattern decreases these problems. | |
1062 | For example, the following is equivalent to the above: | |
1063 | @example | |
1064 | pattern='[[:space:]]*(a)?b' | |
1065 | [[ $line =~ $pattern ]] | |
1066 | @end example | |
1067 | ||
1068 | @noindent | |
1069 | If you want to match a character that's special to the regular expression | |
1070 | grammar, it has to be quoted to remove its special meaning. | |
1071 | This means that in the pattern @samp{xxx.txt}, the @samp{.} matches any | |
1072 | character in the string (its usual regular expression meaning), but in the | |
1073 | pattern @samp{"xxx.txt"} it can only match a literal @samp{.}. | |
1074 | Shell programmers should take special care with backslashes, since backslashes | |
1075 | are used both by the shell and regular expressions to remove the special | |
1076 | meaning from the following character. | |
1077 | The following two sets of commands are @emph{not} equivalent: | |
1078 | @example | |
1079 | pattern='\.' | |
1080 | ||
1081 | [[ . =~ $pattern ]] | |
1082 | [[ . =~ \. ]] | |
1083 | ||
1084 | [[ . =~ "$pattern" ]] | |
1085 | [[ . =~ '\.' ]] | |
1086 | @end example | |
1087 | ||
1088 | @noindent | |
1089 | The first two matches will succeed, but the second two will not, because | |
1090 | in the second two the backslash will be part of the pattern to be matched. | |
1091 | In the first two examples, the backslash removes the special meaning from | |
1092 | @samp{.}, so the literal @samp{.} matches. | |
1093 | If the string in the first examples were anything other than @samp{.}, say | |
1094 | @samp{a}, the pattern would not match, because the quoted @samp{.} in the | |
1095 | pattern loses its special meaning of matching any single character. | |
1096 | ||
cce855bc JA |
1097 | Expressions may be combined using the following operators, listed |
1098 | in decreasing order of precedence: | |
1099 | ||
1100 | @table @code | |
1101 | @item ( @var{expression} ) | |
1102 | Returns the value of @var{expression}. | |
1103 | This may be used to override the normal precedence of operators. | |
ccc6cda3 | 1104 | |
cce855bc JA |
1105 | @item ! @var{expression} |
1106 | True if @var{expression} is false. | |
1107 | ||
1108 | @item @var{expression1} && @var{expression2} | |
1109 | True if both @var{expression1} and @var{expression2} are true. | |
1110 | ||
1111 | @item @var{expression1} || @var{expression2} | |
1112 | True if either @var{expression1} or @var{expression2} is true. | |
ccc6cda3 | 1113 | @end table |
ac50fbac | 1114 | |
cce855bc | 1115 | @noindent |
7117c2d2 | 1116 | The @code{&&} and @code{||} operators do not evaluate @var{expression2} if the |
cce855bc JA |
1117 | value of @var{expression1} is sufficient to determine the return |
1118 | value of the entire conditional expression. | |
cce855bc | 1119 | @end table |
ccc6cda3 JA |
1120 | |
1121 | @node Command Grouping | |
b80f6443 | 1122 | @subsubsection Grouping Commands |
ccc6cda3 JA |
1123 | @cindex commands, grouping |
1124 | ||
1125 | Bash provides two ways to group a list of commands to be executed | |
1126 | as a unit. When commands are grouped, redirections may be applied | |
1127 | to the entire command list. For example, the output of all the | |
1128 | commands in the list may be redirected to a single stream. | |
1129 | ||
1130 | @table @code | |
1131 | @item () | |
1132 | @example | |
1133 | ( @var{list} ) | |
1134 | @end example | |
1135 | ||
1136 | Placing a list of commands between parentheses causes a subshell | |
b80f6443 JA |
1137 | environment to be created (@pxref{Command Execution Environment}), and each |
1138 | of the commands in @var{list} to be executed in that subshell. Since the | |
1139 | @var{list} is executed in a subshell, variable assignments do not remain in | |
1140 | effect after the subshell completes. | |
ccc6cda3 JA |
1141 | |
1142 | @item @{@} | |
1143 | @rwindex @{ | |
1144 | @rwindex @} | |
1145 | @example | |
1146 | @{ @var{list}; @} | |
1147 | @end example | |
1148 | ||
1149 | Placing a list of commands between curly braces causes the list to | |
1150 | be executed in the current shell context. No subshell is created. | |
cce855bc | 1151 | The semicolon (or newline) following @var{list} is required. |
ccc6cda3 JA |
1152 | @end table |
1153 | ||
1154 | In addition to the creation of a subshell, there is a subtle difference | |
1155 | between these two constructs due to historical reasons. The braces | |
1156 | are @code{reserved words}, so they must be separated from the @var{list} | |
3185942a JA |
1157 | by @code{blank}s or other shell metacharacters. |
1158 | The parentheses are @code{operators}, and are | |
ccc6cda3 | 1159 | recognized as separate tokens by the shell even if they are not separated |
d166f048 | 1160 | from the @var{list} by whitespace. |
ccc6cda3 JA |
1161 | |
1162 | The exit status of both of these constructs is the exit status of | |
1163 | @var{list}. | |
1164 | ||
3185942a JA |
1165 | @node Coprocesses |
1166 | @subsection Coprocesses | |
1167 | @cindex coprocess | |
1168 | ||
1169 | A @code{coprocess} is a shell command preceded by the @code{coproc} | |
1170 | reserved word. | |
1171 | A coprocess is executed asynchronously in a subshell, as if the command | |
1172 | had been terminated with the @samp{&} control operator, with a two-way pipe | |
1173 | established between the executing shell and the coprocess. | |
1174 | ||
1175 | The format for a coprocess is: | |
1176 | @example | |
ac50fbac | 1177 | coproc [@var{NAME}] @var{command} [@var{redirections}] |
3185942a JA |
1178 | @end example |
1179 | ||
1180 | @noindent | |
1181 | This creates a coprocess named @var{NAME}. | |
1182 | If @var{NAME} is not supplied, the default name is @var{COPROC}. | |
17345e5a JA |
1183 | @var{NAME} must not be supplied if @var{command} is a simple |
1184 | command (@pxref{Simple Commands}); otherwise, it is interpreted as | |
1185 | the first word of the simple command. | |
3185942a | 1186 | |
ac50fbac | 1187 | When the coprocess is executed, the shell creates an array variable |
3185942a | 1188 | (@pxref{Arrays}) |
ac50fbac | 1189 | named @env{NAME} in the context of the executing shell. |
3185942a JA |
1190 | The standard output of @var{command} |
1191 | is connected via a pipe to a file descriptor in the executing shell, | |
ac50fbac | 1192 | and that file descriptor is assigned to @env{NAME}[0]. |
3185942a JA |
1193 | The standard input of @var{command} |
1194 | is connected via a pipe to a file descriptor in the executing shell, | |
ac50fbac | 1195 | and that file descriptor is assigned to @env{NAME}[1]. |
3185942a JA |
1196 | This pipe is established before any redirections specified by the |
1197 | command (@pxref{Redirections}). | |
1198 | The file descriptors can be utilized as arguments to shell commands | |
1199 | and redirections using standard word expansions. | |
ac50fbac | 1200 | The file descriptors are not available in subshells. |
3185942a | 1201 | |
495aee44 | 1202 | The process ID of the shell spawned to execute the coprocess is |
ac50fbac | 1203 | available as the value of the variable @env{NAME}_PID. |
3185942a JA |
1204 | The @code{wait} |
1205 | builtin command may be used to wait for the coprocess to terminate. | |
1206 | ||
ac50fbac CR |
1207 | Since the coprocess is created as an asynchronous command, |
1208 | the @code{coproc} command always returns success. | |
3185942a JA |
1209 | The return status of a coprocess is the exit status of @var{command}. |
1210 | ||
495aee44 CR |
1211 | @node GNU Parallel |
1212 | @subsection GNU Parallel | |
1213 | ||
ac50fbac CR |
1214 | There are ways to run commands in parallel that are not built into Bash. |
1215 | GNU Parallel is a tool to do just that. | |
1216 | ||
495aee44 CR |
1217 | GNU Parallel, as its name suggests, can be used to build and run commands |
1218 | in parallel. You may run the same command with different arguments, whether | |
ac50fbac CR |
1219 | they are filenames, usernames, hostnames, or lines read from files. GNU |
1220 | Parallel provides shorthand references to many of the most common operations | |
1221 | (input lines, various portions of the input line, different ways to specify | |
1222 | the input source, and so on). Parallel can replace @code{xargs} or feed | |
1223 | commands from its input sources to several different instances of Bash. | |
495aee44 CR |
1224 | |
1225 | For a complete description, refer to the GNU Parallel documentation. A few | |
1226 | examples should provide a brief introduction to its use. | |
1227 | ||
ac50fbac CR |
1228 | For example, it is easy to replace @code{xargs} to gzip all html files in the |
1229 | current directory and its subdirectories: | |
495aee44 | 1230 | @example |
ac50fbac | 1231 | find . -type f -name '*.html' -print | parallel gzip |
495aee44 CR |
1232 | @end example |
1233 | @noindent | |
ac50fbac CR |
1234 | If you need to protect special characters such as newlines in file names, |
1235 | use find's @option{-print0} option and parallel's @option{-0} option. | |
495aee44 CR |
1236 | |
1237 | You can use Parallel to move files from the current directory when the | |
1238 | number of files is too large to process with one @code{mv} invocation: | |
1239 | @example | |
1240 | ls | parallel mv @{@} destdir | |
1241 | @end example | |
1242 | ||
1243 | As you can see, the @{@} is replaced with each line read from standard input. | |
ac50fbac CR |
1244 | While using @code{ls} will work in most instances, it is not sufficient to |
1245 | deal with all filenames. | |
1246 | If you need to accommodate special characters in filenames, you can use | |
1247 | ||
1248 | @example | |
1249 | find . -depth 1 \! -name '.*' -print0 | parallel -0 mv @{@} destdir | |
1250 | @end example | |
1251 | ||
1252 | @noindent | |
1253 | as alluded to above. | |
1254 | ||
495aee44 | 1255 | This will run as many @code{mv} commands as there are files in the current |
ac50fbac CR |
1256 | directory. |
1257 | You can emulate a parallel @code{xargs} by adding the @option{-X} option: | |
495aee44 | 1258 | @example |
ac50fbac | 1259 | find . -depth 1 \! -name '.*' -print0 | parallel -0 -X mv @{@} destdir |
495aee44 CR |
1260 | @end example |
1261 | ||
1262 | GNU Parallel can replace certain common idioms that operate on lines read | |
ac50fbac | 1263 | from a file (in this case, filenames listed one per line): |
495aee44 | 1264 | @example |
ac50fbac CR |
1265 | while IFS= read -r x; do |
1266 | do-something1 "$x" "config-$x" | |
1267 | do-something2 < "$x" | |
1268 | done < file | process-output | |
495aee44 CR |
1269 | @end example |
1270 | ||
1271 | @noindent | |
1272 | with a more compact syntax reminiscent of lambdas: | |
1273 | @example | |
1274 | cat list | parallel "do-something1 @{@} config-@{@} ; do-something2 < @{@}" | process-output | |
1275 | @end example | |
1276 | ||
1277 | Parallel provides a built-in mechanism to remove filename extensions, which | |
1278 | lends itself to batch file transformations or renaming: | |
1279 | @example | |
1280 | ls *.gz | parallel -j+0 "zcat @{@} | bzip2 >@{.@}.bz2 && rm @{@}" | |
1281 | @end example | |
1282 | @noindent | |
1283 | This will recompress all files in the current directory with names ending | |
ac50fbac CR |
1284 | in .gz using bzip2, running one job per CPU (-j+0) in parallel. |
1285 | (We use @code{ls} for brevity here; using @code{find} as above is more | |
1286 | robust in the face of filenames containing unexpected characters.) | |
1287 | Parallel can take arguments from the command line; the above can also be | |
1288 | written as | |
1289 | ||
1290 | @example | |
1291 | parallel "zcat @{@} | bzip2 >@{.@}.bz2 && rm @{@}" ::: *.gz | |
1292 | @end example | |
495aee44 CR |
1293 | |
1294 | If a command generates output, you may want to preserve the input order in | |
1295 | the output. For instance, the following command | |
1296 | @example | |
1297 | @{ echo foss.org.my ; echo debian.org; echo freenetproject.org; @} | parallel traceroute | |
1298 | @end example | |
1299 | @noindent | |
ac50fbac CR |
1300 | will display as output the traceroute invocation that finishes first. |
1301 | Adding the @option{-k} option | |
495aee44 CR |
1302 | @example |
1303 | @{ echo foss.org.my ; echo debian.org; echo freenetproject.org; @} | parallel -k traceroute | |
1304 | @end example | |
1305 | @noindent | |
1306 | will ensure that the output of @code{traceroute foss.org.my} is displayed first. | |
1307 | ||
ac50fbac CR |
1308 | Finally, Parallel can be used to run a sequence of shell commands in parallel, |
1309 | similar to @samp{cat file | bash}. | |
1310 | It is not uncommon to take a list of filenames, create a series of shell | |
1311 | commands to operate on them, and feed that list of commnds to a shell. | |
1312 | Parallel can speed this up. Assuming that @file{file} contains a list of | |
1313 | shell commands, one per line, | |
1314 | ||
1315 | @example | |
1316 | parallel -j 10 < file | |
1317 | @end example | |
1318 | ||
1319 | @noindent | |
1320 | will evaluate the commands using the shell (since no explicit command is | |
1321 | supplied as an argument), in blocks of ten shell jobs at a time. | |
1322 | ||
ccc6cda3 JA |
1323 | @node Shell Functions |
1324 | @section Shell Functions | |
1325 | @cindex shell function | |
1326 | @cindex functions, shell | |
1327 | ||
1328 | Shell functions are a way to group commands for later execution | |
1329 | using a single name for the group. They are executed just like | |
bb70624e JA |
1330 | a "regular" command. |
1331 | When the name of a shell function is used as a simple command name, | |
1332 | the list of commands associated with that function name is executed. | |
1333 | Shell functions are executed in the current | |
ccc6cda3 JA |
1334 | shell context; no new process is created to interpret them. |
1335 | ||
1336 | Functions are declared using this syntax: | |
1337 | @rwindex function | |
1338 | @example | |
ac50fbac CR |
1339 | @var{name} () @var{compound-command} [ @var{redirections} ] |
1340 | @end example | |
1341 | ||
1342 | or | |
1343 | ||
1344 | @example | |
1345 | function @var{name} [()] @var{compound-command} [ @var{redirections} ] | |
ccc6cda3 JA |
1346 | @end example |
1347 | ||
1348 | This defines a shell function named @var{name}. The reserved | |
cce855bc JA |
1349 | word @code{function} is optional. |
1350 | If the @code{function} reserved | |
1351 | word is supplied, the parentheses are optional. | |
b80f6443 JA |
1352 | The @var{body} of the function is the compound command |
1353 | @var{compound-command} (@pxref{Compound Commands}). | |
1354 | That command is usually a @var{list} enclosed between @{ and @}, but | |
a0c0a00f CR |
1355 | may be any compound command listed above, |
1356 | with one exception: If the @code{function} reserved word is used, but the | |
1357 | parentheses are not supplied, the braces are required. | |
b80f6443 JA |
1358 | @var{compound-command} is executed whenever @var{name} is specified as the |
1359 | name of a command. | |
ac50fbac CR |
1360 | When the shell is in @sc{posix} mode (@pxref{Bash POSIX Mode}), |
1361 | @var{name} may not be the same as one of the special builtins | |
1362 | (@pxref{Special Builtins}). | |
b80f6443 JA |
1363 | Any redirections (@pxref{Redirections}) associated with the shell function |
1364 | are performed when the function is executed. | |
1365 | ||
0628567a JA |
1366 | A function definition may be deleted using the @option{-f} option to the |
1367 | @code{unset} builtin (@pxref{Bourne Shell Builtins}). | |
1368 | ||
b80f6443 JA |
1369 | The exit status of a function definition is zero unless a syntax error |
1370 | occurs or a readonly function with the same name already exists. | |
1371 | When executed, the exit status of a function is the exit status of the | |
1372 | last command executed in the body. | |
1373 | ||
1374 | Note that for historical reasons, in the most common usage the curly braces | |
1375 | that surround the body of the function must be separated from the body by | |
bb70624e JA |
1376 | @code{blank}s or newlines. |
1377 | This is because the braces are reserved words and are only recognized | |
3185942a JA |
1378 | as such when they are separated from the command list |
1379 | by whitespace or another shell metacharacter. | |
b80f6443 JA |
1380 | Also, when using the braces, the @var{list} must be terminated by a semicolon, |
1381 | a @samp{&}, or a newline. | |
bb70624e | 1382 | |
ccc6cda3 JA |
1383 | When a function is executed, the arguments to the |
1384 | function become the positional parameters | |
1385 | during its execution (@pxref{Positional Parameters}). | |
d166f048 JA |
1386 | The special parameter @samp{#} that expands to the number of |
1387 | positional parameters is updated to reflect the change. | |
b80f6443 JA |
1388 | Special parameter @code{0} is unchanged. |
1389 | The first element of the @env{FUNCNAME} variable is set to the | |
1390 | name of the function while the function is executing. | |
0001803f | 1391 | |
b80f6443 JA |
1392 | All other aspects of the shell execution |
1393 | environment are identical between a function and its caller | |
0001803f CR |
1394 | with these exceptions: |
1395 | the @env{DEBUG} and @env{RETURN} traps | |
95732b49 | 1396 | are not inherited unless the function has been given the |
b80f6443 JA |
1397 | @code{trace} attribute using the @code{declare} builtin or |
1398 | the @code{-o functrace} option has been enabled with | |
1399 | the @code{set} builtin, | |
0001803f CR |
1400 | (in which case all functions inherit the @env{DEBUG} and @env{RETURN} traps), |
1401 | and the @env{ERR} trap is not inherited unless the @code{-o errtrace} | |
1402 | shell option has been enabled. | |
b80f6443 JA |
1403 | @xref{Bourne Shell Builtins}, for the description of the |
1404 | @code{trap} builtin. | |
ccc6cda3 | 1405 | |
495aee44 CR |
1406 | The @env{FUNCNEST} variable, if set to a numeric value greater |
1407 | than 0, defines a maximum function nesting level. Function | |
1408 | invocations that exceed the limit cause the entire command to | |
1409 | abort. | |
1410 | ||
ccc6cda3 JA |
1411 | If the builtin command @code{return} |
1412 | is executed in a function, the function completes and | |
1413 | execution resumes with the next command after the function | |
b80f6443 JA |
1414 | call. |
1415 | Any command associated with the @code{RETURN} trap is executed | |
1416 | before execution resumes. | |
1417 | When a function completes, the values of the | |
ccc6cda3 | 1418 | positional parameters and the special parameter @samp{#} |
cce855bc | 1419 | are restored to the values they had prior to the function's |
ccc6cda3 | 1420 | execution. If a numeric argument is given to @code{return}, |
f73dda09 | 1421 | that is the function's return status; otherwise the function's |
cce855bc JA |
1422 | return status is the exit status of the last command executed |
1423 | before the @code{return}. | |
ccc6cda3 JA |
1424 | |
1425 | Variables local to the function may be declared with the | |
1426 | @code{local} builtin. These variables are visible only to | |
1427 | the function and the commands it invokes. | |
1428 | ||
b80f6443 | 1429 | Function names and definitions may be listed with the |
ac50fbac CR |
1430 | @option{-f} option to the @code{declare} (@code{typeset}) |
1431 | builtin command (@pxref{Bash Builtins}). | |
b80f6443 JA |
1432 | The @option{-F} option to @code{declare} or @code{typeset} |
1433 | will list the function names only | |
1434 | (and optionally the source file and line number, if the @code{extdebug} | |
1435 | shell option is enabled). | |
1436 | Functions may be exported so that subshells | |
1437 | automatically have them defined with the | |
1438 | @option{-f} option to the @code{export} builtin | |
1439 | (@pxref{Bourne Shell Builtins}). | |
1440 | Note that shell functions and variables with the same name may result | |
1441 | in multiple identically-named entries in the environment passed to the | |
1442 | shell's children. | |
1443 | Care should be taken in cases where this may cause a problem. | |
1444 | ||
495aee44 CR |
1445 | Functions may be recursive. |
1446 | The @code{FUNCNEST} variable may be used to limit the depth of the | |
1447 | function call stack and restrict the number of function invocations. | |
1448 | By default, no limit is placed on the number of recursive calls. | |
ccc6cda3 JA |
1449 | |
1450 | @node Shell Parameters | |
1451 | @section Shell Parameters | |
1452 | @cindex parameters | |
1453 | @cindex variable, shell | |
1454 | @cindex shell variable | |
1455 | ||
1456 | @menu | |
1457 | * Positional Parameters:: The shell's command-line arguments. | |
b80f6443 | 1458 | * Special Parameters:: Parameters denoted by special characters. |
ccc6cda3 JA |
1459 | @end menu |
1460 | ||
1461 | A @var{parameter} is an entity that stores values. | |
1462 | It can be a @code{name}, a number, or one of the special characters | |
1463 | listed below. | |
b80f6443 | 1464 | A @var{variable} is a parameter denoted by a @code{name}. |
f73dda09 JA |
1465 | A variable has a @var{value} and zero or more @var{attributes}. |
1466 | Attributes are assigned using the @code{declare} builtin command | |
1467 | (see the description of the @code{declare} builtin in @ref{Bash Builtins}). | |
ccc6cda3 JA |
1468 | |
1469 | A parameter is set if it has been assigned a value. The null string is | |
1470 | a valid value. Once a variable is set, it may be unset only by using | |
1471 | the @code{unset} builtin command. | |
1472 | ||
1473 | A variable may be assigned to by a statement of the form | |
1474 | @example | |
1475 | @var{name}=[@var{value}] | |
1476 | @end example | |
1477 | @noindent | |
1478 | If @var{value} | |
1479 | is not given, the variable is assigned the null string. All | |
1480 | @var{value}s undergo tilde expansion, parameter and variable expansion, | |
1481 | command substitution, arithmetic expansion, and quote | |
cce855bc | 1482 | removal (detailed below). If the variable has its @code{integer} |
f73dda09 | 1483 | attribute set, then @var{value} |
b80f6443 | 1484 | is evaluated as an arithmetic expression even if the @code{$((@dots{}))} |
cce855bc | 1485 | expansion is not used (@pxref{Arithmetic Expansion}). |
ccc6cda3 JA |
1486 | Word splitting is not performed, with the exception |
1487 | of @code{"$@@"} as explained below. | |
1488 | Filename expansion is not performed. | |
f73dda09 | 1489 | Assignment statements may also appear as arguments to the |
b80f6443 | 1490 | @code{alias}, |
f73dda09 | 1491 | @code{declare}, @code{typeset}, @code{export}, @code{readonly}, |
a0c0a00f | 1492 | and @code{local} builtin commands (@var{declaration} commands). |
ac50fbac CR |
1493 | When in @sc{posix} mode (@pxref{Bash POSIX Mode}), these builtins may appear |
1494 | in a command after one or more instances of the @code{command} builtin | |
1495 | and retain these assignment statement properties. | |
ccc6cda3 | 1496 | |
95732b49 JA |
1497 | In the context where an assignment statement is assigning a value |
1498 | to a shell variable or array index (@pxref{Arrays}), the @samp{+=} | |
1499 | operator can be used to | |
1500 | append to or add to the variable's previous value. | |
a0c0a00f CR |
1501 | This includes arguments to builtin commands such as @code{declare} that |
1502 | accept assignment statements (@var{declaration} commands). | |
495aee44 | 1503 | When @samp{+=} is applied to a variable for which the @var{integer} attribute |
95732b49 JA |
1504 | has been set, @var{value} is evaluated as an arithmetic expression and |
1505 | added to the variable's current value, which is also evaluated. | |
1506 | When @samp{+=} is applied to an array variable using compound assignment | |
1507 | (@pxref{Arrays}), the | |
1508 | variable's value is not unset (as it is when using @samp{=}), and new | |
1509 | values are appended to the array beginning at one greater than the array's | |
3185942a JA |
1510 | maximum index (for indexed arrays), or added as additional key-value pairs |
1511 | in an associative array. | |
95732b49 JA |
1512 | When applied to a string-valued variable, @var{value} is expanded and |
1513 | appended to the variable's value. | |
1514 | ||
ac50fbac | 1515 | A variable can be assigned the @var{nameref} attribute using the |
a0c0a00f | 1516 | @option{-n} option to the @code{declare} or @code{local} builtin commands |
ac50fbac CR |
1517 | (@pxref{Bash Builtins}) |
1518 | to create a @var{nameref}, or a reference to another variable. | |
1519 | This allows variables to be manipulated indirectly. | |
a0c0a00f CR |
1520 | Whenever the nameref variable is referenced, assigned to, unset, or has |
1521 | its attributes modified (other than using or changing the nameref | |
1522 | attribute itself), the | |
1523 | operation is actually performed on the variable specified by the nameref | |
1524 | variable's value. | |
ac50fbac CR |
1525 | A nameref is commonly used within shell functions to refer to a variable |
1526 | whose name is passed as an argument to the function. | |
1527 | For instance, if a variable name is passed to a shell function as its first | |
1528 | argument, running | |
1529 | @example | |
1530 | declare -n ref=$1 | |
1531 | @end example | |
1532 | @noindent | |
1533 | inside the function creates a nameref variable @var{ref} whose value is | |
1534 | the variable name passed as the first argument. | |
a0c0a00f CR |
1535 | References and assignments to @var{ref}, and changes to its attributes, |
1536 | are treated as references, assignments, and attribute modifications | |
1537 | to the variable whose name was passed as @code{$1}. | |
ac50fbac CR |
1538 | |
1539 | If the control variable in a @code{for} loop has the nameref attribute, | |
1540 | the list of words can be a list of shell variables, and a name reference | |
1541 | will be established for each word in the list, in turn, when the loop is | |
1542 | executed. | |
a0c0a00f | 1543 | Array variables cannot be given the nameref attribute. |
ac50fbac CR |
1544 | However, nameref variables can reference array variables and subscripted |
1545 | array variables. | |
1546 | Namerefs can be unset using the @option{-n} option to the @code{unset} builtin | |
1547 | (@pxref{Bourne Shell Builtins}). | |
1548 | Otherwise, if @code{unset} is executed with the name of a nameref variable | |
1549 | as an argument, the variable referenced by the nameref variable will be unset. | |
1550 | ||
ccc6cda3 JA |
1551 | @node Positional Parameters |
1552 | @subsection Positional Parameters | |
1553 | @cindex parameters, positional | |
1554 | ||
cce855bc | 1555 | A @var{positional parameter} is a parameter denoted by one or more |
ccc6cda3 JA |
1556 | digits, other than the single digit @code{0}. Positional parameters are |
1557 | assigned from the shell's arguments when it is invoked, | |
cce855bc | 1558 | and may be reassigned using the @code{set} builtin command. |
bb70624e JA |
1559 | Positional parameter @code{N} may be referenced as @code{$@{N@}}, or |
1560 | as @code{$N} when @code{N} consists of a single digit. | |
1561 | Positional parameters may not be assigned to with assignment statements. | |
1562 | The @code{set} and @code{shift} builtins are used to set and | |
1563 | unset them (@pxref{Shell Builtin Commands}). | |
1564 | The positional parameters are | |
ccc6cda3 JA |
1565 | temporarily replaced when a shell function is executed |
1566 | (@pxref{Shell Functions}). | |
1567 | ||
1568 | When a positional parameter consisting of more than a single | |
1569 | digit is expanded, it must be enclosed in braces. | |
1570 | ||
1571 | @node Special Parameters | |
1572 | @subsection Special Parameters | |
1573 | @cindex parameters, special | |
1574 | ||
1575 | The shell treats several parameters specially. These parameters may | |
1576 | only be referenced; assignment to them is not allowed. | |
1577 | ||
1578 | @vtable @code | |
1579 | ||
1580 | @item * | |
ac50fbac CR |
1581 | @vindex $* |
1582 | ($*) Expands to the positional parameters, starting from one. | |
1583 | When the expansion is not within double quotes, each positional parameter | |
1584 | expands to a separate word. | |
1585 | In contexts where it is performed, those words | |
1586 | are subject to further word splitting and pathname expansion. | |
1587 | When the expansion occurs within double quotes, it expands to a single word | |
a0c0a00f CR |
1588 | with the value of each parameter separated by the first character of the |
1589 | @env{IFS} special variable. That is, @code{"$*"} is equivalent | |
ccc6cda3 JA |
1590 | to @code{"$1@var{c}$2@var{c}@dots{}"}, where @var{c} |
1591 | is the first character of the value of the @code{IFS} | |
d166f048 | 1592 | variable. |
28ef6c31 JA |
1593 | If @env{IFS} is unset, the parameters are separated by spaces. |
1594 | If @env{IFS} is null, the parameters are joined without intervening | |
d166f048 JA |
1595 | separators. |
1596 | ||
ccc6cda3 | 1597 | @item @@ |
ac50fbac CR |
1598 | @vindex $@@ |
1599 | ($@@) Expands to the positional parameters, starting from one. When the | |
cce855bc | 1600 | expansion occurs within double quotes, each parameter expands to a |
ccc6cda3 JA |
1601 | separate word. That is, @code{"$@@"} is equivalent to |
1602 | @code{"$1" "$2" @dots{}}. | |
95732b49 JA |
1603 | If the double-quoted expansion occurs within a word, the expansion of |
1604 | the first parameter is joined with the beginning part of the original | |
1605 | word, and the expansion of the last parameter is joined with the last | |
1606 | part of the original word. | |
ccc6cda3 JA |
1607 | When there are no positional parameters, @code{"$@@"} and |
1608 | @code{$@@} | |
1609 | expand to nothing (i.e., they are removed). | |
1610 | ||
1611 | @item # | |
ac50fbac CR |
1612 | @vindex $# |
1613 | ($#) Expands to the number of positional parameters in decimal. | |
ccc6cda3 JA |
1614 | |
1615 | @item ? | |
ac50fbac CR |
1616 | @vindex $? |
1617 | ($?) Expands to the exit status of the most recently executed foreground | |
ccc6cda3 JA |
1618 | pipeline. |
1619 | ||
1620 | @item - | |
ac50fbac CR |
1621 | @vindex $- |
1622 | ($-, a hyphen.) Expands to the current option flags as specified upon | |
bb70624e | 1623 | invocation, by the @code{set} |
ccc6cda3 | 1624 | builtin command, or those set by the shell itself |
28ef6c31 | 1625 | (such as the @option{-i} option). |
ccc6cda3 JA |
1626 | |
1627 | @item $ | |
ac50fbac CR |
1628 | @vindex $$ |
1629 | ($$) Expands to the process @sc{id} of the shell. In a @code{()} subshell, it | |
bb70624e | 1630 | expands to the process @sc{id} of the invoking shell, not the subshell. |
ccc6cda3 JA |
1631 | |
1632 | @item ! | |
ac50fbac CR |
1633 | @vindex $! |
1634 | ($!) Expands to the process @sc{id} of the job most recently placed into the | |
1635 | background, whether executed as an asynchronous command or using | |
1636 | the @code{bg} builtin (@pxref{Job Control Builtins}). | |
ccc6cda3 JA |
1637 | |
1638 | @item 0 | |
ac50fbac CR |
1639 | @vindex $0 |
1640 | ($0) Expands to the name of the shell or shell script. This is set at | |
cce855bc JA |
1641 | shell initialization. If Bash is invoked with a file of commands |
1642 | (@pxref{Shell Scripts}), @code{$0} is set to the name of that file. | |
28ef6c31 | 1643 | If Bash is started with the @option{-c} option (@pxref{Invoking Bash}), |
cce855bc | 1644 | then @code{$0} is set to the first argument after the string to be |
ccc6cda3 JA |
1645 | executed, if one is present. Otherwise, it is set |
1646 | to the filename used to invoke Bash, as given by argument zero. | |
1647 | ||
1648 | @item _ | |
ac50fbac CR |
1649 | @vindex $_ |
1650 | ($_, an underscore.) | |
95732b49 JA |
1651 | At shell startup, set to the absolute pathname used to invoke the |
1652 | shell or shell script being executed as passed in the environment | |
1653 | or argument list. | |
ccc6cda3 JA |
1654 | Subsequently, expands to the last argument to the previous command, |
1655 | after expansion. | |
95732b49 JA |
1656 | Also set to the full pathname used to invoke each command executed |
1657 | and placed in the environment exported to that command. | |
ccc6cda3 JA |
1658 | When checking mail, this parameter holds the name of the mail file. |
1659 | @end vtable | |
1660 | ||
1661 | @node Shell Expansions | |
1662 | @section Shell Expansions | |
1663 | @cindex expansion | |
1664 | ||
1665 | Expansion is performed on the command line after it has been split into | |
1666 | @code{token}s. There are seven kinds of expansion performed: | |
ac50fbac | 1667 | |
ccc6cda3 JA |
1668 | @itemize @bullet |
1669 | @item brace expansion | |
1670 | @item tilde expansion | |
1671 | @item parameter and variable expansion | |
1672 | @item command substitution | |
1673 | @item arithmetic expansion | |
1674 | @item word splitting | |
1675 | @item filename expansion | |
1676 | @end itemize | |
1677 | ||
1678 | @menu | |
cce855bc JA |
1679 | * Brace Expansion:: Expansion of expressions within braces. |
1680 | * Tilde Expansion:: Expansion of the ~ character. | |
ccc6cda3 JA |
1681 | * Shell Parameter Expansion:: How Bash expands variables to their values. |
1682 | * Command Substitution:: Using the output of a command as an argument. | |
cce855bc | 1683 | * Arithmetic Expansion:: How to use arithmetic in shell expansions. |
ccc6cda3 JA |
1684 | * Process Substitution:: A way to write and read to and from a |
1685 | command. | |
1686 | * Word Splitting:: How the results of expansion are split into separate | |
1687 | arguments. | |
1688 | * Filename Expansion:: A shorthand for specifying filenames matching patterns. | |
1689 | * Quote Removal:: How and when quote characters are removed from | |
1690 | words. | |
1691 | @end menu | |
1692 | ||
ac50fbac CR |
1693 | The order of expansions is: |
1694 | brace expansion; | |
1695 | tilde expansion, parameter and variable expansion, arithmetic expansion, | |
1696 | and command substitution (done in a left-to-right fashion); | |
1697 | word splitting; | |
1698 | and filename expansion. | |
ccc6cda3 JA |
1699 | |
1700 | On systems that can support it, there is an additional expansion | |
ac50fbac CR |
1701 | available: @var{process substitution}. |
1702 | This is performed at the | |
1703 | same time as tilde, parameter, variable, and arithmetic expansion and | |
ccc6cda3 JA |
1704 | command substitution. |
1705 | ||
a0c0a00f CR |
1706 | After these expansions are performed, quote characters present in the |
1707 | original word are removed unless they have been quoted themselves | |
1708 | (@var{quote removal}). | |
1709 | ||
ccc6cda3 JA |
1710 | Only brace expansion, word splitting, and filename expansion |
1711 | can change the number of words of the expansion; other expansions | |
1712 | expand a single word to a single word. | |
1713 | The only exceptions to this are the expansions of | |
d166f048 | 1714 | @code{"$@@"} (@pxref{Special Parameters}) and @code{"$@{@var{name}[@@]@}"} |
ccc6cda3 JA |
1715 | (@pxref{Arrays}). |
1716 | ||
1717 | After all expansions, @code{quote removal} (@pxref{Quote Removal}) | |
1718 | is performed. | |
1719 | ||
cce855bc JA |
1720 | @node Brace Expansion |
1721 | @subsection Brace Expansion | |
1722 | @cindex brace expansion | |
1723 | @cindex expansion, brace | |
1724 | ||
bb70624e JA |
1725 | Brace expansion is a mechanism by which arbitrary strings may be generated. |
1726 | This mechanism is similar to | |
cce855bc | 1727 | @var{filename expansion} (@pxref{Filename Expansion}), |
ac50fbac | 1728 | but the filenames generated need not exist. |
bb70624e | 1729 | Patterns to be brace expanded take the form of an optional @var{preamble}, |
ac50fbac | 1730 | followed by either a series of comma-separated strings or a sequence expression |
b80f6443 | 1731 | between a pair of braces, |
bb70624e JA |
1732 | followed by an optional @var{postscript}. |
1733 | The preamble is prefixed to each string contained within the braces, and | |
1734 | the postscript is then appended to each resulting string, expanding left | |
1735 | to right. | |
1736 | ||
1737 | Brace expansions may be nested. | |
1738 | The results of each expanded string are not sorted; left to right order | |
1739 | is preserved. | |
cce855bc JA |
1740 | For example, |
1741 | @example | |
1742 | bash$ echo a@{d,c,b@}e | |
1743 | ade ace abe | |
1744 | @end example | |
1745 | ||
0001803f | 1746 | A sequence expression takes the form @code{@{@var{x}..@var{y}[..@var{incr}]@}}, |
3185942a JA |
1747 | where @var{x} and @var{y} are either integers or single characters, |
1748 | and @var{incr}, an optional increment, is an integer. | |
b80f6443 JA |
1749 | When integers are supplied, the expression expands to each number between |
1750 | @var{x} and @var{y}, inclusive. | |
3185942a | 1751 | Supplied integers may be prefixed with @samp{0} to force each term to have the |
ac50fbac CR |
1752 | same width. |
1753 | When either @var{x} or @var{y} begins with a zero, the shell | |
3185942a JA |
1754 | attempts to force all generated terms to contain the same number of digits, |
1755 | zero-padding where necessary. | |
b80f6443 | 1756 | When characters are supplied, the expression expands to each character |
ac50fbac CR |
1757 | lexicographically between @var{x} and @var{y}, inclusive, |
1758 | using the default C locale. | |
1759 | Note that both @var{x} and @var{y} must be of the same type. | |
3185942a JA |
1760 | When the increment is supplied, it is used as the difference between |
1761 | each term. The default increment is 1 or -1 as appropriate. | |
b80f6443 | 1762 | |
cce855bc JA |
1763 | Brace expansion is performed before any other expansions, |
1764 | and any characters special to other expansions are preserved | |
1765 | in the result. It is strictly textual. Bash | |
1766 | does not apply any syntactic interpretation to the context of the | |
1767 | expansion or the text between the braces. | |
bb70624e JA |
1768 | To avoid conflicts with parameter expansion, the string @samp{$@{} |
1769 | is not considered eligible for brace expansion. | |
cce855bc JA |
1770 | |
1771 | A correctly-formed brace expansion must contain unquoted opening | |
b80f6443 JA |
1772 | and closing braces, and at least one unquoted comma or a valid |
1773 | sequence expression. | |
cce855bc JA |
1774 | Any incorrectly formed brace expansion is left unchanged. |
1775 | ||
b80f6443 JA |
1776 | A @{ or @samp{,} may be quoted with a backslash to prevent its |
1777 | being considered part of a brace expression. | |
1778 | To avoid conflicts with parameter expansion, the string @samp{$@{} | |
1779 | is not considered eligible for brace expansion. | |
1780 | ||
cce855bc JA |
1781 | This construct is typically used as shorthand when the common |
1782 | prefix of the strings to be generated is longer than in the | |
1783 | above example: | |
1784 | @example | |
1785 | mkdir /usr/local/src/bash/@{old,new,dist,bugs@} | |
1786 | @end example | |
1787 | or | |
1788 | @example | |
1789 | chown root /usr/@{ucb/@{ex,edit@},lib/@{ex?.?*,how_ex@}@} | |
1790 | @end example | |
1791 | ||
1792 | @node Tilde Expansion | |
1793 | @subsection Tilde Expansion | |
1794 | @cindex tilde expansion | |
1795 | @cindex expansion, tilde | |
1796 | ||
1797 | If a word begins with an unquoted tilde character (@samp{~}), all of the | |
1798 | characters up to the first unquoted slash (or all characters, | |
1799 | if there is no unquoted slash) are considered a @var{tilde-prefix}. | |
1800 | If none of the characters in the tilde-prefix are quoted, the | |
1801 | characters in the tilde-prefix following the tilde are treated as a | |
1802 | possible @var{login name}. | |
1803 | If this login name is the null string, the tilde is replaced with the | |
28ef6c31 JA |
1804 | value of the @env{HOME} shell variable. |
1805 | If @env{HOME} is unset, the home directory of the user executing the | |
cce855bc JA |
1806 | shell is substituted instead. |
1807 | Otherwise, the tilde-prefix is replaced with the home directory | |
1808 | associated with the specified login name. | |
1809 | ||
1810 | If the tilde-prefix is @samp{~+}, the value of | |
28ef6c31 | 1811 | the shell variable @env{PWD} replaces the tilde-prefix. |
cce855bc | 1812 | If the tilde-prefix is @samp{~-}, the value of the shell variable |
28ef6c31 | 1813 | @env{OLDPWD}, if it is set, is substituted. |
cce855bc JA |
1814 | |
1815 | If the characters following the tilde in the tilde-prefix consist of a | |
1816 | number @var{N}, optionally prefixed by a @samp{+} or a @samp{-}, | |
1817 | the tilde-prefix is replaced with the | |
1818 | corresponding element from the directory stack, as it would be displayed | |
1819 | by the @code{dirs} builtin invoked with the characters following tilde | |
1820 | in the tilde-prefix as an argument (@pxref{The Directory Stack}). | |
1821 | If the tilde-prefix, sans the tilde, consists of a number without a | |
1822 | leading @samp{+} or @samp{-}, @samp{+} is assumed. | |
1823 | ||
1824 | If the login name is invalid, or the tilde expansion fails, the word is | |
1825 | left unchanged. | |
1826 | ||
1827 | Each variable assignment is checked for unquoted tilde-prefixes immediately | |
95732b49 | 1828 | following a @samp{:} or the first @samp{=}. |
cce855bc | 1829 | In these cases, tilde expansion is also performed. |
ac50fbac | 1830 | Consequently, one may use filenames with tildes in assignments to |
28ef6c31 | 1831 | @env{PATH}, @env{MAILPATH}, and @env{CDPATH}, |
cce855bc JA |
1832 | and the shell assigns the expanded value. |
1833 | ||
1834 | The following table shows how Bash treats unquoted tilde-prefixes: | |
1835 | ||
1836 | @table @code | |
1837 | @item ~ | |
1838 | The value of @code{$HOME} | |
1839 | @item ~/foo | |
1840 | @file{$HOME/foo} | |
1841 | ||
1842 | @item ~fred/foo | |
1843 | The subdirectory @code{foo} of the home directory of the user | |
1844 | @code{fred} | |
1845 | ||
1846 | @item ~+/foo | |
1847 | @file{$PWD/foo} | |
1848 | ||
1849 | @item ~-/foo | |
1850 | @file{$@{OLDPWD-'~-'@}/foo} | |
1851 | ||
1852 | @item ~@var{N} | |
1853 | The string that would be displayed by @samp{dirs +@var{N}} | |
1854 | ||
1855 | @item ~+@var{N} | |
1856 | The string that would be displayed by @samp{dirs +@var{N}} | |
1857 | ||
1858 | @item ~-@var{N} | |
1859 | The string that would be displayed by @samp{dirs -@var{N}} | |
cce855bc JA |
1860 | @end table |
1861 | ||
ccc6cda3 JA |
1862 | @node Shell Parameter Expansion |
1863 | @subsection Shell Parameter Expansion | |
1864 | @cindex parameter expansion | |
1865 | @cindex expansion, parameter | |
1866 | ||
1867 | The @samp{$} character introduces parameter expansion, | |
1868 | command substitution, or arithmetic expansion. The parameter name | |
1869 | or symbol to be expanded may be enclosed in braces, which | |
1870 | are optional but serve to protect the variable to be expanded from | |
1871 | characters immediately following it which could be | |
1872 | interpreted as part of the name. | |
1873 | ||
cce855bc JA |
1874 | When braces are used, the matching ending brace is the first @samp{@}} |
1875 | not escaped by a backslash or within a quoted string, and not within an | |
1876 | embedded arithmetic expansion, command substitution, or parameter | |
1877 | expansion. | |
1878 | ||
ccc6cda3 | 1879 | The basic form of parameter expansion is $@{@var{parameter}@}. |
ac50fbac CR |
1880 | The value of @var{parameter} is substituted. |
1881 | The @var{parameter} is a shell parameter as described above | |
1882 | (@pxref{Shell Parameters}) or an array reference (@pxref{Arrays}). | |
1883 | The braces are required when @var{parameter} | |
ccc6cda3 | 1884 | is a positional parameter with more than one digit, |
ac50fbac | 1885 | or when @var{parameter} is followed by a character that is not to be |
ccc6cda3 JA |
1886 | interpreted as part of its name. |
1887 | ||
0001803f | 1888 | If the first character of @var{parameter} is an exclamation point (!), |
a0c0a00f | 1889 | and @var{parameter} is not a @var{nameref}, |
ac50fbac | 1890 | it introduces a level of variable indirection. |
ccc6cda3 JA |
1891 | Bash uses the value of the variable formed from the rest of |
1892 | @var{parameter} as the name of the variable; this variable is then | |
d166f048 | 1893 | expanded and that value is used in the rest of the substitution, rather |
ccc6cda3 JA |
1894 | than the value of @var{parameter} itself. |
1895 | This is known as @code{indirect expansion}. | |
a0c0a00f CR |
1896 | If @var{parameter} is a nameref, this expands to the name of the |
1897 | variable referenced by @var{parameter} instead of performing the | |
1898 | complete indirect expansion. | |
ac50fbac | 1899 | The exceptions to this are the expansions of $@{!@var{prefix}*@} |
b80f6443 | 1900 | and $@{!@var{name}[@@]@} |
bb70624e | 1901 | described below. |
b80f6443 JA |
1902 | The exclamation point must immediately follow the left brace in order to |
1903 | introduce indirection. | |
ccc6cda3 JA |
1904 | |
1905 | In each of the cases below, @var{word} is subject to tilde expansion, | |
1906 | parameter expansion, command substitution, and arithmetic expansion. | |
bb70624e | 1907 | |
17345e5a | 1908 | When not performing substring expansion, using the form described |
ac50fbac | 1909 | below (e.g., @samp{:-}), Bash tests for a parameter that is unset or null. |
17345e5a JA |
1910 | Omitting the colon results in a test only for a parameter that is unset. |
1911 | Put another way, if the colon is included, | |
1912 | the operator tests for both @var{parameter}'s existence and that its value | |
1913 | is not null; if the colon is omitted, the operator tests only for existence. | |
ccc6cda3 JA |
1914 | |
1915 | @table @code | |
1916 | ||
1917 | @item $@{@var{parameter}:@minus{}@var{word}@} | |
1918 | If @var{parameter} is unset or null, the expansion of | |
1919 | @var{word} is substituted. Otherwise, the value of | |
1920 | @var{parameter} is substituted. | |
1921 | ||
1922 | @item $@{@var{parameter}:=@var{word}@} | |
1923 | If @var{parameter} | |
1924 | is unset or null, the expansion of @var{word} | |
1925 | is assigned to @var{parameter}. | |
b80f6443 JA |
1926 | The value of @var{parameter} is then substituted. |
1927 | Positional parameters and special parameters may not be assigned to | |
1928 | in this way. | |
ccc6cda3 JA |
1929 | |
1930 | @item $@{@var{parameter}:?@var{word}@} | |
1931 | If @var{parameter} | |
1932 | is null or unset, the expansion of @var{word} (or a message | |
1933 | to that effect if @var{word} | |
1934 | is not present) is written to the standard error and the shell, if it | |
1935 | is not interactive, exits. Otherwise, the value of @var{parameter} is | |
1936 | substituted. | |
1937 | ||
1938 | @item $@{@var{parameter}:+@var{word}@} | |
1939 | If @var{parameter} | |
1940 | is null or unset, nothing is substituted, otherwise the expansion of | |
1941 | @var{word} is substituted. | |
1942 | ||
1943 | @item $@{@var{parameter}:@var{offset}@} | |
1944 | @itemx $@{@var{parameter}:@var{offset}:@var{length}@} | |
ac50fbac CR |
1945 | This is referred to as Substring Expansion. |
1946 | It expands to up to @var{length} characters of the value of @var{parameter} | |
cce855bc | 1947 | starting at the character specified by @var{offset}. |
ac50fbac CR |
1948 | If @var{parameter} is @samp{@@}, an indexed array subscripted by |
1949 | @samp{@@} or @samp{*}, or an associative array name, the results differ as | |
1950 | described below. | |
1951 | If @var{length} is omitted, it expands to the substring of the value of | |
1952 | @var{parameter} starting at the character specified by @var{offset} | |
1953 | and extending to the end of the value. | |
ccc6cda3 | 1954 | @var{length} and @var{offset} are arithmetic expressions |
cce855bc | 1955 | (@pxref{Shell Arithmetic}). |
ccc6cda3 | 1956 | |
ccc6cda3 | 1957 | If @var{offset} evaluates to a number less than zero, the value |
ac50fbac CR |
1958 | is used as an offset in characters |
1959 | from the end of the value of @var{parameter}. | |
1960 | If @var{length} evaluates to a number less than zero, | |
1961 | it is interpreted as an offset in characters | |
1962 | from the end of the value of @var{parameter} rather than | |
1963 | a number of characters, and the expansion is the characters between | |
1964 | @var{offset} and that result. | |
1965 | Note that a negative offset must be separated from the colon by at least | |
1966 | one space to avoid being confused with the @samp{:-} expansion. | |
1967 | ||
1968 | Here are some examples illustrating substring expansion on parameters and | |
1969 | subscripted arrays: | |
1970 | ||
1971 | @verbatim | |
1972 | $ string=01234567890abcdefgh | |
1973 | $ echo ${string:7} | |
1974 | 7890abcdefgh | |
1975 | $ echo ${string:7:0} | |
1976 | ||
1977 | $ echo ${string:7:2} | |
1978 | 78 | |
1979 | $ echo ${string:7:-2} | |
1980 | 7890abcdef | |
1981 | $ echo ${string: -7} | |
1982 | bcdefgh | |
1983 | $ echo ${string: -7:0} | |
1984 | ||
1985 | $ echo ${string: -7:2} | |
1986 | bc | |
1987 | $ echo ${string: -7:-2} | |
1988 | bcdef | |
1989 | $ set -- 01234567890abcdefgh | |
1990 | $ echo ${1:7} | |
1991 | 7890abcdefgh | |
1992 | $ echo ${1:7:0} | |
1993 | ||
1994 | $ echo ${1:7:2} | |
1995 | 78 | |
1996 | $ echo ${1:7:-2} | |
1997 | 7890abcdef | |
1998 | $ echo ${1: -7} | |
1999 | bcdefgh | |
2000 | $ echo ${1: -7:0} | |
2001 | ||
2002 | $ echo ${1: -7:2} | |
2003 | bc | |
2004 | $ echo ${1: -7:-2} | |
2005 | bcdef | |
2006 | $ array[0]=01234567890abcdefgh | |
2007 | $ echo ${array[0]:7} | |
2008 | 7890abcdefgh | |
2009 | $ echo ${array[0]:7:0} | |
2010 | ||
2011 | $ echo ${array[0]:7:2} | |
2012 | 78 | |
2013 | $ echo ${array[0]:7:-2} | |
2014 | 7890abcdef | |
2015 | $ echo ${array[0]: -7} | |
2016 | bcdefgh | |
2017 | $ echo ${array[0]: -7:0} | |
2018 | ||
2019 | $ echo ${array[0]: -7:2} | |
2020 | bc | |
2021 | $ echo ${array[0]: -7:-2} | |
2022 | bcdef | |
2023 | @end verbatim | |
2024 | ||
ccc6cda3 JA |
2025 | If @var{parameter} is @samp{@@}, the result is @var{length} positional |
2026 | parameters beginning at @var{offset}. | |
ac50fbac CR |
2027 | A negative @var{offset} is taken relative to one greater than the greatest |
2028 | positional parameter, so an offset of -1 evaluates to the last positional | |
2029 | parameter. | |
2030 | It is an expansion error if @var{length} evaluates to a number less than zero. | |
2031 | ||
2032 | The following examples illustrate substring expansion using positional | |
2033 | parameters: | |
2034 | ||
2035 | @verbatim | |
2036 | $ set -- 1 2 3 4 5 6 7 8 9 0 a b c d e f g h | |
2037 | $ echo ${@:7} | |
2038 | 7 8 9 0 a b c d e f g h | |
2039 | $ echo ${@:7:0} | |
2040 | ||
2041 | $ echo ${@:7:2} | |
2042 | 7 8 | |
2043 | $ echo ${@:7:-2} | |
2044 | bash: -2: substring expression < 0 | |
2045 | $ echo ${@: -7:2} | |
2046 | b c | |
2047 | $ echo ${@:0} | |
2048 | ./bash 1 2 3 4 5 6 7 8 9 0 a b c d e f g h | |
2049 | $ echo ${@:0:2} | |
2050 | ./bash 1 | |
2051 | $ echo ${@: -7:0} | |
2052 | ||
2053 | @end verbatim | |
2054 | ||
3185942a JA |
2055 | If @var{parameter} is an indexed array name subscripted |
2056 | by @samp{@@} or @samp{*}, the result is the @var{length} | |
cce855bc | 2057 | members of the array beginning with @code{$@{@var{parameter}[@var{offset}]@}}. |
95732b49 JA |
2058 | A negative @var{offset} is taken relative to one greater than the maximum |
2059 | index of the specified array. | |
ac50fbac CR |
2060 | It is an expansion error if @var{length} evaluates to a number less than zero. |
2061 | ||
2062 | These examples show how you can use substring expansion with indexed | |
2063 | arrays: | |
2064 | ||
2065 | @verbatim | |
2066 | $ array=(0 1 2 3 4 5 6 7 8 9 0 a b c d e f g h) | |
2067 | $ echo ${array[@]:7} | |
2068 | 7 8 9 0 a b c d e f g h | |
2069 | $ echo ${array[@]:7:2} | |
2070 | 7 8 | |
2071 | $ echo ${array[@]: -7:2} | |
2072 | b c | |
2073 | $ echo ${array[@]: -7:-2} | |
2074 | bash: -2: substring expression < 0 | |
2075 | $ echo ${array[@]:0} | |
2076 | 0 1 2 3 4 5 6 7 8 9 0 a b c d e f g h | |
2077 | $ echo ${array[@]:0:2} | |
2078 | 0 1 | |
2079 | $ echo ${array[@]: -7:0} | |
2080 | ||
2081 | @end verbatim | |
2082 | ||
3185942a JA |
2083 | Substring expansion applied to an associative array produces undefined |
2084 | results. | |
2085 | ||
cce855bc | 2086 | Substring indexing is zero-based unless the positional parameters |
3185942a JA |
2087 | are used, in which case the indexing starts at 1 by default. |
2088 | If @var{offset} is 0, and the positional parameters are used, @code{$@@} is | |
2089 | prefixed to the list. | |
ccc6cda3 | 2090 | |
bb70624e | 2091 | @item $@{!@var{prefix}*@} |
b80f6443 | 2092 | @itemx $@{!@var{prefix}@@@} |
bb70624e | 2093 | Expands to the names of variables whose names begin with @var{prefix}, |
28ef6c31 | 2094 | separated by the first character of the @env{IFS} special variable. |
3185942a JA |
2095 | When @samp{@@} is used and the expansion appears within double quotes, each |
2096 | variable name expands to a separate word. | |
bb70624e | 2097 | |
b80f6443 JA |
2098 | @item $@{!@var{name}[@@]@} |
2099 | @itemx $@{!@var{name}[*]@} | |
2100 | If @var{name} is an array variable, expands to the list of array indices | |
2101 | (keys) assigned in @var{name}. | |
2102 | If @var{name} is not an array, expands to 0 if @var{name} is set and null | |
2103 | otherwise. | |
2104 | When @samp{@@} is used and the expansion appears within double quotes, each | |
2105 | key expands to a separate word. | |
2106 | ||
ccc6cda3 | 2107 | @item $@{#@var{parameter}@} |
cce855bc JA |
2108 | The length in characters of the expanded value of @var{parameter} is |
2109 | substituted. | |
2110 | If @var{parameter} is @samp{*} or @samp{@@}, the value substituted | |
2111 | is the number of positional parameters. | |
2112 | If @var{parameter} is an array name subscripted by @samp{*} or @samp{@@}, | |
2113 | the value substituted is the number of elements in the array. | |
ac50fbac CR |
2114 | If @var{parameter} |
2115 | is an indexed array name subscripted by a negative number, that number is | |
2116 | interpreted as relative to one greater than the maximum index of | |
2117 | @var{parameter}, so negative indices count back from the end of the | |
2118 | array, and an index of -1 references the last element. | |
ccc6cda3 JA |
2119 | |
2120 | @item $@{@var{parameter}#@var{word}@} | |
2121 | @itemx $@{@var{parameter}##@var{word}@} | |
2122 | The @var{word} | |
2123 | is expanded to produce a pattern just as in filename | |
2124 | expansion (@pxref{Filename Expansion}). If the pattern matches | |
cce855bc JA |
2125 | the beginning of the expanded value of @var{parameter}, |
2126 | then the result of the expansion is the expanded value of @var{parameter} | |
ccc6cda3 JA |
2127 | with the shortest matching pattern (the @samp{#} case) or the |
2128 | longest matching pattern (the @samp{##} case) deleted. | |
2129 | If @var{parameter} is @samp{@@} or @samp{*}, | |
2130 | the pattern removal operation is applied to each positional | |
2131 | parameter in turn, and the expansion is the resultant list. | |
2132 | If @var{parameter} is an array variable subscripted with | |
2133 | @samp{@@} or @samp{*}, | |
2134 | the pattern removal operation is applied to each member of the | |
2135 | array in turn, and the expansion is the resultant list. | |
2136 | ||
2137 | @item $@{@var{parameter}%@var{word}@} | |
2138 | @itemx $@{@var{parameter}%%@var{word}@} | |
2139 | The @var{word} is expanded to produce a pattern just as in | |
2140 | filename expansion. | |
cce855bc JA |
2141 | If the pattern matches a trailing portion of the expanded value of |
2142 | @var{parameter}, then the result of the expansion is the value of | |
2143 | @var{parameter} with the shortest matching pattern (the @samp{%} case) | |
2144 | or the longest matching pattern (the @samp{%%} case) deleted. | |
ccc6cda3 JA |
2145 | If @var{parameter} is @samp{@@} or @samp{*}, |
2146 | the pattern removal operation is applied to each positional | |
2147 | parameter in turn, and the expansion is the resultant list. | |
2148 | If @var{parameter} | |
2149 | is an array variable subscripted with @samp{@@} or @samp{*}, | |
2150 | the pattern removal operation is applied to each member of the | |
2151 | array in turn, and the expansion is the resultant list. | |
2152 | ||
2153 | @item $@{@var{parameter}/@var{pattern}/@var{string}@} | |
ccc6cda3 JA |
2154 | |
2155 | The @var{pattern} is expanded to produce a pattern just as in | |
2156 | filename expansion. | |
2157 | @var{Parameter} is expanded and the longest match of @var{pattern} | |
2158 | against its value is replaced with @var{string}. | |
0628567a JA |
2159 | If @var{pattern} begins with @samp{/}, all matches of @var{pattern} are |
2160 | replaced with @var{string}. Normally only the first match is replaced. | |
ccc6cda3 | 2161 | If @var{pattern} begins with @samp{#}, it must match at the beginning |
b72432fd | 2162 | of the expanded value of @var{parameter}. |
ccc6cda3 | 2163 | If @var{pattern} begins with @samp{%}, it must match at the end |
b72432fd | 2164 | of the expanded value of @var{parameter}. |
ccc6cda3 JA |
2165 | If @var{string} is null, matches of @var{pattern} are deleted |
2166 | and the @code{/} following @var{pattern} may be omitted. | |
a0c0a00f CR |
2167 | If the @code{nocasematch} shell option |
2168 | (see the description of @code{shopt} in @ref{The Shopt Builtin}) | |
2169 | is enabled, the match is performed without regard to the case | |
2170 | of alphabetic characters. | |
ccc6cda3 JA |
2171 | If @var{parameter} is @samp{@@} or @samp{*}, |
2172 | the substitution operation is applied to each positional | |
2173 | parameter in turn, and the expansion is the resultant list. | |
2174 | If @var{parameter} | |
2175 | is an array variable subscripted with @samp{@@} or @samp{*}, | |
2176 | the substitution operation is applied to each member of the | |
2177 | array in turn, and the expansion is the resultant list. | |
2178 | ||
3185942a JA |
2179 | @item $@{@var{parameter}^@var{pattern}@} |
2180 | @itemx $@{@var{parameter}^^@var{pattern}@} | |
2181 | @itemx $@{@var{parameter},@var{pattern}@} | |
2182 | @itemx $@{@var{parameter},,@var{pattern}@} | |
2183 | This expansion modifies the case of alphabetic characters in @var{parameter}. | |
2184 | The @var{pattern} is expanded to produce a pattern just as in | |
0001803f | 2185 | filename expansion. |
ac50fbac CR |
2186 | Each character in the expanded value of @var{parameter} is tested against |
2187 | @var{pattern}, and, if it matches the pattern, its case is converted. | |
2188 | The pattern should not attempt to match more than one character. | |
3185942a JA |
2189 | The @samp{^} operator converts lowercase letters matching @var{pattern} |
2190 | to uppercase; the @samp{,} operator converts matching uppercase letters | |
2191 | to lowercase. | |
2192 | The @samp{^^} and @samp{,,} expansions convert each matched character in the | |
2193 | expanded value; the @samp{^} and @samp{,} expansions match and convert only | |
17345e5a | 2194 | the first character in the expanded value. |
3185942a JA |
2195 | If @var{pattern} is omitted, it is treated like a @samp{?}, which matches |
2196 | every character. | |
2197 | If @var{parameter} is @samp{@@} or @samp{*}, | |
2198 | the case modification operation is applied to each positional | |
2199 | parameter in turn, and the expansion is the resultant list. | |
2200 | If @var{parameter} | |
2201 | is an array variable subscripted with @samp{@@} or @samp{*}, | |
2202 | the case modification operation is applied to each member of the | |
2203 | array in turn, and the expansion is the resultant list. | |
a0c0a00f CR |
2204 | |
2205 | @item $@{@var{parameter}@@@var{operator}@} | |
2206 | The expansion is either a transformation of the value of @var{parameter} | |
2207 | or information about @var{parameter} itself, depending on the value of | |
2208 | @var{operator}. Each @var{operator} is a single letter: | |
2209 | ||
2210 | @table @code | |
2211 | @item Q | |
2212 | The expansion is a string that is the value of @var{parameter} quoted in a | |
2213 | format that can be reused as input. | |
2214 | @item E | |
2215 | The expansion is a string that is the value of @var{parameter} with backslash | |
2216 | escape sequences expanded as with the @code{$'@dots{}'} quoting mechansim. | |
2217 | @item P | |
2218 | The expansion is a string that is the result of expanding the value of | |
2219 | @var{parameter} as if it were a prompt string (@pxref{Controlling the Prompt}). | |
2220 | @item A | |
2221 | The expansion is a string in the form of | |
2222 | an assignment statement or @code{declare} command that, if | |
2223 | evaluated, will recreate @var{parameter} with its attributes and value. | |
2224 | @item a | |
2225 | The expansion is a string consisting of flag values representing | |
2226 | @var{parameter}'s attributes. | |
2227 | @end table | |
2228 | ||
2229 | If @var{parameter} is @samp{@@} or @samp{*}, | |
2230 | the operation is applied to each positional | |
2231 | parameter in turn, and the expansion is the resultant list. | |
2232 | If @var{parameter} | |
2233 | is an array variable subscripted with @samp{@@} or @samp{*}, | |
2234 | the operation is applied to each member of the | |
2235 | array in turn, and the expansion is the resultant list. | |
2236 | ||
2237 | The result of the expansion is subject to word splitting and pathname | |
2238 | expansion as described below. | |
ccc6cda3 JA |
2239 | @end table |
2240 | ||
2241 | @node Command Substitution | |
2242 | @subsection Command Substitution | |
2243 | @cindex command substitution | |
2244 | ||
2245 | Command substitution allows the output of a command to replace | |
bb70624e JA |
2246 | the command itself. |
2247 | Command substitution occurs when a command is enclosed as follows: | |
ccc6cda3 JA |
2248 | @example |
2249 | $(@var{command}) | |
2250 | @end example | |
2251 | @noindent | |
2252 | or | |
2253 | @example | |
2254 | `@var{command}` | |
2255 | @end example | |
2256 | ||
2257 | @noindent | |
a0c0a00f CR |
2258 | Bash performs the expansion by executing @var{command} in a subshell environment |
2259 | and replacing the command substitution with the standard output of the | |
ccc6cda3 | 2260 | command, with any trailing newlines deleted. |
cce855bc JA |
2261 | Embedded newlines are not deleted, but they may be removed during |
2262 | word splitting. | |
2263 | The command substitution @code{$(cat @var{file})} can be | |
2264 | replaced by the equivalent but faster @code{$(< @var{file})}. | |
ccc6cda3 JA |
2265 | |
2266 | When the old-style backquote form of substitution is used, | |
2267 | backslash retains its literal meaning except when followed by | |
cce855bc JA |
2268 | @samp{$}, @samp{`}, or @samp{\}. |
2269 | The first backquote not preceded by a backslash terminates the | |
2270 | command substitution. | |
ccc6cda3 JA |
2271 | When using the @code{$(@var{command})} form, all characters between |
2272 | the parentheses make up the command; none are treated specially. | |
2273 | ||
cce855bc JA |
2274 | Command substitutions may be nested. To nest when using the backquoted |
2275 | form, escape the inner backquotes with backslashes. | |
ccc6cda3 JA |
2276 | |
2277 | If the substitution appears within double quotes, word splitting and | |
2278 | filename expansion are not performed on the results. | |
2279 | ||
cce855bc JA |
2280 | @node Arithmetic Expansion |
2281 | @subsection Arithmetic Expansion | |
2282 | @cindex expansion, arithmetic | |
2283 | @cindex arithmetic expansion | |
2284 | ||
2285 | Arithmetic expansion allows the evaluation of an arithmetic expression | |
2286 | and the substitution of the result. The format for arithmetic expansion is: | |
2287 | ||
2288 | @example | |
2289 | $(( @var{expression} )) | |
2290 | @end example | |
2291 | ||
2292 | The expression is treated as if it were within double quotes, but | |
2293 | a double quote inside the parentheses is not treated specially. | |
ac50fbac CR |
2294 | All tokens in the expression undergo parameter and variable expansion, |
2295 | command substitution, and quote removal. | |
2296 | The result is treated as the arithmetic expression to be evaluated. | |
b80f6443 | 2297 | Arithmetic expansions may be nested. |
cce855bc JA |
2298 | |
2299 | The evaluation is performed according to the rules listed below | |
2300 | (@pxref{Shell Arithmetic}). | |
2301 | If the expression is invalid, Bash prints a message indicating | |
2302 | failure to the standard error and no substitution occurs. | |
2303 | ||
ccc6cda3 JA |
2304 | @node Process Substitution |
2305 | @subsection Process Substitution | |
2306 | @cindex process substitution | |
2307 | ||
a0c0a00f CR |
2308 | Process substitution allows a process's input or output to be |
2309 | referred to using a filename. | |
ccc6cda3 JA |
2310 | It takes the form of |
2311 | @example | |
2312 | <(@var{list}) | |
2313 | @end example | |
2314 | @noindent | |
2315 | or | |
2316 | @example | |
2317 | >(@var{list}) | |
2318 | @end example | |
2319 | @noindent | |
a0c0a00f CR |
2320 | The process @var{list} is run asynchronously, and its input or output |
2321 | appears as a filename. | |
2322 | This filename is | |
ccc6cda3 | 2323 | passed as an argument to the current command as the result of the |
a0c0a00f CR |
2324 | expansion. |
2325 | If the @code{>(@var{list})} form is used, writing to | |
ccc6cda3 JA |
2326 | the file will provide input for @var{list}. If the |
2327 | @code{<(@var{list})} form is used, the file passed as an | |
2328 | argument should be read to obtain the output of @var{list}. | |
bb70624e JA |
2329 | Note that no space may appear between the @code{<} or @code{>} |
2330 | and the left parenthesis, otherwise the construct would be interpreted | |
2331 | as a redirection. | |
a0c0a00f CR |
2332 | Process substitution is supported on systems that support named |
2333 | pipes (@sc{fifo}s) or the @file{/dev/fd} method of naming open files. | |
ccc6cda3 | 2334 | |
cce855bc JA |
2335 | When available, process substitution is performed simultaneously with |
2336 | parameter and variable expansion, command substitution, and arithmetic | |
2337 | expansion. | |
ccc6cda3 JA |
2338 | |
2339 | @node Word Splitting | |
2340 | @subsection Word Splitting | |
2341 | @cindex word splitting | |
2342 | ||
2343 | The shell scans the results of parameter expansion, command substitution, | |
2344 | and arithmetic expansion that did not occur within double quotes for | |
2345 | word splitting. | |
2346 | ||
3185942a | 2347 | The shell treats each character of @env{$IFS} as a delimiter, and splits |
ac50fbac CR |
2348 | the results of the other expansions into words using these characters |
2349 | as field terminators. | |
3185942a JA |
2350 | If @env{IFS} is unset, or its value is exactly @code{<space><tab><newline>}, |
2351 | the default, then sequences of | |
2352 | @code{ <space>}, @code{<tab>}, and @code{<newline>} | |
2353 | at the beginning and end of the results of the previous | |
2354 | expansions are ignored, and any sequence of @env{IFS} | |
2355 | characters not at the beginning or end serves to delimit words. | |
2356 | If @env{IFS} has a value other than the default, then sequences of | |
a0c0a00f | 2357 | the whitespace characters @code{space}, @code{tab}, and @code{newline} |
ccc6cda3 JA |
2358 | are ignored at the beginning and end of the |
2359 | word, as long as the whitespace character is in the | |
28ef6c31 JA |
2360 | value of @env{IFS} (an @env{IFS} whitespace character). |
2361 | Any character in @env{IFS} that is not @env{IFS} | |
2362 | whitespace, along with any adjacent @env{IFS} | |
2363 | whitespace characters, delimits a field. A sequence of @env{IFS} | |
ccc6cda3 | 2364 | whitespace characters is also treated as a delimiter. |
28ef6c31 | 2365 | If the value of @env{IFS} is null, no word splitting occurs. |
ccc6cda3 | 2366 | |
a0c0a00f CR |
2367 | Explicit null arguments (@code{""} or @code{''}) are retained |
2368 | and passed to commands as empty strings. | |
ccc6cda3 | 2369 | Unquoted implicit null arguments, resulting from the expansion of |
bb70624e | 2370 | parameters that have no values, are removed. |
ccc6cda3 | 2371 | If a parameter with no value is expanded within double quotes, a |
a0c0a00f CR |
2372 | null argument results and is retained |
2373 | and passed to a command as an empty string. | |
2374 | When a quoted null argument appears as part of a word whose expansion is | |
2375 | non-null, the null argument is removed. | |
2376 | That is, the word | |
2377 | @code{-d''} becomes @code{-d} after word splitting and | |
2378 | null argument removal. | |
ccc6cda3 JA |
2379 | |
2380 | Note that if no expansion occurs, no splitting | |
2381 | is performed. | |
2382 | ||
2383 | @node Filename Expansion | |
2384 | @subsection Filename Expansion | |
cce855bc JA |
2385 | @menu |
2386 | * Pattern Matching:: How the shell matches patterns. | |
2387 | @end menu | |
ccc6cda3 JA |
2388 | @cindex expansion, filename |
2389 | @cindex expansion, pathname | |
2390 | @cindex filename expansion | |
2391 | @cindex pathname expansion | |
2392 | ||
28ef6c31 | 2393 | After word splitting, unless the @option{-f} option has been set |
cce855bc | 2394 | (@pxref{The Set Builtin}), Bash scans each word for the characters |
bb70624e | 2395 | @samp{*}, @samp{?}, and @samp{[}. |
ccc6cda3 JA |
2396 | If one of these characters appears, then the word is |
2397 | regarded as a @var{pattern}, | |
2398 | and replaced with an alphabetically sorted list of | |
ac50fbac CR |
2399 | filenames matching the pattern (@pxref{Pattern Matching}). |
2400 | If no matching filenames are found, | |
ccc6cda3 | 2401 | and the shell option @code{nullglob} is disabled, the word is left |
cce855bc JA |
2402 | unchanged. |
2403 | If the @code{nullglob} option is set, and no matches are found, the word | |
2404 | is removed. | |
b80f6443 JA |
2405 | If the @code{failglob} shell option is set, and no matches are found, |
2406 | an error message is printed and the command is not executed. | |
cce855bc JA |
2407 | If the shell option @code{nocaseglob} is enabled, the match is performed |
2408 | without regard to the case of alphabetic characters. | |
2409 | ||
0001803f | 2410 | When a pattern is used for filename expansion, the character @samp{.} |
ccc6cda3 | 2411 | at the start of a filename or immediately following a slash |
cce855bc | 2412 | must be matched explicitly, unless the shell option @code{dotglob} is set. |
ac50fbac | 2413 | When matching a filename, the slash character must always be |
cce855bc | 2414 | matched explicitly. |
ccc6cda3 | 2415 | In other cases, the @samp{.} character is not treated specially. |
cce855bc | 2416 | |
3185942a | 2417 | See the description of @code{shopt} in @ref{The Shopt Builtin}, |
cce855bc | 2418 | for a description of the @code{nocaseglob}, @code{nullglob}, |
b80f6443 | 2419 | @code{failglob}, and @code{dotglob} options. |
ccc6cda3 | 2420 | |
28ef6c31 | 2421 | The @env{GLOBIGNORE} |
ccc6cda3 | 2422 | shell variable may be used to restrict the set of filenames matching a |
28ef6c31 | 2423 | pattern. If @env{GLOBIGNORE} |
ccc6cda3 | 2424 | is set, each matching filename that also matches one of the patterns in |
a0c0a00f CR |
2425 | @env{GLOBIGNORE} is removed from the list of matches. |
2426 | If the @code{nocaseglob} option is set, the matching against the patterns in | |
2427 | @env{GLOBIGNORE} is performed without regard to case. | |
2428 | The filenames | |
ccc6cda3 | 2429 | @file{.} and @file{..} |
b80f6443 JA |
2430 | are always ignored when @env{GLOBIGNORE} |
2431 | is set and not null. | |
2432 | However, setting @env{GLOBIGNORE} to a non-null value has the effect of | |
ccc6cda3 JA |
2433 | enabling the @code{dotglob} |
2434 | shell option, so all other filenames beginning with a | |
2435 | @samp{.} will match. | |
2436 | To get the old behavior of ignoring filenames beginning with a | |
28ef6c31 JA |
2437 | @samp{.}, make @samp{.*} one of the patterns in @env{GLOBIGNORE}. |
2438 | The @code{dotglob} option is disabled when @env{GLOBIGNORE} | |
ccc6cda3 JA |
2439 | is unset. |
2440 | ||
cce855bc JA |
2441 | @node Pattern Matching |
2442 | @subsubsection Pattern Matching | |
2443 | @cindex pattern matching | |
2444 | @cindex matching, pattern | |
2445 | ||
2446 | Any character that appears in a pattern, other than the special pattern | |
b80f6443 JA |
2447 | characters described below, matches itself. |
2448 | The @sc{nul} character may not occur in a pattern. | |
2449 | A backslash escapes the following character; the | |
2450 | escaping backslash is discarded when matching. | |
2451 | The special pattern characters must be quoted if they are to be matched | |
2452 | literally. | |
cce855bc | 2453 | |
ccc6cda3 JA |
2454 | The special pattern characters have the following meanings: |
2455 | @table @code | |
2456 | @item * | |
2457 | Matches any string, including the null string. | |
3185942a JA |
2458 | When the @code{globstar} shell option is enabled, and @samp{*} is used in |
2459 | a filename expansion context, two adjacent @samp{*}s used as a single | |
2460 | pattern will match all files and zero or more directories and | |
2461 | subdirectories. | |
2462 | If followed by a @samp{/}, two adjacent @samp{*}s will match only | |
2463 | directories and subdirectories. | |
ccc6cda3 JA |
2464 | @item ? |
2465 | Matches any single character. | |
2466 | @item [@dots{}] | |
2467 | Matches any one of the enclosed characters. A pair of characters | |
28ef6c31 | 2468 | separated by a hyphen denotes a @var{range expression}; |
ac50fbac | 2469 | any character that falls between those two characters, inclusive, |
28ef6c31 | 2470 | using the current locale's collating sequence and character set, |
ccc6cda3 JA |
2471 | is matched. If the first character following the |
2472 | @samp{[} is a @samp{!} or a @samp{^} | |
2473 | then any character not enclosed is matched. A @samp{@minus{}} | |
2474 | may be matched by including it as the first or last character | |
2475 | in the set. A @samp{]} may be matched by including it as the first | |
2476 | character in the set. | |
28ef6c31 | 2477 | The sorting order of characters in range expressions is determined by |
ac50fbac CR |
2478 | the current locale and the values of the |
2479 | @env{LC_COLLATE} and @env{LC_ALL} shell variables, if set. | |
28ef6c31 JA |
2480 | |
2481 | For example, in the default C locale, @samp{[a-dx-z]} is equivalent to | |
2482 | @samp{[abcdxyz]}. Many locales sort characters in dictionary order, and in | |
2483 | these locales @samp{[a-dx-z]} is typically not equivalent to @samp{[abcdxyz]}; | |
2484 | it might be equivalent to @samp{[aBbCcDdxXyYz]}, for example. To obtain | |
2485 | the traditional interpretation of ranges in bracket expressions, you can | |
2486 | force the use of the C locale by setting the @env{LC_COLLATE} or | |
ac50fbac CR |
2487 | @env{LC_ALL} environment variable to the value @samp{C}, or enable the |
2488 | @code{globasciiranges} shell option. | |
cce855bc JA |
2489 | |
2490 | Within @samp{[} and @samp{]}, @var{character classes} can be specified | |
2491 | using the syntax | |
2492 | @code{[:}@var{class}@code{:]}, where @var{class} is one of the | |
0628567a | 2493 | following classes defined in the @sc{posix} standard: |
cce855bc JA |
2494 | @example |
2495 | alnum alpha ascii blank cntrl digit graph lower | |
7117c2d2 | 2496 | print punct space upper word xdigit |
cce855bc JA |
2497 | @end example |
2498 | @noindent | |
2499 | A character class matches any character belonging to that class. | |
7117c2d2 JA |
2500 | The @code{word} character class matches letters, digits, and the character |
2501 | @samp{_}. | |
cce855bc JA |
2502 | |
2503 | Within @samp{[} and @samp{]}, an @var{equivalence class} can be | |
2504 | specified using the syntax @code{[=}@var{c}@code{=]}, which | |
2505 | matches all characters with the same collation weight (as defined | |
2506 | by the current locale) as the character @var{c}. | |
2507 | ||
2508 | Within @samp{[} and @samp{]}, the syntax @code{[.}@var{symbol}@code{.]} | |
2509 | matches the collating symbol @var{symbol}. | |
2510 | @end table | |
2511 | ||
2512 | If the @code{extglob} shell option is enabled using the @code{shopt} | |
2513 | builtin, several extended pattern matching operators are recognized. | |
2514 | In the following description, a @var{pattern-list} is a list of one | |
2515 | or more patterns separated by a @samp{|}. | |
2516 | Composite patterns may be formed using one or more of the following | |
2517 | sub-patterns: | |
2518 | ||
2519 | @table @code | |
2520 | @item ?(@var{pattern-list}) | |
2521 | Matches zero or one occurrence of the given patterns. | |
2522 | ||
2523 | @item *(@var{pattern-list}) | |
2524 | Matches zero or more occurrences of the given patterns. | |
2525 | ||
2526 | @item +(@var{pattern-list}) | |
2527 | Matches one or more occurrences of the given patterns. | |
2528 | ||
2529 | @item @@(@var{pattern-list}) | |
95732b49 | 2530 | Matches one of the given patterns. |
cce855bc JA |
2531 | |
2532 | @item !(@var{pattern-list}) | |
2533 | Matches anything except one of the given patterns. | |
ccc6cda3 JA |
2534 | @end table |
2535 | ||
2536 | @node Quote Removal | |
2537 | @subsection Quote Removal | |
2538 | ||
2539 | After the preceding expansions, all unquoted occurrences of the | |
2540 | characters @samp{\}, @samp{'}, and @samp{"} that did not | |
2541 | result from one of the above expansions are removed. | |
2542 | ||
2543 | @node Redirections | |
2544 | @section Redirections | |
2545 | @cindex redirection | |
2546 | ||
2547 | Before a command is executed, its input and output | |
2548 | may be @var{redirected} | |
2549 | using a special notation interpreted by the shell. | |
ac50fbac CR |
2550 | Redirection allows commands' file handles to be |
2551 | duplicated, opened, closed, | |
2552 | made to refer to different files, | |
2553 | and can change the files the command reads from and writes to. | |
2554 | Redirection may also be used to modify file handles in the | |
ccc6cda3 JA |
2555 | current shell execution environment. The following redirection |
2556 | operators may precede or appear anywhere within a | |
2557 | simple command or may follow a command. | |
2558 | Redirections are processed in the order they appear, from | |
2559 | left to right. | |
2560 | ||
0001803f CR |
2561 | Each redirection that may be preceded by a file descriptor number |
2562 | may instead be preceded by a word of the form @{@var{varname}@}. | |
2563 | In this case, for each redirection operator except | |
2564 | >&- and <&-, the shell will allocate a file descriptor greater | |
2565 | than 10 and assign it to @{@var{varname}@}. If >&- or <&- is preceded | |
2566 | by @{@var{varname}@}, the value of @var{varname} defines the file | |
2567 | descriptor to close. | |
2568 | ||
ccc6cda3 JA |
2569 | In the following descriptions, if the file descriptor number is |
2570 | omitted, and the first character of the redirection operator is | |
2571 | @samp{<}, the redirection refers to the standard input (file | |
2572 | descriptor 0). If the first character of the redirection operator | |
2573 | is @samp{>}, the redirection refers to the standard output (file | |
2574 | descriptor 1). | |
2575 | ||
cce855bc JA |
2576 | The word following the redirection operator in the following |
2577 | descriptions, unless otherwise noted, is subjected to brace expansion, | |
2578 | tilde expansion, parameter expansion, command substitution, arithmetic | |
bb70624e | 2579 | expansion, quote removal, filename expansion, and word splitting. |
cce855bc | 2580 | If it expands to more than one word, Bash reports an error. |
ccc6cda3 JA |
2581 | |
2582 | Note that the order of redirections is significant. For example, | |
2583 | the command | |
2584 | @example | |
2585 | ls > @var{dirlist} 2>&1 | |
2586 | @end example | |
2587 | @noindent | |
bb70624e JA |
2588 | directs both standard output (file descriptor 1) and standard error |
2589 | (file descriptor 2) to the file @var{dirlist}, while the command | |
ccc6cda3 JA |
2590 | @example |
2591 | ls 2>&1 > @var{dirlist} | |
2592 | @end example | |
2593 | @noindent | |
2594 | directs only the standard output to file @var{dirlist}, | |
17345e5a | 2595 | because the standard error was made a copy of the standard output |
ccc6cda3 JA |
2596 | before the standard output was redirected to @var{dirlist}. |
2597 | ||
bb70624e | 2598 | Bash handles several filenames specially when they are used in |
a0c0a00f CR |
2599 | redirections, as described in the following table. |
2600 | If the operating system on which Bash is running provides these | |
2601 | special files, bash will use them; otherwise it will emulate them | |
2602 | internally with the behavior described below. | |
bb70624e JA |
2603 | |
2604 | @table @code | |
2605 | @item /dev/fd/@var{fd} | |
2606 | If @var{fd} is a valid integer, file descriptor @var{fd} is duplicated. | |
2607 | ||
2608 | @item /dev/stdin | |
2609 | File descriptor 0 is duplicated. | |
2610 | ||
2611 | @item /dev/stdout | |
2612 | File descriptor 1 is duplicated. | |
2613 | ||
2614 | @item /dev/stderr | |
2615 | File descriptor 2 is duplicated. | |
2616 | ||
2617 | @item /dev/tcp/@var{host}/@var{port} | |
2618 | If @var{host} is a valid hostname or Internet address, and @var{port} | |
ac50fbac CR |
2619 | is an integer port number or service name, Bash attempts to open |
2620 | the corresponding TCP socket. | |
bb70624e JA |
2621 | |
2622 | @item /dev/udp/@var{host}/@var{port} | |
2623 | If @var{host} is a valid hostname or Internet address, and @var{port} | |
ac50fbac CR |
2624 | is an integer port number or service name, Bash attempts to open |
2625 | the corresponding UDP socket. | |
bb70624e JA |
2626 | @end table |
2627 | ||
cce855bc JA |
2628 | A failure to open or create a file causes the redirection to fail. |
2629 | ||
95732b49 JA |
2630 | Redirections using file descriptors greater than 9 should be used with |
2631 | care, as they may conflict with file descriptors the shell uses | |
2632 | internally. | |
2633 | ||
ccc6cda3 JA |
2634 | @subsection Redirecting Input |
2635 | Redirection of input causes the file whose name results from | |
2636 | the expansion of @var{word} | |
2637 | to be opened for reading on file descriptor @code{n}, | |
2638 | or the standard input (file descriptor 0) if @code{n} | |
2639 | is not specified. | |
2640 | ||
2641 | The general format for redirecting input is: | |
2642 | @example | |
7117c2d2 | 2643 | [@var{n}]<@var{word} |
ccc6cda3 JA |
2644 | @end example |
2645 | ||
2646 | @subsection Redirecting Output | |
2647 | Redirection of output causes the file whose name results from | |
2648 | the expansion of @var{word} | |
7117c2d2 JA |
2649 | to be opened for writing on file descriptor @var{n}, |
2650 | or the standard output (file descriptor 1) if @var{n} | |
ccc6cda3 JA |
2651 | is not specified. If the file does not exist it is created; |
2652 | if it does exist it is truncated to zero size. | |
2653 | ||
2654 | The general format for redirecting output is: | |
2655 | @example | |
7117c2d2 | 2656 | [@var{n}]>[|]@var{word} |
ccc6cda3 JA |
2657 | @end example |
2658 | ||
cce855bc JA |
2659 | If the redirection operator is @samp{>}, and the @code{noclobber} |
2660 | option to the @code{set} builtin has been enabled, the redirection | |
bb70624e | 2661 | will fail if the file whose name results from the expansion of |
cce855bc JA |
2662 | @var{word} exists and is a regular file. |
2663 | If the redirection operator is @samp{>|}, or the redirection operator is | |
2664 | @samp{>} and the @code{noclobber} option is not enabled, the redirection | |
2665 | is attempted even if the file named by @var{word} exists. | |
ccc6cda3 JA |
2666 | |
2667 | @subsection Appending Redirected Output | |
2668 | Redirection of output in this fashion | |
2669 | causes the file whose name results from | |
2670 | the expansion of @var{word} | |
7117c2d2 JA |
2671 | to be opened for appending on file descriptor @var{n}, |
2672 | or the standard output (file descriptor 1) if @var{n} | |
ccc6cda3 JA |
2673 | is not specified. If the file does not exist it is created. |
2674 | ||
2675 | The general format for appending output is: | |
2676 | @example | |
7117c2d2 | 2677 | [@var{n}]>>@var{word} |
ccc6cda3 JA |
2678 | @end example |
2679 | ||
2680 | @subsection Redirecting Standard Output and Standard Error | |
3185942a | 2681 | This construct allows both the |
ccc6cda3 JA |
2682 | standard output (file descriptor 1) and |
2683 | the standard error output (file descriptor 2) | |
2684 | to be redirected to the file whose name is the | |
3185942a | 2685 | expansion of @var{word}. |
ccc6cda3 JA |
2686 | |
2687 | There are two formats for redirecting standard output and | |
2688 | standard error: | |
2689 | @example | |
2690 | &>@var{word} | |
2691 | @end example | |
2692 | @noindent | |
2693 | and | |
2694 | @example | |
2695 | >&@var{word} | |
2696 | @end example | |
2697 | @noindent | |
2698 | Of the two forms, the first is preferred. | |
2699 | This is semantically equivalent to | |
2700 | @example | |
2701 | >@var{word} 2>&1 | |
2702 | @end example | |
ac50fbac CR |
2703 | When using the second form, @var{word} may not expand to a number or |
2704 | @samp{-}. If it does, other redirection operators apply | |
2705 | (see Duplicating File Descriptors below) for compatibility reasons. | |
ccc6cda3 | 2706 | |
3185942a JA |
2707 | @subsection Appending Standard Output and Standard Error |
2708 | This construct allows both the | |
2709 | standard output (file descriptor 1) and | |
2710 | the standard error output (file descriptor 2) | |
2711 | to be appended to the file whose name is the | |
2712 | expansion of @var{word}. | |
2713 | ||
2714 | The format for appending standard output and standard error is: | |
2715 | @example | |
2716 | &>>@var{word} | |
2717 | @end example | |
2718 | @noindent | |
2719 | This is semantically equivalent to | |
2720 | @example | |
2721 | >>@var{word} 2>&1 | |
2722 | @end example | |
ac50fbac | 2723 | (see Duplicating File Descriptors below). |
3185942a | 2724 | |
ccc6cda3 JA |
2725 | @subsection Here Documents |
2726 | This type of redirection instructs the shell to read input from the | |
2727 | current source until a line containing only @var{word} | |
2728 | (with no trailing blanks) is seen. All of | |
2729 | the lines read up to that point are then used as the standard | |
a0c0a00f | 2730 | input (or file descriptor @var{n} if @var{n} is specified) for a command. |
ccc6cda3 | 2731 | |
7117c2d2 | 2732 | The format of here-documents is: |
ccc6cda3 | 2733 | @example |
a0c0a00f | 2734 | [@var{n}]<<[@minus{}]@var{word} |
ccc6cda3 JA |
2735 | @var{here-document} |
2736 | @var{delimiter} | |
2737 | @end example | |
2738 | ||
ac50fbac CR |
2739 | No parameter and variable expansion, command substitution, |
2740 | arithmetic expansion, or filename expansion is performed on | |
a0c0a00f | 2741 | @var{word}. If any part of @var{word} is quoted, the |
ccc6cda3 | 2742 | @var{delimiter} is the result of quote removal on @var{word}, |
cce855bc JA |
2743 | and the lines in the here-document are not expanded. |
2744 | If @var{word} is unquoted, | |
ac50fbac CR |
2745 | all lines of the here-document are subjected to |
2746 | parameter expansion, command substitution, and arithmetic expansion, | |
2747 | the character sequence @code{\newline} is ignored, and @samp{\} | |
ccc6cda3 JA |
2748 | must be used to quote the characters |
2749 | @samp{\}, @samp{$}, and @samp{`}. | |
2750 | ||
2751 | If the redirection operator is @samp{<<-}, | |
2752 | then all leading tab characters are stripped from input lines and the | |
2753 | line containing @var{delimiter}. | |
2754 | This allows here-documents within shell scripts to be indented in a | |
2755 | natural fashion. | |
2756 | ||
7117c2d2 JA |
2757 | @subsection Here Strings |
2758 | A variant of here documents, the format is: | |
2759 | @example | |
a0c0a00f | 2760 | [@var{n}]<<< @var{word} |
7117c2d2 JA |
2761 | @end example |
2762 | ||
ac50fbac CR |
2763 | The @var{word} undergoes |
2764 | brace expansion, tilde expansion, parameter and variable expansion, | |
2765 | command substitution, arithmetic expansion, and quote removal. | |
2766 | Pathname expansion and word splitting are not performed. | |
a0c0a00f CR |
2767 | The result is supplied as a single string, |
2768 | with a newline appended, | |
2769 | to the command on its | |
2770 | standard input (or file descriptor @var{n} if @var{n} is specified). | |
7117c2d2 | 2771 | |
ccc6cda3 JA |
2772 | @subsection Duplicating File Descriptors |
2773 | The redirection operator | |
2774 | @example | |
7117c2d2 | 2775 | [@var{n}]<&@var{word} |
ccc6cda3 JA |
2776 | @end example |
2777 | @noindent | |
2778 | is used to duplicate input file descriptors. | |
2779 | If @var{word} | |
7117c2d2 | 2780 | expands to one or more digits, the file descriptor denoted by @var{n} |
cce855bc JA |
2781 | is made to be a copy of that file descriptor. |
2782 | If the digits in @var{word} do not specify a file descriptor open for | |
2783 | input, a redirection error occurs. | |
2784 | If @var{word} | |
ac50fbac CR |
2785 | evaluates to @samp{-}, file descriptor @var{n} is closed. |
2786 | If @var{n} is not specified, the standard input (file descriptor 0) is used. | |
ccc6cda3 JA |
2787 | |
2788 | The operator | |
2789 | @example | |
7117c2d2 | 2790 | [@var{n}]>&@var{word} |
ccc6cda3 JA |
2791 | @end example |
2792 | @noindent | |
2793 | is used similarly to duplicate output file descriptors. If | |
7117c2d2 | 2794 | @var{n} is not specified, the standard output (file descriptor 1) is used. |
cce855bc JA |
2795 | If the digits in @var{word} do not specify a file descriptor open for |
2796 | output, a redirection error occurs. | |
ac50fbac CR |
2797 | If @var{word} |
2798 | evaluates to @samp{-}, file descriptor @var{n} is closed. | |
7117c2d2 | 2799 | As a special case, if @var{n} is omitted, and @var{word} does not |
ac50fbac | 2800 | expand to one or more digits or @samp{-}, the standard output and standard |
ccc6cda3 JA |
2801 | error are redirected as described previously. |
2802 | ||
7117c2d2 JA |
2803 | @subsection Moving File Descriptors |
2804 | The redirection operator | |
2805 | @example | |
2806 | [@var{n}]<&@var{digit}- | |
2807 | @end example | |
2808 | @noindent | |
2809 | moves the file descriptor @var{digit} to file descriptor @var{n}, | |
2810 | or the standard input (file descriptor 0) if @var{n} is not specified. | |
2811 | @var{digit} is closed after being duplicated to @var{n}. | |
2812 | ||
2813 | Similarly, the redirection operator | |
2814 | @example | |
2815 | [@var{n}]>&@var{digit}- | |
2816 | @end example | |
2817 | @noindent | |
2818 | moves the file descriptor @var{digit} to file descriptor @var{n}, | |
2819 | or the standard output (file descriptor 1) if @var{n} is not specified. | |
2820 | ||
ccc6cda3 JA |
2821 | @subsection Opening File Descriptors for Reading and Writing |
2822 | The redirection operator | |
2823 | @example | |
7117c2d2 | 2824 | [@var{n}]<>@var{word} |
ccc6cda3 JA |
2825 | @end example |
2826 | @noindent | |
2827 | causes the file whose name is the expansion of @var{word} | |
2828 | to be opened for both reading and writing on file descriptor | |
7117c2d2 | 2829 | @var{n}, or on file descriptor 0 if @var{n} |
ccc6cda3 JA |
2830 | is not specified. If the file does not exist, it is created. |
2831 | ||
2832 | @node Executing Commands | |
2833 | @section Executing Commands | |
2834 | ||
2835 | @menu | |
cce855bc JA |
2836 | * Simple Command Expansion:: How Bash expands simple commands before |
2837 | executing them. | |
ccc6cda3 | 2838 | * Command Search and Execution:: How Bash finds commands and runs them. |
cce855bc JA |
2839 | * Command Execution Environment:: The environment in which Bash |
2840 | executes commands that are not | |
2841 | shell builtins. | |
ccc6cda3 | 2842 | * Environment:: The environment given to a command. |
ccc6cda3 JA |
2843 | * Exit Status:: The status returned by commands and how Bash |
2844 | interprets it. | |
ccc6cda3 JA |
2845 | * Signals:: What happens when Bash or a command it runs |
2846 | receives a signal. | |
2847 | @end menu | |
2848 | ||
cce855bc JA |
2849 | @node Simple Command Expansion |
2850 | @subsection Simple Command Expansion | |
2851 | @cindex command expansion | |
2852 | ||
2853 | When a simple command is executed, the shell performs the following | |
2854 | expansions, assignments, and redirections, from left to right. | |
2855 | ||
2856 | @enumerate | |
2857 | @item | |
2858 | The words that the parser has marked as variable assignments (those | |
2859 | preceding the command name) and redirections are saved for later | |
2860 | processing. | |
2861 | ||
2862 | @item | |
2863 | The words that are not variable assignments or redirections are | |
2864 | expanded (@pxref{Shell Expansions}). | |
2865 | If any words remain after expansion, the first word | |
2866 | is taken to be the name of the command and the remaining words are | |
2867 | the arguments. | |
2868 | ||
2869 | @item | |
2870 | Redirections are performed as described above (@pxref{Redirections}). | |
2871 | ||
2872 | @item | |
2873 | The text after the @samp{=} in each variable assignment undergoes tilde | |
2874 | expansion, parameter expansion, command substitution, arithmetic expansion, | |
2875 | and quote removal before being assigned to the variable. | |
2876 | @end enumerate | |
2877 | ||
2878 | If no command name results, the variable assignments affect the current | |
2879 | shell environment. Otherwise, the variables are added to the environment | |
2880 | of the executed command and do not affect the current shell environment. | |
2881 | If any of the assignments attempts to assign a value to a readonly variable, | |
2882 | an error occurs, and the command exits with a non-zero status. | |
2883 | ||
2884 | If no command name results, redirections are performed, but do not | |
2885 | affect the current shell environment. A redirection error causes the | |
2886 | command to exit with a non-zero status. | |
2887 | ||
2888 | If there is a command name left after expansion, execution proceeds as | |
2889 | described below. Otherwise, the command exits. If one of the expansions | |
2890 | contained a command substitution, the exit status of the command is | |
2891 | the exit status of the last command substitution performed. If there | |
2892 | were no command substitutions, the command exits with a status of zero. | |
2893 | ||
ccc6cda3 JA |
2894 | @node Command Search and Execution |
2895 | @subsection Command Search and Execution | |
2896 | @cindex command execution | |
2897 | @cindex command search | |
2898 | ||
2899 | After a command has been split into words, if it results in a | |
2900 | simple command and an optional list of arguments, the following | |
2901 | actions are taken. | |
2902 | ||
2903 | @enumerate | |
2904 | @item | |
2905 | If the command name contains no slashes, the shell attempts to | |
2906 | locate it. If there exists a shell function by that name, that | |
bb70624e | 2907 | function is invoked as described in @ref{Shell Functions}. |
ccc6cda3 JA |
2908 | |
2909 | @item | |
2910 | If the name does not match a function, the shell searches for | |
2911 | it in the list of shell builtins. If a match is found, that | |
2912 | builtin is invoked. | |
2913 | ||
2914 | @item | |
2915 | If the name is neither a shell function nor a builtin, | |
2916 | and contains no slashes, Bash searches each element of | |
28ef6c31 | 2917 | @env{$PATH} for a directory containing an executable file |
ccc6cda3 | 2918 | by that name. Bash uses a hash table to remember the full |
28ef6c31 | 2919 | pathnames of executable files to avoid multiple @env{PATH} searches |
cce855bc | 2920 | (see the description of @code{hash} in @ref{Bourne Shell Builtins}). |
28ef6c31 | 2921 | A full search of the directories in @env{$PATH} |
ccc6cda3 | 2922 | is performed only if the command is not found in the hash table. |
3185942a JA |
2923 | If the search is unsuccessful, the shell searches for a defined shell |
2924 | function named @code{command_not_found_handle}. | |
2925 | If that function exists, it is invoked with the original command and | |
2926 | the original command's arguments as its arguments, and the function's | |
2927 | exit status becomes the exit status of the shell. | |
2928 | If that function is not defined, the shell prints an error | |
cce855bc | 2929 | message and returns an exit status of 127. |
ccc6cda3 JA |
2930 | |
2931 | @item | |
2932 | If the search is successful, or if the command name contains | |
cce855bc JA |
2933 | one or more slashes, the shell executes the named program in |
2934 | a separate execution environment. | |
ccc6cda3 JA |
2935 | Argument 0 is set to the name given, and the remaining arguments |
2936 | to the command are set to the arguments supplied, if any. | |
2937 | ||
2938 | @item | |
2939 | If this execution fails because the file is not in executable | |
cce855bc JA |
2940 | format, and the file is not a directory, it is assumed to be a |
2941 | @var{shell script} and the shell executes it as described in | |
2942 | @ref{Shell Scripts}. | |
2943 | ||
2944 | @item | |
2945 | If the command was not begun asynchronously, the shell waits for | |
2946 | the command to complete and collects its exit status. | |
2947 | ||
ccc6cda3 JA |
2948 | @end enumerate |
2949 | ||
cce855bc JA |
2950 | @node Command Execution Environment |
2951 | @subsection Command Execution Environment | |
2952 | @cindex execution environment | |
2953 | ||
2954 | The shell has an @var{execution environment}, which consists of the | |
2955 | following: | |
2956 | ||
2957 | @itemize @bullet | |
2958 | @item | |
2959 | open files inherited by the shell at invocation, as modified by | |
2960 | redirections supplied to the @code{exec} builtin | |
2961 | ||
2962 | @item | |
2963 | the current working directory as set by @code{cd}, @code{pushd}, or | |
2964 | @code{popd}, or inherited by the shell at invocation | |
2965 | ||
2966 | @item | |
2967 | the file creation mode mask as set by @code{umask} or inherited from | |
2968 | the shell's parent | |
2969 | ||
2970 | @item | |
2971 | current traps set by @code{trap} | |
2972 | ||
2973 | @item | |
2974 | shell parameters that are set by variable assignment or with @code{set} | |
2975 | or inherited from the shell's parent in the environment | |
2976 | ||
2977 | @item | |
2978 | shell functions defined during execution or inherited from the shell's | |
2979 | parent in the environment | |
2980 | ||
2981 | @item | |
2982 | options enabled at invocation (either by default or with command-line | |
2983 | arguments) or by @code{set} | |
2984 | ||
2985 | @item | |
3185942a | 2986 | options enabled by @code{shopt} (@pxref{The Shopt Builtin}) |
cce855bc JA |
2987 | |
2988 | @item | |
2989 | shell aliases defined with @code{alias} (@pxref{Aliases}) | |
2990 | ||
2991 | @item | |
bb70624e | 2992 | various process @sc{id}s, including those of background jobs |
cce855bc | 2993 | (@pxref{Lists}), the value of @code{$$}, and the value of |
28ef6c31 | 2994 | @env{$PPID} |
cce855bc JA |
2995 | |
2996 | @end itemize | |
2997 | ||
2998 | When a simple command other than a builtin or shell function | |
2999 | is to be executed, it | |
3000 | is invoked in a separate execution environment that consists of | |
3001 | the following. Unless otherwise noted, the values are inherited | |
3002 | from the shell. | |
3003 | ||
3004 | @itemize @bullet | |
3005 | @item | |
3006 | the shell's open files, plus any modifications and additions specified | |
3007 | by redirections to the command | |
3008 | ||
3009 | @item | |
3010 | the current working directory | |
3011 | ||
3012 | @item | |
3013 | the file creation mode mask | |
3014 | ||
3015 | @item | |
b80f6443 JA |
3016 | shell variables and functions marked for export, along with variables |
3017 | exported for the command, passed in the environment (@pxref{Environment}) | |
cce855bc JA |
3018 | |
3019 | @item | |
3020 | traps caught by the shell are reset to the values inherited from the | |
3021 | shell's parent, and traps ignored by the shell are ignored | |
3022 | ||
3023 | @end itemize | |
3024 | ||
3025 | A command invoked in this separate environment cannot affect the | |
a0c0a00f | 3026 | shell's execution environment. |
cce855bc | 3027 | |
b80f6443 JA |
3028 | Command substitution, commands grouped with parentheses, |
3029 | and asynchronous commands are invoked in a | |
cce855bc JA |
3030 | subshell environment that is a duplicate of the shell environment, |
3031 | except that traps caught by the shell are reset to the values | |
3032 | that the shell inherited from its parent at invocation. Builtin | |
3033 | commands that are invoked as part of a pipeline are also executed | |
3034 | in a subshell environment. Changes made to the subshell environment | |
3035 | cannot affect the shell's execution environment. | |
3036 | ||
3185942a JA |
3037 | Subshells spawned to execute command substitutions inherit the value of |
3038 | the @option{-e} option from the parent shell. When not in @sc{posix} mode, | |
3039 | Bash clears the @option{-e} option in such subshells. | |
3040 | ||
f73dda09 JA |
3041 | If a command is followed by a @samp{&} and job control is not active, the |
3042 | default standard input for the command is the empty file @file{/dev/null}. | |
3043 | Otherwise, the invoked command inherits the file descriptors of the calling | |
3044 | shell as modified by redirections. | |
3045 | ||
ccc6cda3 JA |
3046 | @node Environment |
3047 | @subsection Environment | |
3048 | @cindex environment | |
3049 | ||
3050 | When a program is invoked it is given an array of strings | |
3051 | called the @var{environment}. | |
3052 | This is a list of name-value pairs, of the form @code{name=value}. | |
3053 | ||
bb70624e JA |
3054 | Bash provides several ways to manipulate the environment. |
3055 | On invocation, the shell scans its own environment and | |
ccc6cda3 JA |
3056 | creates a parameter for each name found, automatically marking |
3057 | it for @var{export} | |
3058 | to child processes. Executed commands inherit the environment. | |
3059 | The @code{export} and @samp{declare -x} | |
3060 | commands allow parameters and functions to be added to and | |
3061 | deleted from the environment. If the value of a parameter | |
3062 | in the environment is modified, the new value becomes part | |
3063 | of the environment, replacing the old. The environment | |
3064 | inherited by any executed command consists of the shell's | |
3065 | initial environment, whose values may be modified in the shell, | |
cce855bc JA |
3066 | less any pairs removed by the @code{unset} and @samp{export -n} |
3067 | commands, plus any additions via the @code{export} and | |
3068 | @samp{declare -x} commands. | |
ccc6cda3 JA |
3069 | |
3070 | The environment for any simple command | |
3071 | or function may be augmented temporarily by prefixing it with | |
3072 | parameter assignments, as described in @ref{Shell Parameters}. | |
3073 | These assignment statements affect only the environment seen | |
3074 | by that command. | |
3075 | ||
28ef6c31 | 3076 | If the @option{-k} option is set (@pxref{The Set Builtin}), then all |
ccc6cda3 JA |
3077 | parameter assignments are placed in the environment for a command, |
3078 | not just those that precede the command name. | |
3079 | ||
3080 | When Bash invokes an external command, the variable @samp{$_} | |
ac50fbac | 3081 | is set to the full pathname of the command and passed to that |
ccc6cda3 JA |
3082 | command in its environment. |
3083 | ||
3084 | @node Exit Status | |
3085 | @subsection Exit Status | |
3086 | @cindex exit status | |
3087 | ||
3185942a JA |
3088 | The exit status of an executed command is the value returned by the |
3089 | @var{waitpid} system call or equivalent function. Exit statuses | |
3090 | fall between 0 and 255, though, as explained below, the shell may | |
3091 | use values above 125 specially. Exit statuses from shell builtins and | |
ac50fbac | 3092 | compound commands are also limited to this range. Under certain |
3185942a JA |
3093 | circumstances, the shell will use special values to indicate specific |
3094 | failure modes. | |
3095 | ||
cce855bc | 3096 | For the shell's purposes, a command which exits with a |
ccc6cda3 JA |
3097 | zero exit status has succeeded. |
3098 | A non-zero exit status indicates failure. | |
3099 | This seemingly counter-intuitive scheme is used so there | |
3100 | is one well-defined way to indicate success and a variety of | |
3101 | ways to indicate various failure modes. | |
bb70624e JA |
3102 | When a command terminates on a fatal signal whose number is @var{N}, |
3103 | Bash uses the value 128+@var{N} as the exit status. | |
ccc6cda3 JA |
3104 | |
3105 | If a command is not found, the child process created to | |
3106 | execute it returns a status of 127. If a command is found | |
3107 | but is not executable, the return status is 126. | |
3108 | ||
cce855bc JA |
3109 | If a command fails because of an error during expansion or redirection, |
3110 | the exit status is greater than zero. | |
3111 | ||
ccc6cda3 JA |
3112 | The exit status is used by the Bash conditional commands |
3113 | (@pxref{Conditional Constructs}) and some of the list | |
3114 | constructs (@pxref{Lists}). | |
3115 | ||
3116 | All of the Bash builtins return an exit status of zero if they succeed | |
3117 | and a non-zero status on failure, so they may be used by the | |
3118 | conditional and list constructs. | |
a0c0a00f CR |
3119 | All builtins return an exit status of 2 to indicate incorrect usage, |
3120 | generally invalid options or missing arguments. | |
ccc6cda3 JA |
3121 | |
3122 | @node Signals | |
3123 | @subsection Signals | |
3124 | @cindex signal handling | |
3125 | ||
cce855bc | 3126 | When Bash is interactive, in the absence of any traps, it ignores |
ccc6cda3 JA |
3127 | @code{SIGTERM} (so that @samp{kill 0} does not kill an interactive shell), |
3128 | and @code{SIGINT} | |
3129 | is caught and handled (so that the @code{wait} builtin is interruptible). | |
3130 | When Bash receives a @code{SIGINT}, it breaks out of any executing loops. | |
3131 | In all cases, Bash ignores @code{SIGQUIT}. | |
3132 | If job control is in effect (@pxref{Job Control}), Bash | |
3133 | ignores @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}. | |
3134 | ||
b80f6443 | 3135 | Non-builtin commands started by Bash have signal handlers set to the |
cce855bc JA |
3136 | values inherited by the shell from its parent. |
3137 | When job control is not in effect, asynchronous commands | |
b80f6443 JA |
3138 | ignore @code{SIGINT} and @code{SIGQUIT} in addition to these inherited |
3139 | handlers. | |
cce855bc JA |
3140 | Commands run as a result of |
3141 | command substitution ignore the keyboard-generated job control signals | |
ccc6cda3 JA |
3142 | @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}. |
3143 | ||
3144 | The shell exits by default upon receipt of a @code{SIGHUP}. | |
f73dda09 JA |
3145 | Before exiting, an interactive shell resends the @code{SIGHUP} to |
3146 | all jobs, running or stopped. | |
cce855bc JA |
3147 | Stopped jobs are sent @code{SIGCONT} to ensure that they receive |
3148 | the @code{SIGHUP}. | |
3149 | To prevent the shell from sending the @code{SIGHUP} signal to a | |
3150 | particular job, it should be removed | |
3151 | from the jobs table with the @code{disown} | |
3152 | builtin (@pxref{Job Control Builtins}) or marked | |
3153 | to not receive @code{SIGHUP} using @code{disown -h}. | |
3154 | ||
3155 | If the @code{huponexit} shell option has been set with @code{shopt} | |
3185942a | 3156 | (@pxref{The Shopt Builtin}), Bash sends a @code{SIGHUP} to all jobs when |
cce855bc JA |
3157 | an interactive login shell exits. |
3158 | ||
b80f6443 JA |
3159 | If Bash is waiting for a command to complete and receives a signal |
3160 | for which a trap has been set, the trap will not be executed until | |
a0c0a00f | 3161 | the command completes. |
cce855bc JA |
3162 | When Bash is waiting for an asynchronous |
3163 | command via the @code{wait} builtin, the reception of a signal for | |
3164 | which a trap has been set will cause the @code{wait} builtin to return | |
3165 | immediately with an exit status greater than 128, immediately after | |
3166 | which the trap is executed. | |
ccc6cda3 JA |
3167 | |
3168 | @node Shell Scripts | |
3169 | @section Shell Scripts | |
3170 | @cindex shell script | |
3171 | ||
3172 | A shell script is a text file containing shell commands. When such | |
3173 | a file is used as the first non-option argument when invoking Bash, | |
28ef6c31 | 3174 | and neither the @option{-c} nor @option{-s} option is supplied |
ccc6cda3 JA |
3175 | (@pxref{Invoking Bash}), |
3176 | Bash reads and executes commands from the file, then exits. This | |
f73dda09 JA |
3177 | mode of operation creates a non-interactive shell. The shell first |
3178 | searches for the file in the current directory, and looks in the | |
3179 | directories in @env{$PATH} if not found there. | |
3180 | ||
3181 | When Bash runs | |
ccc6cda3 JA |
3182 | a shell script, it sets the special parameter @code{0} to the name |
3183 | of the file, rather than the name of the shell, and the positional | |
3184 | parameters are set to the remaining arguments, if any are given. | |
3185 | If no additional arguments are supplied, the positional parameters | |
3186 | are unset. | |
3187 | ||
3188 | A shell script may be made executable by using the @code{chmod} command | |
3189 | to turn on the execute bit. When Bash finds such a file while | |
28ef6c31 | 3190 | searching the @env{$PATH} for a command, it spawns a subshell to |
ccc6cda3 JA |
3191 | execute it. In other words, executing |
3192 | @example | |
3193 | filename @var{arguments} | |
3194 | @end example | |
3195 | @noindent | |
3196 | is equivalent to executing | |
3197 | @example | |
3198 | bash filename @var{arguments} | |
3199 | @end example | |
3200 | ||
3201 | @noindent | |
3202 | if @code{filename} is an executable shell script. | |
3203 | This subshell reinitializes itself, so that the effect is as if a | |
cce855bc JA |
3204 | new shell had been invoked to interpret the script, with the |
3205 | exception that the locations of commands remembered by the parent | |
3206 | (see the description of @code{hash} in @ref{Bourne Shell Builtins}) | |
3207 | are retained by the child. | |
ccc6cda3 | 3208 | |
bb70624e | 3209 | Most versions of Unix make this a part of the operating system's command |
ccc6cda3 JA |
3210 | execution mechanism. If the first line of a script begins with |
3211 | the two characters @samp{#!}, the remainder of the line specifies | |
bb70624e JA |
3212 | an interpreter for the program. |
3213 | Thus, you can specify Bash, @code{awk}, Perl, or some other | |
3214 | interpreter and write the rest of the script file in that language. | |
3215 | ||
3216 | The arguments to the interpreter | |
ccc6cda3 JA |
3217 | consist of a single optional argument following the interpreter |
3218 | name on the first line of the script file, followed by the name of | |
3219 | the script file, followed by the rest of the arguments. Bash | |
3220 | will perform this action on operating systems that do not handle it | |
3221 | themselves. Note that some older versions of Unix limit the interpreter | |
3222 | name and argument to a maximum of 32 characters. | |
3223 | ||
bb70624e JA |
3224 | Bash scripts often begin with @code{#! /bin/bash} (assuming that |
3225 | Bash has been installed in @file{/bin}), since this ensures that | |
3226 | Bash will be used to interpret the script, even if it is executed | |
3227 | under another shell. | |
3228 | ||
3229 | @node Shell Builtin Commands | |
3230 | @chapter Shell Builtin Commands | |
ccc6cda3 JA |
3231 | |
3232 | @menu | |
3233 | * Bourne Shell Builtins:: Builtin commands inherited from the Bourne | |
3234 | Shell. | |
bb70624e | 3235 | * Bash Builtins:: Table of builtins specific to Bash. |
3185942a JA |
3236 | * Modifying Shell Behavior:: Builtins to modify shell attributes and |
3237 | optional behavior. | |
bb70624e | 3238 | * Special Builtins:: Builtin commands classified specially by |
0628567a | 3239 | POSIX. |
ccc6cda3 JA |
3240 | @end menu |
3241 | ||
bb70624e JA |
3242 | Builtin commands are contained within the shell itself. |
3243 | When the name of a builtin command is used as the first word of | |
3244 | a simple command (@pxref{Simple Commands}), the shell executes | |
3245 | the command directly, without invoking another program. | |
3246 | Builtin commands are necessary to implement functionality impossible | |
3247 | or inconvenient to obtain with separate utilities. | |
3248 | ||
0628567a | 3249 | This section briefly describes the builtins which Bash inherits from |
bb70624e JA |
3250 | the Bourne Shell, as well as the builtin commands which are unique |
3251 | to or have been extended in Bash. | |
3252 | ||
a0c0a00f | 3253 | Several builtin commands are described in other chapters: builtin |
bb70624e JA |
3254 | commands which provide the Bash interface to the job control |
3255 | facilities (@pxref{Job Control Builtins}), the directory stack | |
3256 | (@pxref{Directory Stack Builtins}), the command history | |
3257 | (@pxref{Bash History Builtins}), and the programmable completion | |
3258 | facilities (@pxref{Programmable Completion Builtins}). | |
3259 | ||
3260 | Many of the builtins have been extended by @sc{posix} or Bash. | |
ccc6cda3 | 3261 | |
b80f6443 JA |
3262 | Unless otherwise noted, each builtin command documented as accepting |
3263 | options preceded by @samp{-} accepts @samp{--} | |
3264 | to signify the end of the options. | |
0001803f CR |
3265 | The @code{:}, @code{true}, @code{false}, and @code{test} |
3266 | builtins do not accept options and do not treat @samp{--} specially. | |
a0c0a00f CR |
3267 | The @code{exit}, @code{logout}, @code{return}, |
3268 | @code{break}, @code{continue}, @code{let}, | |
0001803f CR |
3269 | and @code{shift} builtins accept and process arguments beginning |
3270 | with @samp{-} without requiring @samp{--}. | |
3271 | Other builtins that accept arguments but are not specified as accepting | |
3272 | options interpret arguments beginning with @samp{-} as invalid options and | |
3273 | require @samp{--} to prevent this interpretation. | |
b80f6443 | 3274 | |
ccc6cda3 JA |
3275 | @node Bourne Shell Builtins |
3276 | @section Bourne Shell Builtins | |
3277 | ||
bb70624e | 3278 | The following shell builtin commands are inherited from the Bourne Shell. |
0628567a | 3279 | These commands are implemented as specified by the @sc{posix} standard. |
ccc6cda3 JA |
3280 | |
3281 | @table @code | |
bb70624e | 3282 | @item : @r{(a colon)} |
ccc6cda3 JA |
3283 | @btindex : |
3284 | @example | |
3285 | : [@var{arguments}] | |
3286 | @end example | |
ac50fbac | 3287 | |
ccc6cda3 | 3288 | Do nothing beyond expanding @var{arguments} and performing redirections. |
cce855bc | 3289 | The return status is zero. |
ccc6cda3 | 3290 | |
bb70624e | 3291 | @item . @r{(a period)} |
ccc6cda3 JA |
3292 | @btindex . |
3293 | @example | |
b72432fd | 3294 | . @var{filename} [@var{arguments}] |
ccc6cda3 | 3295 | @end example |
ac50fbac | 3296 | |
ccc6cda3 | 3297 | Read and execute commands from the @var{filename} argument in the |
cce855bc | 3298 | current shell context. If @var{filename} does not contain a slash, |
28ef6c31 JA |
3299 | the @env{PATH} variable is used to find @var{filename}. |
3300 | When Bash is not in @sc{posix} mode, the current directory is searched | |
3301 | if @var{filename} is not found in @env{$PATH}. | |
b72432fd JA |
3302 | If any @var{arguments} are supplied, they become the positional |
3303 | parameters when @var{filename} is executed. Otherwise the positional | |
3304 | parameters are unchanged. | |
a0c0a00f CR |
3305 | If the @option{-T} option is enabled, @code{source} inherits any trap on |
3306 | @code{DEBUG}; if it is not, any @code{DEBUG} trap string is saved and | |
3307 | restored around the call to @code{source}, and @code{source} unsets the | |
3308 | @code{DEBUG} trap while it executes. | |
3309 | If @option{-T} is not set, and the sourced file changes | |
3310 | the @code{DEBUG} trap, the new value is retained when @code{source} completes. | |
cce855bc JA |
3311 | The return status is the exit status of the last command executed, or |
3312 | zero if no commands are executed. If @var{filename} is not found, or | |
3313 | cannot be read, the return status is non-zero. | |
bb70624e | 3314 | This builtin is equivalent to @code{source}. |
ccc6cda3 JA |
3315 | |
3316 | @item break | |
3317 | @btindex break | |
3318 | @example | |
3319 | break [@var{n}] | |
3320 | @end example | |
ac50fbac | 3321 | |
ccc6cda3 JA |
3322 | Exit from a @code{for}, @code{while}, @code{until}, or @code{select} loop. |
3323 | If @var{n} is supplied, the @var{n}th enclosing loop is exited. | |
cce855bc JA |
3324 | @var{n} must be greater than or equal to 1. |
3325 | The return status is zero unless @var{n} is not greater than or equal to 1. | |
ccc6cda3 JA |
3326 | |
3327 | @item cd | |
3328 | @btindex cd | |
3329 | @example | |
ac50fbac | 3330 | cd [-L|[-P [-e]] [-@@] [@var{directory}] |
ccc6cda3 | 3331 | @end example |
ac50fbac | 3332 | |
b80f6443 | 3333 | Change the current working directory to @var{directory}. |
ac50fbac CR |
3334 | If @var{directory} is not supplied, the value of the @env{HOME} |
3335 | shell variable is used. | |
3336 | Any additional arguments following @var{directory} are ignored. | |
3337 | If the shell variable | |
3338 | @env{CDPATH} exists, it is used as a search path: | |
3339 | each directory name in @env{CDPATH} is searched for | |
3340 | @var{directory}, with alternative directory names in @env{CDPATH} | |
3341 | separated by a colon (@samp{:}). | |
b80f6443 JA |
3342 | If @var{directory} begins with a slash, @env{CDPATH} is not used. |
3343 | ||
ac50fbac CR |
3344 | The @option{-P} option means to not follow symbolic links: symbolic links |
3345 | are resolved while @code{cd} is traversing @var{directory} and before | |
3346 | processing an instance of @samp{..} in @var{directory}. | |
3347 | ||
3348 | By default, or when the @option{-L} option is supplied, symbolic links | |
3349 | in @var{directory} are resolved after @code{cd} processes an instance | |
3350 | of @samp{..} in @var{directory}. | |
3351 | ||
3352 | If @samp{..} appears in @var{directory}, it is processed by removing the | |
3353 | immediately preceding pathname component, back to a slash or the beginning | |
3354 | of @var{directory}. | |
3355 | ||
495aee44 CR |
3356 | If the @option{-e} option is supplied with @option{-P} |
3357 | and the current working directory cannot be successfully determined | |
3358 | after a successful directory change, @code{cd} will return an unsuccessful | |
3359 | status. | |
ac50fbac CR |
3360 | |
3361 | On systems that support it, the @option{-@@} option presents the extended | |
3362 | attributes associated with a file as a directory. | |
3363 | ||
3364 | If @var{directory} is @samp{-}, it is converted to @env{$OLDPWD} | |
3365 | before the directory change is attempted. | |
b80f6443 JA |
3366 | |
3367 | If a non-empty directory name from @env{CDPATH} is used, or if | |
3368 | @samp{-} is the first argument, and the directory change is | |
3369 | successful, the absolute pathname of the new working directory is | |
3370 | written to the standard output. | |
3371 | ||
cce855bc JA |
3372 | The return status is zero if the directory is successfully changed, |
3373 | non-zero otherwise. | |
ccc6cda3 JA |
3374 | |
3375 | @item continue | |
3376 | @btindex continue | |
3377 | @example | |
3378 | continue [@var{n}] | |
3379 | @end example | |
ac50fbac | 3380 | |
ccc6cda3 JA |
3381 | Resume the next iteration of an enclosing @code{for}, @code{while}, |
3382 | @code{until}, or @code{select} loop. | |
cce855bc JA |
3383 | If @var{n} is supplied, the execution of the @var{n}th enclosing loop |
3384 | is resumed. | |
3385 | @var{n} must be greater than or equal to 1. | |
3386 | The return status is zero unless @var{n} is not greater than or equal to 1. | |
ccc6cda3 JA |
3387 | |
3388 | @item eval | |
3389 | @btindex eval | |
3390 | @example | |
3391 | eval [@var{arguments}] | |
3392 | @end example | |
ac50fbac | 3393 | |
cce855bc JA |
3394 | The arguments are concatenated together into a single command, which is |
3395 | then read and executed, and its exit status returned as the exit status | |
3396 | of @code{eval}. | |
3397 | If there are no arguments or only empty arguments, the return status is | |
3398 | zero. | |
ccc6cda3 JA |
3399 | |
3400 | @item exec | |
3401 | @btindex exec | |
3402 | @example | |
cce855bc | 3403 | exec [-cl] [-a @var{name}] [@var{command} [@var{arguments}]] |
ccc6cda3 | 3404 | @end example |
ac50fbac | 3405 | |
ccc6cda3 | 3406 | If @var{command} |
cce855bc | 3407 | is supplied, it replaces the shell without creating a new process. |
28ef6c31 | 3408 | If the @option{-l} option is supplied, the shell places a dash at the |
3185942a | 3409 | beginning of the zeroth argument passed to @var{command}. |
ccc6cda3 | 3410 | This is what the @code{login} program does. |
28ef6c31 | 3411 | The @option{-c} option causes @var{command} to be executed with an empty |
cce855bc | 3412 | environment. |
28ef6c31 | 3413 | If @option{-a} is supplied, the shell passes @var{name} as the zeroth |
cce855bc | 3414 | argument to @var{command}. |
ac50fbac CR |
3415 | If @var{command} |
3416 | cannot be executed for some reason, a non-interactive shell exits, | |
3417 | unless the @code{execfail} shell option | |
3418 | is enabled. In that case, it returns failure. | |
3419 | An interactive shell returns failure if the file cannot be executed. | |
ccc6cda3 | 3420 | If no @var{command} is specified, redirections may be used to affect |
cce855bc JA |
3421 | the current shell environment. If there are no redirection errors, the |
3422 | return status is zero; otherwise the return status is non-zero. | |
ccc6cda3 JA |
3423 | |
3424 | @item exit | |
3425 | @btindex exit | |
3426 | @example | |
3427 | exit [@var{n}] | |
3428 | @end example | |
ac50fbac | 3429 | |
ccc6cda3 | 3430 | Exit the shell, returning a status of @var{n} to the shell's parent. |
bb70624e | 3431 | If @var{n} is omitted, the exit status is that of the last command executed. |
cce855bc | 3432 | Any trap on @code{EXIT} is executed before the shell terminates. |
ccc6cda3 JA |
3433 | |
3434 | @item export | |
3435 | @btindex export | |
3436 | @example | |
3437 | export [-fn] [-p] [@var{name}[=@var{value}]] | |
3438 | @end example | |
ac50fbac | 3439 | |
ccc6cda3 | 3440 | Mark each @var{name} to be passed to child processes |
28ef6c31 | 3441 | in the environment. If the @option{-f} option is supplied, the @var{name}s |
cce855bc | 3442 | refer to shell functions; otherwise the names refer to shell variables. |
28ef6c31 JA |
3443 | The @option{-n} option means to no longer mark each @var{name} for export. |
3444 | If no @var{names} are supplied, or if the @option{-p} option is given, a | |
ac50fbac | 3445 | list of names of all exported variables is displayed. |
28ef6c31 | 3446 | The @option{-p} option displays output in a form that may be reused as input. |
b80f6443 JA |
3447 | If a variable name is followed by =@var{value}, the value of |
3448 | the variable is set to @var{value}. | |
3449 | ||
cce855bc | 3450 | The return status is zero unless an invalid option is supplied, one of |
28ef6c31 | 3451 | the names is not a valid shell variable name, or @option{-f} is supplied |
cce855bc | 3452 | with a name that is not a shell function. |
ccc6cda3 JA |
3453 | |
3454 | @item getopts | |
3455 | @btindex getopts | |
3456 | @example | |
3457 | getopts @var{optstring} @var{name} [@var{args}] | |
3458 | @end example | |
ac50fbac | 3459 | |
ccc6cda3 | 3460 | @code{getopts} is used by shell scripts to parse positional parameters. |
bb70624e JA |
3461 | @var{optstring} contains the option characters to be recognized; if a |
3462 | character is followed by a colon, the option is expected to have an | |
ac50fbac | 3463 | argument, which should be separated from it by whitespace. |
bb70624e JA |
3464 | The colon (@samp{:}) and question mark (@samp{?}) may not be |
3465 | used as option characters. | |
ccc6cda3 JA |
3466 | Each time it is invoked, @code{getopts} |
3467 | places the next option in the shell variable @var{name}, initializing | |
3468 | @var{name} if it does not exist, | |
3469 | and the index of the next argument to be processed into the | |
28ef6c31 JA |
3470 | variable @env{OPTIND}. |
3471 | @env{OPTIND} is initialized to 1 each time the shell or a shell script | |
cce855bc JA |
3472 | is invoked. |
3473 | When an option requires an argument, | |
28ef6c31 JA |
3474 | @code{getopts} places that argument into the variable @env{OPTARG}. |
3475 | The shell does not reset @env{OPTIND} automatically; it must be manually | |
cce855bc JA |
3476 | reset between multiple calls to @code{getopts} within the same shell |
3477 | invocation if a new set of parameters is to be used. | |
3478 | ||
3479 | When the end of options is encountered, @code{getopts} exits with a | |
3480 | return value greater than zero. | |
28ef6c31 | 3481 | @env{OPTIND} is set to the index of the first non-option argument, |
495aee44 | 3482 | and @var{name} is set to @samp{?}. |
cce855bc JA |
3483 | |
3484 | @code{getopts} | |
3485 | normally parses the positional parameters, but if more arguments are | |
3486 | given in @var{args}, @code{getopts} parses those instead. | |
ccc6cda3 JA |
3487 | |
3488 | @code{getopts} can report errors in two ways. If the first character of | |
3489 | @var{optstring} is a colon, @var{silent} | |
ac50fbac | 3490 | error reporting is used. In normal operation, diagnostic messages |
cce855bc | 3491 | are printed when invalid options or missing option arguments are |
ccc6cda3 | 3492 | encountered. |
28ef6c31 | 3493 | If the variable @env{OPTERR} |
cce855bc | 3494 | is set to 0, no error messages will be displayed, even if the first |
ccc6cda3 JA |
3495 | character of @code{optstring} is not a colon. |
3496 | ||
cce855bc | 3497 | If an invalid option is seen, |
ccc6cda3 | 3498 | @code{getopts} places @samp{?} into @var{name} and, if not silent, |
28ef6c31 | 3499 | prints an error message and unsets @env{OPTARG}. |
ccc6cda3 | 3500 | If @code{getopts} is silent, the option character found is placed in |
28ef6c31 | 3501 | @env{OPTARG} and no diagnostic message is printed. |
ccc6cda3 JA |
3502 | |
3503 | If a required argument is not found, and @code{getopts} | |
3504 | is not silent, a question mark (@samp{?}) is placed in @var{name}, | |
3505 | @code{OPTARG} is unset, and a diagnostic message is printed. | |
3506 | If @code{getopts} is silent, then a colon (@samp{:}) is placed in | |
28ef6c31 | 3507 | @var{name} and @env{OPTARG} is set to the option character found. |
ccc6cda3 | 3508 | |
ccc6cda3 JA |
3509 | @item hash |
3510 | @btindex hash | |
3511 | @example | |
0628567a | 3512 | hash [-r] [-p @var{filename}] [-dt] [@var{name}] |
ccc6cda3 | 3513 | @end example |
ac50fbac | 3514 | |
495aee44 CR |
3515 | Each time @code{hash} is invoked, it remembers the full pathnames of the |
3516 | commands specified as @var{name} arguments, | |
cce855bc JA |
3517 | so they need not be searched for on subsequent invocations. |
3518 | The commands are found by searching through the directories listed in | |
28ef6c31 | 3519 | @env{$PATH}. |
495aee44 | 3520 | Any previously-remembered pathname is discarded. |
28ef6c31 | 3521 | The @option{-p} option inhibits the path search, and @var{filename} is |
cce855bc | 3522 | used as the location of @var{name}. |
28ef6c31 | 3523 | The @option{-r} option causes the shell to forget all remembered locations. |
7117c2d2 JA |
3524 | The @option{-d} option causes the shell to forget the remembered location |
3525 | of each @var{name}. | |
f73dda09 JA |
3526 | If the @option{-t} option is supplied, the full pathname to which each |
3527 | @var{name} corresponds is printed. If multiple @var{name} arguments are | |
3528 | supplied with @option{-t} the @var{name} is printed before the hashed | |
3529 | full pathname. | |
7117c2d2 JA |
3530 | The @option{-l} option causes output to be displayed in a format |
3531 | that may be reused as input. | |
3532 | If no arguments are given, or if only @option{-l} is supplied, | |
3533 | information about remembered commands is printed. | |
cce855bc JA |
3534 | The return status is zero unless a @var{name} is not found or an invalid |
3535 | option is supplied. | |
ccc6cda3 JA |
3536 | |
3537 | @item pwd | |
3538 | @btindex pwd | |
3539 | @example | |
3540 | pwd [-LP] | |
3541 | @end example | |
ac50fbac | 3542 | |
bb70624e | 3543 | Print the absolute pathname of the current working directory. |
28ef6c31 | 3544 | If the @option{-P} option is supplied, the pathname printed will not |
cce855bc | 3545 | contain symbolic links. |
28ef6c31 | 3546 | If the @option{-L} option is supplied, the pathname printed may contain |
cce855bc JA |
3547 | symbolic links. |
3548 | The return status is zero unless an error is encountered while | |
3549 | determining the name of the current directory or an invalid option | |
3550 | is supplied. | |
ccc6cda3 JA |
3551 | |
3552 | @item readonly | |
3553 | @btindex readonly | |
3554 | @example | |
495aee44 | 3555 | readonly [-aAf] [-p] [@var{name}[=@var{value}]] @dots{} |
ccc6cda3 | 3556 | @end example |
ac50fbac | 3557 | |
cce855bc JA |
3558 | Mark each @var{name} as readonly. |
3559 | The values of these names may not be changed by subsequent assignment. | |
28ef6c31 | 3560 | If the @option{-f} option is supplied, each @var{name} refers to a shell |
cce855bc | 3561 | function. |
3185942a JA |
3562 | The @option{-a} option means each @var{name} refers to an indexed |
3563 | array variable; the @option{-A} option means each @var{name} refers | |
3564 | to an associative array variable. | |
495aee44 | 3565 | If both options are supplied, @option{-A} takes precedence. |
28ef6c31 | 3566 | If no @var{name} arguments are given, or if the @option{-p} |
ccc6cda3 | 3567 | option is supplied, a list of all readonly names is printed. |
495aee44 CR |
3568 | The other options may be used to restrict the output to a subset of |
3569 | the set of readonly names. | |
28ef6c31 | 3570 | The @option{-p} option causes output to be displayed in a format that |
cce855bc | 3571 | may be reused as input. |
b80f6443 JA |
3572 | If a variable name is followed by =@var{value}, the value of |
3573 | the variable is set to @var{value}. | |
cce855bc JA |
3574 | The return status is zero unless an invalid option is supplied, one of |
3575 | the @var{name} arguments is not a valid shell variable or function name, | |
28ef6c31 | 3576 | or the @option{-f} option is supplied with a name that is not a shell function. |
ccc6cda3 JA |
3577 | |
3578 | @item return | |
3579 | @btindex return | |
3580 | @example | |
3581 | return [@var{n}] | |
3582 | @end example | |
ac50fbac CR |
3583 | |
3584 | Cause a shell function to stop executing and return the value @var{n} | |
3585 | to its caller. | |
bb70624e JA |
3586 | If @var{n} is not supplied, the return value is the exit status of the |
3587 | last command executed in the function. | |
a0c0a00f CR |
3588 | If @code{return} is executed by a trap handler, the last command used to |
3589 | determine the status is the last command executed before the trap handler. | |
3590 | if @code{return} is executed during a @code{DEBUG} trap, the last command | |
3591 | used to determine the status is the last command executed by the trap | |
3592 | handler before @code{return} was invoked. | |
ac50fbac CR |
3593 | @code{return} may also be used to terminate execution of a script |
3594 | being executed with the @code{.} (@code{source}) builtin, | |
3595 | returning either @var{n} or | |
bb70624e JA |
3596 | the exit status of the last command executed within the script as the exit |
3597 | status of the script. | |
ac50fbac CR |
3598 | If @var{n} is supplied, the return value is its least significant |
3599 | 8 bits. | |
b80f6443 JA |
3600 | Any command associated with the @code{RETURN} trap is executed |
3601 | before execution resumes after the function or script. | |
ac50fbac CR |
3602 | The return status is non-zero if @code{return} is supplied a non-numeric |
3603 | argument or is used outside a function | |
bb70624e | 3604 | and not during the execution of a script by @code{.} or @code{source}. |
ccc6cda3 JA |
3605 | |
3606 | @item shift | |
3607 | @btindex shift | |
3608 | @example | |
3609 | shift [@var{n}] | |
3610 | @end example | |
ac50fbac | 3611 | |
cce855bc JA |
3612 | Shift the positional parameters to the left by @var{n}. |
3613 | The positional parameters from @var{n}+1 @dots{} @code{$#} are | |
3185942a JA |
3614 | renamed to @code{$1} @dots{} @code{$#}-@var{n}. |
3615 | Parameters represented by the numbers @code{$#} to @code{$#}-@var{n}+1 | |
3616 | are unset. | |
cce855bc JA |
3617 | @var{n} must be a non-negative number less than or equal to @code{$#}. |
3618 | If @var{n} is zero or greater than @code{$#}, the positional parameters | |
3619 | are not changed. | |
bb70624e | 3620 | If @var{n} is not supplied, it is assumed to be 1. |
cce855bc JA |
3621 | The return status is zero unless @var{n} is greater than @code{$#} or |
3622 | less than zero, non-zero otherwise. | |
ccc6cda3 JA |
3623 | |
3624 | @item test | |
3625 | @itemx [ | |
3626 | @btindex test | |
3627 | @btindex [ | |
ac50fbac CR |
3628 | @example |
3629 | test @var{expr} | |
3630 | @end example | |
3631 | ||
a0c0a00f | 3632 | Evaluate a conditional expression @var{expr} and return a status of 0 |
ac50fbac | 3633 | (true) or 1 (false). |
cce855bc JA |
3634 | Each operator and operand must be a separate argument. |
3635 | Expressions are composed of the primaries described below in | |
3636 | @ref{Bash Conditional Expressions}. | |
95732b49 JA |
3637 | @code{test} does not accept any options, nor does it accept and ignore |
3638 | an argument of @option{--} as signifying the end of options. | |
cce855bc | 3639 | |
bb70624e JA |
3640 | When the @code{[} form is used, the last argument to the command must |
3641 | be a @code{]}. | |
3642 | ||
cce855bc JA |
3643 | Expressions may be combined using the following operators, listed in |
3644 | decreasing order of precedence. | |
3185942a | 3645 | The evaluation depends on the number of arguments; see below. |
495aee44 | 3646 | Operator precedence is used when there are five or more arguments. |
cce855bc JA |
3647 | |
3648 | @table @code | |
3649 | @item ! @var{expr} | |
3650 | True if @var{expr} is false. | |
3651 | ||
3652 | @item ( @var{expr} ) | |
3653 | Returns the value of @var{expr}. | |
3654 | This may be used to override the normal precedence of operators. | |
3655 | ||
3656 | @item @var{expr1} -a @var{expr2} | |
3657 | True if both @var{expr1} and @var{expr2} are true. | |
3658 | ||
3659 | @item @var{expr1} -o @var{expr2} | |
3660 | True if either @var{expr1} or @var{expr2} is true. | |
3661 | @end table | |
3662 | ||
3663 | The @code{test} and @code{[} builtins evaluate conditional | |
3664 | expressions using a set of rules based on the number of arguments. | |
3665 | ||
3666 | @table @asis | |
3667 | @item 0 arguments | |
3668 | The expression is false. | |
3669 | ||
3670 | @item 1 argument | |
3671 | The expression is true if and only if the argument is not null. | |
3672 | ||
3673 | @item 2 arguments | |
3674 | If the first argument is @samp{!}, the expression is true if and | |
3675 | only if the second argument is null. | |
3676 | If the first argument is one of the unary conditional operators | |
3677 | (@pxref{Bash Conditional Expressions}), the expression | |
3678 | is true if the unary test is true. | |
3679 | If the first argument is not a valid unary operator, the expression is | |
3680 | false. | |
3681 | ||
3682 | @item 3 arguments | |
495aee44 | 3683 | The following conditions are applied in the order listed. |
cce855bc JA |
3684 | If the second argument is one of the binary conditional |
3685 | operators (@pxref{Bash Conditional Expressions}), the | |
3686 | result of the expression is the result of the binary test using the | |
3687 | first and third arguments as operands. | |
3185942a JA |
3688 | The @samp{-a} and @samp{-o} operators are considered binary operators |
3689 | when there are three arguments. | |
cce855bc JA |
3690 | If the first argument is @samp{!}, the value is the negation of |
3691 | the two-argument test using the second and third arguments. | |
3692 | If the first argument is exactly @samp{(} and the third argument is | |
3693 | exactly @samp{)}, the result is the one-argument test of the second | |
3694 | argument. | |
3695 | Otherwise, the expression is false. | |
cce855bc JA |
3696 | |
3697 | @item 4 arguments | |
3698 | If the first argument is @samp{!}, the result is the negation of | |
3699 | the three-argument expression composed of the remaining arguments. | |
a0c0a00f | 3700 | Otherwise, the expression is parsed and evaluated according to |
cce855bc JA |
3701 | precedence using the rules listed above. |
3702 | ||
3703 | @item 5 or more arguments | |
3704 | The expression is parsed and evaluated according to precedence | |
3705 | using the rules listed above. | |
3706 | @end table | |
ccc6cda3 | 3707 | |
495aee44 CR |
3708 | When used with @code{test} or @samp{[}, the @samp{<} and @samp{>} |
3709 | operators sort lexicographically using ASCII ordering. | |
3710 | ||
ccc6cda3 JA |
3711 | @item times |
3712 | @btindex times | |
3713 | @example | |
3714 | times | |
3715 | @end example | |
ac50fbac | 3716 | |
ccc6cda3 | 3717 | Print out the user and system times used by the shell and its children. |
cce855bc | 3718 | The return status is zero. |
ccc6cda3 JA |
3719 | |
3720 | @item trap | |
3721 | @btindex trap | |
3722 | @example | |
d166f048 | 3723 | trap [-lp] [@var{arg}] [@var{sigspec} @dots{}] |
ccc6cda3 | 3724 | @end example |
ac50fbac | 3725 | |
ccc6cda3 | 3726 | The commands in @var{arg} are to be read and executed when the |
b80f6443 JA |
3727 | shell receives signal @var{sigspec}. If @var{arg} is absent (and |
3728 | there is a single @var{sigspec}) or | |
3729 | equal to @samp{-}, each specified signal's disposition is reset | |
3730 | to the value it had when the shell was started. | |
d166f048 JA |
3731 | If @var{arg} is the null string, then the signal specified by |
3732 | each @var{sigspec} is ignored by the shell and commands it invokes. | |
28ef6c31 | 3733 | If @var{arg} is not present and @option{-p} has been supplied, |
bb70624e JA |
3734 | the shell displays the trap commands associated with each @var{sigspec}. |
3735 | If no arguments are supplied, or | |
28ef6c31 | 3736 | only @option{-p} is given, @code{trap} prints the list of commands |
cce855bc JA |
3737 | associated with each signal number in a form that may be reused as |
3738 | shell input. | |
b80f6443 JA |
3739 | The @option{-l} option causes the shell to print a list of signal names |
3740 | and their corresponding numbers. | |
3741 | Each @var{sigspec} is either a signal name or a signal number. | |
3742 | Signal names are case insensitive and the @code{SIG} prefix is optional. | |
0001803f | 3743 | |
d166f048 JA |
3744 | If a @var{sigspec} |
3745 | is @code{0} or @code{EXIT}, @var{arg} is executed when the shell exits. | |
3746 | If a @var{sigspec} is @code{DEBUG}, the command @var{arg} is executed | |
b80f6443 JA |
3747 | before every simple command, @code{for} command, @code{case} command, |
3748 | @code{select} command, every arithmetic @code{for} command, and before | |
3749 | the first command executes in a shell function. | |
0001803f | 3750 | Refer to the description of the @code{extdebug} option to the |
3185942a | 3751 | @code{shopt} builtin (@pxref{The Shopt Builtin}) for details of its |
b80f6443 | 3752 | effect on the @code{DEBUG} trap. |
0001803f CR |
3753 | If a @var{sigspec} is @code{RETURN}, the command @var{arg} is executed |
3754 | each time a shell function or a script executed with the @code{.} or | |
3755 | @code{source} builtins finishes executing. | |
3756 | ||
f73dda09 | 3757 | If a @var{sigspec} is @code{ERR}, the command @var{arg} |
ac50fbac CR |
3758 | is executed whenever |
3759 | a pipeline (which may consist of a single simple | |
a0c0a00f | 3760 | command), a list, or a compound command returns a |
ac50fbac | 3761 | non-zero exit status, |
b80f6443 JA |
3762 | subject to the following conditions. |
3763 | The @code{ERR} trap is not executed if the failed command is part of the | |
3764 | command list immediately following an @code{until} or @code{while} keyword, | |
17345e5a | 3765 | part of the test following the @code{if} or @code{elif} reserved words, |
ac50fbac CR |
3766 | part of a command executed in a @code{&&} or @code{||} list |
3767 | except the command following the final @code{&&} or @code{||}, | |
3768 | any command in a pipeline but the last, | |
3185942a | 3769 | or if the command's return |
f73dda09 | 3770 | status is being inverted using @code{!}. |
ac50fbac CR |
3771 | These are the same conditions obeyed by the @code{errexit} (@option{-e}) |
3772 | option. | |
ccc6cda3 JA |
3773 | |
3774 | Signals ignored upon entry to the shell cannot be trapped or reset. | |
0628567a | 3775 | Trapped signals that are not being ignored are reset to their original |
0001803f | 3776 | values in a subshell or subshell environment when one is created. |
ccc6cda3 | 3777 | |
cce855bc JA |
3778 | The return status is zero unless a @var{sigspec} does not specify a |
3779 | valid signal. | |
3780 | ||
ccc6cda3 JA |
3781 | @item umask |
3782 | @btindex umask | |
3783 | @example | |
cce855bc | 3784 | umask [-p] [-S] [@var{mode}] |
ccc6cda3 | 3785 | @end example |
ac50fbac | 3786 | |
ccc6cda3 JA |
3787 | Set the shell process's file creation mask to @var{mode}. If |
3788 | @var{mode} begins with a digit, it is interpreted as an octal number; | |
3789 | if not, it is interpreted as a symbolic mode mask similar | |
3790 | to that accepted by the @code{chmod} command. If @var{mode} is | |
28ef6c31 | 3791 | omitted, the current value of the mask is printed. If the @option{-S} |
ccc6cda3 JA |
3792 | option is supplied without a @var{mode} argument, the mask is printed |
3793 | in a symbolic format. | |
28ef6c31 | 3794 | If the @option{-p} option is supplied, and @var{mode} |
cce855bc JA |
3795 | is omitted, the output is in a form that may be reused as input. |
3796 | The return status is zero if the mode is successfully changed or if | |
3797 | no @var{mode} argument is supplied, and non-zero otherwise. | |
ccc6cda3 | 3798 | |
bb70624e JA |
3799 | Note that when the mode is interpreted as an octal number, each number |
3800 | of the umask is subtracted from @code{7}. Thus, a umask of @code{022} | |
3801 | results in permissions of @code{755}. | |
3802 | ||
ccc6cda3 JA |
3803 | @item unset |
3804 | @btindex unset | |
3805 | @example | |
ac50fbac | 3806 | unset [-fnv] [@var{name}] |
ccc6cda3 | 3807 | @end example |
ac50fbac CR |
3808 | |
3809 | Remove each variable or function @var{name}. | |
3810 | If the @option{-v} option is given, each | |
a0c0a00f | 3811 | @var{name} refers to a shell variable and that variable is removed. |
28ef6c31 | 3812 | If the @option{-f} option is given, the @var{name}s refer to shell |
ccc6cda3 | 3813 | functions, and the function definition is removed. |
ac50fbac CR |
3814 | If the @option{-n} option is supplied, and @var{name} is a variable with |
3815 | the @var{nameref} attribute, @var{name} will be unset rather than the | |
3816 | variable it references. | |
3817 | @option{-n} has no effect if the @option{-f} option is supplied. | |
3818 | If no options are supplied, each @var{name} refers to a variable; if | |
3819 | there is no variable by that name, any function with that name is | |
3820 | unset. | |
cce855bc | 3821 | Readonly variables and functions may not be unset. |
b80f6443 | 3822 | The return status is zero unless a @var{name} is readonly. |
ccc6cda3 JA |
3823 | @end table |
3824 | ||
bb70624e JA |
3825 | @node Bash Builtins |
3826 | @section Bash Builtin Commands | |
ccc6cda3 | 3827 | |
bb70624e JA |
3828 | This section describes builtin commands which are unique to |
3829 | or have been extended in Bash. | |
0628567a | 3830 | Some of these commands are specified in the @sc{posix} standard. |
ccc6cda3 | 3831 | |
bb70624e | 3832 | @table @code |
ccc6cda3 | 3833 | |
bb70624e JA |
3834 | @item alias |
3835 | @btindex alias | |
3836 | @example | |
ac50fbac | 3837 | alias [-p] [@var{name}[=@var{value}] @dots{}] |
bb70624e | 3838 | @end example |
ccc6cda3 | 3839 | |
28ef6c31 | 3840 | Without arguments or with the @option{-p} option, @code{alias} prints |
bb70624e JA |
3841 | the list of aliases on the standard output in a form that allows |
3842 | them to be reused as input. | |
3843 | If arguments are supplied, an alias is defined for each @var{name} | |
3844 | whose @var{value} is given. If no @var{value} is given, the name | |
3845 | and value of the alias is printed. | |
3846 | Aliases are described in @ref{Aliases}. | |
ccc6cda3 | 3847 | |
bb70624e JA |
3848 | @item bind |
3849 | @btindex bind | |
3850 | @example | |
ac50fbac | 3851 | bind [-m @var{keymap}] [-lpsvPSVX] |
bb70624e JA |
3852 | bind [-m @var{keymap}] [-q @var{function}] [-u @var{function}] [-r @var{keyseq}] |
3853 | bind [-m @var{keymap}] -f @var{filename} | |
3854 | bind [-m @var{keymap}] -x @var{keyseq:shell-command} | |
3855 | bind [-m @var{keymap}] @var{keyseq:function-name} | |
a0c0a00f | 3856 | bind [-m @var{keymap}] @var{keyseq:readline-command} |
bb70624e | 3857 | @end example |
ccc6cda3 | 3858 | |
bb70624e | 3859 | Display current Readline (@pxref{Command Line Editing}) |
7117c2d2 JA |
3860 | key and function bindings, |
3861 | bind a key sequence to a Readline function or macro, | |
3862 | or set a Readline variable. | |
3863 | Each non-option argument is a command as it would appear in a | |
3185942a | 3864 | Readline initialization file (@pxref{Readline Init File}), |
7117c2d2 | 3865 | but each binding or command must be passed as a separate argument; e.g., |
bb70624e | 3866 | @samp{"\C-x\C-r":re-read-init-file}. |
3185942a | 3867 | |
bb70624e | 3868 | Options, if supplied, have the following meanings: |
cce855bc | 3869 | |
bb70624e JA |
3870 | @table @code |
3871 | @item -m @var{keymap} | |
3872 | Use @var{keymap} as the keymap to be affected by | |
3873 | the subsequent bindings. Acceptable @var{keymap} | |
3874 | names are | |
3875 | @code{emacs}, | |
3876 | @code{emacs-standard}, | |
3877 | @code{emacs-meta}, | |
3878 | @code{emacs-ctlx}, | |
3879 | @code{vi}, | |
28ef6c31 | 3880 | @code{vi-move}, |
bb70624e JA |
3881 | @code{vi-command}, and |
3882 | @code{vi-insert}. | |
a0c0a00f CR |
3883 | @code{vi} is equivalent to @code{vi-command} (@code{vi-move} is also a |
3884 | synonym); @code{emacs} is equivalent to @code{emacs-standard}. | |
cce855bc | 3885 | |
bb70624e JA |
3886 | @item -l |
3887 | List the names of all Readline functions. | |
cce855bc | 3888 | |
bb70624e JA |
3889 | @item -p |
3890 | Display Readline function names and bindings in such a way that they | |
3891 | can be used as input or in a Readline initialization file. | |
cce855bc | 3892 | |
bb70624e JA |
3893 | @item -P |
3894 | List current Readline function names and bindings. | |
ccc6cda3 | 3895 | |
bb70624e JA |
3896 | @item -v |
3897 | Display Readline variable names and values in such a way that they | |
3898 | can be used as input or in a Readline initialization file. | |
ccc6cda3 | 3899 | |
bb70624e JA |
3900 | @item -V |
3901 | List current Readline variable names and values. | |
ccc6cda3 | 3902 | |
bb70624e JA |
3903 | @item -s |
3904 | Display Readline key sequences bound to macros and the strings they output | |
3905 | in such a way that they can be used as input or in a Readline | |
3906 | initialization file. | |
ccc6cda3 | 3907 | |
bb70624e JA |
3908 | @item -S |
3909 | Display Readline key sequences bound to macros and the strings they output. | |
ccc6cda3 | 3910 | |
bb70624e JA |
3911 | @item -f @var{filename} |
3912 | Read key bindings from @var{filename}. | |
ccc6cda3 | 3913 | |
bb70624e JA |
3914 | @item -q @var{function} |
3915 | Query about which keys invoke the named @var{function}. | |
ccc6cda3 | 3916 | |
bb70624e JA |
3917 | @item -u @var{function} |
3918 | Unbind all keys bound to the named @var{function}. | |
cce855bc | 3919 | |
bb70624e JA |
3920 | @item -r @var{keyseq} |
3921 | Remove any current binding for @var{keyseq}. | |
ccc6cda3 | 3922 | |
bb70624e JA |
3923 | @item -x @var{keyseq:shell-command} |
3924 | Cause @var{shell-command} to be executed whenever @var{keyseq} is | |
3925 | entered. | |
3185942a JA |
3926 | When @var{shell-command} is executed, the shell sets the |
3927 | @code{READLINE_LINE} variable to the contents of the Readline line | |
3928 | buffer and the @code{READLINE_POINT} variable to the current location | |
3929 | of the insertion point. | |
3930 | If the executed command changes the value of @code{READLINE_LINE} or | |
3931 | @code{READLINE_POINT}, those new values will be reflected in the | |
3932 | editing state. | |
ac50fbac CR |
3933 | |
3934 | @item -X | |
3935 | List all key sequences bound to shell commands and the associated commands | |
3936 | in a format that can be reused as input. | |
bb70624e | 3937 | @end table |
ccc6cda3 | 3938 | |
bb70624e JA |
3939 | @noindent |
3940 | The return status is zero unless an invalid option is supplied or an | |
3941 | error occurs. | |
ccc6cda3 | 3942 | |
bb70624e JA |
3943 | @item builtin |
3944 | @btindex builtin | |
3945 | @example | |
3946 | builtin [@var{shell-builtin} [@var{args}]] | |
3947 | @end example | |
ac50fbac | 3948 | |
bb70624e JA |
3949 | Run a shell builtin, passing it @var{args}, and return its exit status. |
3950 | This is useful when defining a shell function with the same | |
3951 | name as a shell builtin, retaining the functionality of the builtin within | |
3952 | the function. | |
3953 | The return status is non-zero if @var{shell-builtin} is not a shell | |
3954 | builtin command. | |
ccc6cda3 | 3955 | |
b80f6443 JA |
3956 | @item caller |
3957 | @btindex caller | |
3958 | @example | |
3959 | caller [@var{expr}] | |
3960 | @end example | |
ac50fbac | 3961 | |
b80f6443 JA |
3962 | Returns the context of any active subroutine call (a shell function or |
3963 | a script executed with the @code{.} or @code{source} builtins). | |
3964 | ||
3965 | Without @var{expr}, @code{caller} displays the line number and source | |
3966 | filename of the current subroutine call. | |
a0c0a00f | 3967 | If a non-negative integer is supplied as @var{expr}, @code{caller} |
b80f6443 JA |
3968 | displays the line number, subroutine name, and source file corresponding |
3969 | to that position in the current execution call stack. This extra | |
3970 | information may be used, for example, to print a stack trace. The | |
3971 | current frame is frame 0. | |
3972 | ||
3973 | The return value is 0 unless the shell is not executing a subroutine | |
3974 | call or @var{expr} does not correspond to a valid position in the | |
3975 | call stack. | |
3976 | ||
bb70624e JA |
3977 | @item command |
3978 | @btindex command | |
3979 | @example | |
3980 | command [-pVv] @var{command} [@var{arguments} @dots{}] | |
3981 | @end example | |
ac50fbac | 3982 | |
bb70624e JA |
3983 | Runs @var{command} with @var{arguments} ignoring any shell function |
3984 | named @var{command}. | |
3985 | Only shell builtin commands or commands found by searching the | |
28ef6c31 | 3986 | @env{PATH} are executed. |
bb70624e JA |
3987 | If there is a shell function named @code{ls}, running @samp{command ls} |
3988 | within the function will execute the external command @code{ls} | |
3989 | instead of calling the function recursively. | |
28ef6c31 | 3990 | The @option{-p} option means to use a default value for @env{PATH} |
bb70624e JA |
3991 | that is guaranteed to find all of the standard utilities. |
3992 | The return status in this case is 127 if @var{command} cannot be | |
3993 | found or an error occurred, and the exit status of @var{command} | |
3994 | otherwise. | |
cce855bc | 3995 | |
28ef6c31 JA |
3996 | If either the @option{-V} or @option{-v} option is supplied, a |
3997 | description of @var{command} is printed. The @option{-v} option | |
bb70624e | 3998 | causes a single word indicating the command or file name used to |
28ef6c31 | 3999 | invoke @var{command} to be displayed; the @option{-V} option produces |
bb70624e JA |
4000 | a more verbose description. In this case, the return status is |
4001 | zero if @var{command} is found, and non-zero if not. | |
cce855bc | 4002 | |
bb70624e JA |
4003 | @item declare |
4004 | @btindex declare | |
4005 | @example | |
ac50fbac | 4006 | declare [-aAfFgilnrtux] [-p] [@var{name}[=@var{value}] @dots{}] |
bb70624e | 4007 | @end example |
ccc6cda3 | 4008 | |
bb70624e JA |
4009 | Declare variables and give them attributes. If no @var{name}s |
4010 | are given, then display the values of variables instead. | |
ccc6cda3 | 4011 | |
28ef6c31 | 4012 | The @option{-p} option will display the attributes and values of each |
b80f6443 | 4013 | @var{name}. |
ac50fbac CR |
4014 | When @option{-p} is used with @var{name} arguments, additional options, |
4015 | other than @option{-f} and @option{-F}, are ignored. | |
3185942a JA |
4016 | |
4017 | When @option{-p} is supplied without @var{name} arguments, @code{declare} | |
4018 | will display the attributes and values of all variables having the | |
4019 | attributes specified by the additional options. | |
4020 | If no other options are supplied with @option{-p}, @code{declare} will | |
4021 | display the attributes and values of all shell variables. The @option{-f} | |
4022 | option will restrict the display to shell functions. | |
4023 | ||
28ef6c31 | 4024 | The @option{-F} option inhibits the display of function definitions; |
b80f6443 JA |
4025 | only the function name and attributes are printed. |
4026 | If the @code{extdebug} shell option is enabled using @code{shopt} | |
3185942a | 4027 | (@pxref{The Shopt Builtin}), the source file name and line number where |
a0c0a00f | 4028 | each @var{name} is defined are displayed as well. |
b80f6443 | 4029 | @option{-F} implies @option{-f}. |
495aee44 CR |
4030 | |
4031 | The @option{-g} option forces variables to be created or modified at | |
4032 | the global scope, even when @code{declare} is executed in a shell function. | |
4033 | It is ignored in all other cases. | |
4034 | ||
b80f6443 JA |
4035 | The following options can be used to restrict output to variables with |
4036 | the specified attributes or to give variables attributes: | |
cce855bc | 4037 | |
bb70624e JA |
4038 | @table @code |
4039 | @item -a | |
3185942a JA |
4040 | Each @var{name} is an indexed array variable (@pxref{Arrays}). |
4041 | ||
4042 | @item -A | |
4043 | Each @var{name} is an associative array variable (@pxref{Arrays}). | |
cce855bc | 4044 | |
bb70624e JA |
4045 | @item -f |
4046 | Use function names only. | |
ccc6cda3 | 4047 | |
bb70624e JA |
4048 | @item -i |
4049 | The variable is to be treated as | |
4050 | an integer; arithmetic evaluation (@pxref{Shell Arithmetic}) is | |
4051 | performed when the variable is assigned a value. | |
ccc6cda3 | 4052 | |
3185942a JA |
4053 | @item -l |
4054 | When the variable is assigned a value, all upper-case characters are | |
4055 | converted to lower-case. | |
4056 | The upper-case attribute is disabled. | |
4057 | ||
ac50fbac CR |
4058 | @item -n |
4059 | Give each @var{name} the @var{nameref} attribute, making | |
4060 | it a name reference to another variable. | |
4061 | That other variable is defined by the value of @var{name}. | |
a0c0a00f CR |
4062 | All references, assignments, and attribute modifications |
4063 | to @var{name}, except for those using or changing the | |
ac50fbac CR |
4064 | @option{-n} attribute itself, are performed on the variable referenced by |
4065 | @var{name}'s value. | |
a0c0a00f | 4066 | The nameref attribute cannot be applied to array variables. |
ac50fbac | 4067 | |
bb70624e JA |
4068 | @item -r |
4069 | Make @var{name}s readonly. These names cannot then be assigned values | |
4070 | by subsequent assignment statements or unset. | |
ccc6cda3 | 4071 | |
7117c2d2 JA |
4072 | @item -t |
4073 | Give each @var{name} the @code{trace} attribute. | |
95732b49 JA |
4074 | Traced functions inherit the @code{DEBUG} and @code{RETURN} traps from |
4075 | the calling shell. | |
7117c2d2 JA |
4076 | The trace attribute has no special meaning for variables. |
4077 | ||
3185942a JA |
4078 | @item -u |
4079 | When the variable is assigned a value, all lower-case characters are | |
4080 | converted to upper-case. | |
4081 | The lower-case attribute is disabled. | |
4082 | ||
bb70624e JA |
4083 | @item -x |
4084 | Mark each @var{name} for export to subsequent commands via | |
4085 | the environment. | |
4086 | @end table | |
ccc6cda3 | 4087 | |
3185942a JA |
4088 | Using @samp{+} instead of @samp{-} turns off the attribute instead, |
4089 | with the exceptions that @samp{+a} | |
4090 | may not be used to destroy an array variable and @samp{+r} will not | |
4091 | remove the readonly attribute. | |
bb70624e | 4092 | When used in a function, @code{declare} makes each @var{name} local, |
ac50fbac | 4093 | as with the @code{local} command, unless the @option{-g} option is used. |
495aee44 CR |
4094 | If a variable name is followed by =@var{value}, the value of the variable |
4095 | is set to @var{value}. | |
ccc6cda3 | 4096 | |
ac50fbac CR |
4097 | When using @option{-a} or @option{-A} and the compound assignment syntax to |
4098 | create array variables, additional attributes do not take effect until | |
4099 | subsequent assignments. | |
4100 | ||
bb70624e JA |
4101 | The return status is zero unless an invalid option is encountered, |
4102 | an attempt is made to define a function using @samp{-f foo=bar}, | |
4103 | an attempt is made to assign a value to a readonly variable, | |
4104 | an attempt is made to assign a value to an array variable without | |
4105 | using the compound assignment syntax (@pxref{Arrays}), | |
4106 | one of the @var{names} is not a valid shell variable name, | |
4107 | an attempt is made to turn off readonly status for a readonly variable, | |
4108 | an attempt is made to turn off array status for an array variable, | |
28ef6c31 | 4109 | or an attempt is made to display a non-existent function with @option{-f}. |
ccc6cda3 | 4110 | |
bb70624e JA |
4111 | @item echo |
4112 | @btindex echo | |
4113 | @example | |
4114 | echo [-neE] [@var{arg} @dots{}] | |
4115 | @end example | |
ac50fbac | 4116 | |
bb70624e JA |
4117 | Output the @var{arg}s, separated by spaces, terminated with a |
4118 | newline. | |
ac50fbac | 4119 | The return status is 0 unless a write error occurs. |
28ef6c31 JA |
4120 | If @option{-n} is specified, the trailing newline is suppressed. |
4121 | If the @option{-e} option is given, interpretation of the following | |
bb70624e | 4122 | backslash-escaped characters is enabled. |
28ef6c31 | 4123 | The @option{-E} option disables the interpretation of these escape characters, |
bb70624e JA |
4124 | even on systems where they are interpreted by default. |
4125 | The @code{xpg_echo} shell option may be used to | |
4126 | dynamically determine whether or not @code{echo} expands these | |
4127 | escape characters by default. | |
95732b49 JA |
4128 | @code{echo} does not interpret @option{--} to mean the end of options. |
4129 | ||
bb70624e JA |
4130 | @code{echo} interprets the following escape sequences: |
4131 | @table @code | |
4132 | @item \a | |
4133 | alert (bell) | |
4134 | @item \b | |
4135 | backspace | |
4136 | @item \c | |
3185942a | 4137 | suppress further output |
bb70624e | 4138 | @item \e |
495aee44 | 4139 | @itemx \E |
bb70624e JA |
4140 | escape |
4141 | @item \f | |
4142 | form feed | |
4143 | @item \n | |
4144 | new line | |
4145 | @item \r | |
4146 | carriage return | |
4147 | @item \t | |
4148 | horizontal tab | |
4149 | @item \v | |
4150 | vertical tab | |
4151 | @item \\ | |
4152 | backslash | |
7117c2d2 JA |
4153 | @item \0@var{nnn} |
4154 | the eight-bit character whose value is the octal value @var{nnn} | |
4155 | (zero to three octal digits) | |
f73dda09 JA |
4156 | @item \x@var{HH} |
4157 | the eight-bit character whose value is the hexadecimal value @var{HH} | |
4158 | (one or two hex digits) | |
495aee44 CR |
4159 | @item \u@var{HHHH} |
4160 | the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value | |
4161 | @var{HHHH} (one to four hex digits) | |
4162 | @item \U@var{HHHHHHHH} | |
4163 | the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value | |
4164 | @var{HHHHHHHH} (one to eight hex digits) | |
bb70624e | 4165 | @end table |
ccc6cda3 | 4166 | |
bb70624e JA |
4167 | @item enable |
4168 | @btindex enable | |
4169 | @example | |
3185942a | 4170 | enable [-a] [-dnps] [-f @var{filename}] [@var{name} @dots{}] |
bb70624e | 4171 | @end example |
ac50fbac | 4172 | |
bb70624e JA |
4173 | Enable and disable builtin shell commands. |
4174 | Disabling a builtin allows a disk command which has the same name | |
4175 | as a shell builtin to be executed without specifying a full pathname, | |
4176 | even though the shell normally searches for builtins before disk commands. | |
28ef6c31 | 4177 | If @option{-n} is used, the @var{name}s become disabled. Otherwise |
bb70624e | 4178 | @var{name}s are enabled. For example, to use the @code{test} binary |
28ef6c31 | 4179 | found via @env{$PATH} instead of the shell builtin version, type |
bb70624e | 4180 | @samp{enable -n test}. |
ccc6cda3 | 4181 | |
28ef6c31 | 4182 | If the @option{-p} option is supplied, or no @var{name} arguments appear, |
bb70624e JA |
4183 | a list of shell builtins is printed. With no other arguments, the list |
4184 | consists of all enabled shell builtins. | |
28ef6c31 | 4185 | The @option{-a} option means to list |
bb70624e | 4186 | each builtin with an indication of whether or not it is enabled. |
ccc6cda3 | 4187 | |
28ef6c31 | 4188 | The @option{-f} option means to load the new builtin command @var{name} |
bb70624e | 4189 | from shared object @var{filename}, on systems that support dynamic loading. |
28ef6c31 | 4190 | The @option{-d} option will delete a builtin loaded with @option{-f}. |
ccc6cda3 | 4191 | |
bb70624e | 4192 | If there are no options, a list of the shell builtins is displayed. |
28ef6c31 JA |
4193 | The @option{-s} option restricts @code{enable} to the @sc{posix} special |
4194 | builtins. If @option{-s} is used with @option{-f}, the new builtin becomes | |
bb70624e | 4195 | a special builtin (@pxref{Special Builtins}). |
ccc6cda3 | 4196 | |
bb70624e JA |
4197 | The return status is zero unless a @var{name} is not a shell builtin |
4198 | or there is an error loading a new builtin from a shared object. | |
cce855bc | 4199 | |
bb70624e JA |
4200 | @item help |
4201 | @btindex help | |
4202 | @example | |
3185942a | 4203 | help [-dms] [@var{pattern}] |
bb70624e | 4204 | @end example |
ac50fbac | 4205 | |
bb70624e JA |
4206 | Display helpful information about builtin commands. |
4207 | If @var{pattern} is specified, @code{help} gives detailed help | |
4208 | on all commands matching @var{pattern}, otherwise a list of | |
4209 | the builtins is printed. | |
3185942a JA |
4210 | |
4211 | Options, if supplied, have the following meanings: | |
4212 | ||
4213 | @table @code | |
4214 | @item -d | |
4215 | Display a short description of each @var{pattern} | |
4216 | @item -m | |
4217 | Display the description of each @var{pattern} in a manpage-like format | |
4218 | @item -s | |
4219 | Display only a short usage synopsis for each @var{pattern} | |
4220 | @end table | |
4221 | ||
bb70624e | 4222 | The return status is zero unless no command matches @var{pattern}. |
ccc6cda3 | 4223 | |
bb70624e JA |
4224 | @item let |
4225 | @btindex let | |
4226 | @example | |
ac50fbac | 4227 | let @var{expression} [@var{expression} @dots{}] |
bb70624e | 4228 | @end example |
ac50fbac | 4229 | |
bb70624e JA |
4230 | The @code{let} builtin allows arithmetic to be performed on shell |
4231 | variables. Each @var{expression} is evaluated according to the | |
4232 | rules given below in @ref{Shell Arithmetic}. If the | |
4233 | last @var{expression} evaluates to 0, @code{let} returns 1; | |
4234 | otherwise 0 is returned. | |
ccc6cda3 | 4235 | |
bb70624e JA |
4236 | @item local |
4237 | @btindex local | |
4238 | @example | |
b80f6443 | 4239 | local [@var{option}] @var{name}[=@var{value}] @dots{} |
bb70624e | 4240 | @end example |
ac50fbac | 4241 | |
bb70624e JA |
4242 | For each argument, a local variable named @var{name} is created, |
4243 | and assigned @var{value}. | |
4244 | The @var{option} can be any of the options accepted by @code{declare}. | |
4245 | @code{local} can only be used within a function; it makes the variable | |
4246 | @var{name} have a visible scope restricted to that function and its | |
a0c0a00f CR |
4247 | children. |
4248 | If @var{name} is @samp{-}, the set of shell options is made local to the | |
4249 | function in which @code{local} is invoked: shell options changed using | |
4250 | the @code{set} builtin inside the function are restored to their original | |
4251 | values when the function returns. | |
4252 | The return status is zero unless @code{local} is used outside | |
bb70624e JA |
4253 | a function, an invalid @var{name} is supplied, or @var{name} is a |
4254 | readonly variable. | |
ccc6cda3 | 4255 | |
bb70624e JA |
4256 | @item logout |
4257 | @btindex logout | |
4258 | @example | |
4259 | logout [@var{n}] | |
4260 | @end example | |
ac50fbac | 4261 | |
bb70624e JA |
4262 | Exit a login shell, returning a status of @var{n} to the shell's |
4263 | parent. | |
cce855bc | 4264 | |
3185942a JA |
4265 | @item mapfile |
4266 | @btindex mapfile | |
4267 | @example | |
a0c0a00f | 4268 | mapfile [-d @var{delim}] [-n @var{count}] [-O @var{origin}] [-s @var{count}] [-t] [-u @var{fd}] |
ac50fbac | 4269 | [-C @var{callback}] [-c @var{quantum}] [@var{array}] |
3185942a | 4270 | @end example |
ac50fbac | 4271 | |
0001803f | 4272 | Read lines from the standard input into the indexed array variable @var{array}, |
3185942a JA |
4273 | or from file descriptor @var{fd} |
4274 | if the @option{-u} option is supplied. | |
4275 | The variable @code{MAPFILE} is the default @var{array}. | |
4276 | Options, if supplied, have the following meanings: | |
ac50fbac | 4277 | |
3185942a JA |
4278 | @table @code |
4279 | ||
a0c0a00f CR |
4280 | @item -d |
4281 | The first character of @var{delim} is used to terminate each input line, | |
4282 | rather than newline. | |
3185942a JA |
4283 | @item -n |
4284 | Copy at most @var{count} lines. If @var{count} is 0, all lines are copied. | |
4285 | @item -O | |
4286 | Begin assigning to @var{array} at index @var{origin}. | |
4287 | The default index is 0. | |
4288 | @item -s | |
4289 | Discard the first @var{count} lines read. | |
4290 | @item -t | |
a0c0a00f | 4291 | Remove a trailing @var{delim} (default newline) from each line read. |
3185942a JA |
4292 | @item -u |
4293 | Read lines from file descriptor @var{fd} instead of the standard input. | |
4294 | @item -C | |
4295 | Evaluate @var{callback} each time @var{quantum}P lines are read. | |
4296 | The @option{-c} option specifies @var{quantum}. | |
4297 | @item -c | |
4298 | Specify the number of lines read between each call to @var{callback}. | |
4299 | @end table | |
4300 | ||
a0c0a00f | 4301 | If @option{-C} is specified without @option{-c}, |
3185942a | 4302 | the default quantum is 5000. |
17345e5a | 4303 | When @var{callback} is evaluated, it is supplied the index of the next |
495aee44 CR |
4304 | array element to be assigned and the line to be assigned to that element |
4305 | as additional arguments. | |
a0c0a00f | 4306 | @var{callback} is evaluated after the line is read but before the |
17345e5a | 4307 | array element is assigned. |
3185942a JA |
4308 | |
4309 | If not supplied with an explicit origin, @code{mapfile} will clear @var{array} | |
4310 | before assigning to it. | |
4311 | ||
4312 | @code{mapfile} returns successfully unless an invalid option or option | |
0001803f CR |
4313 | argument is supplied, @var{array} is invalid or unassignable, or @var{array} |
4314 | is not an indexed array. | |
3185942a | 4315 | |
bb70624e JA |
4316 | @item printf |
4317 | @btindex printf | |
4318 | @example | |
3185942a | 4319 | printf [-v @var{var}] @var{format} [@var{arguments}] |
bb70624e | 4320 | @end example |
ac50fbac | 4321 | |
bb70624e JA |
4322 | Write the formatted @var{arguments} to the standard output under the |
4323 | control of the @var{format}. | |
495aee44 CR |
4324 | The @option{-v} option causes the output to be assigned to the variable |
4325 | @var{var} rather than being printed to the standard output. | |
4326 | ||
bb70624e JA |
4327 | The @var{format} is a character string which contains three types of objects: |
4328 | plain characters, which are simply copied to standard output, character | |
4329 | escape sequences, which are converted and copied to the standard output, and | |
4330 | format specifications, each of which causes printing of the next successive | |
4331 | @var{argument}. | |
495aee44 CR |
4332 | In addition to the standard @code{printf(1)} formats, @code{printf} |
4333 | interprets the following extensions: | |
4334 | ||
4335 | @table @code | |
4336 | @item %b | |
ac50fbac | 4337 | Causes @code{printf} to expand backslash escape sequences in the |
a0c0a00f CR |
4338 | corresponding @var{argument} in the same way as @code{echo -e} |
4339 | (@pxref{Bash Builtins}). | |
495aee44 | 4340 | @item %q |
ac50fbac | 4341 | Causes @code{printf} to output the |
bb70624e | 4342 | corresponding @var{argument} in a format that can be reused as shell input. |
495aee44 | 4343 | @item %(@var{datefmt})T |
ac50fbac CR |
4344 | Causes @code{printf} to output the date-time string resulting from using |
4345 | @var{datefmt} as a format string for @code{strftime}(3). | |
4346 | The corresponding @var{argument} is an integer representing the number of | |
4347 | seconds since the epoch. | |
4348 | Two special argument values may be used: -1 represents the current | |
495aee44 | 4349 | time, and -2 represents the time the shell was invoked. |
ac50fbac CR |
4350 | If no argument is specified, conversion behaves as if -1 had been given. |
4351 | This is an exception to the usual @code{printf} behavior. | |
495aee44 | 4352 | @end table |
cce855bc | 4353 | |
495aee44 CR |
4354 | @noindent |
4355 | Arguments to non-string format specifiers are treated as C language constants, | |
4356 | except that a leading plus or minus sign is allowed, and if the leading | |
4357 | character is a single or double quote, the value is the ASCII value of | |
4358 | the following character. | |
95732b49 | 4359 | |
bb70624e JA |
4360 | The @var{format} is reused as necessary to consume all of the @var{arguments}. |
4361 | If the @var{format} requires more @var{arguments} than are supplied, the | |
4362 | extra format specifications behave as if a zero value or null string, as | |
4363 | appropriate, had been supplied. The return value is zero on success, | |
4364 | non-zero on failure. | |
ccc6cda3 | 4365 | |
bb70624e JA |
4366 | @item read |
4367 | @btindex read | |
4368 | @example | |
ac50fbac CR |
4369 | read [-ers] [-a @var{aname}] [-d @var{delim}] [-i @var{text}] [-n @var{nchars}] |
4370 | [-N @var{nchars}] [-p @var{prompt}] [-t @var{timeout}] [-u @var{fd}] [@var{name} @dots{}] | |
bb70624e | 4371 | @end example |
ac50fbac | 4372 | |
7117c2d2 | 4373 | One line is read from the standard input, or from the file descriptor |
a0c0a00f CR |
4374 | @var{fd} supplied as an argument to the @option{-u} option, |
4375 | split into words as described above in @ref{Word Splitting}, | |
4376 | and the first word | |
bb70624e | 4377 | is assigned to the first @var{name}, the second word to the second @var{name}, |
a0c0a00f CR |
4378 | and so on. |
4379 | If there are more words than names, | |
4380 | the remaining words and their intervening delimiters are assigned | |
bb70624e | 4381 | to the last @var{name}. |
7117c2d2 | 4382 | If there are fewer words read from the input stream than names, |
bb70624e | 4383 | the remaining names are assigned empty values. |
28ef6c31 | 4384 | The characters in the value of the @env{IFS} variable |
ac50fbac CR |
4385 | are used to split the line into words using the same rules the shell |
4386 | uses for expansion (described above in @ref{Word Splitting}). | |
bb70624e JA |
4387 | The backslash character @samp{\} may be used to remove any special |
4388 | meaning for the next character read and for line continuation. | |
4389 | If no names are supplied, the line read is assigned to the | |
28ef6c31 | 4390 | variable @env{REPLY}. |
a0c0a00f CR |
4391 | The exit status is zero, unless end-of-file is encountered, @code{read} |
4392 | times out (in which case the status is greater than 128), | |
ac50fbac CR |
4393 | a variable assignment error (such as assigning to a readonly variable) occurs, |
4394 | or an invalid file descriptor is supplied as the argument to @option{-u}. | |
3185942a | 4395 | |
bb70624e | 4396 | Options, if supplied, have the following meanings: |
ccc6cda3 | 4397 | |
bb70624e JA |
4398 | @table @code |
4399 | @item -a @var{aname} | |
4400 | The words are assigned to sequential indices of the array variable | |
4401 | @var{aname}, starting at 0. | |
4402 | All elements are removed from @var{aname} before the assignment. | |
4403 | Other @var{name} arguments are ignored. | |
ccc6cda3 | 4404 | |
bb70624e JA |
4405 | @item -d @var{delim} |
4406 | The first character of @var{delim} is used to terminate the input line, | |
4407 | rather than newline. | |
ccc6cda3 | 4408 | |
bb70624e JA |
4409 | @item -e |
4410 | Readline (@pxref{Command Line Editing}) is used to obtain the line. | |
3185942a JA |
4411 | Readline uses the current (or default, if line editing was not previously |
4412 | active) editing settings. | |
4413 | ||
4414 | @item -i @var{text} | |
4415 | If Readline is being used to read the line, @var{text} is placed into | |
4416 | the editing buffer before editing begins. | |
ccc6cda3 | 4417 | |
bb70624e JA |
4418 | @item -n @var{nchars} |
4419 | @code{read} returns after reading @var{nchars} characters rather than | |
a0c0a00f | 4420 | waiting for a complete line of input, but honors a delimiter if fewer |
0001803f CR |
4421 | than @var{nchars} characters are read before the delimiter. |
4422 | ||
4423 | @item -N @var{nchars} | |
4424 | @code{read} returns after reading exactly @var{nchars} characters rather | |
4425 | than waiting for a complete line of input, unless EOF is encountered or | |
4426 | @code{read} times out. | |
4427 | Delimiter characters encountered in the input are | |
4428 | not treated specially and do not cause @code{read} to return until | |
4429 | @var{nchars} characters are read. | |
a0c0a00f CR |
4430 | The result is not split on the characters in @code{IFS}; the intent is |
4431 | that the variable is assigned exactly the characters read | |
4432 | (with the exception of backslash; see the @option{-r} option below). | |
ccc6cda3 | 4433 | |
bb70624e JA |
4434 | @item -p @var{prompt} |
4435 | Display @var{prompt}, without a trailing newline, before attempting | |
4436 | to read any input. | |
4437 | The prompt is displayed only if input is coming from a terminal. | |
ccc6cda3 | 4438 | |
bb70624e JA |
4439 | @item -r |
4440 | If this option is given, backslash does not act as an escape character. | |
4441 | The backslash is considered to be part of the line. | |
4442 | In particular, a backslash-newline pair may not be used as a line | |
4443 | continuation. | |
ccc6cda3 | 4444 | |
bb70624e JA |
4445 | @item -s |
4446 | Silent mode. If input is coming from a terminal, characters are | |
4447 | not echoed. | |
ccc6cda3 | 4448 | |
bb70624e JA |
4449 | @item -t @var{timeout} |
4450 | Cause @code{read} to time out and return failure if a complete line of | |
ac50fbac CR |
4451 | input (or a specified number of characters) |
4452 | is not read within @var{timeout} seconds. | |
3185942a JA |
4453 | @var{timeout} may be a decimal number with a fractional portion following |
4454 | the decimal point. | |
4455 | This option is only effective if @code{read} is reading input from a | |
4456 | terminal, pipe, or other special file; it has no effect when reading | |
4457 | from regular files. | |
ac50fbac CR |
4458 | If @code{read} times out, @code{read} saves any partial input read into |
4459 | the specified variable @var{name}. | |
4460 | If @var{timeout} is 0, @code{read} returns immediately, without trying to | |
4461 | read and data. The exit status is 0 if input is available on | |
4462 | the specified file descriptor, non-zero otherwise. | |
3185942a | 4463 | The exit status is greater than 128 if the timeout is exceeded. |
ccc6cda3 | 4464 | |
7117c2d2 JA |
4465 | @item -u @var{fd} |
4466 | Read input from file descriptor @var{fd}. | |
bb70624e | 4467 | @end table |
ccc6cda3 | 4468 | |
17345e5a JA |
4469 | @item readarray |
4470 | @btindex readarray | |
4471 | @example | |
a0c0a00f | 4472 | readarray [-d @var{delim}] [-n @var{count}] [-O @var{origin}] [-s @var{count}] [-t] [-u @var{fd}] |
ac50fbac | 4473 | [-C @var{callback}] [-c @var{quantum}] [@var{array}] |
17345e5a | 4474 | @end example |
ac50fbac | 4475 | |
0001803f | 4476 | Read lines from the standard input into the indexed array variable @var{array}, |
17345e5a JA |
4477 | or from file descriptor @var{fd} |
4478 | if the @option{-u} option is supplied. | |
4479 | ||
4480 | A synonym for @code{mapfile}. | |
4481 | ||
3185942a JA |
4482 | @item source |
4483 | @btindex source | |
bb70624e | 4484 | @example |
3185942a | 4485 | source @var{filename} |
bb70624e | 4486 | @end example |
ac50fbac | 4487 | |
3185942a | 4488 | A synonym for @code{.} (@pxref{Bourne Shell Builtins}). |
cce855bc | 4489 | |
3185942a JA |
4490 | @item type |
4491 | @btindex type | |
4492 | @example | |
4493 | type [-afptP] [@var{name} @dots{}] | |
4494 | @end example | |
ac50fbac | 4495 | |
3185942a JA |
4496 | For each @var{name}, indicate how it would be interpreted if used as a |
4497 | command name. | |
cce855bc | 4498 | |
3185942a JA |
4499 | If the @option{-t} option is used, @code{type} prints a single word |
4500 | which is one of @samp{alias}, @samp{function}, @samp{builtin}, | |
4501 | @samp{file} or @samp{keyword}, | |
4502 | if @var{name} is an alias, shell function, shell builtin, | |
4503 | disk file, or shell reserved word, respectively. | |
4504 | If the @var{name} is not found, then nothing is printed, and | |
4505 | @code{type} returns a failure status. | |
ccc6cda3 | 4506 | |
3185942a JA |
4507 | If the @option{-p} option is used, @code{type} either returns the name |
4508 | of the disk file that would be executed, or nothing if @option{-t} | |
4509 | would not return @samp{file}. | |
ccc6cda3 | 4510 | |
3185942a JA |
4511 | The @option{-P} option forces a path search for each @var{name}, even if |
4512 | @option{-t} would not return @samp{file}. | |
cce855bc | 4513 | |
3185942a | 4514 | If a command is hashed, @option{-p} and @option{-P} print the hashed value, |
ac50fbac | 4515 | which is not necessarily the file that appears first in @code{$PATH}. |
ccc6cda3 | 4516 | |
3185942a JA |
4517 | If the @option{-a} option is used, @code{type} returns all of the places |
4518 | that contain an executable named @var{file}. | |
4519 | This includes aliases and functions, if and only if the @option{-p} option | |
4520 | is not also used. | |
cce855bc | 4521 | |
3185942a JA |
4522 | If the @option{-f} option is used, @code{type} does not attempt to find |
4523 | shell functions, as with the @code{command} builtin. | |
ccc6cda3 | 4524 | |
3185942a JA |
4525 | The return status is zero if all of the @var{names} are found, non-zero |
4526 | if any are not found. | |
ccc6cda3 | 4527 | |
3185942a JA |
4528 | @item typeset |
4529 | @btindex typeset | |
4530 | @example | |
ac50fbac | 4531 | typeset [-afFgrxilnrtux] [-p] [@var{name}[=@var{value}] @dots{}] |
3185942a | 4532 | @end example |
ac50fbac | 4533 | |
3185942a | 4534 | The @code{typeset} command is supplied for compatibility with the Korn |
ac50fbac CR |
4535 | shell. |
4536 | It is a synonym for the @code{declare} builtin command. | |
ccc6cda3 | 4537 | |
3185942a JA |
4538 | @item ulimit |
4539 | @btindex ulimit | |
4540 | @example | |
a0c0a00f | 4541 | ulimit [-HSabcdefiklmnpqrstuvxPT] [@var{limit}] |
3185942a | 4542 | @end example |
ac50fbac | 4543 | |
3185942a JA |
4544 | @code{ulimit} provides control over the resources available to processes |
4545 | started by the shell, on systems that allow such control. If an | |
4546 | option is given, it is interpreted as follows: | |
ac50fbac | 4547 | |
3185942a JA |
4548 | @table @code |
4549 | @item -S | |
4550 | Change and report the soft limit associated with a resource. | |
ccc6cda3 | 4551 | |
3185942a JA |
4552 | @item -H |
4553 | Change and report the hard limit associated with a resource. | |
ccc6cda3 | 4554 | |
3185942a JA |
4555 | @item -a |
4556 | All current limits are reported. | |
cce855bc | 4557 | |
3185942a JA |
4558 | @item -b |
4559 | The maximum socket buffer size. | |
f1be666c | 4560 | |
3185942a JA |
4561 | @item -c |
4562 | The maximum size of core files created. | |
ccc6cda3 | 4563 | |
3185942a JA |
4564 | @item -d |
4565 | The maximum size of a process's data segment. | |
cce855bc | 4566 | |
3185942a JA |
4567 | @item -e |
4568 | The maximum scheduling priority ("nice"). | |
ccc6cda3 | 4569 | |
3185942a JA |
4570 | @item -f |
4571 | The maximum size of files written by the shell and its children. | |
b80f6443 | 4572 | |
3185942a JA |
4573 | @item -i |
4574 | The maximum number of pending signals. | |
b80f6443 | 4575 | |
a0c0a00f CR |
4576 | @item -k |
4577 | The maximum number of kqueues that may be allocated. | |
4578 | ||
3185942a JA |
4579 | @item -l |
4580 | The maximum size that may be locked into memory. | |
b80f6443 | 4581 | |
3185942a | 4582 | @item -m |
17345e5a | 4583 | The maximum resident set size (many systems do not honor this limit). |
95732b49 | 4584 | |
3185942a | 4585 | @item -n |
17345e5a JA |
4586 | The maximum number of open file descriptors (most systems do not |
4587 | allow this value to be set). | |
ccc6cda3 | 4588 | |
bb70624e JA |
4589 | @item -p |
4590 | The pipe buffer size. | |
ccc6cda3 | 4591 | |
0628567a JA |
4592 | @item -q |
4593 | The maximum number of bytes in POSIX message queues. | |
4594 | ||
4595 | @item -r | |
4596 | The maximum real-time scheduling priority. | |
4597 | ||
bb70624e JA |
4598 | @item -s |
4599 | The maximum stack size. | |
ccc6cda3 | 4600 | |
bb70624e JA |
4601 | @item -t |
4602 | The maximum amount of cpu time in seconds. | |
ccc6cda3 | 4603 | |
bb70624e JA |
4604 | @item -u |
4605 | The maximum number of processes available to a single user. | |
ccc6cda3 | 4606 | |
bb70624e | 4607 | @item -v |
495aee44 CR |
4608 | The maximum amount of virtual memory available to the shell, and, on |
4609 | some systems, to its children. | |
ccc6cda3 | 4610 | |
0628567a JA |
4611 | @item -x |
4612 | The maximum number of file locks. | |
4613 | ||
a0c0a00f CR |
4614 | @item -P |
4615 | The maximum number of pseudoterminals. | |
4616 | ||
3185942a JA |
4617 | @item -T |
4618 | The maximum number of threads. | |
bb70624e | 4619 | @end table |
ccc6cda3 | 4620 | |
ac50fbac CR |
4621 | If @var{limit} is given, and the @option{-a} option is not used, |
4622 | @var{limit} is the new value of the specified resource. | |
4623 | The special @var{limit} values @code{hard}, @code{soft}, and | |
f73dda09 JA |
4624 | @code{unlimited} stand for the current hard limit, the current soft limit, |
4625 | and no limit, respectively. | |
3185942a JA |
4626 | A hard limit cannot be increased by a non-root user once it is set; |
4627 | a soft limit may be increased up to the value of the hard limit. | |
bb70624e | 4628 | Otherwise, the current value of the soft limit for the specified resource |
28ef6c31 JA |
4629 | is printed, unless the @option{-H} option is supplied. |
4630 | When setting new limits, if neither @option{-H} nor @option{-S} is supplied, | |
bb70624e | 4631 | both the hard and soft limits are set. |
28ef6c31 | 4632 | If no option is given, then @option{-f} is assumed. Values are in 1024-byte |
ac50fbac | 4633 | increments, except for @option{-t}, which is in seconds; @option{-p}, |
a0c0a00f CR |
4634 | which is in units of 512-byte blocks; |
4635 | @option{-P}, | |
4636 | @option{-T}, | |
4637 | @option{-b}, | |
4638 | @option{-k}, | |
4639 | @option{-n} and @option{-u}, which are unscaled values; | |
4640 | and, when in @sc{posix} Mode (@pxref{Bash POSIX Mode}), | |
4641 | @option{-c} and @option{-f}, which are in 512-byte increments. | |
ccc6cda3 | 4642 | |
f73dda09 JA |
4643 | The return status is zero unless an invalid option or argument is supplied, |
4644 | or an error occurs while setting a new limit. | |
ccc6cda3 | 4645 | |
bb70624e JA |
4646 | @item unalias |
4647 | @btindex unalias | |
4648 | @example | |
4649 | unalias [-a] [@var{name} @dots{} ] | |
4650 | @end example | |
ccc6cda3 | 4651 | |
28ef6c31 | 4652 | Remove each @var{name} from the list of aliases. If @option{-a} is |
bb70624e JA |
4653 | supplied, all aliases are removed. |
4654 | Aliases are described in @ref{Aliases}. | |
ccc6cda3 JA |
4655 | @end table |
4656 | ||
3185942a JA |
4657 | @node Modifying Shell Behavior |
4658 | @section Modifying Shell Behavior | |
4659 | ||
4660 | @menu | |
4661 | * The Set Builtin:: Change the values of shell attributes and | |
4662 | positional parameters. | |
4663 | * The Shopt Builtin:: Modify shell optional behavior. | |
4664 | @end menu | |
4665 | ||
bb70624e | 4666 | @node The Set Builtin |
3185942a | 4667 | @subsection The Set Builtin |
ccc6cda3 | 4668 | |
3185942a JA |
4669 | This builtin is so complicated that it deserves its own section. @code{set} |
4670 | allows you to change the values of shell options and set the positional | |
4671 | parameters, or to display the names and values of shell variables. | |
ccc6cda3 | 4672 | |
bb70624e JA |
4673 | @table @code |
4674 | @item set | |
4675 | @btindex set | |
4676 | @example | |
495aee44 CR |
4677 | set [--abefhkmnptuvxBCEHPT] [-o @var{option-name}] [@var{argument} @dots{}] |
4678 | set [+abefhkmnptuvxBCEHPT] [+o @var{option-name}] [@var{argument} @dots{}] | |
bb70624e | 4679 | @end example |
ccc6cda3 | 4680 | |
bb70624e JA |
4681 | If no options or arguments are supplied, @code{set} displays the names |
4682 | and values of all shell variables and functions, sorted according to the | |
95732b49 JA |
4683 | current locale, in a format that may be reused as input |
4684 | for setting or resetting the currently-set variables. | |
4685 | Read-only variables cannot be reset. | |
4686 | In @sc{posix} mode, only shell variables are listed. | |
ccc6cda3 | 4687 | |
bb70624e JA |
4688 | When options are supplied, they set or unset shell attributes. |
4689 | Options, if specified, have the following meanings: | |
ccc6cda3 | 4690 | |
bb70624e JA |
4691 | @table @code |
4692 | @item -a | |
a0c0a00f CR |
4693 | Each variable or function that is created or modified is given the |
4694 | export attribute and marked for export to the environment of | |
4695 | subsequent commands. | |
ccc6cda3 | 4696 | |
bb70624e JA |
4697 | @item -b |
4698 | Cause the status of terminated background jobs to be reported | |
4699 | immediately, rather than before printing the next primary prompt. | |
ccc6cda3 | 4700 | |
bb70624e | 4701 | @item -e |
ac50fbac CR |
4702 | Exit immediately if |
4703 | a pipeline (@pxref{Pipelines}), which may consist of a single simple command | |
4704 | (@pxref{Simple Commands}), | |
4705 | a list (@pxref{Lists}), | |
4706 | or a compound command (@pxref{Compound Commands}) | |
17345e5a JA |
4707 | returns a non-zero status. |
4708 | The shell does not exit if the command that fails is part of the | |
3185942a JA |
4709 | command list immediately following a @code{while} or @code{until} keyword, |
4710 | part of the test in an @code{if} statement, | |
17345e5a JA |
4711 | part of any command executed in a @code{&&} or @code{||} list except |
4712 | the command following the final @code{&&} or @code{||}, | |
3185942a | 4713 | any command in a pipeline but the last, |
17345e5a | 4714 | or if the command's return status is being inverted with @code{!}. |
ac50fbac CR |
4715 | If a compound command other than a subshell |
4716 | returns a non-zero status because a command failed | |
4717 | while @option{-e} was being ignored, the shell does not exit. | |
f73dda09 | 4718 | A trap on @code{ERR}, if set, is executed before the shell exits. |
ccc6cda3 | 4719 | |
17345e5a JA |
4720 | This option applies to the shell environment and each subshell environment |
4721 | separately (@pxref{Command Execution Environment}), and may cause | |
4722 | subshells to exit before executing all the commands in the subshell. | |
4723 | ||
ac50fbac CR |
4724 | If a compound command or shell function executes in a context where |
4725 | @option{-e} is being ignored, | |
4726 | none of the commands executed within the compound command or function body | |
4727 | will be affected by the @option{-e} setting, even if @option{-e} is set | |
4728 | and a command returns a failure status. | |
4729 | If a compound command or shell function sets @option{-e} while executing in | |
4730 | a context where @option{-e} is ignored, that setting will not have any | |
4731 | effect until the compound command or the command containing the function | |
4732 | call completes. | |
4733 | ||
bb70624e | 4734 | @item -f |
0001803f | 4735 | Disable filename expansion (globbing). |
ccc6cda3 | 4736 | |
bb70624e JA |
4737 | @item -h |
4738 | Locate and remember (hash) commands as they are looked up for execution. | |
4739 | This option is enabled by default. | |
ccc6cda3 | 4740 | |
bb70624e JA |
4741 | @item -k |
4742 | All arguments in the form of assignment statements are placed | |
4743 | in the environment for a command, not just those that precede | |
4744 | the command name. | |
ccc6cda3 | 4745 | |
bb70624e JA |
4746 | @item -m |
4747 | Job control is enabled (@pxref{Job Control}). | |
ac50fbac CR |
4748 | All processes run in a separate process group. |
4749 | When a background job completes, the shell prints a line | |
4750 | containing its exit status. | |
ccc6cda3 | 4751 | |
bb70624e | 4752 | @item -n |
a0c0a00f CR |
4753 | Read commands but do not execute them. |
4754 | This may be used to check a script for syntax errors. | |
bb70624e | 4755 | This option is ignored by interactive shells. |
b72432fd | 4756 | |
bb70624e | 4757 | @item -o @var{option-name} |
ccc6cda3 | 4758 | |
bb70624e | 4759 | Set the option corresponding to @var{option-name}: |
ccc6cda3 | 4760 | |
bb70624e JA |
4761 | @table @code |
4762 | @item allexport | |
4763 | Same as @code{-a}. | |
ccc6cda3 | 4764 | |
bb70624e JA |
4765 | @item braceexpand |
4766 | Same as @code{-B}. | |
ccc6cda3 | 4767 | |
bb70624e JA |
4768 | @item emacs |
4769 | Use an @code{emacs}-style line editing interface (@pxref{Command Line Editing}). | |
3185942a | 4770 | This also affects the editing interface used for @code{read -e}. |
d166f048 | 4771 | |
bb70624e JA |
4772 | @item errexit |
4773 | Same as @code{-e}. | |
d166f048 | 4774 | |
b80f6443 JA |
4775 | @item errtrace |
4776 | Same as @code{-E}. | |
4777 | ||
4778 | @item functrace | |
4779 | Same as @code{-T}. | |
4780 | ||
bb70624e JA |
4781 | @item hashall |
4782 | Same as @code{-h}. | |
ccc6cda3 | 4783 | |
bb70624e JA |
4784 | @item histexpand |
4785 | Same as @code{-H}. | |
ccc6cda3 | 4786 | |
bb70624e JA |
4787 | @item history |
4788 | Enable command history, as described in @ref{Bash History Facilities}. | |
4789 | This option is on by default in interactive shells. | |
ccc6cda3 | 4790 | |
bb70624e JA |
4791 | @item ignoreeof |
4792 | An interactive shell will not exit upon reading EOF. | |
ccc6cda3 | 4793 | |
bb70624e JA |
4794 | @item keyword |
4795 | Same as @code{-k}. | |
ccc6cda3 | 4796 | |
bb70624e JA |
4797 | @item monitor |
4798 | Same as @code{-m}. | |
ccc6cda3 | 4799 | |
bb70624e JA |
4800 | @item noclobber |
4801 | Same as @code{-C}. | |
ccc6cda3 | 4802 | |
bb70624e JA |
4803 | @item noexec |
4804 | Same as @code{-n}. | |
ccc6cda3 | 4805 | |
bb70624e JA |
4806 | @item noglob |
4807 | Same as @code{-f}. | |
ccc6cda3 | 4808 | |
f73dda09 JA |
4809 | @item nolog |
4810 | Currently ignored. | |
4811 | ||
3185942a JA |
4812 | @item notify |
4813 | Same as @code{-b}. | |
4814 | ||
4815 | @item nounset | |
4816 | Same as @code{-u}. | |
4817 | ||
4818 | @item onecmd | |
4819 | Same as @code{-t}. | |
4820 | ||
4821 | @item physical | |
4822 | Same as @code{-P}. | |
4823 | ||
4824 | @item pipefail | |
4825 | If set, the return value of a pipeline is the value of the last | |
4826 | (rightmost) command to exit with a non-zero status, or zero if all | |
4827 | commands in the pipeline exit successfully. | |
4828 | This option is disabled by default. | |
4829 | ||
4830 | @item posix | |
4831 | Change the behavior of Bash where the default operation differs | |
4832 | from the @sc{posix} standard to match the standard | |
4833 | (@pxref{Bash POSIX Mode}). | |
4834 | This is intended to make Bash behave as a strict superset of that | |
4835 | standard. | |
4836 | ||
4837 | @item privileged | |
4838 | Same as @code{-p}. | |
4839 | ||
4840 | @item verbose | |
4841 | Same as @code{-v}. | |
4842 | ||
4843 | @item vi | |
4844 | Use a @code{vi}-style line editing interface. | |
4845 | This also affects the editing interface used for @code{read -e}. | |
4846 | ||
4847 | @item xtrace | |
4848 | Same as @code{-x}. | |
4849 | @end table | |
4850 | ||
4851 | @item -p | |
4852 | Turn on privileged mode. | |
4853 | In this mode, the @env{$BASH_ENV} and @env{$ENV} files are not | |
4854 | processed, shell functions are not inherited from the environment, | |
0001803f CR |
4855 | and the @env{SHELLOPTS}, @env{BASHOPTS}, @env{CDPATH} and @env{GLOBIGNORE} |
4856 | variables, if they appear in the environment, are ignored. | |
3185942a | 4857 | If the shell is started with the effective user (group) id not equal to the |
ac50fbac | 4858 | real user (group) id, and the @option{-p} option is not supplied, these actions |
3185942a | 4859 | are taken and the effective user id is set to the real user id. |
ac50fbac | 4860 | If the @option{-p} option is supplied at startup, the effective user id is |
3185942a JA |
4861 | not reset. |
4862 | Turning this option off causes the effective user | |
4863 | and group ids to be set to the real user and group ids. | |
4864 | ||
4865 | @item -t | |
4866 | Exit after reading and executing one command. | |
4867 | ||
4868 | @item -u | |
89a92869 CR |
4869 | Treat unset variables and parameters other than the special parameters |
4870 | @samp{@@} or @samp{*} as an error when performing parameter expansion. | |
3185942a JA |
4871 | An error message will be written to the standard error, and a non-interactive |
4872 | shell will exit. | |
4873 | ||
4874 | @item -v | |
4875 | Print shell input lines as they are read. | |
4876 | ||
4877 | @item -x | |
4878 | Print a trace of simple commands, @code{for} commands, @code{case} | |
4879 | commands, @code{select} commands, and arithmetic @code{for} commands | |
4880 | and their arguments or associated word lists after they are | |
4881 | expanded and before they are executed. The value of the @env{PS4} | |
4882 | variable is expanded and the resultant value is printed before | |
4883 | the command and its expanded arguments. | |
4884 | ||
4885 | @item -B | |
4886 | The shell will perform brace expansion (@pxref{Brace Expansion}). | |
4887 | This option is on by default. | |
4888 | ||
4889 | @item -C | |
4890 | Prevent output redirection using @samp{>}, @samp{>&}, and @samp{<>} | |
4891 | from overwriting existing files. | |
4892 | ||
4893 | @item -E | |
4894 | If set, any trap on @code{ERR} is inherited by shell functions, command | |
4895 | substitutions, and commands executed in a subshell environment. | |
4896 | The @code{ERR} trap is normally not inherited in such cases. | |
4897 | ||
4898 | @item -H | |
4899 | Enable @samp{!} style history substitution (@pxref{History Interaction}). | |
4900 | This option is on by default for interactive shells. | |
4901 | ||
4902 | @item -P | |
ac50fbac | 4903 | If set, do not resolve symbolic links when performing commands such as |
3185942a JA |
4904 | @code{cd} which change the current directory. The physical directory |
4905 | is used instead. By default, Bash follows | |
4906 | the logical chain of directories when performing commands | |
4907 | which change the current directory. | |
4908 | ||
4909 | For example, if @file{/usr/sys} is a symbolic link to @file{/usr/local/sys} | |
4910 | then: | |
4911 | @example | |
4912 | $ cd /usr/sys; echo $PWD | |
4913 | /usr/sys | |
4914 | $ cd ..; pwd | |
4915 | /usr | |
4916 | @end example | |
4917 | ||
4918 | @noindent | |
4919 | If @code{set -P} is on, then: | |
4920 | @example | |
4921 | $ cd /usr/sys; echo $PWD | |
4922 | /usr/local/sys | |
4923 | $ cd ..; pwd | |
4924 | /usr/local | |
4925 | @end example | |
4926 | ||
4927 | @item -T | |
4928 | If set, any trap on @code{DEBUG} and @code{RETURN} are inherited by | |
4929 | shell functions, command substitutions, and commands executed | |
4930 | in a subshell environment. | |
4931 | The @code{DEBUG} and @code{RETURN} traps are normally not inherited | |
4932 | in such cases. | |
4933 | ||
4934 | @item -- | |
4935 | If no arguments follow this option, then the positional parameters are | |
4936 | unset. Otherwise, the positional parameters are set to the | |
4937 | @var{arguments}, even if some of them begin with a @samp{-}. | |
4938 | ||
4939 | @item - | |
4940 | Signal the end of options, cause all remaining @var{arguments} | |
4941 | to be assigned to the positional parameters. The @option{-x} | |
4942 | and @option{-v} options are turned off. | |
4943 | If there are no arguments, the positional parameters remain unchanged. | |
4944 | @end table | |
4945 | ||
4946 | Using @samp{+} rather than @samp{-} causes these options to be | |
4947 | turned off. The options can also be used upon invocation of the | |
4948 | shell. The current set of options may be found in @code{$-}. | |
4949 | ||
4950 | The remaining N @var{arguments} are positional parameters and are | |
4951 | assigned, in order, to @code{$1}, @code{$2}, @dots{} @code{$N}. | |
4952 | The special parameter @code{#} is set to N. | |
4953 | ||
4954 | The return status is always zero unless an invalid option is supplied. | |
4955 | @end table | |
4956 | ||
4957 | @node The Shopt Builtin | |
4958 | @subsection The Shopt Builtin | |
4959 | ||
4960 | This builtin allows you to change additional shell optional behavior. | |
4961 | ||
4962 | @table @code | |
4963 | ||
4964 | @item shopt | |
4965 | @btindex shopt | |
4966 | @example | |
4967 | shopt [-pqsu] [-o] [@var{optname} @dots{}] | |
4968 | @end example | |
ac50fbac CR |
4969 | |
4970 | Toggle the values of settings controlling optional shell behavior. | |
4971 | The settings can be either those listed below, or, if the | |
4972 | @option{-o} option is used, those available with the @option{-o} | |
4973 | option to the @code{set} builtin command (@pxref{The Set Builtin}). | |
3185942a JA |
4974 | With no options, or with the @option{-p} option, a list of all settable |
4975 | options is displayed, with an indication of whether or not each is set. | |
4976 | The @option{-p} option causes output to be displayed in a form that | |
4977 | may be reused as input. | |
4978 | Other options have the following meanings: | |
4979 | ||
4980 | @table @code | |
4981 | @item -s | |
4982 | Enable (set) each @var{optname}. | |
4983 | ||
4984 | @item -u | |
4985 | Disable (unset) each @var{optname}. | |
4986 | ||
4987 | @item -q | |
4988 | Suppresses normal output; the return status | |
4989 | indicates whether the @var{optname} is set or unset. | |
4990 | If multiple @var{optname} arguments are given with @option{-q}, | |
4991 | the return status is zero if all @var{optnames} are enabled; | |
4992 | non-zero otherwise. | |
4993 | ||
4994 | @item -o | |
4995 | Restricts the values of | |
4996 | @var{optname} to be those defined for the @option{-o} option to the | |
4997 | @code{set} builtin (@pxref{The Set Builtin}). | |
4998 | @end table | |
4999 | ||
5000 | If either @option{-s} or @option{-u} | |
ac50fbac | 5001 | is used with no @var{optname} arguments, @code{shopt} shows only |
3185942a JA |
5002 | those options which are set or unset, respectively. |
5003 | ||
5004 | Unless otherwise noted, the @code{shopt} options are disabled (off) | |
5005 | by default. | |
5006 | ||
5007 | The return status when listing options is zero if all @var{optnames} | |
5008 | are enabled, non-zero otherwise. When setting or unsetting options, | |
5009 | the return status is zero unless an @var{optname} is not a valid shell | |
5010 | option. | |
5011 | ||
5012 | The list of @code{shopt} options is: | |
5013 | @table @code | |
5014 | ||
5015 | @item autocd | |
5016 | If set, a command name that is the name of a directory is executed as if | |
5017 | it were the argument to the @code{cd} command. | |
5018 | This option is only used by interactive shells. | |
5019 | ||
5020 | @item cdable_vars | |
5021 | If this is set, an argument to the @code{cd} builtin command that | |
5022 | is not a directory is assumed to be the name of a variable whose | |
5023 | value is the directory to change to. | |
5024 | ||
5025 | @item cdspell | |
5026 | If set, minor errors in the spelling of a directory component in a | |
5027 | @code{cd} command will be corrected. | |
5028 | The errors checked for are transposed characters, | |
5029 | a missing character, and a character too many. | |
5030 | If a correction is found, the corrected path is printed, | |
5031 | and the command proceeds. | |
5032 | This option is only used by interactive shells. | |
5033 | ||
5034 | @item checkhash | |
5035 | If this is set, Bash checks that a command found in the hash | |
5036 | table exists before trying to execute it. If a hashed command no | |
5037 | longer exists, a normal path search is performed. | |
5038 | ||
5039 | @item checkjobs | |
5040 | If set, Bash lists the status of any stopped and running jobs before | |
5041 | exiting an interactive shell. If any jobs are running, this causes | |
5042 | the exit to be deferred until a second exit is attempted without an | |
5043 | intervening command (@pxref{Job Control}). | |
5044 | The shell always postpones exiting if any jobs are stopped. | |
5045 | ||
5046 | @item checkwinsize | |
5047 | If set, Bash checks the window size after each command | |
ac50fbac | 5048 | and, if necessary, updates the values of |
3185942a JA |
5049 | @env{LINES} and @env{COLUMNS}. |
5050 | ||
5051 | @item cmdhist | |
5052 | If set, Bash | |
5053 | attempts to save all lines of a multiple-line | |
5054 | command in the same history entry. This allows | |
5055 | easy re-editing of multi-line commands. | |
5056 | ||
5057 | @item compat31 | |
5058 | If set, Bash | |
5059 | changes its behavior to that of version 3.1 with respect to quoted | |
ac50fbac CR |
5060 | arguments to the conditional command's @samp{=~} operator |
5061 | and with respect to locale-specific | |
5062 | string comparison when using the @code{[[} | |
5063 | conditional command's @samp{<} and @samp{>} operators. | |
5064 | Bash versions prior to bash-4.1 use ASCII collation and strcmp(3); | |
5065 | bash-4.1 and later use the current locale's collation sequence and strcoll(3). | |
495aee44 CR |
5066 | |
5067 | @item compat32 | |
5068 | If set, Bash | |
5069 | changes its behavior to that of version 3.2 with respect to locale-specific | |
ac50fbac | 5070 | string comparison when using the @code{[[} |
a0c0a00f CR |
5071 | conditional command's @samp{<} and @samp{>} operators (see previous item) |
5072 | and the effect of interrupting a command list. | |
5073 | Bash versions 3.2 and earlier continue with the next command in the list | |
5074 | after one terminates due to an interrupt. | |
495aee44 CR |
5075 | |
5076 | @item compat40 | |
5077 | If set, Bash | |
5078 | changes its behavior to that of version 4.0 with respect to locale-specific | |
ac50fbac CR |
5079 | string comparison when using the @code{[[} |
5080 | conditional command's @samp{<} and @samp{>} operators (see description | |
5081 | of @code{compat31}) | |
495aee44 | 5082 | and the effect of interrupting a command list. |
ac50fbac CR |
5083 | Bash versions 4.0 and later interrupt the list as if the shell received the |
5084 | interrupt; previous versions continue with the next command in the list. | |
495aee44 CR |
5085 | |
5086 | @item compat41 | |
ac50fbac | 5087 | If set, Bash, when in @sc{posix} mode, treats a single quote in a double-quoted |
495aee44 CR |
5088 | parameter expansion as a special character. The single quotes must match |
5089 | (an even number) and the characters between the single quotes are considered | |
5090 | quoted. This is the behavior of @sc{posix} mode through version 4.1. | |
5091 | The default Bash behavior remains as in previous versions. | |
3185942a | 5092 | |
ac50fbac CR |
5093 | @item compat42 |
5094 | If set, Bash | |
5095 | does not process the replacement string in the pattern substitution word | |
5096 | expansion using quote removal. | |
5097 | ||
a0c0a00f CR |
5098 | @item compat43 |
5099 | If set, Bash | |
5100 | does not print a warning message if an attempt is made to use a quoted compound | |
5101 | array assignment as an argument to @code{declare}, | |
5102 | makes word expansion errors | |
5103 | non-fatal errors that cause the current command to fail (the default behavior is | |
5104 | to make them fatal errors that cause the shell to exit), | |
5105 | and does not reset the | |
5106 | loop state when a shell function is executed (this allows @code{break} or | |
5107 | @code{continue} in a shell function to affect loops in the caller's context). | |
5108 | ||
ac50fbac CR |
5109 | @item complete_fullquote |
5110 | If set, Bash | |
5111 | quotes all shell metacharacters in filenames and directory names when | |
5112 | performing completion. | |
5113 | If not set, Bash | |
5114 | removes metacharacters such as the dollar sign from the set of | |
5115 | characters that will be quoted in completed filenames | |
5116 | when these metacharacters appear in shell variable references in words to be | |
5117 | completed. | |
5118 | This means that dollar signs in variable names that expand to directories | |
5119 | will not be quoted; | |
5120 | however, any dollar signs appearing in filenames will not be quoted, either. | |
5121 | This is active only when bash is using backslashes to quote completed | |
5122 | filenames. | |
5123 | This variable is set by default, which is the default Bash behavior in | |
5124 | versions through 4.2. | |
5125 | ||
16b2d7f4 CR |
5126 | @item direxpand |
5127 | If set, Bash | |
5128 | replaces directory names with the results of word expansion when performing | |
5129 | filename completion. This changes the contents of the readline editing | |
5130 | buffer. | |
5131 | If not set, Bash attempts to preserve what the user typed. | |
5132 | ||
3185942a JA |
5133 | @item dirspell |
5134 | If set, Bash | |
5135 | attempts spelling correction on directory names during word completion | |
5136 | if the directory name initially supplied does not exist. | |
5137 | ||
5138 | @item dotglob | |
5139 | If set, Bash includes filenames beginning with a `.' in | |
5140 | the results of filename expansion. | |
5141 | ||
5142 | @item execfail | |
5143 | If this is set, a non-interactive shell will not exit if | |
5144 | it cannot execute the file specified as an argument to the @code{exec} | |
5145 | builtin command. An interactive shell does not exit if @code{exec} | |
5146 | fails. | |
5147 | ||
5148 | @item expand_aliases | |
5149 | If set, aliases are expanded as described below under Aliases, | |
5150 | @ref{Aliases}. | |
5151 | This option is enabled by default for interactive shells. | |
5152 | ||
5153 | @item extdebug | |
a0c0a00f CR |
5154 | If set at shell invocation, arrange to execute the debugger profile |
5155 | before the shell starts, identical to the @option{--debugger} option. | |
5156 | If set after invocation, behavior intended for use by debuggers is enabled: | |
3185942a JA |
5157 | |
5158 | @enumerate | |
5159 | @item | |
5160 | The @option{-F} option to the @code{declare} builtin (@pxref{Bash Builtins}) | |
5161 | displays the source file name and line number corresponding to each function | |
5162 | name supplied as an argument. | |
5163 | ||
5164 | @item | |
5165 | If the command run by the @code{DEBUG} trap returns a non-zero value, the | |
5166 | next command is skipped and not executed. | |
5167 | ||
5168 | @item | |
5169 | If the command run by the @code{DEBUG} trap returns a value of 2, and the | |
5170 | shell is executing in a subroutine (a shell function or a shell script | |
a0c0a00f CR |
5171 | executed by the @code{.} or @code{source} builtins), the shell simulates |
5172 | a call to @code{return}. | |
3185942a JA |
5173 | |
5174 | @item | |
5175 | @code{BASH_ARGC} and @code{BASH_ARGV} are updated as described in their | |
5176 | descriptions (@pxref{Bash Variables}). | |
5177 | ||
5178 | @item | |
a0c0a00f | 5179 | Function tracing is enabled: command substitution, shell functions, and |
3185942a JA |
5180 | subshells invoked with @code{( @var{command} )} inherit the |
5181 | @code{DEBUG} and @code{RETURN} traps. | |
5182 | ||
5183 | @item | |
a0c0a00f | 5184 | Error tracing is enabled: command substitution, shell functions, and |
3185942a | 5185 | subshells invoked with @code{( @var{command} )} inherit the |
495aee44 | 5186 | @code{ERR} trap. |
3185942a JA |
5187 | @end enumerate |
5188 | ||
5189 | @item extglob | |
5190 | If set, the extended pattern matching features described above | |
5191 | (@pxref{Pattern Matching}) are enabled. | |
5192 | ||
5193 | @item extquote | |
5194 | If set, @code{$'@var{string}'} and @code{$"@var{string}"} quoting is | |
5195 | performed within @code{$@{@var{parameter}@}} expansions | |
5196 | enclosed in double quotes. This option is enabled by default. | |
ccc6cda3 | 5197 | |
3185942a | 5198 | @item failglob |
0001803f | 5199 | If set, patterns which fail to match filenames during filename expansion |
3185942a | 5200 | result in an expansion error. |
ccc6cda3 | 5201 | |
3185942a JA |
5202 | @item force_fignore |
5203 | If set, the suffixes specified by the @env{FIGNORE} shell variable | |
5204 | cause words to be ignored when performing word completion even if | |
5205 | the ignored words are the only possible completions. | |
5206 | @xref{Bash Variables}, for a description of @env{FIGNORE}. | |
5207 | This option is enabled by default. | |
ccc6cda3 | 5208 | |
ac50fbac CR |
5209 | @item globasciiranges |
5210 | If set, range expressions used in pattern matching bracket expressions | |
5211 | (@pxref{Pattern Matching}) | |
5212 | behave as if in the traditional C locale when performing | |
5213 | comparisons. That is, the current locale's collating sequence | |
5214 | is not taken into account, so | |
5215 | @samp{b} will not collate between @samp{A} and @samp{B}, | |
5216 | and upper-case and lower-case ASCII characters will collate together. | |
5217 | ||
3185942a JA |
5218 | @item globstar |
5219 | If set, the pattern @samp{**} used in a filename expansion context will | |
495aee44 | 5220 | match all files and zero or more directories and subdirectories. |
3185942a JA |
5221 | If the pattern is followed by a @samp{/}, only directories and |
5222 | subdirectories match. | |
ccc6cda3 | 5223 | |
3185942a JA |
5224 | @item gnu_errfmt |
5225 | If set, shell error messages are written in the standard @sc{gnu} error | |
5226 | message format. | |
b80f6443 | 5227 | |
3185942a JA |
5228 | @item histappend |
5229 | If set, the history list is appended to the file named by the value | |
5230 | of the @env{HISTFILE} | |
5231 | variable when the shell exits, rather than overwriting the file. | |
ccc6cda3 | 5232 | |
3185942a JA |
5233 | @item histreedit |
5234 | If set, and Readline | |
5235 | is being used, a user is given the opportunity to re-edit a | |
5236 | failed history substitution. | |
cce855bc | 5237 | |
3185942a JA |
5238 | @item histverify |
5239 | If set, and Readline | |
5240 | is being used, the results of history substitution are not immediately | |
5241 | passed to the shell parser. Instead, the resulting line is loaded into | |
5242 | the Readline editing buffer, allowing further modification. | |
ccc6cda3 | 5243 | |
3185942a JA |
5244 | @item hostcomplete |
5245 | If set, and Readline is being used, Bash will attempt to perform | |
5246 | hostname completion when a word containing a @samp{@@} is being | |
5247 | completed (@pxref{Commands For Completion}). This option is enabled | |
5248 | by default. | |
ccc6cda3 | 5249 | |
3185942a JA |
5250 | @item huponexit |
5251 | If set, Bash will send @code{SIGHUP} to all jobs when an interactive | |
5252 | login shell exits (@pxref{Signals}). | |
ccc6cda3 | 5253 | |
a0c0a00f CR |
5254 | @item inherit_errexit |
5255 | If set, command substitution inherits the value of the @code{errexit} option, | |
5256 | instead of unsetting it in the subshell environment. | |
5257 | This option is enabled when @sc{posix} mode is enabled. | |
5258 | ||
3185942a JA |
5259 | @item interactive_comments |
5260 | Allow a word beginning with @samp{#} | |
5261 | to cause that word and all remaining characters on that | |
5262 | line to be ignored in an interactive shell. | |
5263 | This option is enabled by default. | |
cce855bc | 5264 | |
495aee44 CR |
5265 | @item lastpipe |
5266 | If set, and job control is not active, the shell runs the last command of | |
5267 | a pipeline not executed in the background in the current shell environment. | |
5268 | ||
3185942a JA |
5269 | @item lithist |
5270 | If enabled, and the @code{cmdhist} | |
5271 | option is enabled, multi-line commands are saved to the history with | |
5272 | embedded newlines rather than using semicolon separators where possible. | |
ccc6cda3 | 5273 | |
3185942a JA |
5274 | @item login_shell |
5275 | The shell sets this option if it is started as a login shell | |
5276 | (@pxref{Invoking Bash}). | |
5277 | The value may not be changed. | |
ccc6cda3 | 5278 | |
3185942a | 5279 | @item mailwarn |
a0c0a00f | 5280 | If set, and a file that Bash is checking for mail has been |
3185942a JA |
5281 | accessed since the last time it was checked, the message |
5282 | @code{"The mail in @var{mailfile} has been read"} is displayed. | |
ccc6cda3 | 5283 | |
3185942a JA |
5284 | @item no_empty_cmd_completion |
5285 | If set, and Readline is being used, Bash will not attempt to search | |
5286 | the @env{PATH} for possible completions when completion is attempted | |
5287 | on an empty line. | |
ccc6cda3 | 5288 | |
3185942a JA |
5289 | @item nocaseglob |
5290 | If set, Bash matches filenames in a case-insensitive fashion when | |
5291 | performing filename expansion. | |
ccc6cda3 | 5292 | |
3185942a JA |
5293 | @item nocasematch |
5294 | If set, Bash matches patterns in a case-insensitive fashion when | |
5295 | performing matching while executing @code{case} or @code{[[} | |
a0c0a00f CR |
5296 | conditional commands, |
5297 | when performing pattern substitution word expansions, | |
5298 | or when filtering possible completions as part of programmable completion. | |
ccc6cda3 | 5299 | |
3185942a JA |
5300 | @item nullglob |
5301 | If set, Bash allows filename patterns which match no | |
5302 | files to expand to a null string, rather than themselves. | |
b80f6443 | 5303 | |
3185942a JA |
5304 | @item progcomp |
5305 | If set, the programmable completion facilities | |
5306 | (@pxref{Programmable Completion}) are enabled. | |
5307 | This option is enabled by default. | |
ccc6cda3 | 5308 | |
3185942a JA |
5309 | @item promptvars |
5310 | If set, prompt strings undergo | |
5311 | parameter expansion, command substitution, arithmetic | |
5312 | expansion, and quote removal after being expanded | |
ac50fbac | 5313 | as described below (@pxref{Controlling the Prompt}). |
3185942a | 5314 | This option is enabled by default. |
ccc6cda3 | 5315 | |
3185942a JA |
5316 | @item restricted_shell |
5317 | The shell sets this option if it is started in restricted mode | |
5318 | (@pxref{The Restricted Shell}). | |
5319 | The value may not be changed. | |
5320 | This is not reset when the startup files are executed, allowing | |
5321 | the startup files to discover whether or not a shell is restricted. | |
ccc6cda3 | 5322 | |
3185942a JA |
5323 | @item shift_verbose |
5324 | If this is set, the @code{shift} | |
5325 | builtin prints an error message when the shift count exceeds the | |
5326 | number of positional parameters. | |
ccc6cda3 | 5327 | |
3185942a JA |
5328 | @item sourcepath |
5329 | If set, the @code{source} builtin uses the value of @env{PATH} | |
5330 | to find the directory containing the file supplied as an argument. | |
5331 | This option is enabled by default. | |
b80f6443 | 5332 | |
3185942a JA |
5333 | @item xpg_echo |
5334 | If set, the @code{echo} builtin expands backslash-escape sequences | |
5335 | by default. | |
bb70624e | 5336 | |
ccc6cda3 JA |
5337 | @end table |
5338 | ||
3185942a JA |
5339 | @noindent |
5340 | The return status when listing options is zero if all @var{optnames} | |
5341 | are enabled, non-zero otherwise. | |
5342 | When setting or unsetting options, the return status is zero unless an | |
5343 | @var{optname} is not a valid shell option. | |
ccc6cda3 JA |
5344 | @end table |
5345 | ||
bb70624e JA |
5346 | @node Special Builtins |
5347 | @section Special Builtins | |
5348 | @cindex special builtin | |
cce855bc | 5349 | |
0628567a | 5350 | For historical reasons, the @sc{posix} standard has classified |
bb70624e JA |
5351 | several builtin commands as @emph{special}. |
5352 | When Bash is executing in @sc{posix} mode, the special builtins | |
5353 | differ from other builtin commands in three respects: | |
ccc6cda3 | 5354 | |
bb70624e JA |
5355 | @enumerate |
5356 | @item | |
5357 | Special builtins are found before shell functions during command lookup. | |
cce855bc | 5358 | |
bb70624e JA |
5359 | @item |
5360 | If a special builtin returns an error status, a non-interactive shell exits. | |
cce855bc | 5361 | |
bb70624e JA |
5362 | @item |
5363 | Assignment statements preceding the command stay in effect in the shell | |
5364 | environment after the command completes. | |
5365 | @end enumerate | |
ccc6cda3 | 5366 | |
bb70624e JA |
5367 | When Bash is not executing in @sc{posix} mode, these builtins behave no |
5368 | differently than the rest of the Bash builtin commands. | |
5369 | The Bash @sc{posix} mode is described in @ref{Bash POSIX Mode}. | |
ccc6cda3 | 5370 | |
bb70624e | 5371 | These are the @sc{posix} special builtins: |
ccc6cda3 | 5372 | @example |
bb70624e JA |
5373 | @w{break : . continue eval exec exit export readonly return set} |
5374 | @w{shift trap unset} | |
ccc6cda3 | 5375 | @end example |
ccc6cda3 | 5376 | |
bb70624e JA |
5377 | @node Shell Variables |
5378 | @chapter Shell Variables | |
cce855bc | 5379 | |
bb70624e JA |
5380 | @menu |
5381 | * Bourne Shell Variables:: Variables which Bash uses in the same way | |
5382 | as the Bourne Shell. | |
5383 | * Bash Variables:: List of variables that exist in Bash. | |
5384 | @end menu | |
cce855bc | 5385 | |
bb70624e JA |
5386 | This chapter describes the shell variables that Bash uses. |
5387 | Bash automatically assigns default values to a number of variables. | |
ccc6cda3 | 5388 | |
bb70624e JA |
5389 | @node Bourne Shell Variables |
5390 | @section Bourne Shell Variables | |
ccc6cda3 | 5391 | |
bb70624e JA |
5392 | Bash uses certain shell variables in the same way as the Bourne shell. |
5393 | In some cases, Bash assigns a default value to the variable. | |
ccc6cda3 | 5394 | |
bb70624e | 5395 | @vtable @code |
ccc6cda3 | 5396 | |
bb70624e JA |
5397 | @item CDPATH |
5398 | A colon-separated list of directories used as a search path for | |
5399 | the @code{cd} builtin command. | |
ccc6cda3 | 5400 | |
bb70624e JA |
5401 | @item HOME |
5402 | The current user's home directory; the default for the @code{cd} builtin | |
5403 | command. | |
5404 | The value of this variable is also used by tilde expansion | |
5405 | (@pxref{Tilde Expansion}). | |
ccc6cda3 | 5406 | |
bb70624e JA |
5407 | @item IFS |
5408 | A list of characters that separate fields; used when the shell splits | |
5409 | words as part of expansion. | |
ccc6cda3 | 5410 | |
bb70624e | 5411 | @item MAIL |
495aee44 CR |
5412 | If this parameter is set to a filename or directory name |
5413 | and the @env{MAILPATH} variable | |
bb70624e | 5414 | is not set, Bash informs the user of the arrival of mail in |
495aee44 | 5415 | the specified file or Maildir-format directory. |
ccc6cda3 | 5416 | |
bb70624e JA |
5417 | @item MAILPATH |
5418 | A colon-separated list of filenames which the shell periodically checks | |
5419 | for new mail. | |
5420 | Each list entry can specify the message that is printed when new mail | |
ac50fbac | 5421 | arrives in the mail file by separating the filename from the message with |
bb70624e JA |
5422 | a @samp{?}. |
5423 | When used in the text of the message, @code{$_} expands to the name of | |
5424 | the current mail file. | |
ccc6cda3 | 5425 | |
bb70624e JA |
5426 | @item OPTARG |
5427 | The value of the last option argument processed by the @code{getopts} builtin. | |
ccc6cda3 | 5428 | |
bb70624e JA |
5429 | @item OPTIND |
5430 | The index of the last option argument processed by the @code{getopts} builtin. | |
ccc6cda3 | 5431 | |
bb70624e JA |
5432 | @item PATH |
5433 | A colon-separated list of directories in which the shell looks for | |
5434 | commands. | |
b80f6443 JA |
5435 | A zero-length (null) directory name in the value of @code{PATH} indicates the |
5436 | current directory. | |
5437 | A null directory name may appear as two adjacent colons, or as an initial | |
5438 | or trailing colon. | |
5439 | ||
bb70624e JA |
5440 | @item PS1 |
5441 | The primary prompt string. The default value is @samp{\s-\v\$ }. | |
ac50fbac | 5442 | @xref{Controlling the Prompt}, for the complete list of escape |
28ef6c31 | 5443 | sequences that are expanded before @env{PS1} is displayed. |
ccc6cda3 | 5444 | |
bb70624e JA |
5445 | @item PS2 |
5446 | The secondary prompt string. The default value is @samp{> }. | |
ccc6cda3 | 5447 | |
bb70624e | 5448 | @end vtable |
ccc6cda3 | 5449 | |
bb70624e JA |
5450 | @node Bash Variables |
5451 | @section Bash Variables | |
ccc6cda3 | 5452 | |
bb70624e JA |
5453 | These variables are set or used by Bash, but other shells |
5454 | do not normally treat them specially. | |
ccc6cda3 | 5455 | |
bb70624e JA |
5456 | A few variables used by Bash are described in different chapters: |
5457 | variables for controlling the job control facilities | |
5458 | (@pxref{Job Control Variables}). | |
ccc6cda3 | 5459 | |
bb70624e | 5460 | @vtable @code |
cce855bc | 5461 | |
bb70624e JA |
5462 | @item BASH |
5463 | The full pathname used to execute the current instance of Bash. | |
cce855bc | 5464 | |
0001803f CR |
5465 | @item BASHOPTS |
5466 | A colon-separated list of enabled shell options. Each word in | |
5467 | the list is a valid argument for the @option{-s} option to the | |
5468 | @code{shopt} builtin command (@pxref{The Shopt Builtin}). | |
5469 | The options appearing in @env{BASHOPTS} are those reported | |
5470 | as @samp{on} by @samp{shopt}. | |
5471 | If this variable is in the environment when Bash | |
5472 | starts up, each shell option in the list will be enabled before | |
5473 | reading any startup files. This variable is readonly. | |
5474 | ||
3185942a | 5475 | @item BASHPID |
495aee44 | 5476 | Expands to the process ID of the current Bash process. |
3185942a JA |
5477 | This differs from @code{$$} under certain circumstances, such as subshells |
5478 | that do not require Bash to be re-initialized. | |
5479 | ||
5480 | @item BASH_ALIASES | |
5481 | An associative array variable whose members correspond to the internal | |
495aee44 | 5482 | list of aliases as maintained by the @code{alias} builtin. |
3185942a | 5483 | (@pxref{Bourne Shell Builtins}). |
a0c0a00f CR |
5484 | Elements added to this array appear in the alias list; however, |
5485 | unsetting array elements currently does not cause aliases to be removed | |
5486 | from the alias list. | |
5487 | If @code{BASH_ALIASES} | |
5488 | is unset, it loses its special properties, even if it is | |
5489 | subsequently reset. | |
3185942a | 5490 | |
b80f6443 JA |
5491 | @item BASH_ARGC |
5492 | An array variable whose values are the number of parameters in each | |
5493 | frame of the current bash execution call stack. The number of | |
5494 | parameters to the current subroutine (shell function or script executed | |
5495 | with @code{.} or @code{source}) is at the top of the stack. When a | |
5496 | subroutine is executed, the number of parameters passed is pushed onto | |
5497 | @code{BASH_ARGC}. | |
95732b49 | 5498 | The shell sets @code{BASH_ARGC} only when in extended debugging mode |
3185942a | 5499 | (see @ref{The Shopt Builtin} |
95732b49 JA |
5500 | for a description of the @code{extdebug} option to the @code{shopt} |
5501 | builtin). | |
b80f6443 JA |
5502 | |
5503 | @item BASH_ARGV | |
5504 | An array variable containing all of the parameters in the current bash | |
5505 | execution call stack. The final parameter of the last subroutine call | |
5506 | is at the top of the stack; the first parameter of the initial call is | |
5507 | at the bottom. When a subroutine is executed, the parameters supplied | |
5508 | are pushed onto @code{BASH_ARGV}. | |
95732b49 | 5509 | The shell sets @code{BASH_ARGV} only when in extended debugging mode |
3185942a | 5510 | (see @ref{The Shopt Builtin} |
95732b49 JA |
5511 | for a description of the @code{extdebug} option to the @code{shopt} |
5512 | builtin). | |
b80f6443 | 5513 | |
3185942a JA |
5514 | @item BASH_CMDS |
5515 | An associative array variable whose members correspond to the internal | |
5516 | hash table of commands as maintained by the @code{hash} builtin | |
5517 | (@pxref{Bourne Shell Builtins}). | |
a0c0a00f CR |
5518 | Elements added to this array appear in the hash table; however, |
5519 | unsetting array elements currently does not cause command names to be removed | |
5520 | from the hash table. | |
5521 | If @code{BASH_CMDS} | |
5522 | is unset, it loses its special properties, even if it is | |
5523 | subsequently reset. | |
3185942a | 5524 | |
b80f6443 JA |
5525 | @item BASH_COMMAND |
5526 | The command currently being executed or about to be executed, unless the | |
5527 | shell is executing a command as the result of a trap, | |
5528 | in which case it is the command executing at the time of the trap. | |
5529 | ||
ac50fbac CR |
5530 | @item BASH_COMPAT |
5531 | The value is used to set the shell's compatibility level. | |
5532 | @xref{The Shopt Builtin}, for a description of the various compatibility | |
5533 | levels and their effects. | |
5534 | The value may be a decimal number (e.g., 4.2) or an integer (e.g., 42) | |
5535 | corresponding to the desired compatibility level. | |
5536 | If @code{BASH_COMPAT} is unset or set to the empty string, the compatibility | |
5537 | level is set to the default for the current version. | |
5538 | If @code{BASH_COMPAT} is set to a value that is not one of the valid | |
5539 | compatibility levels, the shell prints an error message and sets the | |
5540 | compatibility level to the default for the current version. | |
5541 | The valid compatibility levels correspond to the compatibility options | |
5542 | accepted by the @code{shopt} builtin described above (for example, | |
5543 | @var{compat42} means that 4.2 and 42 are valid values). | |
5544 | The current version is also a valid value. | |
5545 | ||
bb70624e JA |
5546 | @item BASH_ENV |
5547 | If this variable is set when Bash is invoked to execute a shell | |
5548 | script, its value is expanded and used as the name of a startup file | |
5549 | to read before executing the script. @xref{Bash Startup Files}. | |
ccc6cda3 | 5550 | |
b80f6443 JA |
5551 | @item BASH_EXECUTION_STRING |
5552 | The command argument to the @option{-c} invocation option. | |
5553 | ||
5554 | @item BASH_LINENO | |
5555 | An array variable whose members are the line numbers in source files | |
495aee44 CR |
5556 | where each corresponding member of @var{FUNCNAME} was invoked. |
5557 | @code{$@{BASH_LINENO[$i]@}} is the line number in the source file | |
5558 | (@code{$@{BASH_SOURCE[$i+1]@}}) where | |
3185942a | 5559 | @code{$@{FUNCNAME[$i]@}} was called (or @code{$@{BASH_LINENO[$i-1]@}} if |
495aee44 | 5560 | referenced within another shell function). |
b80f6443 JA |
5561 | Use @code{LINENO} to obtain the current line number. |
5562 | ||
a0c0a00f CR |
5563 | @item BASH_LOADABLES_PATH |
5564 | A colon-separated list of directories in which the shell looks for | |
5565 | dynamically loadable builtins specified by the | |
5566 | @code{enable} command. | |
5567 | ||
b80f6443 JA |
5568 | @item BASH_REMATCH |
5569 | An array variable whose members are assigned by the @samp{=~} binary | |
5570 | operator to the @code{[[} conditional command | |
5571 | (@pxref{Conditional Constructs}). | |
5572 | The element with index 0 is the portion of the string | |
5573 | matching the entire regular expression. | |
5574 | The element with index @var{n} is the portion of the | |
5575 | string matching the @var{n}th parenthesized subexpression. | |
5576 | This variable is read-only. | |
5577 | ||
5578 | @item BASH_SOURCE | |
495aee44 CR |
5579 | An array variable whose members are the source filenames where the |
5580 | corresponding shell function names in the @code{FUNCNAME} array | |
5581 | variable are defined. | |
5582 | The shell function @code{$@{FUNCNAME[$i]@}} is defined in the file | |
5583 | @code{$@{BASH_SOURCE[$i]@}} and called from @code{$@{BASH_SOURCE[$i+1]@}} | |
b80f6443 JA |
5584 | |
5585 | @item BASH_SUBSHELL | |
ac50fbac CR |
5586 | Incremented by one within each subshell or subshell environment when |
5587 | the shell begins executing in that environment. | |
b80f6443 | 5588 | The initial value is 0. |
ccc6cda3 | 5589 | |
bb70624e JA |
5590 | @item BASH_VERSINFO |
5591 | A readonly array variable (@pxref{Arrays}) | |
5592 | whose members hold version information for this instance of Bash. | |
5593 | The values assigned to the array members are as follows: | |
ccc6cda3 | 5594 | |
bb70624e | 5595 | @table @code |
ccc6cda3 | 5596 | |
bb70624e JA |
5597 | @item BASH_VERSINFO[0] |
5598 | The major version number (the @var{release}). | |
cce855bc | 5599 | |
bb70624e JA |
5600 | @item BASH_VERSINFO[1] |
5601 | The minor version number (the @var{version}). | |
ccc6cda3 | 5602 | |
bb70624e JA |
5603 | @item BASH_VERSINFO[2] |
5604 | The patch level. | |
ccc6cda3 | 5605 | |
bb70624e JA |
5606 | @item BASH_VERSINFO[3] |
5607 | The build version. | |
ccc6cda3 | 5608 | |
bb70624e JA |
5609 | @item BASH_VERSINFO[4] |
5610 | The release status (e.g., @var{beta1}). | |
cce855bc | 5611 | |
bb70624e | 5612 | @item BASH_VERSINFO[5] |
28ef6c31 | 5613 | The value of @env{MACHTYPE}. |
bb70624e | 5614 | @end table |
ccc6cda3 | 5615 | |
b80f6443 JA |
5616 | @item BASH_VERSION |
5617 | The version number of the current instance of Bash. | |
5618 | ||
0001803f CR |
5619 | @item BASH_XTRACEFD |
5620 | If set to an integer corresponding to a valid file descriptor, Bash | |
5621 | will write the trace output generated when @samp{set -x} | |
5622 | is enabled to that file descriptor. | |
5623 | This allows tracing output to be separated from diagnostic and error | |
5624 | messages. | |
5625 | The file descriptor is closed when @code{BASH_XTRACEFD} is unset or assigned | |
5626 | a new value. | |
5627 | Unsetting @code{BASH_XTRACEFD} or assigning it the empty string causes the | |
5628 | trace output to be sent to the standard error. | |
5629 | Note that setting @code{BASH_XTRACEFD} to 2 (the standard error file | |
5630 | descriptor) and then unsetting it will result in the standard error | |
5631 | being closed. | |
5632 | ||
ac50fbac CR |
5633 | @item CHILD_MAX |
5634 | Set the number of exited child status values for the shell to remember. | |
5635 | Bash will not allow this value to be decreased below a @sc{posix}-mandated | |
5636 | minimum, and there is a maximum value (currently 8192) that this may | |
5637 | not exceed. | |
5638 | The minimum value is system-dependent. | |
5639 | ||
f73dda09 | 5640 | @item COLUMNS |
495aee44 | 5641 | Used by the @code{select} command to determine the terminal width |
ac50fbac CR |
5642 | when printing selection lists. |
5643 | Automatically set if the @code{checkwinsize} option is enabled | |
5644 | (@pxref{The Shopt Builtin}), or in an interactive shell upon receipt of a | |
f73dda09 | 5645 | @code{SIGWINCH}. |
bb70624e JA |
5646 | |
5647 | @item COMP_CWORD | |
28ef6c31 | 5648 | An index into @env{$@{COMP_WORDS@}} of the word containing the current |
bb70624e JA |
5649 | cursor position. |
5650 | This variable is available only in shell functions invoked by the | |
5651 | programmable completion facilities (@pxref{Programmable Completion}). | |
5652 | ||
5653 | @item COMP_LINE | |
5654 | The current command line. | |
5655 | This variable is available only in shell functions and external | |
5656 | commands invoked by the | |
5657 | programmable completion facilities (@pxref{Programmable Completion}). | |
5658 | ||
5659 | @item COMP_POINT | |
5660 | The index of the current cursor position relative to the beginning of | |
5661 | the current command. | |
5662 | If the current cursor position is at the end of the current command, | |
5663 | the value of this variable is equal to @code{$@{#COMP_LINE@}}. | |
5664 | This variable is available only in shell functions and external | |
5665 | commands invoked by the | |
5666 | programmable completion facilities (@pxref{Programmable Completion}). | |
5667 | ||
3185942a JA |
5668 | @item COMP_TYPE |
5669 | Set to an integer value corresponding to the type of completion attempted | |
5670 | that caused a completion function to be called: | |
5671 | @var{TAB}, for normal completion, | |
5672 | @samp{?}, for listing completions after successive tabs, | |
5673 | @samp{!}, for listing alternatives on partial word completion, | |
5674 | @samp{@@}, to list completions if the word is not unmodified, | |
5675 | or | |
5676 | @samp{%}, for menu completion. | |
5677 | This variable is available only in shell functions and external | |
5678 | commands invoked by the | |
5679 | programmable completion facilities (@pxref{Programmable Completion}). | |
5680 | ||
5681 | @item COMP_KEY | |
5682 | The key (or final key of a key sequence) used to invoke the current | |
5683 | completion function. | |
5684 | ||
b80f6443 JA |
5685 | @item COMP_WORDBREAKS |
5686 | The set of characters that the Readline library treats as word | |
5687 | separators when performing word completion. | |
5688 | If @code{COMP_WORDBREAKS} is unset, it loses its special properties, | |
5689 | even if it is subsequently reset. | |
5690 | ||
f73dda09 JA |
5691 | @item COMP_WORDS |
5692 | An array variable consisting of the individual | |
5693 | words in the current command line. | |
17345e5a JA |
5694 | The line is split into words as Readline would split it, using |
5695 | @code{COMP_WORDBREAKS} as described above. | |
f73dda09 JA |
5696 | This variable is available only in shell functions invoked by the |
5697 | programmable completion facilities (@pxref{Programmable Completion}). | |
5698 | ||
bb70624e JA |
5699 | @item COMPREPLY |
5700 | An array variable from which Bash reads the possible completions | |
5701 | generated by a shell function invoked by the programmable completion | |
5702 | facility (@pxref{Programmable Completion}). | |
ac50fbac | 5703 | Each array element contains one possible completion. |
b72432fd | 5704 | |
495aee44 CR |
5705 | @item COPROC |
5706 | An array variable created to hold the file descriptors | |
5707 | for output from and input to an unnamed coprocess (@pxref{Coprocesses}). | |
5708 | ||
bb70624e JA |
5709 | @item DIRSTACK |
5710 | An array variable containing the current contents of the directory stack. | |
5711 | Directories appear in the stack in the order they are displayed by the | |
5712 | @code{dirs} builtin. | |
5713 | Assigning to members of this array variable may be used to modify | |
5714 | directories already in the stack, but the @code{pushd} and @code{popd} | |
5715 | builtins must be used to add and remove directories. | |
5716 | Assignment to this variable will not change the current directory. | |
28ef6c31 | 5717 | If @env{DIRSTACK} is unset, it loses its special properties, even if |
bb70624e | 5718 | it is subsequently reset. |
ccc6cda3 | 5719 | |
b80f6443 JA |
5720 | @item EMACS |
5721 | If Bash finds this variable in the environment when the shell | |
5722 | starts with value @samp{t}, it assumes that the shell is running in an | |
495aee44 CR |
5723 | Emacs shell buffer and disables line editing. |
5724 | ||
5725 | @item ENV | |
5726 | Similar to @code{BASH_ENV}; used when the shell is invoked in | |
5727 | @sc{posix} Mode (@pxref{Bash POSIX Mode}). | |
b80f6443 | 5728 | |
bb70624e JA |
5729 | @item EUID |
5730 | The numeric effective user id of the current user. This variable | |
5731 | is readonly. | |
ccc6cda3 | 5732 | |
a0c0a00f CR |
5733 | @item EXECIGNORE |
5734 | A colon-separated list of shell patterns (@pxref{Pattern Matching}) | |
5735 | defining the list of filenames to be ignored by command search using | |
5736 | @code{PATH}. | |
5737 | Files whose full pathnames match one of these patterns are not considered | |
5738 | executable files for the purposes of completion and command execution | |
5739 | via @code{PATH} lookup. | |
5740 | This does not affect the behavior of the @code{[}, @code{test}, and @code{[[} | |
5741 | commands. | |
5742 | Full pathnames in the command hash table are not subject to @code{EXECIGNORE}. | |
5743 | Use this variable to ignore shared library files that have the executable | |
5744 | bit set, but are not executable files. | |
5745 | The pattern matching honors the setting of the @code{extglob} shell | |
5746 | option. | |
5747 | ||
bb70624e | 5748 | @item FCEDIT |
28ef6c31 | 5749 | The editor used as a default by the @option{-e} option to the @code{fc} |
bb70624e | 5750 | builtin command. |
cce855bc | 5751 | |
bb70624e JA |
5752 | @item FIGNORE |
5753 | A colon-separated list of suffixes to ignore when performing | |
5754 | filename completion. | |
ac50fbac | 5755 | A filename whose suffix matches one of the entries in |
28ef6c31 | 5756 | @env{FIGNORE} |
ac50fbac | 5757 | is excluded from the list of matched filenames. A sample |
bb70624e | 5758 | value is @samp{.o:~} |
cce855bc | 5759 | |
f73dda09 | 5760 | @item FUNCNAME |
b80f6443 JA |
5761 | An array variable containing the names of all shell functions |
5762 | currently in the execution call stack. | |
5763 | The element with index 0 is the name of any currently-executing | |
5764 | shell function. | |
495aee44 CR |
5765 | The bottom-most element (the one with the highest index) |
5766 | is @code{"main"}. | |
f73dda09 | 5767 | This variable exists only when a shell function is executing. |
a0c0a00f | 5768 | Assignments to @env{FUNCNAME} have no effect. |
f73dda09 JA |
5769 | If @env{FUNCNAME} is unset, it loses its special properties, even if |
5770 | it is subsequently reset. | |
5771 | ||
495aee44 CR |
5772 | This variable can be used with @code{BASH_LINENO} and @code{BASH_SOURCE}. |
5773 | Each element of @code{FUNCNAME} has corresponding elements in | |
5774 | @code{BASH_LINENO} and @code{BASH_SOURCE} to describe the call stack. | |
5775 | For instance, @code{$@{FUNCNAME[$i]@}} was called from the file | |
5776 | @code{$@{BASH_SOURCE[$i+1]@}} at line number @code{$@{BASH_LINENO[$i]@}}. | |
5777 | The @code{caller} builtin displays the current call stack using this | |
5778 | information. | |
5779 | ||
5780 | @item FUNCNEST | |
5781 | If set to a numeric value greater than 0, defines a maximum function | |
5782 | nesting level. Function invocations that exceed this nesting level | |
5783 | will cause the current command to abort. | |
5784 | ||
bb70624e JA |
5785 | @item GLOBIGNORE |
5786 | A colon-separated list of patterns defining the set of filenames to | |
5787 | be ignored by filename expansion. | |
5788 | If a filename matched by a filename expansion pattern also matches one | |
28ef6c31 | 5789 | of the patterns in @env{GLOBIGNORE}, it is removed from the list |
bb70624e | 5790 | of matches. |
a0c0a00f CR |
5791 | The pattern matching honors the setting of the @code{extglob} shell |
5792 | option. | |
ccc6cda3 | 5793 | |
bb70624e JA |
5794 | @item GROUPS |
5795 | An array variable containing the list of groups of which the current | |
5796 | user is a member. | |
a0c0a00f | 5797 | Assignments to @env{GROUPS} have no effect. |
28ef6c31 | 5798 | If @env{GROUPS} is unset, it loses its special properties, even if it is |
bb70624e | 5799 | subsequently reset. |
ccc6cda3 | 5800 | |
bb70624e JA |
5801 | @item histchars |
5802 | Up to three characters which control history expansion, quick | |
5803 | substitution, and tokenization (@pxref{History Interaction}). | |
5804 | The first character is the | |
5805 | @var{history expansion} character, that is, the character which signifies the | |
5806 | start of a history expansion, normally @samp{!}. The second character is the | |
5807 | character which signifies `quick substitution' when seen as the first | |
5808 | character on a line, normally @samp{^}. The optional third character is the | |
5809 | character which indicates that the remainder of the line is a comment when | |
5810 | found as the first character of a word, usually @samp{#}. The history | |
5811 | comment character causes history substitution to be skipped for the | |
5812 | remaining words on the line. It does not necessarily cause the shell | |
5813 | parser to treat the rest of the line as a comment. | |
ccc6cda3 | 5814 | |
bb70624e JA |
5815 | @item HISTCMD |
5816 | The history number, or index in the history list, of the current | |
28ef6c31 | 5817 | command. If @env{HISTCMD} is unset, it loses its special properties, |
bb70624e | 5818 | even if it is subsequently reset. |
ccc6cda3 | 5819 | |
bb70624e | 5820 | @item HISTCONTROL |
b80f6443 JA |
5821 | A colon-separated list of values controlling how commands are saved on |
5822 | the history list. | |
5823 | If the list of values includes @samp{ignorespace}, lines which begin | |
5824 | with a space character are not saved in the history list. | |
5825 | A value of @samp{ignoredups} causes lines which match the previous | |
5826 | history entry to not be saved. | |
5827 | A value of @samp{ignoreboth} is shorthand for | |
5828 | @samp{ignorespace} and @samp{ignoredups}. | |
5829 | A value of @samp{erasedups} causes all previous lines matching the | |
5830 | current line to be removed from the history list before that line | |
5831 | is saved. | |
5832 | Any value not in the above list is ignored. | |
5833 | If @env{HISTCONTROL} is unset, or does not include a valid value, | |
5834 | all lines read by the shell parser are saved on the history list, | |
5835 | subject to the value of @env{HISTIGNORE}. | |
bb70624e JA |
5836 | The second and subsequent lines of a multi-line compound command are |
5837 | not tested, and are added to the history regardless of the value of | |
28ef6c31 | 5838 | @env{HISTCONTROL}. |
ccc6cda3 | 5839 | |
f73dda09 JA |
5840 | @item HISTFILE |
5841 | The name of the file to which the command history is saved. The | |
5842 | default value is @file{~/.bash_history}. | |
5843 | ||
5844 | @item HISTFILESIZE | |
ac50fbac CR |
5845 | The maximum number of lines contained in the history file. |
5846 | When this variable is assigned a value, the history file is truncated, | |
5847 | if necessary, to contain no more than that number of lines | |
5848 | by removing the oldest entries. | |
f73dda09 | 5849 | The history file is also truncated to this size after |
ac50fbac CR |
5850 | writing it when a shell exits. |
5851 | If the value is 0, the history file is truncated to zero size. | |
5852 | Non-numeric values and numeric values less than zero inhibit truncation. | |
5853 | The shell sets the default value to the value of @env{HISTSIZE} | |
5854 | after reading any startup files. | |
f73dda09 | 5855 | |
bb70624e JA |
5856 | @item HISTIGNORE |
5857 | A colon-separated list of patterns used to decide which command | |
5858 | lines should be saved on the history list. Each pattern is | |
5859 | anchored at the beginning of the line and must match the complete | |
5860 | line (no implicit @samp{*} is appended). Each pattern is tested | |
28ef6c31 | 5861 | against the line after the checks specified by @env{HISTCONTROL} |
bb70624e JA |
5862 | are applied. In addition to the normal shell pattern matching |
5863 | characters, @samp{&} matches the previous history line. @samp{&} | |
5864 | may be escaped using a backslash; the backslash is removed | |
5865 | before attempting a match. | |
5866 | The second and subsequent lines of a multi-line compound command are | |
5867 | not tested, and are added to the history regardless of the value of | |
28ef6c31 | 5868 | @env{HISTIGNORE}. |
a0c0a00f CR |
5869 | The pattern matching honors the setting of the @code{extglob} shell |
5870 | option. | |
ccc6cda3 | 5871 | |
28ef6c31 | 5872 | @env{HISTIGNORE} subsumes the function of @env{HISTCONTROL}. A |
bb70624e JA |
5873 | pattern of @samp{&} is identical to @code{ignoredups}, and a |
5874 | pattern of @samp{[ ]*} is identical to @code{ignorespace}. | |
5875 | Combining these two patterns, separating them with a colon, | |
5876 | provides the functionality of @code{ignoreboth}. | |
ccc6cda3 | 5877 | |
bb70624e JA |
5878 | @item HISTSIZE |
5879 | The maximum number of commands to remember on the history list. | |
ac50fbac CR |
5880 | If the value is 0, commands are not saved in the history list. |
5881 | Numeric values less than zero result in every command being saved | |
5882 | on the history list (there is no limit). | |
5883 | The shell sets the default value to 500 after reading any startup files. | |
ccc6cda3 | 5884 | |
b80f6443 JA |
5885 | @item HISTTIMEFORMAT |
5886 | If this variable is set and not null, its value is used as a format string | |
5887 | for @var{strftime} to print the time stamp associated with each history | |
5888 | entry displayed by the @code{history} builtin. | |
5889 | If this variable is set, time stamps are written to the history file so | |
5890 | they may be preserved across shell sessions. | |
3185942a JA |
5891 | This uses the history comment character to distinguish timestamps from |
5892 | other history lines. | |
b80f6443 | 5893 | |
bb70624e JA |
5894 | @item HOSTFILE |
5895 | Contains the name of a file in the same format as @file{/etc/hosts} that | |
5896 | should be read when the shell needs to complete a hostname. | |
5897 | The list of possible hostname completions may be changed while the shell | |
5898 | is running; | |
5899 | the next time hostname completion is attempted after the | |
5900 | value is changed, Bash adds the contents of the new file to the | |
5901 | existing list. | |
0001803f CR |
5902 | If @env{HOSTFILE} is set, but has no value, or does not name a readable file, |
5903 | Bash attempts to read | |
bb70624e | 5904 | @file{/etc/hosts} to obtain the list of possible hostname completions. |
28ef6c31 | 5905 | When @env{HOSTFILE} is unset, the hostname list is cleared. |
ccc6cda3 | 5906 | |
bb70624e JA |
5907 | @item HOSTNAME |
5908 | The name of the current host. | |
ccc6cda3 | 5909 | |
bb70624e JA |
5910 | @item HOSTTYPE |
5911 | A string describing the machine Bash is running on. | |
ccc6cda3 | 5912 | |
bb70624e JA |
5913 | @item IGNOREEOF |
5914 | Controls the action of the shell on receipt of an @code{EOF} character | |
5915 | as the sole input. If set, the value denotes the number | |
5916 | of consecutive @code{EOF} characters that can be read as the | |
5917 | first character on an input line | |
5918 | before the shell will exit. If the variable exists but does not | |
5919 | have a numeric value (or has no value) then the default is 10. | |
5920 | If the variable does not exist, then @code{EOF} signifies the end of | |
5921 | input to the shell. This is only in effect for interactive shells. | |
ccc6cda3 | 5922 | |
bb70624e JA |
5923 | @item INPUTRC |
5924 | The name of the Readline initialization file, overriding the default | |
5925 | of @file{~/.inputrc}. | |
ccc6cda3 | 5926 | |
bb70624e JA |
5927 | @item LANG |
5928 | Used to determine the locale category for any category not specifically | |
5929 | selected with a variable starting with @code{LC_}. | |
ccc6cda3 | 5930 | |
bb70624e | 5931 | @item LC_ALL |
28ef6c31 | 5932 | This variable overrides the value of @env{LANG} and any other |
bb70624e | 5933 | @code{LC_} variable specifying a locale category. |
ccc6cda3 | 5934 | |
bb70624e JA |
5935 | @item LC_COLLATE |
5936 | This variable determines the collation order used when sorting the | |
5937 | results of filename expansion, and | |
5938 | determines the behavior of range expressions, equivalence classes, | |
5939 | and collating sequences within filename expansion and pattern matching | |
5940 | (@pxref{Filename Expansion}). | |
ccc6cda3 | 5941 | |
bb70624e JA |
5942 | @item LC_CTYPE |
5943 | This variable determines the interpretation of characters and the | |
5944 | behavior of character classes within filename expansion and pattern | |
5945 | matching (@pxref{Filename Expansion}). | |
ccc6cda3 | 5946 | |
bb70624e JA |
5947 | @item LC_MESSAGES |
5948 | This variable determines the locale used to translate double-quoted | |
5949 | strings preceded by a @samp{$} (@pxref{Locale Translation}). | |
ccc6cda3 | 5950 | |
bb70624e JA |
5951 | @item LC_NUMERIC |
5952 | This variable determines the locale category used for number formatting. | |
ccc6cda3 | 5953 | |
a0c0a00f CR |
5954 | @item LC_TIME |
5955 | This variable determines the locale category used for data and time | |
5956 | formatting. | |
5957 | ||
f73dda09 JA |
5958 | @item LINENO |
5959 | The line number in the script or shell function currently executing. | |
5960 | ||
28ef6c31 | 5961 | @item LINES |
495aee44 | 5962 | Used by the @code{select} command to determine the column length |
ac50fbac CR |
5963 | for printing selection lists. |
5964 | Automatically set if the @code{checkwinsize} option is enabled | |
5965 | (@pxref{The Shopt Builtin}), or in an interactive shell upon receipt of a | |
28ef6c31 JA |
5966 | @code{SIGWINCH}. |
5967 | ||
bb70624e JA |
5968 | @item MACHTYPE |
5969 | A string that fully describes the system type on which Bash | |
5970 | is executing, in the standard @sc{gnu} @var{cpu-company-system} format. | |
ccc6cda3 | 5971 | |
bb70624e JA |
5972 | @item MAILCHECK |
5973 | How often (in seconds) that the shell should check for mail in the | |
28ef6c31 JA |
5974 | files specified in the @env{MAILPATH} or @env{MAIL} variables. |
5975 | The default is 60 seconds. When it is time to check | |
5976 | for mail, the shell does so before displaying the primary prompt. | |
5977 | If this variable is unset, or set to a value that is not a number | |
5978 | greater than or equal to zero, the shell disables mail checking. | |
ccc6cda3 | 5979 | |
495aee44 CR |
5980 | @item MAPFILE |
5981 | An array variable created to hold the text read by the | |
5982 | @code{mapfile} builtin when no variable name is supplied. | |
5983 | ||
bb70624e JA |
5984 | @item OLDPWD |
5985 | The previous working directory as set by the @code{cd} builtin. | |
ccc6cda3 | 5986 | |
bb70624e JA |
5987 | @item OPTERR |
5988 | If set to the value 1, Bash displays error messages | |
5989 | generated by the @code{getopts} builtin command. | |
ccc6cda3 | 5990 | |
bb70624e JA |
5991 | @item OSTYPE |
5992 | A string describing the operating system Bash is running on. | |
cce855bc | 5993 | |
bb70624e JA |
5994 | @item PIPESTATUS |
5995 | An array variable (@pxref{Arrays}) | |
5996 | containing a list of exit status values from the processes | |
5997 | in the most-recently-executed foreground pipeline (which may | |
5998 | contain only a single command). | |
cce855bc | 5999 | |
f73dda09 | 6000 | @item POSIXLY_CORRECT |
ac50fbac | 6001 | If this variable is in the environment when Bash starts, the shell |
f73dda09 JA |
6002 | enters @sc{posix} mode (@pxref{Bash POSIX Mode}) before reading the |
6003 | startup files, as if the @option{--posix} invocation option had been supplied. | |
ac50fbac | 6004 | If it is set while the shell is running, Bash enables @sc{posix} mode, |
f73dda09 JA |
6005 | as if the command |
6006 | @example | |
6007 | @code{set -o posix} | |
6008 | @end example | |
6009 | @noindent | |
6010 | had been executed. | |
6011 | ||
bb70624e JA |
6012 | @item PPID |
6013 | The process @sc{id} of the shell's parent process. This variable | |
6014 | is readonly. | |
ccc6cda3 | 6015 | |
bb70624e JA |
6016 | @item PROMPT_COMMAND |
6017 | If set, the value is interpreted as a command to execute | |
28ef6c31 | 6018 | before the printing of each primary prompt (@env{$PS1}). |
ccc6cda3 | 6019 | |
3185942a JA |
6020 | @item PROMPT_DIRTRIM |
6021 | If set to a number greater than zero, the value is used as the number of | |
6022 | trailing directory components to retain when expanding the @code{\w} and | |
ac50fbac | 6023 | @code{\W} prompt string escapes (@pxref{Controlling the Prompt}). |
3185942a JA |
6024 | Characters removed are replaced with an ellipsis. |
6025 | ||
a0c0a00f CR |
6026 | @item PS0 |
6027 | The value of this parameter is expanded like @var{PS1} | |
6028 | and displayed by interactive shells after reading a command | |
6029 | and before the command is executed. | |
6030 | ||
bb70624e JA |
6031 | @item PS3 |
6032 | The value of this variable is used as the prompt for the | |
6033 | @code{select} command. If this variable is not set, the | |
6034 | @code{select} command prompts with @samp{#? } | |
ccc6cda3 | 6035 | |
bb70624e JA |
6036 | @item PS4 |
6037 | The value is the prompt printed before the command line is echoed | |
28ef6c31 JA |
6038 | when the @option{-x} option is set (@pxref{The Set Builtin}). |
6039 | The first character of @env{PS4} is replicated multiple times, as | |
bb70624e JA |
6040 | necessary, to indicate multiple levels of indirection. |
6041 | The default is @samp{+ }. | |
ccc6cda3 | 6042 | |
bb70624e JA |
6043 | @item PWD |
6044 | The current working directory as set by the @code{cd} builtin. | |
ccc6cda3 | 6045 | |
bb70624e JA |
6046 | @item RANDOM |
6047 | Each time this parameter is referenced, a random integer | |
6048 | between 0 and 32767 is generated. Assigning a value to this | |
6049 | variable seeds the random number generator. | |
ccc6cda3 | 6050 | |
495aee44 CR |
6051 | @item READLINE_LINE |
6052 | The contents of the Readline line buffer, for use | |
6053 | with @samp{bind -x} (@pxref{Bash Builtins}). | |
6054 | ||
6055 | @item READLINE_POINT | |
6056 | The position of the insertion point in the Readline line buffer, for use | |
6057 | with @samp{bind -x} (@pxref{Bash Builtins}). | |
6058 | ||
bb70624e JA |
6059 | @item REPLY |
6060 | The default variable for the @code{read} builtin. | |
ccc6cda3 | 6061 | |
bb70624e JA |
6062 | @item SECONDS |
6063 | This variable expands to the number of seconds since the | |
6064 | shell was started. Assignment to this variable resets | |
6065 | the count to the value assigned, and the expanded value | |
6066 | becomes the value assigned plus the number of seconds | |
6067 | since the assignment. | |
ccc6cda3 | 6068 | |
b80f6443 JA |
6069 | @item SHELL |
6070 | The full pathname to the shell is kept in this environment variable. | |
6071 | If it is not set when the shell starts, | |
6072 | Bash assigns to it the full pathname of the current user's login shell. | |
6073 | ||
bb70624e JA |
6074 | @item SHELLOPTS |
6075 | A colon-separated list of enabled shell options. Each word in | |
28ef6c31 | 6076 | the list is a valid argument for the @option{-o} option to the |
bb70624e | 6077 | @code{set} builtin command (@pxref{The Set Builtin}). |
28ef6c31 | 6078 | The options appearing in @env{SHELLOPTS} are those reported |
bb70624e JA |
6079 | as @samp{on} by @samp{set -o}. |
6080 | If this variable is in the environment when Bash | |
6081 | starts up, each shell option in the list will be enabled before | |
6082 | reading any startup files. This variable is readonly. | |
ccc6cda3 | 6083 | |
bb70624e JA |
6084 | @item SHLVL |
6085 | Incremented by one each time a new instance of Bash is started. This is | |
6086 | intended to be a count of how deeply your Bash shells are nested. | |
ccc6cda3 | 6087 | |
bb70624e JA |
6088 | @item TIMEFORMAT |
6089 | The value of this parameter is used as a format string specifying | |
6090 | how the timing information for pipelines prefixed with the @code{time} | |
6091 | reserved word should be displayed. | |
6092 | The @samp{%} character introduces an | |
6093 | escape sequence that is expanded to a time value or other | |
6094 | information. | |
6095 | The escape sequences and their meanings are as | |
6096 | follows; the braces denote optional portions. | |
ccc6cda3 | 6097 | |
bb70624e | 6098 | @table @code |
ccc6cda3 | 6099 | |
bb70624e JA |
6100 | @item %% |
6101 | A literal @samp{%}. | |
ccc6cda3 | 6102 | |
bb70624e JA |
6103 | @item %[@var{p}][l]R |
6104 | The elapsed time in seconds. | |
ccc6cda3 | 6105 | |
bb70624e JA |
6106 | @item %[@var{p}][l]U |
6107 | The number of CPU seconds spent in user mode. | |
ccc6cda3 | 6108 | |
bb70624e JA |
6109 | @item %[@var{p}][l]S |
6110 | The number of CPU seconds spent in system mode. | |
ccc6cda3 | 6111 | |
bb70624e JA |
6112 | @item %P |
6113 | The CPU percentage, computed as (%U + %S) / %R. | |
6114 | @end table | |
ccc6cda3 | 6115 | |
bb70624e JA |
6116 | The optional @var{p} is a digit specifying the precision, the number of |
6117 | fractional digits after a decimal point. | |
6118 | A value of 0 causes no decimal point or fraction to be output. | |
6119 | At most three places after the decimal point may be specified; values | |
6120 | of @var{p} greater than 3 are changed to 3. | |
6121 | If @var{p} is not specified, the value 3 is used. | |
ccc6cda3 | 6122 | |
bb70624e JA |
6123 | The optional @code{l} specifies a longer format, including minutes, of |
6124 | the form @var{MM}m@var{SS}.@var{FF}s. | |
6125 | The value of @var{p} determines whether or not the fraction is included. | |
ccc6cda3 | 6126 | |
bb70624e JA |
6127 | If this variable is not set, Bash acts as if it had the value |
6128 | @example | |
6129 | @code{$'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS'} | |
6130 | @end example | |
6131 | If the value is null, no timing information is displayed. | |
6132 | A trailing newline is added when the format string is displayed. | |
ccc6cda3 | 6133 | |
bb70624e | 6134 | @item TMOUT |
7117c2d2 JA |
6135 | If set to a value greater than zero, @code{TMOUT} is treated as the |
6136 | default timeout for the @code{read} builtin (@pxref{Bash Builtins}). | |
6137 | The @code{select} command (@pxref{Conditional Constructs}) terminates | |
6138 | if input does not arrive after @code{TMOUT} seconds when input is coming | |
6139 | from a terminal. | |
6140 | ||
3185942a | 6141 | In an interactive shell, the value is interpreted as |
ac50fbac CR |
6142 | the number of seconds to wait for a line of input after issuing |
6143 | the primary prompt. | |
6144 | Bash | |
6145 | terminates after waiting for that number of seconds if a complete | |
6146 | line of input does not arrive. | |
ccc6cda3 | 6147 | |
95732b49 JA |
6148 | @item TMPDIR |
6149 | If set, Bash uses its value as the name of a directory in which | |
6150 | Bash creates temporary files for the shell's use. | |
6151 | ||
bb70624e JA |
6152 | @item UID |
6153 | The numeric real user id of the current user. This variable is readonly. | |
ccc6cda3 | 6154 | |
bb70624e | 6155 | @end vtable |
ccc6cda3 | 6156 | |
bb70624e JA |
6157 | @node Bash Features |
6158 | @chapter Bash Features | |
ccc6cda3 | 6159 | |
ac50fbac | 6160 | This chapter describes features unique to Bash. |
ccc6cda3 | 6161 | |
bb70624e JA |
6162 | @menu |
6163 | * Invoking Bash:: Command line options that you can give | |
6164 | to Bash. | |
6165 | * Bash Startup Files:: When and how Bash executes scripts. | |
6166 | * Interactive Shells:: What an interactive shell is. | |
6167 | * Bash Conditional Expressions:: Primitives used in composing expressions for | |
6168 | the @code{test} builtin. | |
6169 | * Shell Arithmetic:: Arithmetic on shell variables. | |
6170 | * Aliases:: Substituting one command for another. | |
6171 | * Arrays:: Array Variables. | |
6172 | * The Directory Stack:: History of visited directories. | |
ac50fbac | 6173 | * Controlling the Prompt:: Customizing the various prompt strings. |
bb70624e JA |
6174 | * The Restricted Shell:: A more controlled mode of shell execution. |
6175 | * Bash POSIX Mode:: Making Bash behave more closely to what | |
6176 | the POSIX standard specifies. | |
6177 | @end menu | |
ccc6cda3 | 6178 | |
bb70624e JA |
6179 | @node Invoking Bash |
6180 | @section Invoking Bash | |
ccc6cda3 | 6181 | |
bb70624e | 6182 | @example |
f73dda09 JA |
6183 | bash [long-opt] [-ir] [-abefhkmnptuvxdBCDHP] [-o @var{option}] [-O @var{shopt_option}] [@var{argument} @dots{}] |
6184 | bash [long-opt] [-abefhkmnptuvxdBCDHP] [-o @var{option}] [-O @var{shopt_option}] -c @var{string} [@var{argument} @dots{}] | |
6185 | bash [long-opt] -s [-abefhkmnptuvxdBCDHP] [-o @var{option}] [-O @var{shopt_option}] [@var{argument} @dots{}] | |
bb70624e | 6186 | @end example |
ccc6cda3 | 6187 | |
495aee44 CR |
6188 | All of the single-character options used with the @code{set} builtin |
6189 | (@pxref{The Set Builtin}) can be used as options when the shell is invoked. | |
6190 | In addition, there are several multi-character | |
bb70624e | 6191 | options that you can use. These options must appear on the command |
7117c2d2 | 6192 | line before the single-character options to be recognized. |
ccc6cda3 | 6193 | |
bb70624e | 6194 | @table @code |
b80f6443 JA |
6195 | @item --debugger |
6196 | Arrange for the debugger profile to be executed before the shell | |
3185942a | 6197 | starts. Turns on extended debugging mode (see @ref{The Shopt Builtin} |
b80f6443 | 6198 | for a description of the @code{extdebug} option to the @code{shopt} |
495aee44 | 6199 | builtin). |
b80f6443 | 6200 | |
bb70624e JA |
6201 | @item --dump-po-strings |
6202 | A list of all double-quoted strings preceded by @samp{$} | |
95732b49 | 6203 | is printed on the standard output |
bb70624e | 6204 | in the @sc{gnu} @code{gettext} PO (portable object) file format. |
28ef6c31 | 6205 | Equivalent to @option{-D} except for the output format. |
ccc6cda3 | 6206 | |
bb70624e | 6207 | @item --dump-strings |
28ef6c31 | 6208 | Equivalent to @option{-D}. |
ccc6cda3 | 6209 | |
bb70624e | 6210 | @item --help |
3185942a | 6211 | Display a usage message on standard output and exit successfully. |
ccc6cda3 | 6212 | |
28ef6c31 JA |
6213 | @item --init-file @var{filename} |
6214 | @itemx --rcfile @var{filename} | |
6215 | Execute commands from @var{filename} (instead of @file{~/.bashrc}) | |
6216 | in an interactive shell. | |
6217 | ||
bb70624e | 6218 | @item --login |
7117c2d2 | 6219 | Equivalent to @option{-l}. |
ccc6cda3 | 6220 | |
bb70624e JA |
6221 | @item --noediting |
6222 | Do not use the @sc{gnu} Readline library (@pxref{Command Line Editing}) | |
6223 | to read command lines when the shell is interactive. | |
ccc6cda3 | 6224 | |
bb70624e JA |
6225 | @item --noprofile |
6226 | Don't load the system-wide startup file @file{/etc/profile} | |
6227 | or any of the personal initialization files | |
6228 | @file{~/.bash_profile}, @file{~/.bash_login}, or @file{~/.profile} | |
6229 | when Bash is invoked as a login shell. | |
ccc6cda3 | 6230 | |
bb70624e JA |
6231 | @item --norc |
6232 | Don't read the @file{~/.bashrc} initialization file in an | |
6233 | interactive shell. This is on by default if the shell is | |
6234 | invoked as @code{sh}. | |
ccc6cda3 | 6235 | |
bb70624e JA |
6236 | @item --posix |
6237 | Change the behavior of Bash where the default operation differs | |
0628567a | 6238 | from the @sc{posix} standard to match the standard. This |
bb70624e JA |
6239 | is intended to make Bash behave as a strict superset of that |
6240 | standard. @xref{Bash POSIX Mode}, for a description of the Bash | |
6241 | @sc{posix} mode. | |
ccc6cda3 | 6242 | |
bb70624e JA |
6243 | @item --restricted |
6244 | Make the shell a restricted shell (@pxref{The Restricted Shell}). | |
ccc6cda3 | 6245 | |
bb70624e | 6246 | @item --verbose |
28ef6c31 | 6247 | Equivalent to @option{-v}. Print shell input lines as they're read. |
ccc6cda3 | 6248 | |
bb70624e JA |
6249 | @item --version |
6250 | Show version information for this instance of | |
6251 | Bash on the standard output and exit successfully. | |
ccc6cda3 JA |
6252 | @end table |
6253 | ||
bb70624e JA |
6254 | There are several single-character options that may be supplied at |
6255 | invocation which are not available with the @code{set} builtin. | |
cce855bc | 6256 | |
bb70624e | 6257 | @table @code |
ac50fbac | 6258 | @item -c |
a0c0a00f CR |
6259 | Read and execute commands from the first non-option argument |
6260 | @var{command_string}, then exit. | |
6261 | If there are arguments after the @var{command_string}, | |
6262 | the first argument is assigned to @code{$0} | |
6263 | and any remaining arguments are assigned to the positional parameters. | |
6264 | The assignment to @code{$0} sets the name of the shell, which is used | |
6265 | in warning and error messages. | |
ccc6cda3 | 6266 | |
bb70624e JA |
6267 | @item -i |
6268 | Force the shell to run interactively. Interactive shells are | |
6269 | described in @ref{Interactive Shells}. | |
ccc6cda3 | 6270 | |
7117c2d2 JA |
6271 | @item -l |
6272 | Make this shell act as if it had been directly invoked by login. | |
6273 | When the shell is interactive, this is equivalent to starting a | |
6274 | login shell with @samp{exec -l bash}. | |
6275 | When the shell is not interactive, the login shell startup files will | |
6276 | be executed. | |
6277 | @samp{exec bash -l} or @samp{exec bash --login} | |
6278 | will replace the current shell with a Bash login shell. | |
6279 | @xref{Bash Startup Files}, for a description of the special behavior | |
6280 | of a login shell. | |
6281 | ||
bb70624e JA |
6282 | @item -r |
6283 | Make the shell a restricted shell (@pxref{The Restricted Shell}). | |
ccc6cda3 | 6284 | |
bb70624e JA |
6285 | @item -s |
6286 | If this option is present, or if no arguments remain after option | |
6287 | processing, then commands are read from the standard input. | |
6288 | This option allows the positional parameters to be set | |
6289 | when invoking an interactive shell. | |
6290 | ||
6291 | @item -D | |
6292 | A list of all double-quoted strings preceded by @samp{$} | |
95732b49 | 6293 | is printed on the standard output. |
bb70624e JA |
6294 | These are the strings that |
6295 | are subject to language translation when the current locale | |
6296 | is not @code{C} or @code{POSIX} (@pxref{Locale Translation}). | |
28ef6c31 | 6297 | This implies the @option{-n} option; no commands will be executed. |
bb70624e | 6298 | |
f73dda09 JA |
6299 | @item [-+]O [@var{shopt_option}] |
6300 | @var{shopt_option} is one of the shell options accepted by the | |
3185942a | 6301 | @code{shopt} builtin (@pxref{The Shopt Builtin}). |
f73dda09 JA |
6302 | If @var{shopt_option} is present, @option{-O} sets the value of that option; |
6303 | @option{+O} unsets it. | |
6304 | If @var{shopt_option} is not supplied, the names and values of the shell | |
6305 | options accepted by @code{shopt} are printed on the standard output. | |
6306 | If the invocation option is @option{+O}, the output is displayed in a format | |
6307 | that may be reused as input. | |
6308 | ||
bb70624e JA |
6309 | @item -- |
6310 | A @code{--} signals the end of options and disables further option | |
6311 | processing. | |
6312 | Any arguments after the @code{--} are treated as filenames and arguments. | |
bb70624e JA |
6313 | @end table |
6314 | ||
f73dda09 JA |
6315 | @cindex login shell |
6316 | A @emph{login} shell is one whose first character of argument zero is | |
6317 | @samp{-}, or one invoked with the @option{--login} option. | |
6318 | ||
bb70624e JA |
6319 | @cindex interactive shell |
6320 | An @emph{interactive} shell is one started without non-option arguments, | |
28ef6c31 JA |
6321 | unless @option{-s} is specified, |
6322 | without specifying the @option{-c} option, and whose input and output are both | |
bb70624e | 6323 | connected to terminals (as determined by @code{isatty(3)}), or one |
28ef6c31 | 6324 | started with the @option{-i} option. @xref{Interactive Shells}, for more |
bb70624e JA |
6325 | information. |
6326 | ||
6327 | If arguments remain after option processing, and neither the | |
28ef6c31 | 6328 | @option{-c} nor the @option{-s} |
bb70624e JA |
6329 | option has been supplied, the first argument is assumed to |
6330 | be the name of a file containing shell commands (@pxref{Shell Scripts}). | |
6331 | When Bash is invoked in this fashion, @code{$0} | |
6332 | is set to the name of the file, and the positional parameters | |
6333 | are set to the remaining arguments. | |
6334 | Bash reads and executes commands from this file, then exits. | |
6335 | Bash's exit status is the exit status of the last command executed | |
6336 | in the script. If no commands are executed, the exit status is 0. | |
6337 | ||
6338 | @node Bash Startup Files | |
6339 | @section Bash Startup Files | |
6340 | @cindex startup files | |
6341 | ||
3185942a | 6342 | This section describes how Bash executes its startup files. |
bb70624e | 6343 | If any of the files exist but cannot be read, Bash reports an error. |
ac50fbac | 6344 | Tildes are expanded in filenames as described above under |
bb70624e JA |
6345 | Tilde Expansion (@pxref{Tilde Expansion}). |
6346 | ||
6347 | Interactive shells are described in @ref{Interactive Shells}. | |
6348 | ||
28ef6c31 | 6349 | @subsubheading Invoked as an interactive login shell, or with @option{--login} |
bb70624e JA |
6350 | |
6351 | When Bash is invoked as an interactive login shell, or as a | |
28ef6c31 | 6352 | non-interactive shell with the @option{--login} option, it first reads and |
bb70624e JA |
6353 | executes commands from the file @file{/etc/profile}, if that file exists. |
6354 | After reading that file, it looks for @file{~/.bash_profile}, | |
6355 | @file{~/.bash_login}, and @file{~/.profile}, in that order, and reads | |
6356 | and executes commands from the first one that exists and is readable. | |
28ef6c31 | 6357 | The @option{--noprofile} option may be used when the shell is started to |
bb70624e JA |
6358 | inhibit this behavior. |
6359 | ||
a0c0a00f CR |
6360 | When an interactive login shell exits, |
6361 | or a non-interactive login shell executes the @code{exit} builtin command, | |
6362 | Bash reads and executes commands from | |
bb70624e JA |
6363 | the file @file{~/.bash_logout}, if it exists. |
6364 | ||
6365 | @subsubheading Invoked as an interactive non-login shell | |
6366 | ||
6367 | When an interactive shell that is not a login shell is started, Bash | |
6368 | reads and executes commands from @file{~/.bashrc}, if that file exists. | |
28ef6c31 JA |
6369 | This may be inhibited by using the @option{--norc} option. |
6370 | The @option{--rcfile @var{file}} option will force Bash to read and | |
bb70624e JA |
6371 | execute commands from @var{file} instead of @file{~/.bashrc}. |
6372 | ||
6373 | So, typically, your @file{~/.bash_profile} contains the line | |
6374 | @example | |
6375 | @code{if [ -f ~/.bashrc ]; then . ~/.bashrc; fi} | |
6376 | @end example | |
6377 | @noindent | |
6378 | after (or before) any login-specific initializations. | |
6379 | ||
6380 | @subsubheading Invoked non-interactively | |
6381 | ||
6382 | When Bash is started non-interactively, to run a shell script, | |
28ef6c31 | 6383 | for example, it looks for the variable @env{BASH_ENV} in the environment, |
bb70624e JA |
6384 | expands its value if it appears there, and uses the expanded value as |
6385 | the name of a file to read and execute. Bash behaves as if the | |
6386 | following command were executed: | |
6387 | @example | |
6388 | @code{if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi} | |
6389 | @end example | |
6390 | @noindent | |
28ef6c31 | 6391 | but the value of the @env{PATH} variable is not used to search for the |
ac50fbac | 6392 | filename. |
bb70624e | 6393 | |
28ef6c31 JA |
6394 | As noted above, if a non-interactive shell is invoked with the |
6395 | @option{--login} option, Bash attempts to read and execute commands from the | |
6396 | login shell startup files. | |
6397 | ||
bb70624e JA |
6398 | @subsubheading Invoked with name @code{sh} |
6399 | ||
6400 | If Bash is invoked with the name @code{sh}, it tries to mimic the | |
6401 | startup behavior of historical versions of @code{sh} as closely as | |
6402 | possible, while conforming to the @sc{posix} standard as well. | |
6403 | ||
6404 | When invoked as an interactive login shell, or as a non-interactive | |
28ef6c31 | 6405 | shell with the @option{--login} option, it first attempts to read |
bb70624e JA |
6406 | and execute commands from @file{/etc/profile} and @file{~/.profile}, in |
6407 | that order. | |
28ef6c31 | 6408 | The @option{--noprofile} option may be used to inhibit this behavior. |
bb70624e | 6409 | When invoked as an interactive shell with the name @code{sh}, Bash |
28ef6c31 | 6410 | looks for the variable @env{ENV}, expands its value if it is defined, |
bb70624e JA |
6411 | and uses the expanded value as the name of a file to read and execute. |
6412 | Since a shell invoked as @code{sh} does not attempt to read and execute | |
28ef6c31 | 6413 | commands from any other startup files, the @option{--rcfile} option has |
bb70624e JA |
6414 | no effect. |
6415 | A non-interactive shell invoked with the name @code{sh} does not attempt | |
6416 | to read any other startup files. | |
6417 | ||
6418 | When invoked as @code{sh}, Bash enters @sc{posix} mode after | |
6419 | the startup files are read. | |
6420 | ||
6421 | @subsubheading Invoked in @sc{posix} mode | |
6422 | ||
6423 | When Bash is started in @sc{posix} mode, as with the | |
28ef6c31 | 6424 | @option{--posix} command line option, it follows the @sc{posix} standard |
bb70624e | 6425 | for startup files. |
28ef6c31 | 6426 | In this mode, interactive shells expand the @env{ENV} variable |
bb70624e JA |
6427 | and commands are read and executed from the file whose name is the |
6428 | expanded value. | |
6429 | No other startup files are read. | |
6430 | ||
6431 | @subsubheading Invoked by remote shell daemon | |
6432 | ||
3185942a | 6433 | Bash attempts to determine when it is being run with its standard input |
495aee44 | 6434 | connected to a network connection, as when executed by the remote shell |
3185942a JA |
6435 | daemon, usually @code{rshd}, or the secure shell daemon @code{sshd}. |
6436 | If Bash determines it is being run in | |
6437 | this fashion, it reads and executes commands from @file{~/.bashrc}, if that | |
bb70624e JA |
6438 | file exists and is readable. |
6439 | It will not do this if invoked as @code{sh}. | |
28ef6c31 JA |
6440 | The @option{--norc} option may be used to inhibit this behavior, and the |
6441 | @option{--rcfile} option may be used to force another file to be read, but | |
ac50fbac CR |
6442 | neither @code{rshd} nor @code{sshd} generally invoke the shell with those |
6443 | options or allow them to be specified. | |
bb70624e JA |
6444 | |
6445 | @subsubheading Invoked with unequal effective and real @sc{uid/gid}s | |
6446 | ||
6447 | If Bash is started with the effective user (group) id not equal to the | |
ac50fbac | 6448 | real user (group) id, and the @option{-p} option is not supplied, no startup |
bb70624e | 6449 | files are read, shell functions are not inherited from the environment, |
0001803f CR |
6450 | the @env{SHELLOPTS}, @env{BASHOPTS}, @env{CDPATH}, and @env{GLOBIGNORE} |
6451 | variables, if they appear in the environment, are ignored, and the effective | |
6452 | user id is set to the real user id. | |
ac50fbac | 6453 | If the @option{-p} option is supplied at invocation, the startup behavior is |
bb70624e JA |
6454 | the same, but the effective user id is not reset. |
6455 | ||
6456 | @node Interactive Shells | |
6457 | @section Interactive Shells | |
6458 | @cindex interactive shell | |
6459 | @cindex shell, interactive | |
6460 | ||
6461 | @menu | |
6462 | * What is an Interactive Shell?:: What determines whether a shell is Interactive. | |
6463 | * Is this Shell Interactive?:: How to tell if a shell is interactive. | |
6464 | * Interactive Shell Behavior:: What changes in a interactive shell? | |
6465 | @end menu | |
6466 | ||
6467 | @node What is an Interactive Shell? | |
6468 | @subsection What is an Interactive Shell? | |
6469 | ||
6470 | An interactive shell | |
28ef6c31 | 6471 | is one started without non-option arguments, unless @option{-s} is |
3185942a | 6472 | specified, without specifying the @option{-c} option, and |
b80f6443 | 6473 | whose input and error output are both |
bb70624e | 6474 | connected to terminals (as determined by @code{isatty(3)}), |
28ef6c31 | 6475 | or one started with the @option{-i} option. |
bb70624e JA |
6476 | |
6477 | An interactive shell generally reads from and writes to a user's | |
6478 | terminal. | |
6479 | ||
28ef6c31 | 6480 | The @option{-s} invocation option may be used to set the positional parameters |
bb70624e JA |
6481 | when an interactive shell is started. |
6482 | ||
6483 | @node Is this Shell Interactive? | |
6484 | @subsection Is this Shell Interactive? | |
6485 | ||
6486 | To determine within a startup script whether or not Bash is | |
6487 | running interactively, | |
6488 | test the value of the @samp{-} special parameter. | |
6489 | It contains @code{i} when the shell is interactive. For example: | |
6490 | ||
6491 | @example | |
6492 | case "$-" in | |
6493 | *i*) echo This shell is interactive ;; | |
6494 | *) echo This shell is not interactive ;; | |
6495 | esac | |
6496 | @end example | |
6497 | ||
6498 | Alternatively, startup scripts may examine the variable | |
28ef6c31 | 6499 | @env{PS1}; it is unset in non-interactive shells, and set in |
bb70624e JA |
6500 | interactive shells. Thus: |
6501 | ||
6502 | @example | |
6503 | if [ -z "$PS1" ]; then | |
6504 | echo This shell is not interactive | |
6505 | else | |
6506 | echo This shell is interactive | |
6507 | fi | |
6508 | @end example | |
6509 | ||
6510 | @node Interactive Shell Behavior | |
6511 | @subsection Interactive Shell Behavior | |
6512 | ||
6513 | When the shell is running interactively, it changes its behavior in | |
6514 | several ways. | |
6515 | ||
6516 | @enumerate | |
6517 | @item | |
6518 | Startup files are read and executed as described in @ref{Bash Startup Files}. | |
6519 | ||
6520 | @item | |
6521 | Job Control (@pxref{Job Control}) is enabled by default. When job | |
6522 | control is in effect, Bash ignores the keyboard-generated job control | |
6523 | signals @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}. | |
6524 | ||
6525 | @item | |
28ef6c31 JA |
6526 | Bash expands and displays @env{PS1} before reading the first line |
6527 | of a command, and expands and displays @env{PS2} before reading the | |
bb70624e | 6528 | second and subsequent lines of a multi-line command. |
a0c0a00f | 6529 | Bash displays @env{PS0} after it reads a command but before executing it. |
bb70624e JA |
6530 | |
6531 | @item | |
28ef6c31 JA |
6532 | Bash executes the value of the @env{PROMPT_COMMAND} variable as a command |
6533 | before printing the primary prompt, @env{$PS1} | |
bb70624e JA |
6534 | (@pxref{Bash Variables}). |
6535 | ||
6536 | @item | |
6537 | Readline (@pxref{Command Line Editing}) is used to read commands from | |
6538 | the user's terminal. | |
6539 | ||
6540 | @item | |
6541 | Bash inspects the value of the @code{ignoreeof} option to @code{set -o} | |
6542 | instead of exiting immediately when it receives an @code{EOF} on its | |
6543 | standard input when reading a command (@pxref{The Set Builtin}). | |
6544 | ||
6545 | @item | |
6546 | Command history (@pxref{Bash History Facilities}) | |
6547 | and history expansion (@pxref{History Interaction}) | |
6548 | are enabled by default. | |
28ef6c31 | 6549 | Bash will save the command history to the file named by @env{$HISTFILE} |
ac50fbac | 6550 | when a shell with history enabled exits. |
bb70624e JA |
6551 | |
6552 | @item | |
6553 | Alias expansion (@pxref{Aliases}) is performed by default. | |
6554 | ||
6555 | @item | |
6556 | In the absence of any traps, Bash ignores @code{SIGTERM} | |
6557 | (@pxref{Signals}). | |
6558 | ||
6559 | @item | |
6560 | In the absence of any traps, @code{SIGINT} is caught and handled | |
6561 | ((@pxref{Signals}). | |
6562 | @code{SIGINT} will interrupt some shell builtins. | |
6563 | ||
6564 | @item | |
6565 | An interactive login shell sends a @code{SIGHUP} to all jobs on exit | |
3185942a | 6566 | if the @code{huponexit} shell option has been enabled (@pxref{Signals}). |
bb70624e JA |
6567 | |
6568 | @item | |
28ef6c31 | 6569 | The @option{-n} invocation option is ignored, and @samp{set -n} has |
bb70624e JA |
6570 | no effect (@pxref{The Set Builtin}). |
6571 | ||
6572 | @item | |
6573 | Bash will check for mail periodically, depending on the values of the | |
28ef6c31 | 6574 | @env{MAIL}, @env{MAILPATH}, and @env{MAILCHECK} shell variables |
bb70624e JA |
6575 | (@pxref{Bash Variables}). |
6576 | ||
6577 | @item | |
6578 | Expansion errors due to references to unbound shell variables after | |
6579 | @samp{set -u} has been enabled will not cause the shell to exit | |
6580 | (@pxref{The Set Builtin}). | |
6581 | ||
6582 | @item | |
6583 | The shell will not exit on expansion errors caused by @var{var} being unset | |
6584 | or null in @code{$@{@var{var}:?@var{word}@}} expansions | |
6585 | (@pxref{Shell Parameter Expansion}). | |
6586 | ||
6587 | @item | |
6588 | Redirection errors encountered by shell builtins will not cause the | |
6589 | shell to exit. | |
6590 | ||
6591 | @item | |
6592 | When running in @sc{posix} mode, a special builtin returning an error | |
6593 | status will not cause the shell to exit (@pxref{Bash POSIX Mode}). | |
95732b49 | 6594 | |
bb70624e JA |
6595 | @item |
6596 | A failed @code{exec} will not cause the shell to exit | |
6597 | (@pxref{Bourne Shell Builtins}). | |
6598 | ||
6599 | @item | |
6600 | Parser syntax errors will not cause the shell to exit. | |
6601 | ||
6602 | @item | |
6603 | Simple spelling correction for directory arguments to the @code{cd} | |
6604 | builtin is enabled by default (see the description of the @code{cdspell} | |
3185942a | 6605 | option to the @code{shopt} builtin in @ref{The Shopt Builtin}). |
bb70624e JA |
6606 | |
6607 | @item | |
28ef6c31 | 6608 | The shell will check the value of the @env{TMOUT} variable and exit |
bb70624e | 6609 | if a command is not read within the specified number of seconds after |
28ef6c31 | 6610 | printing @env{$PS1} (@pxref{Bash Variables}). |
bb70624e JA |
6611 | |
6612 | @end enumerate | |
6613 | ||
6614 | @node Bash Conditional Expressions | |
6615 | @section Bash Conditional Expressions | |
6616 | @cindex expressions, conditional | |
6617 | ||
6618 | Conditional expressions are used by the @code{[[} compound command | |
6619 | and the @code{test} and @code{[} builtin commands. | |
6620 | ||
6621 | Expressions may be unary or binary. | |
6622 | Unary expressions are often used to examine the status of a file. | |
6623 | There are string operators and numeric comparison operators as well. | |
a0c0a00f CR |
6624 | Bash handles several filenames specially when they are used in |
6625 | expressions. | |
6626 | If the operating system on which Bash is running provides these | |
6627 | special files, Bash will use them; otherwise it will emulate them | |
6628 | internally with this behavior: | |
bb70624e JA |
6629 | If the @var{file} argument to one of the primaries is of the form |
6630 | @file{/dev/fd/@var{N}}, then file descriptor @var{N} is checked. | |
6631 | If the @var{file} argument to one of the primaries is one of | |
6632 | @file{/dev/stdin}, @file{/dev/stdout}, or @file{/dev/stderr}, file | |
6633 | descriptor 0, 1, or 2, respectively, is checked. | |
ccc6cda3 | 6634 | |
ac50fbac | 6635 | When used with @code{[[}, the @samp{<} and @samp{>} operators sort |
0001803f | 6636 | lexicographically using the current locale. |
495aee44 | 6637 | The @code{test} command uses ASCII ordering. |
0001803f | 6638 | |
95732b49 JA |
6639 | Unless otherwise specified, primaries that operate on files follow symbolic |
6640 | links and operate on the target of the link, rather than the link itself. | |
6641 | ||
ccc6cda3 | 6642 | @table @code |
cce855bc JA |
6643 | @item -a @var{file} |
6644 | True if @var{file} exists. | |
6645 | ||
ccc6cda3 JA |
6646 | @item -b @var{file} |
6647 | True if @var{file} exists and is a block special file. | |
6648 | ||
6649 | @item -c @var{file} | |
6650 | True if @var{file} exists and is a character special file. | |
6651 | ||
6652 | @item -d @var{file} | |
6653 | True if @var{file} exists and is a directory. | |
6654 | ||
6655 | @item -e @var{file} | |
6656 | True if @var{file} exists. | |
6657 | ||
6658 | @item -f @var{file} | |
6659 | True if @var{file} exists and is a regular file. | |
6660 | ||
6661 | @item -g @var{file} | |
cce855bc | 6662 | True if @var{file} exists and its set-group-id bit is set. |
ccc6cda3 | 6663 | |
b72432fd JA |
6664 | @item -h @var{file} |
6665 | True if @var{file} exists and is a symbolic link. | |
6666 | ||
ccc6cda3 | 6667 | @item -k @var{file} |
cce855bc | 6668 | True if @var{file} exists and its "sticky" bit is set. |
ccc6cda3 JA |
6669 | |
6670 | @item -p @var{file} | |
cce855bc | 6671 | True if @var{file} exists and is a named pipe (FIFO). |
ccc6cda3 JA |
6672 | |
6673 | @item -r @var{file} | |
6674 | True if @var{file} exists and is readable. | |
6675 | ||
6676 | @item -s @var{file} | |
6677 | True if @var{file} exists and has a size greater than zero. | |
6678 | ||
ccc6cda3 | 6679 | @item -t @var{fd} |
cce855bc | 6680 | True if file descriptor @var{fd} is open and refers to a terminal. |
ccc6cda3 JA |
6681 | |
6682 | @item -u @var{file} | |
6683 | True if @var{file} exists and its set-user-id bit is set. | |
6684 | ||
6685 | @item -w @var{file} | |
6686 | True if @var{file} exists and is writable. | |
6687 | ||
6688 | @item -x @var{file} | |
6689 | True if @var{file} exists and is executable. | |
6690 | ||
ccc6cda3 JA |
6691 | @item -G @var{file} |
6692 | True if @var{file} exists and is owned by the effective group id. | |
6693 | ||
cce855bc JA |
6694 | @item -L @var{file} |
6695 | True if @var{file} exists and is a symbolic link. | |
6696 | ||
495aee44 CR |
6697 | @item -N @var{file} |
6698 | True if @var{file} exists and has been modified since it was last read. | |
6699 | ||
6700 | @item -O @var{file} | |
6701 | True if @var{file} exists and is owned by the effective user id. | |
6702 | ||
cce855bc JA |
6703 | @item -S @var{file} |
6704 | True if @var{file} exists and is a socket. | |
6705 | ||
495aee44 CR |
6706 | @item @var{file1} -ef @var{file2} |
6707 | True if @var{file1} and @var{file2} refer to the same device and | |
6708 | inode numbers. | |
cce855bc | 6709 | |
ccc6cda3 | 6710 | @item @var{file1} -nt @var{file2} |
7117c2d2 JA |
6711 | True if @var{file1} is newer (according to modification date) |
6712 | than @var{file2}, or if @var{file1} exists and @var{file2} does not. | |
ccc6cda3 JA |
6713 | |
6714 | @item @var{file1} -ot @var{file2} | |
7117c2d2 JA |
6715 | True if @var{file1} is older than @var{file2}, |
6716 | or if @var{file2} exists and @var{file1} does not. | |
ccc6cda3 | 6717 | |
ccc6cda3 | 6718 | @item -o @var{optname} |
495aee44 | 6719 | True if the shell option @var{optname} is enabled. |
28ef6c31 | 6720 | The list of options appears in the description of the @option{-o} |
ccc6cda3 JA |
6721 | option to the @code{set} builtin (@pxref{The Set Builtin}). |
6722 | ||
495aee44 CR |
6723 | @item -v @var{varname} |
6724 | True if the shell variable @var{varname} is set (has been assigned a value). | |
6725 | ||
ac50fbac CR |
6726 | @item -R @var{varname} |
6727 | True if the shell variable @var{varname} is set and is a name reference. | |
6728 | ||
ccc6cda3 JA |
6729 | @item -z @var{string} |
6730 | True if the length of @var{string} is zero. | |
6731 | ||
6732 | @item -n @var{string} | |
6733 | @itemx @var{string} | |
6734 | True if the length of @var{string} is non-zero. | |
6735 | ||
cce855bc | 6736 | @item @var{string1} == @var{string2} |
0001803f | 6737 | @itemx @var{string1} = @var{string2} |
cce855bc | 6738 | True if the strings are equal. |
ac50fbac CR |
6739 | When used with the @code{[[} command, this performs pattern matching as |
6740 | described above (@pxref{Conditional Constructs}). | |
6741 | ||
0001803f | 6742 | @samp{=} should be used with the @code{test} command for @sc{posix} conformance. |
ccc6cda3 JA |
6743 | |
6744 | @item @var{string1} != @var{string2} | |
6745 | True if the strings are not equal. | |
6746 | ||
6747 | @item @var{string1} < @var{string2} | |
0001803f | 6748 | True if @var{string1} sorts before @var{string2} lexicographically. |
ccc6cda3 JA |
6749 | |
6750 | @item @var{string1} > @var{string2} | |
0001803f | 6751 | True if @var{string1} sorts after @var{string2} lexicographically. |
ccc6cda3 JA |
6752 | |
6753 | @item @var{arg1} OP @var{arg2} | |
6754 | @code{OP} is one of | |
6755 | @samp{-eq}, @samp{-ne}, @samp{-lt}, @samp{-le}, @samp{-gt}, or @samp{-ge}. | |
6756 | These arithmetic binary operators return true if @var{arg1} | |
6757 | is equal to, not equal to, less than, less than or equal to, | |
6758 | greater than, or greater than or equal to @var{arg2}, | |
6759 | respectively. @var{Arg1} and @var{arg2} | |
6760 | may be positive or negative integers. | |
ccc6cda3 JA |
6761 | @end table |
6762 | ||
bb70624e JA |
6763 | @node Shell Arithmetic |
6764 | @section Shell Arithmetic | |
6765 | @cindex arithmetic, shell | |
6766 | @cindex shell arithmetic | |
6767 | @cindex expressions, arithmetic | |
6768 | @cindex evaluation, arithmetic | |
6769 | @cindex arithmetic evaluation | |
ccc6cda3 | 6770 | |
bb70624e | 6771 | The shell allows arithmetic expressions to be evaluated, as one of |
a0c0a00f CR |
6772 | the shell expansions or by using the @code{((} compound command, the |
6773 | @code{let} builtin, or the @option{-i} option to the @code{declare} builtin. | |
ccc6cda3 | 6774 | |
7117c2d2 | 6775 | Evaluation is done in fixed-width integers with no check for overflow, |
bb70624e | 6776 | though division by 0 is trapped and flagged as an error. |
b80f6443 JA |
6777 | The operators and their precedence, associativity, and values |
6778 | are the same as in the C language. | |
bb70624e JA |
6779 | The following list of operators is grouped into levels of |
6780 | equal-precedence operators. | |
6781 | The levels are listed in order of decreasing precedence. | |
cce855bc | 6782 | |
bb70624e | 6783 | @table @code |
d166f048 | 6784 | |
bb70624e JA |
6785 | @item @var{id}++ @var{id}-- |
6786 | variable post-increment and post-decrement | |
cce855bc | 6787 | |
bb70624e JA |
6788 | @item ++@var{id} --@var{id} |
6789 | variable pre-increment and pre-decrement | |
ccc6cda3 | 6790 | |
bb70624e JA |
6791 | @item - + |
6792 | unary minus and plus | |
ccc6cda3 | 6793 | |
bb70624e JA |
6794 | @item ! ~ |
6795 | logical and bitwise negation | |
ccc6cda3 | 6796 | |
bb70624e JA |
6797 | @item ** |
6798 | exponentiation | |
ccc6cda3 | 6799 | |
bb70624e JA |
6800 | @item * / % |
6801 | multiplication, division, remainder | |
ccc6cda3 | 6802 | |
bb70624e JA |
6803 | @item + - |
6804 | addition, subtraction | |
cce855bc | 6805 | |
bb70624e JA |
6806 | @item << >> |
6807 | left and right bitwise shifts | |
cce855bc | 6808 | |
bb70624e JA |
6809 | @item <= >= < > |
6810 | comparison | |
ccc6cda3 | 6811 | |
bb70624e JA |
6812 | @item == != |
6813 | equality and inequality | |
ccc6cda3 | 6814 | |
bb70624e JA |
6815 | @item & |
6816 | bitwise AND | |
ccc6cda3 | 6817 | |
bb70624e JA |
6818 | @item ^ |
6819 | bitwise exclusive OR | |
ccc6cda3 | 6820 | |
bb70624e JA |
6821 | @item | |
6822 | bitwise OR | |
cce855bc | 6823 | |
bb70624e JA |
6824 | @item && |
6825 | logical AND | |
cce855bc | 6826 | |
bb70624e JA |
6827 | @item || |
6828 | logical OR | |
cce855bc | 6829 | |
bb70624e | 6830 | @item expr ? expr : expr |
b80f6443 | 6831 | conditional operator |
cce855bc | 6832 | |
bb70624e JA |
6833 | @item = *= /= %= += -= <<= >>= &= ^= |= |
6834 | assignment | |
cce855bc | 6835 | |
bb70624e JA |
6836 | @item expr1 , expr2 |
6837 | comma | |
6838 | @end table | |
ccc6cda3 | 6839 | |
bb70624e JA |
6840 | Shell variables are allowed as operands; parameter expansion is |
6841 | performed before the expression is evaluated. | |
6842 | Within an expression, shell variables may also be referenced by name | |
6843 | without using the parameter expansion syntax. | |
b80f6443 JA |
6844 | A shell variable that is null or unset evaluates to 0 when referenced |
6845 | by name without using the parameter expansion syntax. | |
bb70624e | 6846 | The value of a variable is evaluated as an arithmetic expression |
b80f6443 JA |
6847 | when it is referenced, or when a variable which has been given the |
6848 | @var{integer} attribute using @samp{declare -i} is assigned a value. | |
6849 | A null value evaluates to 0. | |
495aee44 | 6850 | A shell variable need not have its @var{integer} attribute turned on |
bb70624e | 6851 | to be used in an expression. |
ccc6cda3 | 6852 | |
bb70624e JA |
6853 | Constants with a leading 0 are interpreted as octal numbers. |
6854 | A leading @samp{0x} or @samp{0X} denotes hexadecimal. Otherwise, | |
495aee44 | 6855 | numbers take the form [@var{base}@code{#}]@var{n}, where the optional @var{base} |
bb70624e | 6856 | is a decimal number between 2 and 64 representing the arithmetic |
ac50fbac CR |
6857 | base, and @var{n} is a number in that base. |
6858 | If @var{base}@code{#} is omitted, then base 10 is used. | |
6859 | When specifying @var{n}, | |
a0c0a00f | 6860 | the digits greater than 9 are represented by the lowercase letters, |
f73dda09 | 6861 | the uppercase letters, @samp{@@}, and @samp{_}, in that order. |
bb70624e | 6862 | If @var{base} is less than or equal to 36, lowercase and uppercase |
95732b49 | 6863 | letters may be used interchangeably to represent numbers between 10 |
bb70624e | 6864 | and 35. |
ccc6cda3 | 6865 | |
bb70624e JA |
6866 | Operators are evaluated in order of precedence. Sub-expressions in |
6867 | parentheses are evaluated first and may override the precedence | |
6868 | rules above. | |
ccc6cda3 | 6869 | |
bb70624e JA |
6870 | @node Aliases |
6871 | @section Aliases | |
6872 | @cindex alias expansion | |
ccc6cda3 | 6873 | |
bb70624e JA |
6874 | @var{Aliases} allow a string to be substituted for a word when it is used |
6875 | as the first word of a simple command. | |
6876 | The shell maintains a list of aliases that may be set and unset with | |
6877 | the @code{alias} and @code{unalias} builtin commands. | |
ccc6cda3 | 6878 | |
bb70624e JA |
6879 | The first word of each simple command, if unquoted, is checked to see |
6880 | if it has an alias. | |
6881 | If so, that word is replaced by the text of the alias. | |
b80f6443 JA |
6882 | The characters @samp{/}, @samp{$}, @samp{`}, @samp{=} and any of the |
6883 | shell metacharacters or quoting characters listed above may not appear | |
6884 | in an alias name. | |
6885 | The replacement text may contain any valid | |
6886 | shell input, including shell metacharacters. | |
bb70624e JA |
6887 | The first word of the replacement text is tested for |
6888 | aliases, but a word that is identical to an alias being expanded | |
b80f6443 JA |
6889 | is not expanded a second time. |
6890 | This means that one may alias @code{ls} to @code{"ls -F"}, | |
bb70624e | 6891 | for instance, and Bash does not try to recursively expand the |
ac50fbac CR |
6892 | replacement text. |
6893 | If the last character of the alias value is a | |
6894 | @var{blank}, then the next command word following the | |
bb70624e | 6895 | alias is also checked for alias expansion. |
ccc6cda3 | 6896 | |
bb70624e JA |
6897 | Aliases are created and listed with the @code{alias} |
6898 | command, and removed with the @code{unalias} command. | |
ccc6cda3 | 6899 | |
bb70624e JA |
6900 | There is no mechanism for using arguments in the replacement text, |
6901 | as in @code{csh}. | |
6902 | If arguments are needed, a shell function should be used | |
6903 | (@pxref{Shell Functions}). | |
ccc6cda3 | 6904 | |
bb70624e JA |
6905 | Aliases are not expanded when the shell is not interactive, |
6906 | unless the @code{expand_aliases} shell option is set using | |
3185942a | 6907 | @code{shopt} (@pxref{The Shopt Builtin}). |
ccc6cda3 | 6908 | |
bb70624e JA |
6909 | The rules concerning the definition and use of aliases are |
6910 | somewhat confusing. Bash | |
6911 | always reads at least one complete line | |
6912 | of input before executing any | |
6913 | of the commands on that line. Aliases are expanded when a | |
6914 | command is read, not when it is executed. Therefore, an | |
6915 | alias definition appearing on the same line as another | |
6916 | command does not take effect until the next line of input is read. | |
6917 | The commands following the alias definition | |
6918 | on that line are not affected by the new alias. | |
6919 | This behavior is also an issue when functions are executed. | |
6920 | Aliases are expanded when a function definition is read, | |
6921 | not when the function is executed, because a function definition | |
a0c0a00f | 6922 | is itself a command. As a consequence, aliases |
bb70624e JA |
6923 | defined in a function are not available until after that |
6924 | function is executed. To be safe, always put | |
6925 | alias definitions on a separate line, and do not use @code{alias} | |
6926 | in compound commands. | |
ccc6cda3 | 6927 | |
bb70624e | 6928 | For almost every purpose, shell functions are preferred over aliases. |
ccc6cda3 | 6929 | |
bb70624e JA |
6930 | @node Arrays |
6931 | @section Arrays | |
6932 | @cindex arrays | |
d166f048 | 6933 | |
3185942a JA |
6934 | Bash provides one-dimensional indexed and associative array variables. |
6935 | Any variable may be used as an indexed array; | |
6936 | the @code{declare} builtin will explicitly declare an array. | |
bb70624e JA |
6937 | There is no maximum |
6938 | limit on the size of an array, nor any requirement that members | |
3185942a JA |
6939 | be indexed or assigned contiguously. |
6940 | Indexed arrays are referenced using integers (including arithmetic | |
ac50fbac | 6941 | expressions (@pxref{Shell Arithmetic})) and are zero-based; |
3185942a | 6942 | associative arrays use arbitrary strings. |
ac50fbac | 6943 | Unless otherwise noted, indexed array indices must be non-negative integers. |
ccc6cda3 | 6944 | |
3185942a JA |
6945 | An indexed array is created automatically if any variable is assigned to |
6946 | using the syntax | |
bb70624e | 6947 | @example |
ac50fbac | 6948 | @var{name}[@var{subscript}]=@var{value} |
bb70624e | 6949 | @end example |
ccc6cda3 | 6950 | |
bb70624e JA |
6951 | @noindent |
6952 | The @var{subscript} | |
495aee44 | 6953 | is treated as an arithmetic expression that must evaluate to a number. |
495aee44 | 6954 | To explicitly declare an array, use |
bb70624e JA |
6955 | @example |
6956 | declare -a @var{name} | |
6957 | @end example | |
6958 | @noindent | |
6959 | The syntax | |
6960 | @example | |
6961 | declare -a @var{name}[@var{subscript}] | |
6962 | @end example | |
6963 | @noindent | |
3185942a JA |
6964 | is also accepted; the @var{subscript} is ignored. |
6965 | ||
ac50fbac | 6966 | @noindent |
3185942a JA |
6967 | Associative arrays are created using |
6968 | @example | |
6969 | declare -A @var{name}. | |
6970 | @end example | |
6971 | ||
6972 | Attributes may be | |
bb70624e JA |
6973 | specified for an array variable using the @code{declare} and |
6974 | @code{readonly} builtins. Each attribute applies to all members of | |
6975 | an array. | |
ccc6cda3 | 6976 | |
bb70624e JA |
6977 | Arrays are assigned to using compound assignments of the form |
6978 | @example | |
ac50fbac | 6979 | @var{name}=(@var{value1} @var{value2} @dots{} ) |
bb70624e JA |
6980 | @end example |
6981 | @noindent | |
6982 | where each | |
3185942a | 6983 | @var{value} is of the form @code{[@var{subscript}]=}@var{string}. |
ac50fbac | 6984 | Indexed array assignments do not require anything but @var{string}. |
3185942a | 6985 | When assigning to indexed arrays, if |
bb70624e JA |
6986 | the optional subscript is supplied, that index is assigned to; |
6987 | otherwise the index of the element assigned is the last index assigned | |
6988 | to by the statement plus one. Indexing starts at zero. | |
3185942a JA |
6989 | |
6990 | When assigning to an associative array, the subscript is required. | |
6991 | ||
bb70624e JA |
6992 | This syntax is also accepted by the @code{declare} |
6993 | builtin. Individual array elements may be assigned to using the | |
ac50fbac CR |
6994 | @code{@var{name}[@var{subscript}]=@var{value}} syntax introduced above. |
6995 | ||
6996 | When assigning to an indexed array, if @var{name} | |
6997 | is subscripted by a negative number, that number is | |
6998 | interpreted as relative to one greater than the maximum index of | |
6999 | @var{name}, so negative indices count back from the end of the | |
7000 | array, and an index of -1 references the last element. | |
cce855bc | 7001 | |
bb70624e | 7002 | Any element of an array may be referenced using |
ac50fbac | 7003 | @code{$@{@var{name}[@var{subscript}]@}}. |
bb70624e JA |
7004 | The braces are required to avoid |
7005 | conflicts with the shell's filename expansion operators. If the | |
7006 | @var{subscript} is @samp{@@} or @samp{*}, the word expands to all members | |
7007 | of the array @var{name}. These subscripts differ only when the word | |
95732b49 JA |
7008 | appears within double quotes. |
7009 | If the word is double-quoted, | |
ac50fbac | 7010 | @code{$@{@var{name}[*]@}} expands to a single word with |
bb70624e | 7011 | the value of each array member separated by the first character of the |
ac50fbac | 7012 | @env{IFS} variable, and @code{$@{@var{name}[@@]@}} expands each element of |
bb70624e | 7013 | @var{name} to a separate word. When there are no array members, |
ac50fbac | 7014 | @code{$@{@var{name}[@@]@}} expands to nothing. |
95732b49 JA |
7015 | If the double-quoted expansion occurs within a word, the expansion of |
7016 | the first parameter is joined with the beginning part of the original | |
7017 | word, and the expansion of the last parameter is joined with the last | |
7018 | part of the original word. | |
7019 | This is analogous to the | |
bb70624e | 7020 | expansion of the special parameters @samp{@@} and @samp{*}. |
ac50fbac CR |
7021 | @code{$@{#@var{name}[@var{subscript}]@}} expands to the length of |
7022 | @code{$@{@var{name}[@var{subscript}]@}}. | |
bb70624e JA |
7023 | If @var{subscript} is @samp{@@} or |
7024 | @samp{*}, the expansion is the number of elements in the array. | |
ac50fbac CR |
7025 | If the @var{subscript} |
7026 | used to reference an element of an indexed array | |
a0c0a00f | 7027 | evaluates to a number less than zero, it is |
ac50fbac CR |
7028 | interpreted as relative to one greater than the maximum index of the array, |
7029 | so negative indices count back from the end of the array, | |
7030 | and an index of -1 refers to the last element. | |
ccc6cda3 | 7031 | |
a0c0a00f CR |
7032 | Referencing an array variable without a subscript is equivalent to |
7033 | referencing with a subscript of 0. | |
7034 | Any reference to a variable using a valid subscript is legal, and | |
7035 | @code{bash} will create an array if necessary. | |
7036 | ||
0001803f CR |
7037 | An array variable is considered set if a subscript has been assigned a |
7038 | value. The null string is a valid value. | |
7039 | ||
ac50fbac CR |
7040 | It is possible to obtain the keys (indices) of an array as well as the values. |
7041 | $@{!@var{name}[@@]@} and $@{!@var{name}[*]@} expand to the indices | |
7042 | assigned in array variable @var{name}. | |
7043 | The treatment when in double quotes is similar to the expansion of the | |
7044 | special parameters @samp{@@} and @samp{*} within double quotes. | |
7045 | ||
bb70624e | 7046 | The @code{unset} builtin is used to destroy arrays. |
ac50fbac | 7047 | @code{unset @var{name}[@var{subscript}]} |
bb70624e | 7048 | destroys the array element at index @var{subscript}. |
ac50fbac | 7049 | Negative subscripts to indexed arrays are interpreted as described above. |
95732b49 | 7050 | Care must be taken to avoid unwanted side effects caused by filename |
0001803f | 7051 | expansion. |
ac50fbac CR |
7052 | @code{unset @var{name}}, where @var{name} is an array, removes the |
7053 | entire array. A subscript of @samp{*} or @samp{@@} also removes the | |
bb70624e | 7054 | entire array. |
ccc6cda3 | 7055 | |
bb70624e | 7056 | The @code{declare}, @code{local}, and @code{readonly} |
3185942a JA |
7057 | builtins each accept a @option{-a} option to specify an indexed |
7058 | array and a @option{-A} option to specify an associative array. | |
495aee44 | 7059 | If both options are supplied, @option{-A} takes precedence. |
3185942a | 7060 | The @code{read} builtin accepts a @option{-a} |
bb70624e JA |
7061 | option to assign a list of words read from the standard input |
7062 | to an array, and can read values from the standard input into | |
7063 | individual array elements. The @code{set} and @code{declare} | |
7064 | builtins display array values in a way that allows them to be | |
7065 | reused as input. | |
ccc6cda3 | 7066 | |
bb70624e JA |
7067 | @node The Directory Stack |
7068 | @section The Directory Stack | |
7069 | @cindex directory stack | |
ccc6cda3 | 7070 | |
bb70624e JA |
7071 | @menu |
7072 | * Directory Stack Builtins:: Bash builtin commands to manipulate | |
7073 | the directory stack. | |
7074 | @end menu | |
ccc6cda3 | 7075 | |
bb70624e JA |
7076 | The directory stack is a list of recently-visited directories. The |
7077 | @code{pushd} builtin adds directories to the stack as it changes | |
7078 | the current directory, and the @code{popd} builtin removes specified | |
7079 | directories from the stack and changes the current directory to | |
7080 | the directory removed. The @code{dirs} builtin displays the contents | |
a0c0a00f | 7081 | of the directory stack. The current directory is always the "top" |
bb70624e | 7082 | of the directory stack. |
ccc6cda3 | 7083 | |
bb70624e | 7084 | The contents of the directory stack are also visible |
28ef6c31 | 7085 | as the value of the @env{DIRSTACK} shell variable. |
ccc6cda3 | 7086 | |
bb70624e JA |
7087 | @node Directory Stack Builtins |
7088 | @subsection Directory Stack Builtins | |
ccc6cda3 | 7089 | |
bb70624e | 7090 | @table @code |
ccc6cda3 | 7091 | |
bb70624e JA |
7092 | @item dirs |
7093 | @btindex dirs | |
7094 | @example | |
ac50fbac | 7095 | dirs [-clpv] [+@var{N} | -@var{N}] |
bb70624e | 7096 | @end example |
ac50fbac | 7097 | |
bb70624e JA |
7098 | Display the list of currently remembered directories. Directories |
7099 | are added to the list with the @code{pushd} command; the | |
7100 | @code{popd} command removes directories from the list. | |
a0c0a00f | 7101 | The current directory is always the first directory in the stack. |
ac50fbac | 7102 | |
bb70624e | 7103 | @table @code |
bb70624e JA |
7104 | @item -c |
7105 | Clears the directory stack by deleting all of the elements. | |
7106 | @item -l | |
ac50fbac CR |
7107 | Produces a listing using full pathnames; |
7108 | the default listing format uses a tilde to denote the home directory. | |
bb70624e JA |
7109 | @item -p |
7110 | Causes @code{dirs} to print the directory stack with one entry per | |
7111 | line. | |
7112 | @item -v | |
7113 | Causes @code{dirs} to print the directory stack with one entry per | |
7114 | line, prefixing each entry with its index in the stack. | |
ac50fbac CR |
7115 | @item +@var{N} |
7116 | Displays the @var{N}th directory (counting from the left of the | |
7117 | list printed by @code{dirs} when invoked without options), starting | |
7118 | with zero. | |
7119 | @item -@var{N} | |
7120 | Displays the @var{N}th directory (counting from the right of the | |
7121 | list printed by @code{dirs} when invoked without options), starting | |
7122 | with zero. | |
bb70624e JA |
7123 | @end table |
7124 | ||
7125 | @item popd | |
7126 | @btindex popd | |
7127 | @example | |
ac50fbac | 7128 | popd [-n] [+@var{N} | -@var{N}] |
bb70624e JA |
7129 | @end example |
7130 | ||
bb70624e JA |
7131 | When no arguments are given, @code{popd} |
7132 | removes the top directory from the stack and | |
a0c0a00f CR |
7133 | performs a @code{cd} to the new top directory. |
7134 | The elements are numbered from 0 starting at the first directory | |
7135 | listed with @code{dirs}; that is, @code{popd} is equivalent to @code{popd +0}. | |
ac50fbac | 7136 | |
bb70624e | 7137 | @table @code |
ac50fbac CR |
7138 | @item -n |
7139 | Suppresses the normal change of directory when removing directories | |
7140 | from the stack, so that only the stack is manipulated. | |
bb70624e JA |
7141 | @item +@var{N} |
7142 | Removes the @var{N}th directory (counting from the left of the | |
7143 | list printed by @code{dirs}), starting with zero. | |
7144 | @item -@var{N} | |
7145 | Removes the @var{N}th directory (counting from the right of the | |
7146 | list printed by @code{dirs}), starting with zero. | |
bb70624e JA |
7147 | @end table |
7148 | ||
7149 | @btindex pushd | |
7150 | @item pushd | |
7151 | @example | |
ac50fbac | 7152 | pushd [-n] [@var{+N} | @var{-N} | @var{dir}] |
bb70624e JA |
7153 | @end example |
7154 | ||
7155 | Save the current directory on the top of the directory stack | |
7156 | and then @code{cd} to @var{dir}. | |
a0c0a00f CR |
7157 | With no arguments, @code{pushd} exchanges the top two directories |
7158 | and makes the new top the current directory. | |
bb70624e JA |
7159 | |
7160 | @table @code | |
3185942a | 7161 | @item -n |
a0c0a00f CR |
7162 | Suppresses the normal change of directory when rotating or |
7163 | adding directories to the stack, so that only the stack is manipulated. | |
bb70624e JA |
7164 | @item +@var{N} |
7165 | Brings the @var{N}th directory (counting from the left of the | |
7166 | list printed by @code{dirs}, starting with zero) to the top of | |
7167 | the list by rotating the stack. | |
7168 | @item -@var{N} | |
7169 | Brings the @var{N}th directory (counting from the right of the | |
7170 | list printed by @code{dirs}, starting with zero) to the top of | |
7171 | the list by rotating the stack. | |
bb70624e | 7172 | @item @var{dir} |
a0c0a00f | 7173 | Makes @var{dir} be the top of the stack, making |
ac50fbac CR |
7174 | it the new current directory as if it had been supplied as an argument |
7175 | to the @code{cd} builtin. | |
bb70624e | 7176 | @end table |
bb70624e JA |
7177 | @end table |
7178 | ||
ac50fbac | 7179 | @node Controlling the Prompt |
bb70624e JA |
7180 | @section Controlling the Prompt |
7181 | @cindex prompting | |
ccc6cda3 | 7182 | |
28ef6c31 JA |
7183 | The value of the variable @env{PROMPT_COMMAND} is examined just before |
7184 | Bash prints each primary prompt. If @env{PROMPT_COMMAND} is set and | |
bb70624e JA |
7185 | has a non-null value, then the |
7186 | value is executed just as if it had been typed on the command line. | |
ccc6cda3 | 7187 | |
bb70624e | 7188 | In addition, the following table describes the special characters which |
ac50fbac | 7189 | can appear in the prompt variables @env{PS1} to @env{PS4}: |
ccc6cda3 | 7190 | |
bb70624e JA |
7191 | @table @code |
7192 | @item \a | |
7193 | A bell character. | |
7194 | @item \d | |
7195 | The date, in "Weekday Month Date" format (e.g., "Tue May 26"). | |
7117c2d2 JA |
7196 | @item \D@{@var{format}@} |
7197 | The @var{format} is passed to @code{strftime}(3) and the result is inserted | |
7198 | into the prompt string; an empty @var{format} results in a locale-specific | |
7199 | time representation. The braces are required. | |
bb70624e JA |
7200 | @item \e |
7201 | An escape character. | |
7202 | @item \h | |
7203 | The hostname, up to the first `.'. | |
7204 | @item \H | |
7205 | The hostname. | |
7206 | @item \j | |
7207 | The number of jobs currently managed by the shell. | |
7208 | @item \l | |
7209 | The basename of the shell's terminal device name. | |
7210 | @item \n | |
7211 | A newline. | |
7212 | @item \r | |
7213 | A carriage return. | |
7214 | @item \s | |
7215 | The name of the shell, the basename of @code{$0} (the portion | |
7216 | following the final slash). | |
7217 | @item \t | |
7218 | The time, in 24-hour HH:MM:SS format. | |
7219 | @item \T | |
7220 | The time, in 12-hour HH:MM:SS format. | |
7221 | @item \@@ | |
7222 | The time, in 12-hour am/pm format. | |
f73dda09 JA |
7223 | @item \A |
7224 | The time, in 24-hour HH:MM format. | |
bb70624e JA |
7225 | @item \u |
7226 | The username of the current user. | |
7227 | @item \v | |
7228 | The version of Bash (e.g., 2.00) | |
7229 | @item \V | |
7230 | The release of Bash, version + patchlevel (e.g., 2.00.0) | |
7231 | @item \w | |
3185942a JA |
7232 | The current working directory, with @env{$HOME} abbreviated with a tilde |
7233 | (uses the @env{$PROMPT_DIRTRIM} variable). | |
bb70624e | 7234 | @item \W |
b80f6443 | 7235 | The basename of @env{$PWD}, with @env{$HOME} abbreviated with a tilde. |
bb70624e JA |
7236 | @item \! |
7237 | The history number of this command. | |
7238 | @item \# | |
7239 | The command number of this command. | |
7240 | @item \$ | |
7241 | If the effective uid is 0, @code{#}, otherwise @code{$}. | |
7242 | @item \@var{nnn} | |
7243 | The character whose ASCII code is the octal value @var{nnn}. | |
7244 | @item \\ | |
7245 | A backslash. | |
7246 | @item \[ | |
7247 | Begin a sequence of non-printing characters. This could be used to | |
7248 | embed a terminal control sequence into the prompt. | |
7249 | @item \] | |
7250 | End a sequence of non-printing characters. | |
7251 | @end table | |
ccc6cda3 | 7252 | |
bb70624e JA |
7253 | The command number and the history number are usually different: |
7254 | the history number of a command is its position in the history | |
7255 | list, which may include commands restored from the history file | |
7256 | (@pxref{Bash History Facilities}), while the command number is | |
7257 | the position in the sequence of commands executed during the current | |
7258 | shell session. | |
ccc6cda3 | 7259 | |
bb70624e JA |
7260 | After the string is decoded, it is expanded via |
7261 | parameter expansion, command substitution, arithmetic | |
7262 | expansion, and quote removal, subject to the value of the | |
7263 | @code{promptvars} shell option (@pxref{Bash Builtins}). | |
ccc6cda3 | 7264 | |
bb70624e JA |
7265 | @node The Restricted Shell |
7266 | @section The Restricted Shell | |
7267 | @cindex restricted shell | |
ccc6cda3 | 7268 | |
bb70624e | 7269 | If Bash is started with the name @code{rbash}, or the |
28ef6c31 | 7270 | @option{--restricted} |
7117c2d2 JA |
7271 | or |
7272 | @option{-r} | |
bb70624e JA |
7273 | option is supplied at invocation, the shell becomes restricted. |
7274 | A restricted shell is used to | |
7275 | set up an environment more controlled than the standard shell. | |
7276 | A restricted shell behaves identically to @code{bash} | |
7117c2d2 JA |
7277 | with the exception that the following are disallowed or not performed: |
7278 | ||
bb70624e JA |
7279 | @itemize @bullet |
7280 | @item | |
7281 | Changing directories with the @code{cd} builtin. | |
7282 | @item | |
28ef6c31 JA |
7283 | Setting or unsetting the values of the @env{SHELL}, @env{PATH}, |
7284 | @env{ENV}, or @env{BASH_ENV} variables. | |
bb70624e JA |
7285 | @item |
7286 | Specifying command names containing slashes. | |
7287 | @item | |
7288 | Specifying a filename containing a slash as an argument to the @code{.} | |
7289 | builtin command. | |
7290 | @item | |
28ef6c31 | 7291 | Specifying a filename containing a slash as an argument to the @option{-p} |
bb70624e JA |
7292 | option to the @code{hash} builtin command. |
7293 | @item | |
7294 | Importing function definitions from the shell environment at startup. | |
7295 | @item | |
28ef6c31 | 7296 | Parsing the value of @env{SHELLOPTS} from the shell environment at startup. |
bb70624e JA |
7297 | @item |
7298 | Redirecting output using the @samp{>}, @samp{>|}, @samp{<>}, @samp{>&}, | |
7299 | @samp{&>}, and @samp{>>} redirection operators. | |
7300 | @item | |
7301 | Using the @code{exec} builtin to replace the shell with another command. | |
7302 | @item | |
7303 | Adding or deleting builtin commands with the | |
28ef6c31 | 7304 | @option{-f} and @option{-d} options to the @code{enable} builtin. |
bb70624e | 7305 | @item |
7117c2d2 JA |
7306 | Using the @code{enable} builtin command to enable disabled shell builtins. |
7307 | @item | |
28ef6c31 | 7308 | Specifying the @option{-p} option to the @code{command} builtin. |
bb70624e JA |
7309 | @item |
7310 | Turning off restricted mode with @samp{set +r} or @samp{set +o restricted}. | |
7311 | @end itemize | |
cce855bc | 7312 | |
7117c2d2 JA |
7313 | These restrictions are enforced after any startup files are read. |
7314 | ||
7315 | When a command that is found to be a shell script is executed | |
7316 | (@pxref{Shell Scripts}), @code{rbash} turns off any restrictions in | |
7317 | the shell spawned to execute the script. | |
7318 | ||
bb70624e JA |
7319 | @node Bash POSIX Mode |
7320 | @section Bash POSIX Mode | |
7321 | @cindex POSIX Mode | |
cce855bc | 7322 | |
28ef6c31 | 7323 | Starting Bash with the @option{--posix} command-line option or executing |
bb70624e | 7324 | @samp{set -o posix} while Bash is running will cause Bash to conform more |
0628567a | 7325 | closely to the @sc{posix} standard by changing the behavior to |
bb70624e | 7326 | match that specified by @sc{posix} in areas where the Bash default differs. |
ccc6cda3 | 7327 | |
7117c2d2 JA |
7328 | When invoked as @code{sh}, Bash enters @sc{posix} mode after reading the |
7329 | startup files. | |
7330 | ||
bb70624e | 7331 | The following list is what's changed when `@sc{posix} mode' is in effect: |
ccc6cda3 | 7332 | |
bb70624e JA |
7333 | @enumerate |
7334 | @item | |
7335 | When a command in the hash table no longer exists, Bash will re-search | |
28ef6c31 | 7336 | @env{$PATH} to find the new location. This is also available with |
bb70624e | 7337 | @samp{shopt -s checkhash}. |
ccc6cda3 | 7338 | |
bb70624e | 7339 | @item |
28ef6c31 JA |
7340 | The message printed by the job control code and builtins when a job |
7341 | exits with a non-zero status is `Done(status)'. | |
ccc6cda3 | 7342 | |
bb70624e JA |
7343 | @item |
7344 | The message printed by the job control code and builtins when a job | |
28ef6c31 JA |
7345 | is stopped is `Stopped(@var{signame})', where @var{signame} is, for |
7346 | example, @code{SIGTSTP}. | |
ccc6cda3 | 7347 | |
bb70624e | 7348 | @item |
a0c0a00f | 7349 | Alias expansion is always enabled, even in non-interactive shells. |
95732b49 JA |
7350 | |
7351 | @item | |
7352 | Reserved words appearing in a context where reserved words are recognized | |
7353 | do not undergo alias expansion. | |
ccc6cda3 | 7354 | |
bb70624e | 7355 | @item |
0628567a | 7356 | The @sc{posix} @env{PS1} and @env{PS2} expansions of @samp{!} to |
bb70624e | 7357 | the history number and @samp{!!} to @samp{!} are enabled, |
28ef6c31 JA |
7358 | and parameter expansion is performed on the values of @env{PS1} and |
7359 | @env{PS2} regardless of the setting of the @code{promptvars} option. | |
ccc6cda3 | 7360 | |
bb70624e | 7361 | @item |
0628567a | 7362 | The @sc{posix} startup files are executed (@env{$ENV}) rather than |
bb70624e | 7363 | the normal Bash files. |
ccc6cda3 | 7364 | |
bb70624e JA |
7365 | @item |
7366 | Tilde expansion is only performed on assignments preceding a command | |
7367 | name, rather than on all assignment statements on the line. | |
cce855bc | 7368 | |
bb70624e JA |
7369 | @item |
7370 | The default history file is @file{~/.sh_history} (this is the | |
28ef6c31 | 7371 | default value of @env{$HISTFILE}). |
ccc6cda3 | 7372 | |
bb70624e JA |
7373 | @item |
7374 | Redirection operators do not perform filename expansion on the word | |
7375 | in the redirection unless the shell is interactive. | |
ccc6cda3 | 7376 | |
bb70624e JA |
7377 | @item |
7378 | Redirection operators do not perform word splitting on the word in the | |
7379 | redirection. | |
ccc6cda3 | 7380 | |
bb70624e JA |
7381 | @item |
7382 | Function names must be valid shell @code{name}s. That is, they may not | |
7383 | contain characters other than letters, digits, and underscores, and | |
7384 | may not start with a digit. Declaring a function with an invalid name | |
7385 | causes a fatal syntax error in non-interactive shells. | |
ccc6cda3 | 7386 | |
ac50fbac CR |
7387 | @item |
7388 | Function names may not be the same as one of the @sc{posix} special | |
7389 | builtins. | |
7390 | ||
bb70624e | 7391 | @item |
0628567a | 7392 | @sc{posix} special builtins are found before shell functions |
bb70624e | 7393 | during command lookup. |
cce855bc | 7394 | |
a0c0a00f CR |
7395 | @item |
7396 | When printing shell function definitions (e.g., by @code{type}), Bash does | |
7397 | not print the @code{function} keyword. | |
7398 | ||
7399 | @item | |
7400 | Literal tildes that appear as the first character in elements of | |
7401 | the @env{PATH} variable are not expanded as described above | |
7402 | under @ref{Tilde Expansion}. | |
7403 | ||
495aee44 CR |
7404 | @item |
7405 | The @code{time} reserved word may be used by itself as a command. When | |
7406 | used in this way, it displays timing statistics for the shell and its | |
7407 | completed children. The @env{TIMEFORMAT} variable controls the format | |
7408 | of the timing information. | |
7409 | ||
7410 | @item | |
7411 | When parsing and expanding a $@{@dots{}@} expansion that appears within | |
7412 | double quotes, single quotes are no longer special and cannot be used to | |
7413 | quote a closing brace or other special character, unless the operator is | |
7414 | one of those defined to perform pattern removal. In this case, they do | |
7415 | not have to appear as matched pairs. | |
7416 | ||
7417 | @item | |
7418 | The parser does not recognize @code{time} as a reserved word if the next | |
7419 | token begins with a @samp{-}. | |
7420 | ||
a0c0a00f CR |
7421 | @item |
7422 | The @samp{!} character does not introduce history expansion within a | |
7423 | double-quoted string, even if the @code{histexpand} option is enabled. | |
7424 | ||
bb70624e | 7425 | @item |
0628567a | 7426 | If a @sc{posix} special builtin returns an error status, a |
bb70624e | 7427 | non-interactive shell exits. The fatal errors are those listed in |
495aee44 | 7428 | the @sc{posix} standard, and include things like passing incorrect options, |
bb70624e JA |
7429 | redirection errors, variable assignment errors for assignments preceding |
7430 | the command name, and so on. | |
ccc6cda3 | 7431 | |
bb70624e JA |
7432 | @item |
7433 | A non-interactive shell exits with an error status if a variable | |
7434 | assignment error occurs when no command name follows the assignment | |
7435 | statements. | |
7436 | A variable assignment error occurs, for example, when trying to assign | |
7437 | a value to a readonly variable. | |
ccc6cda3 | 7438 | |
495aee44 | 7439 | @item |
ac50fbac | 7440 | A non-interactive shell exits with an error status if a variable |
495aee44 CR |
7441 | assignment error occurs in an assignment statement preceding a special |
7442 | builtin, but not with any other simple command. | |
7443 | ||
bb70624e JA |
7444 | @item |
7445 | A non-interactive shell exits with an error status if the iteration | |
7446 | variable in a @code{for} statement or the selection variable in a | |
7447 | @code{select} statement is a readonly variable. | |
ccc6cda3 | 7448 | |
a0c0a00f CR |
7449 | @item |
7450 | Non-interactive shells exit if @var{filename} in @code{.} @var{filename} | |
7451 | is not found. | |
7452 | ||
7453 | @item | |
7454 | Non-interactive shells exit if a syntax error in an arithmetic expansion | |
7455 | results in an invalid expression. | |
7456 | ||
7457 | @item | |
7458 | Non-interactive shells exit if a parameter expansion error occurs. | |
7459 | ||
7460 | @item | |
7461 | Non-interactive shells exit if there is a syntax error in a script read | |
7462 | with the @code{.} or @code{source} builtins, or in a string processed by | |
7463 | the @code{eval} builtin. | |
7464 | ||
bb70624e JA |
7465 | @item |
7466 | Process substitution is not available. | |
ccc6cda3 | 7467 | |
ac50fbac CR |
7468 | @item |
7469 | While variable indirection is available, it may not be applied to the | |
7470 | @samp{#} and @samp{?} special parameters. | |
7471 | ||
a0c0a00f CR |
7472 | @item |
7473 | When expanding the @samp{*} special parameter in a pattern context where the | |
7474 | expansion is double-quoted does not treat the @code{$*} as if it were | |
7475 | double-quoted. | |
7476 | ||
bb70624e | 7477 | @item |
0628567a | 7478 | Assignment statements preceding @sc{posix} special builtins |
bb70624e | 7479 | persist in the shell environment after the builtin completes. |
ccc6cda3 | 7480 | |
28ef6c31 JA |
7481 | @item |
7482 | Assignment statements preceding shell function calls persist in the | |
7483 | shell environment after the function returns, as if a @sc{posix} | |
7484 | special builtin command had been executed. | |
7485 | ||
a0c0a00f CR |
7486 | @item |
7487 | The @code{command} builtin does not prevent builtins that take assignment | |
7488 | statements as arguments from expanding them as assignment statements; | |
7489 | when not in @sc{posix} mode, assignment builtins lose their assignment | |
7490 | statement expansion properties when preceded by @code{command}. | |
7491 | ||
7492 | @item | |
7493 | The @code{bg} builtin uses the required format to describe each job placed | |
7494 | in the background, which does not include an indication of whether the job | |
7495 | is the current or previous job. | |
7496 | ||
7497 | @item | |
7498 | The output of @samp{kill -l} prints all the signal names on a single line, | |
7499 | separated by spaces, without the @samp{SIG} prefix. | |
7500 | ||
7501 | @item | |
7502 | The @code{kill} builtin does not accept signal names with a @samp{SIG} | |
7503 | prefix. | |
7504 | ||
bb70624e JA |
7505 | @item |
7506 | The @code{export} and @code{readonly} builtin commands display their | |
0628567a | 7507 | output in the format required by @sc{posix}. |
ccc6cda3 | 7508 | |
28ef6c31 JA |
7509 | @item |
7510 | The @code{trap} builtin displays signal names without the leading | |
7511 | @code{SIG}. | |
7512 | ||
b80f6443 JA |
7513 | @item |
7514 | The @code{trap} builtin doesn't check the first argument for a possible | |
7515 | signal specification and revert the signal handling to the original | |
eb873671 JA |
7516 | disposition if it is, unless that argument consists solely of digits and |
7517 | is a valid signal number. If users want to reset the handler for a given | |
b80f6443 JA |
7518 | signal to the original disposition, they should use @samp{-} as the |
7519 | first argument. | |
7520 | ||
28ef6c31 JA |
7521 | @item |
7522 | The @code{.} and @code{source} builtins do not search the current directory | |
7523 | for the filename argument if it is not found by searching @env{PATH}. | |
7524 | ||
7525 | @item | |
a0c0a00f CR |
7526 | Enabling @sc{posix} mode has the effect of setting the |
7527 | @code{inherit_errexit} option, so | |
7528 | subshells spawned to execute command substitutions inherit the value of | |
7529 | the @option{-e} option from the parent shell. | |
7530 | When the @code{inherit_errexit} option is not enabled, | |
28ef6c31 JA |
7531 | Bash clears the @option{-e} option in such subshells. |
7532 | ||
b80f6443 JA |
7533 | @item |
7534 | When the @code{alias} builtin displays alias definitions, it does not | |
7535 | display them with a leading @samp{alias } unless the @option{-p} option | |
7536 | is supplied. | |
7537 | ||
28ef6c31 JA |
7538 | @item |
7539 | When the @code{set} builtin is invoked without options, it does not display | |
7540 | shell function names and definitions. | |
7541 | ||
f73dda09 JA |
7542 | @item |
7543 | When the @code{set} builtin is invoked without options, it displays | |
7544 | variable values without quotes, unless they contain shell metacharacters, | |
7545 | even if the result contains nonprinting characters. | |
7117c2d2 JA |
7546 | |
7547 | @item | |
7548 | When the @code{cd} builtin is invoked in @var{logical} mode, and the pathname | |
7549 | constructed from @code{$PWD} and the directory name supplied as an argument | |
7550 | does not refer to an existing directory, @code{cd} will fail instead of | |
7551 | falling back to @var{physical} mode. | |
95732b49 | 7552 | |
95732b49 JA |
7553 | @item |
7554 | The @code{pwd} builtin verifies that the value it prints is the same as the | |
7555 | current directory, even if it is not asked to check the file system with the | |
7556 | @option{-P} option. | |
7557 | ||
7558 | @item | |
7559 | When listing the history, the @code{fc} builtin does not include an | |
7560 | indication of whether or not a history entry has been modified. | |
7561 | ||
7562 | @item | |
7563 | The default editor used by @code{fc} is @code{ed}. | |
7564 | ||
7565 | @item | |
7566 | The @code{type} and @code{command} builtins will not report a non-executable | |
7567 | file as having been found, though the shell will attempt to execute such a | |
7568 | file if it is the only so-named file found in @code{$PATH}. | |
7569 | ||
7570 | @item | |
7571 | The @code{vi} editing mode will invoke the @code{vi} editor directly when | |
3185942a | 7572 | the @samp{v} command is run, instead of checking @code{$VISUAL} and |
95732b49 JA |
7573 | @code{$EDITOR}. |
7574 | ||
7575 | @item | |
7576 | When the @code{xpg_echo} option is enabled, Bash does not attempt to interpret | |
7577 | any arguments to @code{echo} as options. Each argument is displayed, after | |
7578 | escape characters are converted. | |
7579 | ||
3185942a JA |
7580 | @item |
7581 | The @code{ulimit} builtin uses a block size of 512 bytes for the @option{-c} | |
7582 | and @option{-f} options. | |
7583 | ||
0001803f CR |
7584 | @item |
7585 | The arrival of @code{SIGCHLD} when a trap is set on @code{SIGCHLD} does | |
7586 | not interrupt the @code{wait} builtin and cause it to return immediately. | |
7587 | The trap command is run once for each child that exits. | |
7588 | ||
ac50fbac CR |
7589 | @item |
7590 | The @code{read} builtin may be interrupted by a signal for which a trap | |
7591 | has been set. | |
7592 | If Bash receives a trapped signal while executing @code{read}, the trap | |
7593 | handler executes and @code{read} returns an exit status greater than 128. | |
7594 | ||
a0c0a00f CR |
7595 | @item |
7596 | Bash removes an exited background process's status from the list of such | |
7597 | statuses after the @code{wait} builtin is used to obtain it. | |
7598 | ||
bb70624e | 7599 | @end enumerate |
ccc6cda3 | 7600 | |
0628567a | 7601 | There is other @sc{posix} behavior that Bash does not implement by |
95732b49 | 7602 | default even when in @sc{posix} mode. |
bb70624e | 7603 | Specifically: |
ccc6cda3 | 7604 | |
bb70624e | 7605 | @enumerate |
28ef6c31 JA |
7606 | |
7607 | @item | |
95732b49 JA |
7608 | The @code{fc} builtin checks @code{$EDITOR} as a program to edit history |
7609 | entries if @code{FCEDIT} is unset, rather than defaulting directly to | |
7610 | @code{ed}. @code{fc} uses @code{ed} if @code{EDITOR} is unset. | |
28ef6c31 JA |
7611 | |
7612 | @item | |
95732b49 JA |
7613 | As noted above, Bash requires the @code{xpg_echo} option to be enabled for |
7614 | the @code{echo} builtin to be fully conformant. | |
28ef6c31 | 7615 | |
bb70624e | 7616 | @end enumerate |
ccc6cda3 | 7617 | |
95732b49 JA |
7618 | Bash can be configured to be @sc{posix}-conformant by default, by specifying |
7619 | the @option{--enable-strict-posix-default} to @code{configure} when building | |
7620 | (@pxref{Optional Features}). | |
7621 | ||
bb70624e JA |
7622 | @node Job Control |
7623 | @chapter Job Control | |
ccc6cda3 | 7624 | |
bb70624e JA |
7625 | This chapter discusses what job control is, how it works, and how |
7626 | Bash allows you to access its facilities. | |
ccc6cda3 | 7627 | |
bb70624e JA |
7628 | @menu |
7629 | * Job Control Basics:: How job control works. | |
7630 | * Job Control Builtins:: Bash builtin commands used to interact | |
7631 | with job control. | |
7632 | * Job Control Variables:: Variables Bash uses to customize job | |
7633 | control. | |
7634 | @end menu | |
ccc6cda3 | 7635 | |
bb70624e JA |
7636 | @node Job Control Basics |
7637 | @section Job Control Basics | |
7638 | @cindex job control | |
7639 | @cindex foreground | |
7640 | @cindex background | |
7641 | @cindex suspending jobs | |
ccc6cda3 | 7642 | |
bb70624e JA |
7643 | Job control |
7644 | refers to the ability to selectively stop (suspend) | |
7645 | the execution of processes and continue (resume) | |
7646 | their execution at a later point. A user typically employs | |
7647 | this facility via an interactive interface supplied jointly | |
0001803f | 7648 | by the operating system kernel's terminal driver and Bash. |
ccc6cda3 | 7649 | |
bb70624e JA |
7650 | The shell associates a @var{job} with each pipeline. It keeps a |
7651 | table of currently executing jobs, which may be listed with the | |
7652 | @code{jobs} command. When Bash starts a job | |
7653 | asynchronously, it prints a line that looks | |
7654 | like: | |
7655 | @example | |
7656 | [1] 25647 | |
7657 | @end example | |
7658 | @noindent | |
7659 | indicating that this job is job number 1 and that the process @sc{id} | |
7660 | of the last process in the pipeline associated with this job is | |
7661 | 25647. All of the processes in a single pipeline are members of | |
7662 | the same job. Bash uses the @var{job} abstraction as the | |
7663 | basis for job control. | |
ccc6cda3 | 7664 | |
bb70624e JA |
7665 | To facilitate the implementation of the user interface to job |
7666 | control, the operating system maintains the notion of a current terminal | |
7667 | process group @sc{id}. Members of this process group (processes whose | |
7668 | process group @sc{id} is equal to the current terminal process group | |
7669 | @sc{id}) receive keyboard-generated signals such as @code{SIGINT}. | |
7670 | These processes are said to be in the foreground. Background | |
7671 | processes are those whose process group @sc{id} differs from the | |
7672 | terminal's; such processes are immune to keyboard-generated | |
0001803f CR |
7673 | signals. Only foreground processes are allowed to read from or, if |
7674 | the user so specifies with @code{stty tostop}, write to the terminal. | |
7675 | Background processes which attempt to | |
7676 | read from (write to when @code{stty tostop} is in effect) the | |
7677 | terminal are sent a @code{SIGTTIN} (@code{SIGTTOU}) | |
7678 | signal by the kernel's terminal driver, | |
7679 | which, unless caught, suspends the process. | |
ccc6cda3 | 7680 | |
bb70624e JA |
7681 | If the operating system on which Bash is running supports |
7682 | job control, Bash contains facilities to use it. Typing the | |
7683 | @var{suspend} character (typically @samp{^Z}, Control-Z) while a | |
7684 | process is running causes that process to be stopped and returns | |
7685 | control to Bash. Typing the @var{delayed suspend} character | |
7686 | (typically @samp{^Y}, Control-Y) causes the process to be stopped | |
7687 | when it attempts to read input from the terminal, and control to | |
7688 | be returned to Bash. The user then manipulates the state of | |
7689 | this job, using the @code{bg} command to continue it in the | |
7690 | background, the @code{fg} command to continue it in the | |
7691 | foreground, or the @code{kill} command to kill it. A @samp{^Z} | |
7692 | takes effect immediately, and has the additional side effect of | |
7693 | causing pending output and typeahead to be discarded. | |
ccc6cda3 | 7694 | |
bb70624e | 7695 | There are a number of ways to refer to a job in the shell. The |
3185942a | 7696 | character @samp{%} introduces a job specification (@var{jobspec}). |
cce855bc | 7697 | |
bb70624e | 7698 | Job number @code{n} may be referred to as @samp{%n}. |
95732b49 JA |
7699 | The symbols @samp{%%} and @samp{%+} refer to the shell's notion of the |
7700 | current job, which is the last job stopped while it was in the foreground | |
7701 | or started in the background. | |
7702 | A single @samp{%} (with no accompanying job specification) also refers | |
7703 | to the current job. | |
3185942a JA |
7704 | The previous job may be referenced using @samp{%-}. |
7705 | If there is only a single job, @samp{%+} and @samp{%-} can both be used | |
7706 | to refer to that job. | |
7707 | In output pertaining to jobs (e.g., the output of the @code{jobs} | |
7708 | command), the current job is always flagged with a @samp{+}, and the | |
bb70624e | 7709 | previous job with a @samp{-}. |
cce855bc | 7710 | |
bb70624e JA |
7711 | A job may also be referred to |
7712 | using a prefix of the name used to start it, or using a substring | |
7713 | that appears in its command line. For example, @samp{%ce} refers | |
ac50fbac | 7714 | to a stopped @code{ce} job. Using @samp{%?ce}, on the |
bb70624e JA |
7715 | other hand, refers to any job containing the string @samp{ce} in |
7716 | its command line. If the prefix or substring matches more than one job, | |
7717 | Bash reports an error. | |
cce855bc | 7718 | |
bb70624e JA |
7719 | Simply naming a job can be used to bring it into the foreground: |
7720 | @samp{%1} is a synonym for @samp{fg %1}, bringing job 1 from the | |
7721 | background into the foreground. Similarly, @samp{%1 &} resumes | |
7722 | job 1 in the background, equivalent to @samp{bg %1} | |
cce855bc | 7723 | |
bb70624e JA |
7724 | The shell learns immediately whenever a job changes state. |
7725 | Normally, Bash waits until it is about to print a prompt | |
7726 | before reporting changes in a job's status so as to not interrupt | |
f73dda09 JA |
7727 | any other output. |
7728 | If the @option{-b} option to the @code{set} builtin is enabled, | |
bb70624e | 7729 | Bash reports such changes immediately (@pxref{The Set Builtin}). |
f73dda09 JA |
7730 | Any trap on @code{SIGCHLD} is executed for each child process |
7731 | that exits. | |
ccc6cda3 | 7732 | |
3185942a JA |
7733 | If an attempt to exit Bash is made while jobs are stopped, (or running, if |
7734 | the @code{checkjobs} option is enabled -- see @ref{The Shopt Builtin}), the | |
7735 | shell prints a warning message, and if the @code{checkjobs} option is | |
7736 | enabled, lists the jobs and their statuses. | |
bb70624e JA |
7737 | The @code{jobs} command may then be used to inspect their status. |
7738 | If a second attempt to exit is made without an intervening command, | |
3185942a | 7739 | Bash does not print another warning, and any stopped jobs are terminated. |
ccc6cda3 | 7740 | |
bb70624e JA |
7741 | @node Job Control Builtins |
7742 | @section Job Control Builtins | |
ccc6cda3 JA |
7743 | |
7744 | @table @code | |
7745 | ||
bb70624e JA |
7746 | @item bg |
7747 | @btindex bg | |
ccc6cda3 | 7748 | @example |
95732b49 | 7749 | bg [@var{jobspec} @dots{}] |
ccc6cda3 | 7750 | @end example |
ac50fbac | 7751 | |
95732b49 | 7752 | Resume each suspended job @var{jobspec} in the background, as if it |
bb70624e JA |
7753 | had been started with @samp{&}. |
7754 | If @var{jobspec} is not supplied, the current job is used. | |
7755 | The return status is zero unless it is run when job control is not | |
95732b49 JA |
7756 | enabled, or, when run with job control enabled, any |
7757 | @var{jobspec} was not found or specifies a job | |
7758 | that was started without job control. | |
cce855bc | 7759 | |
bb70624e JA |
7760 | @item fg |
7761 | @btindex fg | |
7762 | @example | |
7763 | fg [@var{jobspec}] | |
7764 | @end example | |
ac50fbac | 7765 | |
bb70624e JA |
7766 | Resume the job @var{jobspec} in the foreground and make it the current job. |
7767 | If @var{jobspec} is not supplied, the current job is used. | |
7768 | The return status is that of the command placed into the foreground, | |
7769 | or non-zero if run when job control is disabled or, when run with | |
7770 | job control enabled, @var{jobspec} does not specify a valid job or | |
7771 | @var{jobspec} specifies a job that was started without job control. | |
cce855bc | 7772 | |
bb70624e JA |
7773 | @item jobs |
7774 | @btindex jobs | |
cce855bc | 7775 | @example |
bb70624e JA |
7776 | jobs [-lnprs] [@var{jobspec}] |
7777 | jobs -x @var{command} [@var{arguments}] | |
cce855bc JA |
7778 | @end example |
7779 | ||
bb70624e JA |
7780 | The first form lists the active jobs. The options have the |
7781 | following meanings: | |
7782 | ||
7783 | @table @code | |
7784 | @item -l | |
7785 | List process @sc{id}s in addition to the normal information. | |
7786 | ||
7787 | @item -n | |
7788 | Display information only about jobs that have changed status since | |
7789 | the user was last notified of their status. | |
7790 | ||
7791 | @item -p | |
7792 | List only the process @sc{id} of the job's process group leader. | |
7793 | ||
7794 | @item -r | |
ac50fbac | 7795 | Display only running jobs. |
bb70624e JA |
7796 | |
7797 | @item -s | |
ac50fbac | 7798 | Display only stopped jobs. |
ccc6cda3 JA |
7799 | @end table |
7800 | ||
bb70624e JA |
7801 | If @var{jobspec} is given, |
7802 | output is restricted to information about that job. | |
7803 | If @var{jobspec} is not supplied, the status of all jobs is | |
7804 | listed. | |
ccc6cda3 | 7805 | |
28ef6c31 | 7806 | If the @option{-x} option is supplied, @code{jobs} replaces any |
bb70624e JA |
7807 | @var{jobspec} found in @var{command} or @var{arguments} with the |
7808 | corresponding process group @sc{id}, and executes @var{command}, | |
7809 | passing it @var{argument}s, returning its exit status. | |
ccc6cda3 | 7810 | |
bb70624e JA |
7811 | @item kill |
7812 | @btindex kill | |
ccc6cda3 | 7813 | @example |
bb70624e | 7814 | kill [-s @var{sigspec}] [-n @var{signum}] [-@var{sigspec}] @var{jobspec} or @var{pid} |
a0c0a00f | 7815 | kill -l|-L [@var{exit_status}] |
ccc6cda3 | 7816 | @end example |
ac50fbac | 7817 | |
bb70624e JA |
7818 | Send a signal specified by @var{sigspec} or @var{signum} to the process |
7819 | named by job specification @var{jobspec} or process @sc{id} @var{pid}. | |
b80f6443 JA |
7820 | @var{sigspec} is either a case-insensitive signal name such as |
7821 | @code{SIGINT} (with or without the @code{SIG} prefix) | |
7822 | or a signal number; @var{signum} is a signal number. | |
bb70624e | 7823 | If @var{sigspec} and @var{signum} are not present, @code{SIGTERM} is used. |
28ef6c31 JA |
7824 | The @option{-l} option lists the signal names. |
7825 | If any arguments are supplied when @option{-l} is given, the names of the | |
bb70624e JA |
7826 | signals corresponding to the arguments are listed, and the return status |
7827 | is zero. | |
7828 | @var{exit_status} is a number specifying a signal number or the exit | |
7829 | status of a process terminated by a signal. | |
a0c0a00f | 7830 | The @option{-L} option is equivalent to @option{-l}. |
bb70624e JA |
7831 | The return status is zero if at least one signal was successfully sent, |
7832 | or non-zero if an error occurs or an invalid option is encountered. | |
ccc6cda3 | 7833 | |
bb70624e JA |
7834 | @item wait |
7835 | @btindex wait | |
ccc6cda3 | 7836 | @example |
ac50fbac | 7837 | wait [-n] [@var{jobspec} or @var{pid} @dots{}] |
ccc6cda3 | 7838 | @end example |
ac50fbac | 7839 | |
95732b49 JA |
7840 | Wait until the child process specified by each process @sc{id} @var{pid} |
7841 | or job specification @var{jobspec} exits and return the exit status of the | |
7842 | last command waited for. | |
bb70624e JA |
7843 | If a job spec is given, all processes in the job are waited for. |
7844 | If no arguments are given, all currently active child processes are | |
7845 | waited for, and the return status is zero. | |
ac50fbac CR |
7846 | If the @option{-n} option is supplied, @code{wait} waits for any job to |
7847 | terminate and returns its exit status. | |
bb70624e JA |
7848 | If neither @var{jobspec} nor @var{pid} specifies an active child process |
7849 | of the shell, the return status is 127. | |
7850 | ||
7851 | @item disown | |
7852 | @btindex disown | |
ccc6cda3 | 7853 | @example |
a0c0a00f | 7854 | disown [-ar] [-h] [@var{jobspec} @dots{} | @var{pid} @dots{} ] |
ccc6cda3 | 7855 | @end example |
ac50fbac CR |
7856 | |
7857 | Without options, remove each @var{jobspec} from the table of | |
bb70624e | 7858 | active jobs. |
28ef6c31 | 7859 | If the @option{-h} option is given, the job is not removed from the table, |
bb70624e JA |
7860 | but is marked so that @code{SIGHUP} is not sent to the job if the shell |
7861 | receives a @code{SIGHUP}. | |
ac50fbac CR |
7862 | If @var{jobspec} is not present, and neither the @option{-a} nor the |
7863 | @option{-r} option is supplied, the current job is used. | |
28ef6c31 JA |
7864 | If no @var{jobspec} is supplied, the @option{-a} option means to remove or |
7865 | mark all jobs; the @option{-r} option without a @var{jobspec} | |
bb70624e | 7866 | argument restricts operation to running jobs. |
ccc6cda3 | 7867 | |
bb70624e JA |
7868 | @item suspend |
7869 | @btindex suspend | |
ccc6cda3 | 7870 | @example |
bb70624e | 7871 | suspend [-f] |
ccc6cda3 | 7872 | @end example |
ac50fbac | 7873 | |
bb70624e | 7874 | Suspend the execution of this shell until it receives a |
3185942a JA |
7875 | @code{SIGCONT} signal. |
7876 | A login shell cannot be suspended; the @option{-f} | |
7877 | option can be used to override this and force the suspension. | |
bb70624e | 7878 | @end table |
ccc6cda3 | 7879 | |
bb70624e JA |
7880 | When job control is not active, the @code{kill} and @code{wait} |
7881 | builtins do not accept @var{jobspec} arguments. They must be | |
7882 | supplied process @sc{id}s. | |
ccc6cda3 | 7883 | |
bb70624e JA |
7884 | @node Job Control Variables |
7885 | @section Job Control Variables | |
ccc6cda3 | 7886 | |
bb70624e | 7887 | @vtable @code |
cce855bc | 7888 | |
bb70624e JA |
7889 | @item auto_resume |
7890 | This variable controls how the shell interacts with the user and | |
7891 | job control. If this variable exists then single word simple | |
7892 | commands without redirections are treated as candidates for resumption | |
7893 | of an existing job. There is no ambiguity allowed; if there is | |
7894 | more than one job beginning with the string typed, then | |
7895 | the most recently accessed job will be selected. | |
7896 | The name of a stopped job, in this context, is the command line | |
7897 | used to start it. If this variable is set to the value @samp{exact}, | |
7898 | the string supplied must match the name of a stopped job exactly; | |
7899 | if set to @samp{substring}, | |
7900 | the string supplied needs to match a substring of the name of a | |
7901 | stopped job. The @samp{substring} value provides functionality | |
7902 | analogous to the @samp{%?} job @sc{id} (@pxref{Job Control Basics}). | |
7903 | If set to any other value, the supplied string must | |
7904 | be a prefix of a stopped job's name; this provides functionality | |
7905 | analogous to the @samp{%} job @sc{id}. | |
cce855bc | 7906 | |
bb70624e | 7907 | @end vtable |
cce855bc | 7908 | |
bb70624e JA |
7909 | @set readline-appendix |
7910 | @set history-appendix | |
7911 | @cindex Readline, how to use | |
b80f6443 | 7912 | @include rluser.texi |
bb70624e | 7913 | @cindex History, how to use |
b80f6443 | 7914 | @include hsuser.texi |
bb70624e JA |
7915 | @clear readline-appendix |
7916 | @clear history-appendix | |
cce855bc | 7917 | |
bb70624e JA |
7918 | @node Installing Bash |
7919 | @chapter Installing Bash | |
cce855bc | 7920 | |
bb70624e JA |
7921 | This chapter provides basic instructions for installing Bash on |
7922 | the various supported platforms. The distribution supports the | |
7923 | @sc{gnu} operating systems, nearly every version of Unix, and several | |
7924 | non-Unix systems such as BeOS and Interix. | |
7925 | Other independent ports exist for | |
b80f6443 | 7926 | @sc{ms-dos}, @sc{os/2}, and Windows platforms. |
cce855bc | 7927 | |
bb70624e JA |
7928 | @menu |
7929 | * Basic Installation:: Installation instructions. | |
bb70624e JA |
7930 | * Compilers and Options:: How to set special options for various |
7931 | systems. | |
bb70624e JA |
7932 | * Compiling For Multiple Architectures:: How to compile Bash for more |
7933 | than one kind of system from | |
7934 | the same source tree. | |
bb70624e | 7935 | * Installation Names:: How to set the various paths used by the installation. |
bb70624e | 7936 | * Specifying the System Type:: How to configure Bash for a particular system. |
bb70624e JA |
7937 | * Sharing Defaults:: How to share default configuration values among GNU |
7938 | programs. | |
bb70624e | 7939 | * Operation Controls:: Options recognized by the configuration program. |
bb70624e JA |
7940 | * Optional Features:: How to enable and disable optional features when |
7941 | building Bash. | |
7942 | @end menu | |
ccc6cda3 | 7943 | |
bb70624e JA |
7944 | @node Basic Installation |
7945 | @section Basic Installation | |
7946 | @cindex installation | |
7947 | @cindex configuration | |
7948 | @cindex Bash installation | |
7949 | @cindex Bash configuration | |
ccc6cda3 | 7950 | |
bb70624e | 7951 | These are installation instructions for Bash. |
ccc6cda3 | 7952 | |
bb70624e | 7953 | The simplest way to compile Bash is: |
ccc6cda3 | 7954 | |
bb70624e | 7955 | @enumerate |
ccc6cda3 | 7956 | @item |
bb70624e JA |
7957 | @code{cd} to the directory containing the source code and type |
7958 | @samp{./configure} to configure Bash for your system. If you're | |
7959 | using @code{csh} on an old version of System V, you might need to | |
7960 | type @samp{sh ./configure} instead to prevent @code{csh} from trying | |
7961 | to execute @code{configure} itself. | |
7962 | ||
7963 | Running @code{configure} takes some time. | |
7964 | While running, it prints messages telling which features it is | |
7965 | checking for. | |
7966 | ||
ccc6cda3 | 7967 | @item |
bb70624e JA |
7968 | Type @samp{make} to compile Bash and build the @code{bashbug} bug |
7969 | reporting script. | |
7970 | ||
ccc6cda3 | 7971 | @item |
bb70624e JA |
7972 | Optionally, type @samp{make tests} to run the Bash test suite. |
7973 | ||
ccc6cda3 | 7974 | @item |
bb70624e JA |
7975 | Type @samp{make install} to install @code{bash} and @code{bashbug}. |
7976 | This will also install the manual pages and Info file. | |
ccc6cda3 | 7977 | |
bb70624e | 7978 | @end enumerate |
ccc6cda3 | 7979 | |
bb70624e JA |
7980 | The @code{configure} shell script attempts to guess correct |
7981 | values for various system-dependent variables used during | |
7982 | compilation. It uses those values to create a @file{Makefile} in | |
7983 | each directory of the package (the top directory, the | |
7984 | @file{builtins}, @file{doc}, and @file{support} directories, | |
7985 | each directory under @file{lib}, and several others). It also creates a | |
7986 | @file{config.h} file containing system-dependent definitions. | |
7987 | Finally, it creates a shell script named @code{config.status} that you | |
7988 | can run in the future to recreate the current configuration, a | |
7989 | file @file{config.cache} that saves the results of its tests to | |
7990 | speed up reconfiguring, and a file @file{config.log} containing | |
7991 | compiler output (useful mainly for debugging @code{configure}). | |
7992 | If at some point | |
7993 | @file{config.cache} contains results you don't want to keep, you | |
7994 | may remove or edit it. | |
ccc6cda3 | 7995 | |
bb70624e JA |
7996 | To find out more about the options and arguments that the |
7997 | @code{configure} script understands, type | |
ccc6cda3 | 7998 | |
bb70624e JA |
7999 | @example |
8000 | bash-2.04$ ./configure --help | |
8001 | @end example | |
ccc6cda3 | 8002 | |
bb70624e JA |
8003 | @noindent |
8004 | at the Bash prompt in your Bash source directory. | |
ccc6cda3 | 8005 | |
bb70624e JA |
8006 | If you need to do unusual things to compile Bash, please |
8007 | try to figure out how @code{configure} could check whether or not | |
8008 | to do them, and mail diffs or instructions to | |
8009 | @email{bash-maintainers@@gnu.org} so they can be | |
8010 | considered for the next release. | |
ccc6cda3 | 8011 | |
ac50fbac | 8012 | The file @file{configure.ac} is used to create @code{configure} |
bb70624e | 8013 | by a program called Autoconf. You only need |
ac50fbac | 8014 | @file{configure.ac} if you want to change it or regenerate |
bb70624e | 8015 | @code{configure} using a newer version of Autoconf. If |
f73dda09 | 8016 | you do this, make sure you are using Autoconf version 2.50 or |
bb70624e | 8017 | newer. |
ccc6cda3 | 8018 | |
bb70624e JA |
8019 | You can remove the program binaries and object files from the |
8020 | source code directory by typing @samp{make clean}. To also remove the | |
8021 | files that @code{configure} created (so you can compile Bash for | |
8022 | a different kind of computer), type @samp{make distclean}. | |
ccc6cda3 | 8023 | |
bb70624e JA |
8024 | @node Compilers and Options |
8025 | @section Compilers and Options | |
ccc6cda3 | 8026 | |
bb70624e JA |
8027 | Some systems require unusual options for compilation or linking |
8028 | that the @code{configure} script does not know about. You can | |
8029 | give @code{configure} initial values for variables by setting | |
8030 | them in the environment. Using a Bourne-compatible shell, you | |
8031 | can do that on the command line like this: | |
ccc6cda3 | 8032 | |
bb70624e JA |
8033 | @example |
8034 | CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure | |
8035 | @end example | |
ccc6cda3 | 8036 | |
bb70624e | 8037 | On systems that have the @code{env} program, you can do it like this: |
ccc6cda3 | 8038 | |
bb70624e JA |
8039 | @example |
8040 | env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure | |
8041 | @end example | |
ccc6cda3 | 8042 | |
bb70624e JA |
8043 | The configuration process uses GCC to build Bash if it |
8044 | is available. | |
cce855bc | 8045 | |
bb70624e JA |
8046 | @node Compiling For Multiple Architectures |
8047 | @section Compiling For Multiple Architectures | |
ccc6cda3 | 8048 | |
bb70624e JA |
8049 | You can compile Bash for more than one kind of computer at the |
8050 | same time, by placing the object files for each architecture in their | |
8051 | own directory. To do this, you must use a version of @code{make} that | |
8052 | supports the @code{VPATH} variable, such as GNU @code{make}. | |
8053 | @code{cd} to the | |
8054 | directory where you want the object files and executables to go and run | |
8055 | the @code{configure} script from the source directory. You may need to | |
28ef6c31 | 8056 | supply the @option{--srcdir=PATH} argument to tell @code{configure} where the |
bb70624e JA |
8057 | source files are. @code{configure} automatically checks for the |
8058 | source code in the directory that @code{configure} is in and in `..'. | |
ccc6cda3 | 8059 | |
bb70624e JA |
8060 | If you have to use a @code{make} that does not supports the @code{VPATH} |
8061 | variable, you can compile Bash for one architecture at a | |
8062 | time in the source code directory. After you have installed | |
8063 | Bash for one architecture, use @samp{make distclean} before | |
8064 | reconfiguring for another architecture. | |
ccc6cda3 | 8065 | |
bb70624e JA |
8066 | Alternatively, if your system supports symbolic links, you can use the |
8067 | @file{support/mkclone} script to create a build tree which has | |
8068 | symbolic links back to each file in the source directory. Here's an | |
8069 | example that creates a build directory in the current directory from a | |
8070 | source directory @file{/usr/gnu/src/bash-2.0}: | |
8071 | ||
8072 | @example | |
8073 | bash /usr/gnu/src/bash-2.0/support/mkclone -s /usr/gnu/src/bash-2.0 . | |
8074 | @end example | |
8075 | ||
8076 | @noindent | |
8077 | The @code{mkclone} script requires Bash, so you must have already built | |
8078 | Bash for at least one architecture before you can create build | |
8079 | directories for other architectures. | |
8080 | ||
8081 | @node Installation Names | |
8082 | @section Installation Names | |
ccc6cda3 | 8083 | |
bb70624e JA |
8084 | By default, @samp{make install} will install into |
8085 | @file{/usr/local/bin}, @file{/usr/local/man}, etc. You can | |
8086 | specify an installation prefix other than @file{/usr/local} by | |
f73dda09 JA |
8087 | giving @code{configure} the option @option{--prefix=@var{PATH}}, |
8088 | or by specifying a value for the @code{DESTDIR} @samp{make} | |
8089 | variable when running @samp{make install}. | |
ccc6cda3 | 8090 | |
bb70624e JA |
8091 | You can specify separate installation prefixes for |
8092 | architecture-specific files and architecture-independent files. | |
8093 | If you give @code{configure} the option | |
28ef6c31 | 8094 | @option{--exec-prefix=@var{PATH}}, @samp{make install} will use |
bb70624e JA |
8095 | @var{PATH} as the prefix for installing programs and libraries. |
8096 | Documentation and other data files will still use the regular prefix. | |
cce855bc | 8097 | |
bb70624e JA |
8098 | @node Specifying the System Type |
8099 | @section Specifying the System Type | |
ccc6cda3 | 8100 | |
bb70624e | 8101 | There may be some features @code{configure} can not figure out |
f73dda09 | 8102 | automatically, but need to determine by the type of host Bash |
bb70624e JA |
8103 | will run on. Usually @code{configure} can figure that |
8104 | out, but if it prints a message saying it can not guess the host | |
28ef6c31 | 8105 | type, give it the @option{--host=TYPE} option. @samp{TYPE} can |
bb70624e JA |
8106 | either be a short name for the system type, such as @samp{sun4}, |
8107 | or a canonical name with three fields: @samp{CPU-COMPANY-SYSTEM} | |
f73dda09 | 8108 | (e.g., @samp{i386-unknown-freebsd4.2}). |
ccc6cda3 | 8109 | |
bb70624e JA |
8110 | See the file @file{support/config.sub} for the possible |
8111 | values of each field. | |
ccc6cda3 | 8112 | |
bb70624e JA |
8113 | @node Sharing Defaults |
8114 | @section Sharing Defaults | |
ccc6cda3 | 8115 | |
bb70624e JA |
8116 | If you want to set default values for @code{configure} scripts to |
8117 | share, you can create a site shell script called | |
8118 | @code{config.site} that gives default values for variables like | |
8119 | @code{CC}, @code{cache_file}, and @code{prefix}. @code{configure} | |
8120 | looks for @file{PREFIX/share/config.site} if it exists, then | |
8121 | @file{PREFIX/etc/config.site} if it exists. Or, you can set the | |
8122 | @code{CONFIG_SITE} environment variable to the location of the site | |
8123 | script. A warning: the Bash @code{configure} looks for a site script, | |
8124 | but not all @code{configure} scripts do. | |
d166f048 | 8125 | |
bb70624e JA |
8126 | @node Operation Controls |
8127 | @section Operation Controls | |
ccc6cda3 | 8128 | |
bb70624e JA |
8129 | @code{configure} recognizes the following options to control how it |
8130 | operates. | |
ccc6cda3 | 8131 | |
bb70624e | 8132 | @table @code |
ccc6cda3 | 8133 | |
bb70624e JA |
8134 | @item --cache-file=@var{file} |
8135 | Use and save the results of the tests in | |
8136 | @var{file} instead of @file{./config.cache}. Set @var{file} to | |
8137 | @file{/dev/null} to disable caching, for debugging | |
8138 | @code{configure}. | |
ccc6cda3 | 8139 | |
bb70624e JA |
8140 | @item --help |
8141 | Print a summary of the options to @code{configure}, and exit. | |
ccc6cda3 | 8142 | |
bb70624e JA |
8143 | @item --quiet |
8144 | @itemx --silent | |
8145 | @itemx -q | |
8146 | Do not print messages saying which checks are being made. | |
ccc6cda3 | 8147 | |
bb70624e JA |
8148 | @item --srcdir=@var{dir} |
8149 | Look for the Bash source code in directory @var{dir}. Usually | |
8150 | @code{configure} can determine that directory automatically. | |
ccc6cda3 | 8151 | |
bb70624e JA |
8152 | @item --version |
8153 | Print the version of Autoconf used to generate the @code{configure} | |
8154 | script, and exit. | |
8155 | @end table | |
ccc6cda3 | 8156 | |
bb70624e JA |
8157 | @code{configure} also accepts some other, not widely used, boilerplate |
8158 | options. @samp{configure --help} prints the complete list. | |
ccc6cda3 | 8159 | |
bb70624e JA |
8160 | @node Optional Features |
8161 | @section Optional Features | |
ccc6cda3 | 8162 | |
28ef6c31 | 8163 | The Bash @code{configure} has a number of @option{--enable-@var{feature}} |
bb70624e | 8164 | options, where @var{feature} indicates an optional part of Bash. |
28ef6c31 | 8165 | There are also several @option{--with-@var{package}} options, |
bb70624e JA |
8166 | where @var{package} is something like @samp{bash-malloc} or @samp{purify}. |
8167 | To turn off the default use of a package, use | |
28ef6c31 JA |
8168 | @option{--without-@var{package}}. To configure Bash without a feature |
8169 | that is enabled by default, use @option{--disable-@var{feature}}. | |
ccc6cda3 | 8170 | |
28ef6c31 JA |
8171 | Here is a complete list of the @option{--enable-} and |
8172 | @option{--with-} options that the Bash @code{configure} recognizes. | |
ccc6cda3 | 8173 | |
bb70624e JA |
8174 | @table @code |
8175 | @item --with-afs | |
8176 | Define if you are using the Andrew File System from Transarc. | |
ccc6cda3 | 8177 | |
bb70624e JA |
8178 | @item --with-bash-malloc |
8179 | Use the Bash version of | |
95732b49 | 8180 | @code{malloc} in the directory @file{lib/malloc}. This is not the same |
bb70624e | 8181 | @code{malloc} that appears in @sc{gnu} libc, but an older version |
95732b49 JA |
8182 | originally derived from the 4.2 @sc{bsd} @code{malloc}. This @code{malloc} |
8183 | is very fast, but wastes some space on each allocation. | |
bb70624e JA |
8184 | This option is enabled by default. |
8185 | The @file{NOTES} file contains a list of systems for | |
8186 | which this should be turned off, and @code{configure} disables this | |
8187 | option automatically for a number of systems. | |
ccc6cda3 | 8188 | |
bb70624e JA |
8189 | @item --with-curses |
8190 | Use the curses library instead of the termcap library. This should | |
8191 | be supplied if your system has an inadequate or incomplete termcap | |
8192 | database. | |
ccc6cda3 | 8193 | |
bb70624e JA |
8194 | @item --with-gnu-malloc |
8195 | A synonym for @code{--with-bash-malloc}. | |
ccc6cda3 | 8196 | |
f73dda09 | 8197 | @item --with-installed-readline[=@var{PREFIX}] |
bb70624e JA |
8198 | Define this to make Bash link with a locally-installed version of Readline |
8199 | rather than the version in @file{lib/readline}. This works only with | |
95732b49 | 8200 | Readline 5.0 and later versions. If @var{PREFIX} is @code{yes} or not |
f73dda09 JA |
8201 | supplied, @code{configure} uses the values of the make variables |
8202 | @code{includedir} and @code{libdir}, which are subdirectories of @code{prefix} | |
8203 | by default, to find the installed version of Readline if it is not in | |
8204 | the standard system include and library directories. | |
8205 | If @var{PREFIX} is @code{no}, Bash links with the version in | |
8206 | @file{lib/readline}. | |
8207 | If @var{PREFIX} is set to any other value, @code{configure} treats it as | |
8208 | a directory pathname and looks for | |
8209 | the installed version of Readline in subdirectories of that directory | |
8210 | (include files in @var{PREFIX}/@code{include} and the library in | |
8211 | @var{PREFIX}/@code{lib}). | |
ccc6cda3 | 8212 | |
bb70624e JA |
8213 | @item --with-purify |
8214 | Define this to use the Purify memory allocation checker from Rational | |
8215 | Software. | |
ccc6cda3 | 8216 | |
bb70624e JA |
8217 | @item --enable-minimal-config |
8218 | This produces a shell with minimal features, close to the historical | |
8219 | Bourne shell. | |
8220 | @end table | |
ccc6cda3 | 8221 | |
28ef6c31 | 8222 | There are several @option{--enable-} options that alter how Bash is |
bb70624e | 8223 | compiled and linked, rather than changing run-time features. |
ccc6cda3 JA |
8224 | |
8225 | @table @code | |
f73dda09 JA |
8226 | @item --enable-largefile |
8227 | Enable support for @uref{http://www.sas.com/standards/large_file/x_open.20Mar96.html, | |
8228 | large files} if the operating system requires special compiler options | |
7117c2d2 JA |
8229 | to build programs which can access large files. This is enabled by |
8230 | default, if the operating system provides large file support. | |
f73dda09 | 8231 | |
bb70624e JA |
8232 | @item --enable-profiling |
8233 | This builds a Bash binary that produces profiling information to be | |
8234 | processed by @code{gprof} each time it is executed. | |
ccc6cda3 | 8235 | |
bb70624e JA |
8236 | @item --enable-static-link |
8237 | This causes Bash to be linked statically, if @code{gcc} is being used. | |
8238 | This could be used to build a version to use as root's shell. | |
8239 | @end table | |
8240 | ||
8241 | The @samp{minimal-config} option can be used to disable all of | |
8242 | the following options, but it is processed first, so individual | |
8243 | options may be enabled using @samp{enable-@var{feature}}. | |
8244 | ||
ac50fbac | 8245 | All of the following options except for @samp{disabled-builtins}, |
a0c0a00f | 8246 | @samp{direxpand-default}, and |
bb70624e JA |
8247 | @samp{xpg-echo-default} are |
8248 | enabled by default, unless the operating system does not provide the | |
8249 | necessary support. | |
8250 | ||
8251 | @table @code | |
8252 | @item --enable-alias | |
8253 | Allow alias expansion and include the @code{alias} and @code{unalias} | |
8254 | builtins (@pxref{Aliases}). | |
ccc6cda3 | 8255 | |
bb70624e JA |
8256 | @item --enable-arith-for-command |
8257 | Include support for the alternate form of the @code{for} command | |
8258 | that behaves like the C language @code{for} statement | |
8259 | (@pxref{Looping Constructs}). | |
ccc6cda3 | 8260 | |
bb70624e JA |
8261 | @item --enable-array-variables |
8262 | Include support for one-dimensional array shell variables | |
8263 | (@pxref{Arrays}). | |
ccc6cda3 | 8264 | |
bb70624e JA |
8265 | @item --enable-bang-history |
8266 | Include support for @code{csh}-like history substitution | |
8267 | (@pxref{History Interaction}). | |
ccc6cda3 | 8268 | |
bb70624e JA |
8269 | @item --enable-brace-expansion |
8270 | Include @code{csh}-like brace expansion | |
8271 | ( @code{b@{a,b@}c} @expansion{} @code{bac bbc} ). | |
8272 | See @ref{Brace Expansion}, for a complete description. | |
ccc6cda3 | 8273 | |
3185942a JA |
8274 | @item --enable-casemod-attributes |
8275 | Include support for case-modifying attributes in the @code{declare} builtin | |
8276 | and assignment statements. Variables with the @var{uppercase} attribute, | |
8277 | for example, will have their values converted to uppercase upon assignment. | |
8278 | ||
8279 | @item --enable-casemod-expansion | |
8280 | Include support for case-modifying word expansions. | |
8281 | ||
bb70624e JA |
8282 | @item --enable-command-timing |
8283 | Include support for recognizing @code{time} as a reserved word and for | |
8284 | displaying timing statistics for the pipeline following @code{time} | |
8285 | (@pxref{Pipelines}). | |
8286 | This allows pipelines as well as shell builtins and functions to be timed. | |
ccc6cda3 | 8287 | |
bb70624e | 8288 | @item --enable-cond-command |
b80f6443 JA |
8289 | Include support for the @code{[[} conditional command. |
8290 | (@pxref{Conditional Constructs}). | |
8291 | ||
8292 | @item --enable-cond-regexp | |
495aee44 | 8293 | Include support for matching @sc{posix} regular expressions using the |
b80f6443 | 8294 | @samp{=~} binary operator in the @code{[[} conditional command. |
bb70624e | 8295 | (@pxref{Conditional Constructs}). |
ccc6cda3 | 8296 | |
3185942a JA |
8297 | @item --enable-coprocesses |
8298 | Include support for coprocesses and the @code{coproc} reserved word | |
8299 | (@pxref{Pipelines}). | |
8300 | ||
95732b49 JA |
8301 | @item --enable-debugger |
8302 | Include support for the bash debugger (distributed separately). | |
8303 | ||
ac50fbac CR |
8304 | @item --enable-direxpand-default |
8305 | Cause the @code{direxpand} shell option (@pxref{The Shopt Builtin}) | |
8306 | to be enabled by default when the shell starts. | |
8307 | It is normally disabled by default. | |
8308 | ||
bb70624e JA |
8309 | @item --enable-directory-stack |
8310 | Include support for a @code{csh}-like directory stack and the | |
8311 | @code{pushd}, @code{popd}, and @code{dirs} builtins | |
8312 | (@pxref{The Directory Stack}). | |
ccc6cda3 | 8313 | |
bb70624e JA |
8314 | @item --enable-disabled-builtins |
8315 | Allow builtin commands to be invoked via @samp{builtin xxx} | |
8316 | even after @code{xxx} has been disabled using @samp{enable -n xxx}. | |
8317 | See @ref{Bash Builtins}, for details of the @code{builtin} and | |
8318 | @code{enable} builtin commands. | |
ccc6cda3 | 8319 | |
bb70624e JA |
8320 | @item --enable-dparen-arithmetic |
8321 | Include support for the @code{((@dots{}))} command | |
8322 | (@pxref{Conditional Constructs}). | |
ccc6cda3 | 8323 | |
bb70624e JA |
8324 | @item --enable-extended-glob |
8325 | Include support for the extended pattern matching features described | |
8326 | above under @ref{Pattern Matching}. | |
ccc6cda3 | 8327 | |
0001803f CR |
8328 | @item --enable-extended-glob-default |
8329 | Set the default value of the @var{extglob} shell option described | |
8330 | above under @ref{The Shopt Builtin} to be enabled. | |
8331 | ||
a0c0a00f CR |
8332 | @item --enable-function-import |
8333 | Include support for importing function definitions exported by another | |
8334 | instance of the shell from the environment. This option is enabled by | |
8335 | default. | |
8336 | ||
ac50fbac CR |
8337 | @item --enable-glob-asciirange-default |
8338 | Set the default value of the @var{globasciiranges} shell option described | |
8339 | above under @ref{The Shopt Builtin} to be enabled. | |
8340 | This controls the behavior of character ranges when used in pattern matching | |
8341 | bracket expressions. | |
8342 | ||
bb70624e JA |
8343 | @item --enable-help-builtin |
8344 | Include the @code{help} builtin, which displays help on shell builtins and | |
8345 | variables (@pxref{Bash Builtins}). | |
ccc6cda3 | 8346 | |
bb70624e JA |
8347 | @item --enable-history |
8348 | Include command history and the @code{fc} and @code{history} | |
8349 | builtin commands (@pxref{Bash History Facilities}). | |
ccc6cda3 | 8350 | |
bb70624e JA |
8351 | @item --enable-job-control |
8352 | This enables the job control features (@pxref{Job Control}), | |
8353 | if the operating system supports them. | |
ccc6cda3 | 8354 | |
b80f6443 JA |
8355 | @item --enable-multibyte |
8356 | This enables support for multibyte characters if the operating | |
8357 | system provides the necessary support. | |
8358 | ||
bb70624e JA |
8359 | @item --enable-net-redirections |
8360 | This enables the special handling of filenames of the form | |
8361 | @code{/dev/tcp/@var{host}/@var{port}} and | |
8362 | @code{/dev/udp/@var{host}/@var{port}} | |
8363 | when used in redirections (@pxref{Redirections}). | |
ccc6cda3 | 8364 | |
bb70624e JA |
8365 | @item --enable-process-substitution |
8366 | This enables process substitution (@pxref{Process Substitution}) if | |
8367 | the operating system provides the necessary support. | |
ccc6cda3 | 8368 | |
95732b49 JA |
8369 | @item --enable-progcomp |
8370 | Enable the programmable completion facilities | |
8371 | (@pxref{Programmable Completion}). | |
8372 | If Readline is not enabled, this option has no effect. | |
8373 | ||
bb70624e JA |
8374 | @item --enable-prompt-string-decoding |
8375 | Turn on the interpretation of a number of backslash-escaped characters | |
28ef6c31 | 8376 | in the @env{$PS1}, @env{$PS2}, @env{$PS3}, and @env{$PS4} prompt |
ac50fbac | 8377 | strings. See @ref{Controlling the Prompt}, for a complete list of prompt |
bb70624e | 8378 | string escape sequences. |
ccc6cda3 | 8379 | |
bb70624e JA |
8380 | @item --enable-readline |
8381 | Include support for command-line editing and history with the Bash | |
8382 | version of the Readline library (@pxref{Command Line Editing}). | |
ccc6cda3 | 8383 | |
bb70624e JA |
8384 | @item --enable-restricted |
8385 | Include support for a @dfn{restricted shell}. If this is enabled, Bash, | |
8386 | when called as @code{rbash}, enters a restricted mode. See | |
8387 | @ref{The Restricted Shell}, for a description of restricted mode. | |
ccc6cda3 | 8388 | |
bb70624e | 8389 | @item --enable-select |
495aee44 CR |
8390 | Include the @code{select} compound command, which allows the generation of |
8391 | simple menus (@pxref{Conditional Constructs}). | |
ccc6cda3 | 8392 | |
95732b49 JA |
8393 | @item --enable-separate-helpfiles |
8394 | Use external files for the documentation displayed by the @code{help} builtin | |
8395 | instead of storing the text internally. | |
8396 | ||
8397 | @item --enable-single-help-strings | |
8398 | Store the text displayed by the @code{help} builtin as a single string for | |
8399 | each help topic. This aids in translating the text to different languages. | |
8400 | You may need to disable this if your compiler cannot handle very long string | |
8401 | literals. | |
8402 | ||
8403 | @item --enable-strict-posix-default | |
8404 | Make Bash @sc{posix}-conformant by default (@pxref{Bash POSIX Mode}). | |
8405 | ||
bb70624e JA |
8406 | @item --enable-usg-echo-default |
8407 | A synonym for @code{--enable-xpg-echo-default}. | |
ccc6cda3 | 8408 | |
bb70624e JA |
8409 | @item --enable-xpg-echo-default |
8410 | Make the @code{echo} builtin expand backslash-escaped characters by default, | |
28ef6c31 | 8411 | without requiring the @option{-e} option. |
bb70624e JA |
8412 | This sets the default value of the @code{xpg_echo} shell option to @code{on}, |
8413 | which makes the Bash @code{echo} behave more like the version specified in | |
95732b49 | 8414 | the Single Unix Specification, version 3. |
bb70624e JA |
8415 | @xref{Bash Builtins}, for a description of the escape sequences that |
8416 | @code{echo} recognizes. | |
bb70624e | 8417 | @end table |
ccc6cda3 | 8418 | |
bb70624e JA |
8419 | The file @file{config-top.h} contains C Preprocessor |
8420 | @samp{#define} statements for options which are not settable from | |
8421 | @code{configure}. | |
8422 | Some of these are not meant to be changed; beware of the consequences if | |
8423 | you do. | |
8424 | Read the comments associated with each definition for more | |
8425 | information about its effect. | |
ccc6cda3 | 8426 | |
bb70624e JA |
8427 | @node Reporting Bugs |
8428 | @appendix Reporting Bugs | |
ccc6cda3 | 8429 | |
bb70624e JA |
8430 | Please report all bugs you find in Bash. |
8431 | But first, you should | |
8432 | make sure that it really is a bug, and that it appears in the latest | |
b80f6443 JA |
8433 | version of Bash. |
8434 | The latest version of Bash is always available for FTP from | |
0001803f | 8435 | @uref{ftp://ftp.gnu.org/pub/gnu/bash/}. |
ccc6cda3 | 8436 | |
bb70624e JA |
8437 | Once you have determined that a bug actually exists, use the |
8438 | @code{bashbug} command to submit a bug report. | |
8439 | If you have a fix, you are encouraged to mail that as well! | |
8440 | Suggestions and `philosophical' bug reports may be mailed | |
8441 | to @email{bug-bash@@gnu.org} or posted to the Usenet | |
8442 | newsgroup @code{gnu.bash.bug}. | |
ccc6cda3 | 8443 | |
bb70624e JA |
8444 | All bug reports should include: |
8445 | @itemize @bullet | |
8446 | @item | |
8447 | The version number of Bash. | |
8448 | @item | |
8449 | The hardware and operating system. | |
8450 | @item | |
8451 | The compiler used to compile Bash. | |
8452 | @item | |
8453 | A description of the bug behaviour. | |
8454 | @item | |
8455 | A short script or `recipe' which exercises the bug and may be used | |
8456 | to reproduce it. | |
8457 | @end itemize | |
ccc6cda3 | 8458 | |
bb70624e JA |
8459 | @noindent |
8460 | @code{bashbug} inserts the first three items automatically into | |
8461 | the template it provides for filing a bug report. | |
ccc6cda3 | 8462 | |
bb70624e | 8463 | Please send all reports concerning this manual to |
ac50fbac | 8464 | @email{bug-bash@@gnu.org}. |
ccc6cda3 | 8465 | |
bb70624e JA |
8466 | @node Major Differences From The Bourne Shell |
8467 | @appendix Major Differences From The Bourne Shell | |
d166f048 | 8468 | |
bb70624e JA |
8469 | Bash implements essentially the same grammar, parameter and |
8470 | variable expansion, redirection, and quoting as the Bourne Shell. | |
0628567a | 8471 | Bash uses the @sc{posix} standard as the specification of |
bb70624e JA |
8472 | how these features are to be implemented. There are some |
8473 | differences between the traditional Bourne shell and Bash; this | |
8474 | section quickly details the differences of significance. A | |
8475 | number of these differences are explained in greater depth in | |
8476 | previous sections. | |
95732b49 JA |
8477 | This section uses the version of @code{sh} included in SVR4.2 (the |
8478 | last version of the historical Bourne shell) as the baseline reference. | |
ccc6cda3 | 8479 | |
bb70624e | 8480 | @itemize @bullet |
ccc6cda3 | 8481 | |
ccc6cda3 | 8482 | @item |
bb70624e | 8483 | Bash is @sc{posix}-conformant, even where the @sc{posix} specification |
28ef6c31 | 8484 | differs from traditional @code{sh} behavior (@pxref{Bash POSIX Mode}). |
ccc6cda3 JA |
8485 | |
8486 | @item | |
bb70624e | 8487 | Bash has multi-character invocation options (@pxref{Invoking Bash}). |
ccc6cda3 JA |
8488 | |
8489 | @item | |
bb70624e JA |
8490 | Bash has command-line editing (@pxref{Command Line Editing}) and |
8491 | the @code{bind} builtin. | |
ccc6cda3 JA |
8492 | |
8493 | @item | |
bb70624e | 8494 | Bash provides a programmable word completion mechanism |
3185942a JA |
8495 | (@pxref{Programmable Completion}), and builtin commands |
8496 | @code{complete}, @code{compgen}, and @code{compopt}, to | |
8497 | manipulate it. | |
ccc6cda3 | 8498 | |
bb70624e JA |
8499 | @item |
8500 | Bash has command history (@pxref{Bash History Facilities}) and the | |
8501 | @code{history} and @code{fc} builtins to manipulate it. | |
b80f6443 JA |
8502 | The Bash history list maintains timestamp information and uses the |
8503 | value of the @code{HISTTIMEFORMAT} variable to display it. | |
ccc6cda3 | 8504 | |
bb70624e JA |
8505 | @item |
8506 | Bash implements @code{csh}-like history expansion | |
8507 | (@pxref{History Interaction}). | |
ccc6cda3 | 8508 | |
bb70624e JA |
8509 | @item |
8510 | Bash has one-dimensional array variables (@pxref{Arrays}), and the | |
8511 | appropriate variable expansions and assignment syntax to use them. | |
8512 | Several of the Bash builtins take options to act on arrays. | |
8513 | Bash provides a number of built-in array variables. | |
ccc6cda3 | 8514 | |
bb70624e JA |
8515 | @item |
8516 | The @code{$'@dots{}'} quoting syntax, which expands ANSI-C | |
8517 | backslash-escaped characters in the text between the single quotes, | |
8518 | is supported (@pxref{ANSI-C Quoting}). | |
ccc6cda3 | 8519 | |
bb70624e JA |
8520 | @item |
8521 | Bash supports the @code{$"@dots{}"} quoting syntax to do | |
8522 | locale-specific translation of the characters between the double | |
28ef6c31 | 8523 | quotes. The @option{-D}, @option{--dump-strings}, and @option{--dump-po-strings} |
bb70624e JA |
8524 | invocation options list the translatable strings found in a script |
8525 | (@pxref{Locale Translation}). | |
ccc6cda3 | 8526 | |
bb70624e JA |
8527 | @item |
8528 | Bash implements the @code{!} keyword to negate the return value of | |
8529 | a pipeline (@pxref{Pipelines}). | |
8530 | Very useful when an @code{if} statement needs to act only if a test fails. | |
95732b49 JA |
8531 | The Bash @samp{-o pipefail} option to @code{set} will cause a pipeline to |
8532 | return a failure status if any command fails. | |
ccc6cda3 | 8533 | |
bb70624e JA |
8534 | @item |
8535 | Bash has the @code{time} reserved word and command timing (@pxref{Pipelines}). | |
8536 | The display of the timing statistics may be controlled with the | |
28ef6c31 | 8537 | @env{TIMEFORMAT} variable. |
ccc6cda3 | 8538 | |
bb70624e JA |
8539 | @item |
8540 | Bash implements the @code{for (( @var{expr1} ; @var{expr2} ; @var{expr3} ))} | |
8541 | arithmetic for command, similar to the C language (@pxref{Looping Constructs}). | |
ccc6cda3 | 8542 | |
bb70624e JA |
8543 | @item |
8544 | Bash includes the @code{select} compound command, which allows the | |
8545 | generation of simple menus (@pxref{Conditional Constructs}). | |
ccc6cda3 | 8546 | |
bb70624e JA |
8547 | @item |
8548 | Bash includes the @code{[[} compound command, which makes conditional | |
95732b49 JA |
8549 | testing part of the shell grammar (@pxref{Conditional Constructs}), including |
8550 | optional regular expression matching. | |
8551 | ||
8552 | @item | |
8553 | Bash provides optional case-insensitive matching for the @code{case} and | |
8554 | @code{[[} constructs. | |
ccc6cda3 | 8555 | |
bb70624e JA |
8556 | @item |
8557 | Bash includes brace expansion (@pxref{Brace Expansion}) and tilde | |
8558 | expansion (@pxref{Tilde Expansion}). | |
ccc6cda3 | 8559 | |
bb70624e JA |
8560 | @item |
8561 | Bash implements command aliases and the @code{alias} and @code{unalias} | |
8562 | builtins (@pxref{Aliases}). | |
ccc6cda3 | 8563 | |
bb70624e JA |
8564 | @item |
8565 | Bash provides shell arithmetic, the @code{((} compound command | |
8566 | (@pxref{Conditional Constructs}), | |
8567 | and arithmetic expansion (@pxref{Shell Arithmetic}). | |
ccc6cda3 | 8568 | |
bb70624e JA |
8569 | @item |
8570 | Variables present in the shell's initial environment are automatically | |
8571 | exported to child processes. The Bourne shell does not normally do | |
8572 | this unless the variables are explicitly marked using the @code{export} | |
8573 | command. | |
ccc6cda3 | 8574 | |
95732b49 JA |
8575 | @item |
8576 | Bash supports the @samp{+=} assignment operator, which appends to the value | |
8577 | of the variable named on the left hand side. | |
8578 | ||
bb70624e JA |
8579 | @item |
8580 | Bash includes the @sc{posix} pattern removal @samp{%}, @samp{#}, @samp{%%} | |
8581 | and @samp{##} expansions to remove leading or trailing substrings from | |
8582 | variable values (@pxref{Shell Parameter Expansion}). | |
ccc6cda3 | 8583 | |
bb70624e JA |
8584 | @item |
8585 | The expansion @code{$@{#xx@}}, which returns the length of @code{$@{xx@}}, | |
8586 | is supported (@pxref{Shell Parameter Expansion}). | |
ccc6cda3 | 8587 | |
bb70624e JA |
8588 | @item |
8589 | The expansion @code{$@{var:}@var{offset}@code{[:}@var{length}@code{]@}}, | |
8590 | which expands to the substring of @code{var}'s value of length | |
8591 | @var{length}, beginning at @var{offset}, is present | |
8592 | (@pxref{Shell Parameter Expansion}). | |
ccc6cda3 | 8593 | |
bb70624e JA |
8594 | @item |
8595 | The expansion | |
8596 | @code{$@{var/[/]}@var{pattern}@code{[/}@var{replacement}@code{]@}}, | |
8597 | which matches @var{pattern} and replaces it with @var{replacement} in | |
8598 | the value of @code{var}, is available (@pxref{Shell Parameter Expansion}). | |
ccc6cda3 | 8599 | |
bb70624e | 8600 | @item |
ac50fbac | 8601 | The expansion @code{$@{!@var{prefix}*@}} expansion, which expands to |
bb70624e JA |
8602 | the names of all shell variables whose names begin with @var{prefix}, |
8603 | is available (@pxref{Shell Parameter Expansion}). | |
ccc6cda3 | 8604 | |
bb70624e JA |
8605 | @item |
8606 | Bash has @var{indirect} variable expansion using @code{$@{!word@}} | |
8607 | (@pxref{Shell Parameter Expansion}). | |
ccc6cda3 | 8608 | |
bb70624e JA |
8609 | @item |
8610 | Bash can expand positional parameters beyond @code{$9} using | |
8611 | @code{$@{@var{num}@}}. | |
ccc6cda3 | 8612 | |
bb70624e JA |
8613 | @item |
8614 | The @sc{posix} @code{$()} form of command substitution | |
8615 | is implemented (@pxref{Command Substitution}), | |
8616 | and preferred to the Bourne shell's @code{``} (which | |
8617 | is also implemented for backwards compatibility). | |
ccc6cda3 | 8618 | |
bb70624e JA |
8619 | @item |
8620 | Bash has process substitution (@pxref{Process Substitution}). | |
ccc6cda3 | 8621 | |
bb70624e JA |
8622 | @item |
8623 | Bash automatically assigns variables that provide information about the | |
28ef6c31 JA |
8624 | current user (@env{UID}, @env{EUID}, and @env{GROUPS}), the current host |
8625 | (@env{HOSTTYPE}, @env{OSTYPE}, @env{MACHTYPE}, and @env{HOSTNAME}), | |
8626 | and the instance of Bash that is running (@env{BASH}, | |
8627 | @env{BASH_VERSION}, and @env{BASH_VERSINFO}). @xref{Bash Variables}, | |
bb70624e | 8628 | for details. |
ccc6cda3 | 8629 | |
bb70624e | 8630 | @item |
28ef6c31 | 8631 | The @env{IFS} variable is used to split only the results of expansion, |
bb70624e JA |
8632 | not all words (@pxref{Word Splitting}). |
8633 | This closes a longstanding shell security hole. | |
ccc6cda3 | 8634 | |
ac50fbac CR |
8635 | @item |
8636 | The filename expansion bracket expression code uses @samp{!} and @samp{^} | |
8637 | to negate the set of characters between the brackets. | |
8638 | The Bourne shell uses only @samp{!}. | |
8639 | ||
bb70624e | 8640 | @item |
0628567a | 8641 | Bash implements the full set of @sc{posix} filename expansion operators, |
bb70624e JA |
8642 | including @var{character classes}, @var{equivalence classes}, and |
8643 | @var{collating symbols} (@pxref{Filename Expansion}). | |
ccc6cda3 | 8644 | |
bb70624e JA |
8645 | @item |
8646 | Bash implements extended pattern matching features when the @code{extglob} | |
8647 | shell option is enabled (@pxref{Pattern Matching}). | |
ccc6cda3 | 8648 | |
bb70624e JA |
8649 | @item |
8650 | It is possible to have a variable and a function with the same name; | |
8651 | @code{sh} does not separate the two name spaces. | |
ccc6cda3 | 8652 | |
bb70624e JA |
8653 | @item |
8654 | Bash functions are permitted to have local variables using the | |
8655 | @code{local} builtin, and thus useful recursive functions may be written | |
8656 | (@pxref{Bash Builtins}). | |
ccc6cda3 | 8657 | |
bb70624e JA |
8658 | @item |
8659 | Variable assignments preceding commands affect only that command, even | |
8660 | builtins and functions (@pxref{Environment}). | |
8661 | In @code{sh}, all variable assignments | |
8662 | preceding commands are global unless the command is executed from the | |
8663 | file system. | |
ccc6cda3 | 8664 | |
bb70624e JA |
8665 | @item |
8666 | Bash performs filename expansion on filenames specified as operands | |
8667 | to input and output redirection operators (@pxref{Redirections}). | |
ccc6cda3 | 8668 | |
bb70624e JA |
8669 | @item |
8670 | Bash contains the @samp{<>} redirection operator, allowing a file to be | |
8671 | opened for both reading and writing, and the @samp{&>} redirection | |
8672 | operator, for directing standard output and standard error to the same | |
8673 | file (@pxref{Redirections}). | |
ccc6cda3 | 8674 | |
95732b49 JA |
8675 | @item |
8676 | Bash includes the @samp{<<<} redirection operator, allowing a string to | |
8677 | be used as the standard input to a command. | |
8678 | ||
8679 | @item | |
8680 | Bash implements the @samp{[n]<&@var{word}} and @samp{[n]>&@var{word}} | |
8681 | redirection operators, which move one file descriptor to another. | |
8682 | ||
bb70624e JA |
8683 | @item |
8684 | Bash treats a number of filenames specially when they are | |
8685 | used in redirection operators (@pxref{Redirections}). | |
ccc6cda3 | 8686 | |
bb70624e JA |
8687 | @item |
8688 | Bash can open network connections to arbitrary machines and services | |
8689 | with the redirection operators (@pxref{Redirections}). | |
ccc6cda3 | 8690 | |
bb70624e JA |
8691 | @item |
8692 | The @code{noclobber} option is available to avoid overwriting existing | |
8693 | files with output redirection (@pxref{The Set Builtin}). | |
8694 | The @samp{>|} redirection operator may be used to override @code{noclobber}. | |
d166f048 | 8695 | |
bb70624e JA |
8696 | @item |
8697 | The Bash @code{cd} and @code{pwd} builtins (@pxref{Bourne Shell Builtins}) | |
28ef6c31 | 8698 | each take @option{-L} and @option{-P} options to switch between logical and |
bb70624e | 8699 | physical modes. |
d166f048 | 8700 | |
bb70624e JA |
8701 | @item |
8702 | Bash allows a function to override a builtin with the same name, and provides | |
8703 | access to that builtin's functionality within the function via the | |
8704 | @code{builtin} and @code{command} builtins (@pxref{Bash Builtins}). | |
d166f048 | 8705 | |
bb70624e JA |
8706 | @item |
8707 | The @code{command} builtin allows selective disabling of functions | |
8708 | when command lookup is performed (@pxref{Bash Builtins}). | |
ccc6cda3 | 8709 | |
bb70624e JA |
8710 | @item |
8711 | Individual builtins may be enabled or disabled using the @code{enable} | |
8712 | builtin (@pxref{Bash Builtins}). | |
b72432fd | 8713 | |
bb70624e JA |
8714 | @item |
8715 | The Bash @code{exec} builtin takes additional options that allow users | |
8716 | to control the contents of the environment passed to the executed | |
8717 | command, and what the zeroth argument to the command is to be | |
8718 | (@pxref{Bourne Shell Builtins}). | |
ccc6cda3 | 8719 | |
bb70624e JA |
8720 | @item |
8721 | Shell functions may be exported to children via the environment | |
8722 | using @code{export -f} (@pxref{Shell Functions}). | |
ccc6cda3 | 8723 | |
bb70624e JA |
8724 | @item |
8725 | The Bash @code{export}, @code{readonly}, and @code{declare} builtins can | |
28ef6c31 | 8726 | take a @option{-f} option to act on shell functions, a @option{-p} option to |
bb70624e | 8727 | display variables with various attributes set in a format that can be |
28ef6c31 | 8728 | used as shell input, a @option{-n} option to remove various variable |
bb70624e JA |
8729 | attributes, and @samp{name=value} arguments to set variable attributes |
8730 | and values simultaneously. | |
cce855bc | 8731 | |
bb70624e JA |
8732 | @item |
8733 | The Bash @code{hash} builtin allows a name to be associated with | |
8734 | an arbitrary filename, even when that filename cannot be found by | |
28ef6c31 | 8735 | searching the @env{$PATH}, using @samp{hash -p} |
bb70624e | 8736 | (@pxref{Bourne Shell Builtins}). |
cce855bc | 8737 | |
bb70624e JA |
8738 | @item |
8739 | Bash includes a @code{help} builtin for quick reference to shell | |
8740 | facilities (@pxref{Bash Builtins}). | |
cce855bc | 8741 | |
bb70624e JA |
8742 | @item |
8743 | The @code{printf} builtin is available to display formatted output | |
8744 | (@pxref{Bash Builtins}). | |
ccc6cda3 | 8745 | |
bb70624e JA |
8746 | @item |
8747 | The Bash @code{read} builtin (@pxref{Bash Builtins}) | |
8748 | will read a line ending in @samp{\} with | |
28ef6c31 | 8749 | the @option{-r} option, and will use the @env{REPLY} variable as a |
bb70624e JA |
8750 | default if no non-option arguments are supplied. |
8751 | The Bash @code{read} builtin | |
28ef6c31 JA |
8752 | also accepts a prompt string with the @option{-p} option and will use |
8753 | Readline to obtain the line when given the @option{-e} option. | |
bb70624e | 8754 | The @code{read} builtin also has additional options to control input: |
28ef6c31 JA |
8755 | the @option{-s} option will turn off echoing of input characters as |
8756 | they are read, the @option{-t} option will allow @code{read} to time out | |
bb70624e | 8757 | if input does not arrive within a specified number of seconds, the |
28ef6c31 JA |
8758 | @option{-n} option will allow reading only a specified number of |
8759 | characters rather than a full line, and the @option{-d} option will read | |
bb70624e | 8760 | until a particular character rather than newline. |
ccc6cda3 | 8761 | |
bb70624e JA |
8762 | @item |
8763 | The @code{return} builtin may be used to abort execution of scripts | |
8764 | executed with the @code{.} or @code{source} builtins | |
8765 | (@pxref{Bourne Shell Builtins}). | |
ccc6cda3 | 8766 | |
bb70624e JA |
8767 | @item |
8768 | Bash includes the @code{shopt} builtin, for finer control of shell | |
3185942a | 8769 | optional capabilities (@pxref{The Shopt Builtin}), and allows these options |
f73dda09 | 8770 | to be set and unset at shell invocation (@pxref{Invoking Bash}). |
ccc6cda3 | 8771 | |
bb70624e JA |
8772 | @item |
8773 | Bash has much more optional behavior controllable with the @code{set} | |
8774 | builtin (@pxref{The Set Builtin}). | |
ccc6cda3 | 8775 | |
b80f6443 | 8776 | @item |
ac50fbac | 8777 | The @samp{-x} (@option{xtrace}) option displays commands other than |
b80f6443 JA |
8778 | simple commands when performing an execution trace |
8779 | (@pxref{The Set Builtin}). | |
8780 | ||
bb70624e JA |
8781 | @item |
8782 | The @code{test} builtin (@pxref{Bourne Shell Builtins}) | |
8783 | is slightly different, as it implements the @sc{posix} algorithm, | |
8784 | which specifies the behavior based on the number of arguments. | |
d166f048 | 8785 | |
b80f6443 JA |
8786 | @item |
8787 | Bash includes the @code{caller} builtin, which displays the context of | |
8788 | any active subroutine call (a shell function or a script executed with | |
8789 | the @code{.} or @code{source} builtins). This supports the bash | |
8790 | debugger. | |
8791 | ||
bb70624e | 8792 | @item |
f73dda09 JA |
8793 | The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows a |
8794 | @code{DEBUG} pseudo-signal specification, similar to @code{EXIT}. | |
b80f6443 JA |
8795 | Commands specified with a @code{DEBUG} trap are executed before every |
8796 | simple command, @code{for} command, @code{case} command, | |
8797 | @code{select} command, every arithmetic @code{for} command, and before | |
8798 | the first command executes in a shell function. | |
7117c2d2 | 8799 | The @code{DEBUG} trap is not inherited by shell functions unless the |
b80f6443 JA |
8800 | function has been given the @code{trace} attribute or the |
8801 | @code{functrace} option has been enabled using the @code{shopt} builtin. | |
8802 | The @code{extdebug} shell option has additional effects on the | |
8803 | @code{DEBUG} trap. | |
f73dda09 JA |
8804 | |
8805 | The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows an | |
8806 | @code{ERR} pseudo-signal specification, similar to @code{EXIT} and @code{DEBUG}. | |
8807 | Commands specified with an @code{ERR} trap are executed after a simple | |
8808 | command fails, with a few exceptions. | |
b80f6443 JA |
8809 | The @code{ERR} trap is not inherited by shell functions unless the |
8810 | @code{-o errtrace} option to the @code{set} builtin is enabled. | |
8811 | ||
8812 | The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows a | |
8813 | @code{RETURN} pseudo-signal specification, similar to | |
8814 | @code{EXIT} and @code{DEBUG}. | |
8815 | Commands specified with an @code{RETURN} trap are executed before | |
8816 | execution resumes after a shell function or a shell script executed with | |
8817 | @code{.} or @code{source} returns. | |
95732b49 JA |
8818 | The @code{RETURN} trap is not inherited by shell functions unless the |
8819 | function has been given the @code{trace} attribute or the | |
8820 | @code{functrace} option has been enabled using the @code{shopt} builtin. | |
d166f048 | 8821 | |
bb70624e JA |
8822 | @item |
8823 | The Bash @code{type} builtin is more extensive and gives more information | |
8824 | about the names it finds (@pxref{Bash Builtins}). | |
cce855bc | 8825 | |
bb70624e | 8826 | @item |
28ef6c31 | 8827 | The Bash @code{umask} builtin permits a @option{-p} option to cause |
bb70624e JA |
8828 | the output to be displayed in the form of a @code{umask} command |
8829 | that may be reused as input (@pxref{Bourne Shell Builtins}). | |
ccc6cda3 | 8830 | |
bb70624e JA |
8831 | @item |
8832 | Bash implements a @code{csh}-like directory stack, and provides the | |
8833 | @code{pushd}, @code{popd}, and @code{dirs} builtins to manipulate it | |
8834 | (@pxref{The Directory Stack}). | |
8835 | Bash also makes the directory stack visible as the value of the | |
28ef6c31 | 8836 | @env{DIRSTACK} shell variable. |
d166f048 | 8837 | |
bb70624e JA |
8838 | @item |
8839 | Bash interprets special backslash-escaped characters in the prompt | |
ac50fbac | 8840 | strings when interactive (@pxref{Controlling the Prompt}). |
cce855bc | 8841 | |
bb70624e JA |
8842 | @item |
8843 | The Bash restricted mode is more useful (@pxref{The Restricted Shell}); | |
8844 | the SVR4.2 shell restricted mode is too limited. | |
d166f048 | 8845 | |
bb70624e JA |
8846 | @item |
8847 | The @code{disown} builtin can remove a job from the internal shell | |
8848 | job table (@pxref{Job Control Builtins}) or suppress the sending | |
8849 | of @code{SIGHUP} to a job when the shell exits as the result of a | |
8850 | @code{SIGHUP}. | |
d166f048 | 8851 | |
95732b49 JA |
8852 | @item |
8853 | Bash includes a number of features to support a separate debugger for | |
8854 | shell scripts. | |
8855 | ||
bb70624e JA |
8856 | @item |
8857 | The SVR4.2 shell has two privilege-related builtins | |
8858 | (@code{mldmode} and @code{priv}) not present in Bash. | |
d166f048 | 8859 | |
bb70624e JA |
8860 | @item |
8861 | Bash does not have the @code{stop} or @code{newgrp} builtins. | |
ccc6cda3 | 8862 | |
bb70624e | 8863 | @item |
28ef6c31 | 8864 | Bash does not use the @env{SHACCT} variable or perform shell accounting. |
ccc6cda3 | 8865 | |
bb70624e | 8866 | @item |
28ef6c31 JA |
8867 | The SVR4.2 @code{sh} uses a @env{TIMEOUT} variable like Bash uses |
8868 | @env{TMOUT}. | |
ccc6cda3 | 8869 | |
bb70624e | 8870 | @end itemize |
d166f048 | 8871 | |
bb70624e JA |
8872 | @noindent |
8873 | More features unique to Bash may be found in @ref{Bash Features}. | |
d166f048 | 8874 | |
ccc6cda3 | 8875 | |
bb70624e | 8876 | @appendixsec Implementation Differences From The SVR4.2 Shell |
ccc6cda3 | 8877 | |
bb70624e JA |
8878 | Since Bash is a completely new implementation, it does not suffer from |
8879 | many of the limitations of the SVR4.2 shell. For instance: | |
ccc6cda3 | 8880 | |
bb70624e | 8881 | @itemize @bullet |
ccc6cda3 | 8882 | |
bb70624e JA |
8883 | @item |
8884 | Bash does not fork a subshell when redirecting into or out of | |
8885 | a shell control structure such as an @code{if} or @code{while} | |
8886 | statement. | |
ccc6cda3 | 8887 | |
bb70624e JA |
8888 | @item |
8889 | Bash does not allow unbalanced quotes. The SVR4.2 shell will silently | |
8890 | insert a needed closing quote at @code{EOF} under certain circumstances. | |
8891 | This can be the cause of some hard-to-find errors. | |
ccc6cda3 | 8892 | |
bb70624e JA |
8893 | @item |
8894 | The SVR4.2 shell uses a baroque memory management scheme based on | |
8895 | trapping @code{SIGSEGV}. If the shell is started from a process with | |
8896 | @code{SIGSEGV} blocked (e.g., by using the @code{system()} C library | |
8897 | function call), it misbehaves badly. | |
ccc6cda3 | 8898 | |
ccc6cda3 | 8899 | @item |
bb70624e | 8900 | In a questionable attempt at security, the SVR4.2 shell, |
28ef6c31 | 8901 | when invoked without the @option{-p} option, will alter its real |
bb70624e JA |
8902 | and effective @sc{uid} and @sc{gid} if they are less than some |
8903 | magic threshold value, commonly 100. | |
8904 | This can lead to unexpected results. | |
8905 | ||
ccc6cda3 | 8906 | @item |
bb70624e JA |
8907 | The SVR4.2 shell does not allow users to trap @code{SIGSEGV}, |
8908 | @code{SIGALRM}, or @code{SIGCHLD}. | |
8909 | ||
ccc6cda3 | 8910 | @item |
28ef6c31 JA |
8911 | The SVR4.2 shell does not allow the @env{IFS}, @env{MAILCHECK}, |
8912 | @env{PATH}, @env{PS1}, or @env{PS2} variables to be unset. | |
bb70624e | 8913 | |
ccc6cda3 | 8914 | @item |
bb70624e JA |
8915 | The SVR4.2 shell treats @samp{^} as the undocumented equivalent of |
8916 | @samp{|}. | |
8917 | ||
ccc6cda3 | 8918 | @item |
bb70624e JA |
8919 | Bash allows multiple option arguments when it is invoked (@code{-x -v}); |
8920 | the SVR4.2 shell allows only one option argument (@code{-xv}). In | |
8921 | fact, some versions of the shell dump core if the second argument begins | |
8922 | with a @samp{-}. | |
ccc6cda3 | 8923 | |
bb70624e JA |
8924 | @item |
8925 | The SVR4.2 shell exits a script if any builtin fails; Bash exits | |
0628567a JA |
8926 | a script only if one of the @sc{posix} special builtins fails, and |
8927 | only for certain failures, as enumerated in the @sc{posix} standard. | |
ccc6cda3 | 8928 | |
bb70624e JA |
8929 | @item |
8930 | The SVR4.2 shell behaves differently when invoked as @code{jsh} | |
8931 | (it turns on job control). | |
8932 | @end itemize | |
ccc6cda3 | 8933 | |
3185942a JA |
8934 | @node GNU Free Documentation License |
8935 | @appendix GNU Free Documentation License | |
8936 | ||
8937 | @include fdl.texi | |
8938 | ||
8939 | @node Indexes | |
8940 | @appendix Indexes | |
b80f6443 JA |
8941 | |
8942 | @menu | |
3185942a JA |
8943 | * Builtin Index:: Index of Bash builtin commands. |
8944 | * Reserved Word Index:: Index of Bash reserved words. | |
8945 | * Variable Index:: Quick reference helps you find the | |
8946 | variable you want. | |
8947 | * Function Index:: Index of bindable Readline functions. | |
8948 | * Concept Index:: General index for concepts described in | |
8949 | this manual. | |
b80f6443 JA |
8950 | @end menu |
8951 | ||
ccc6cda3 | 8952 | @node Builtin Index |
3185942a | 8953 | @appendixsec Index of Shell Builtin Commands |
ccc6cda3 JA |
8954 | @printindex bt |
8955 | ||
8956 | @node Reserved Word Index | |
3185942a | 8957 | @appendixsec Index of Shell Reserved Words |
ccc6cda3 JA |
8958 | @printindex rw |
8959 | ||
8960 | @node Variable Index | |
3185942a | 8961 | @appendixsec Parameter and Variable Index |
ccc6cda3 JA |
8962 | @printindex vr |
8963 | ||
8964 | @node Function Index | |
3185942a | 8965 | @appendixsec Function Index |
ccc6cda3 JA |
8966 | @printindex fn |
8967 | ||
8968 | @node Concept Index | |
3185942a | 8969 | @appendixsec Concept Index |
ccc6cda3 JA |
8970 | @printindex cp |
8971 | ||
ccc6cda3 | 8972 | @bye |