]>
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 | |
5 | @c %**end of header | |
6 | ||
7 | @ignore | |
28ef6c31 | 8 | Last Change: Wed Mar 28 14:48:38 EST 2001 |
ccc6cda3 JA |
9 | @end ignore |
10 | ||
28ef6c31 JA |
11 | @set EDITION 2.5 |
12 | @set VERSION 2.05 | |
13 | @set UPDATED 28 Mar 2001 | |
14 | @set UPDATE-MONTH Mar 2001 | |
ccc6cda3 JA |
15 | |
16 | @iftex | |
17 | @finalout | |
18 | @end iftex | |
19 | ||
20 | @setchapternewpage odd | |
21 | @defcodeindex bt | |
22 | @defcodeindex rw | |
23 | @set BashFeatures | |
24 | ||
cce855bc | 25 | @ifinfo |
e8ce775d JA |
26 | @dircategory Utilities |
27 | @direntry | |
cce855bc | 28 | * Bash: (bash). The GNU Bourne-Again SHell. |
e8ce775d JA |
29 | @end direntry |
30 | ||
ccc6cda3 JA |
31 | @format |
32 | This text is a brief description of the features that are present in | |
33 | the Bash shell. | |
34 | ||
35 | This is Edition @value{EDITION}, last updated @value{UPDATED}, | |
36 | of @cite{The GNU Bash Reference Manual}, | |
37 | for @code{Bash}, Version @value{VERSION}. | |
38 | ||
b72432fd | 39 | Copyright (C) 1991-1999 Free Software Foundation, Inc. |
ccc6cda3 JA |
40 | |
41 | Permission is granted to make and distribute verbatim copies of | |
42 | this manual provided the copyright notice and this permission notice | |
43 | are preserved on all copies. | |
44 | ||
45 | @ignore | |
46 | Permission is granted to process this file through TeX and print the | |
47 | results, provided the printed document carries copying permission | |
48 | notice identical to this one except for the removal of this paragraph | |
49 | (this paragraph not being relevant to the printed manual). | |
50 | ||
51 | @end ignore | |
52 | Permission is granted to copy and distribute modified versions of this | |
53 | manual under the conditions for verbatim copying, provided that the entire | |
54 | resulting derived work is distributed under the terms of a permission | |
55 | notice identical to this one. | |
56 | ||
57 | Permission is granted to copy and distribute translations of this manual | |
58 | into another language, under the above conditions for modified versions, | |
59 | except that this permission notice may be stated in a translation approved | |
cce855bc | 60 | by the Free Software Foundation. |
ccc6cda3 JA |
61 | @end format |
62 | @end ifinfo | |
63 | ||
64 | @titlepage | |
65 | @title Bash Reference Manual | |
66 | @subtitle Reference Documentation for Bash | |
b72432fd JA |
67 | @subtitle Edition @value{EDITION}, for @code{Bash} Version @value{VERSION}. |
68 | @subtitle @value{UPDATE-MONTH} | |
ccc6cda3 JA |
69 | @author Chet Ramey, Case Western Reserve University |
70 | @author Brian Fox, Free Software Foundation | |
71 | @page | |
72 | @vskip 0pt plus 1filll | |
b72432fd | 73 | Copyright @copyright{} 1991-1999 Free Software Foundation, Inc. |
ccc6cda3 JA |
74 | |
75 | Permission is granted to make and distribute verbatim copies of | |
76 | this manual provided the copyright notice and this permission notice | |
77 | are preserved on all copies. | |
78 | ||
79 | Permission is granted to copy and distribute modified versions of this | |
80 | manual under the conditions for verbatim copying, provided that the entire | |
81 | resulting derived work is distributed under the terms of a permission | |
82 | notice identical to this one. | |
83 | ||
84 | Permission is granted to copy and distribute translations of this manual | |
85 | into another language, under the above conditions for modified versions, | |
86 | except that this permission notice may be stated in a translation approved | |
87 | by the Free Software Foundation. | |
88 | @end titlepage | |
89 | ||
90 | @ifinfo | |
91 | @node Top, Introduction, (dir), (dir) | |
92 | @top Bash Features | |
93 | @end ifinfo | |
94 | ||
95 | @ifinfo | |
96 | This text is a brief description of the features that are present in | |
97 | the Bash shell. | |
98 | ||
99 | This is Edition @value{EDITION}, last updated @value{UPDATED}, | |
100 | of @cite{The GNU Bash Reference Manual}, | |
101 | for @code{Bash}, Version @value{VERSION}. | |
102 | ||
103 | Copyright (C) 1991, 1993, 1996 Free Software Foundation, Inc. | |
104 | ||
105 | Bash contains features that appear in other popular shells, and some | |
106 | features that only appear in Bash. Some of the shells that Bash has | |
107 | borrowed concepts from are the Bourne Shell (@file{sh}), the Korn Shell | |
108 | (@file{ksh}), and the C-shell (@file{csh} and its successor, | |
109 | @file{tcsh}). The following menu breaks the features up into | |
110 | categories based upon which one of these other shells inspired the | |
111 | feature. | |
112 | ||
113 | This manual is meant as a brief introduction to features found in | |
114 | Bash. The Bash manual page should be used as the definitive | |
115 | reference on shell behavior. | |
116 | ||
117 | @menu | |
118 | * Introduction:: An introduction to the shell. | |
119 | ||
120 | * Definitions:: Some definitions used in the rest of this | |
121 | manual. | |
122 | ||
123 | * Basic Shell Features:: The shell "building blocks". | |
124 | ||
bb70624e JA |
125 | * Shell Builtin Commands:: Commands that are a part of the shell. |
126 | ||
127 | * Shell Variables:: Variables used or set by Bash. | |
ccc6cda3 | 128 | |
ccc6cda3 JA |
129 | * Bash Features:: Features found only in Bash. |
130 | ||
131 | * Job Control:: A chapter describing what job control is | |
132 | and how Bash allows you to use it. | |
133 | ||
134 | * Using History Interactively:: Chapter dealing with history expansion | |
135 | rules. | |
136 | ||
137 | * Command Line Editing:: Chapter describing the command line | |
138 | editing features. | |
139 | ||
140 | * Installing Bash:: How to build and install Bash on your system. | |
141 | ||
142 | * Reporting Bugs:: How to report bugs in Bash. | |
143 | ||
bb70624e JA |
144 | * Major Differences From The Bourne Shell:: A terse list of the differences |
145 | between Bash and historical | |
146 | versions of /bin/sh. | |
147 | ||
ccc6cda3 JA |
148 | * Builtin Index:: Index of Bash builtin commands. |
149 | ||
150 | * Reserved Word Index:: Index of Bash reserved words. | |
151 | ||
152 | * Variable Index:: Quick reference helps you find the | |
153 | variable you want. | |
154 | ||
155 | * Function Index:: Index of bindable Readline functions. | |
156 | ||
157 | * Concept Index:: General index for concepts described in | |
158 | this manual. | |
159 | @end menu | |
160 | @end ifinfo | |
161 | ||
162 | @node Introduction | |
163 | @chapter Introduction | |
164 | @menu | |
165 | * What is Bash?:: A short description of Bash. | |
166 | ||
167 | * What is a shell?:: A brief introduction to shells. | |
168 | @end menu | |
169 | ||
170 | @node What is Bash? | |
171 | @section What is Bash? | |
172 | ||
173 | Bash is the shell, or command language interpreter, | |
bb70624e | 174 | for the @sc{gnu} operating system. |
ccc6cda3 | 175 | The name is an acronym for the @samp{Bourne-Again SHell}, |
bb70624e JA |
176 | a pun on Stephen Bourne, the author of the direct ancestor of |
177 | the current Unix shell @code{/bin/sh}, | |
ccc6cda3 JA |
178 | which appeared in the Seventh Edition Bell Labs Research version |
179 | of Unix. | |
180 | ||
bb70624e | 181 | Bash is largely compatible with @code{sh} and incorporates useful |
ccc6cda3 | 182 | features from the Korn shell @code{ksh} and the C shell @code{csh}. |
bb70624e JA |
183 | It is intended to be a conformant implementation of the @sc{ieee} |
184 | @sc{posix} Shell and Tools specification (@sc{ieee} Working Group 1003.2). | |
cce855bc JA |
185 | It offers functional improvements over @code{sh} for both interactive and |
186 | programming use. | |
ccc6cda3 | 187 | |
bb70624e JA |
188 | While the @sc{gnu} operating system provides other shells, including |
189 | a version of @code{csh}, Bash is the default shell. | |
190 | Like other @sc{gnu} software, Bash is quite portable. It currently runs | |
ccc6cda3 | 191 | on nearly every version of Unix and a few other operating systems @minus{} |
bb70624e JA |
192 | independently-supported ports exist for @sc{ms-dos}, @sc{os/2}, |
193 | Windows @sc{95/98}, and Windows @sc{nt}. | |
ccc6cda3 JA |
194 | |
195 | @node What is a shell? | |
196 | @section What is a shell? | |
197 | ||
198 | At its base, a shell is simply a macro processor that executes | |
199 | commands. A Unix shell is both a command interpreter, which | |
bb70624e | 200 | provides the user interface to the rich set of @sc{gnu} utilities, |
ccc6cda3 | 201 | and a programming language, allowing these utilitites to be |
cce855bc | 202 | combined. Files containing commands can be created, and become |
ccc6cda3 | 203 | commands themselves. These new commands have the same status as |
bb70624e | 204 | system commands in directories such as @file{/bin}, allowing users |
ccc6cda3 JA |
205 | or groups to establish custom environments. |
206 | ||
bb70624e | 207 | A shell allows execution of @sc{gnu} commands, both synchronously and |
cce855bc JA |
208 | asynchronously. |
209 | The shell waits for synchronous commands to complete before accepting | |
210 | more input; asynchronous commands continue to execute in parallel | |
211 | with the shell while it reads and executes additional commands. | |
212 | The @dfn{redirection} constructs permit | |
bb70624e JA |
213 | fine-grained control of the input and output of those commands. |
214 | Moreover, the shell allows control over the contents of commands' | |
215 | environments. | |
216 | Shells may be used interactively or non-interactively: they accept | |
217 | input typed from the keyboard or from a file. | |
218 | ||
219 | Shells also provide a small set of built-in | |
ccc6cda3 | 220 | commands (@dfn{builtins}) implementing functionality impossible |
bb70624e JA |
221 | or inconvenient to obtain via separate utilities. |
222 | For example, @code{cd}, @code{break}, @code{continue}, and | |
223 | @code{exec}) cannot be implemented outside of the shell because | |
224 | they directly manipulate the shell itself. | |
225 | The @code{history}, @code{getopts}, @code{kill}, or @code{pwd} | |
226 | builtins, among others, could be implemented in separate utilities, | |
227 | but they are more convenient to use as builtin commands. | |
228 | All of the shell builtins are described in | |
ccc6cda3 JA |
229 | subsequent sections. |
230 | ||
231 | While executing commands is essential, most of the power (and | |
232 | complexity) of shells is due to their embedded programming | |
233 | languages. Like any high-level language, the shell provides | |
234 | variables, flow control constructs, quoting, and functions. | |
235 | ||
bb70624e | 236 | Shells offer features geared specifically for |
ccc6cda3 JA |
237 | interactive use rather than to augment the programming language. |
238 | These interactive features include job control, command line | |
239 | editing, history and aliases. Each of these features is | |
240 | described in this manual. | |
241 | ||
242 | @node Definitions | |
243 | @chapter Definitions | |
244 | These definitions are used throughout the remainder of this manual. | |
245 | ||
246 | @table @code | |
247 | ||
248 | @item POSIX | |
249 | @cindex POSIX | |
250 | A family of open system standards based on Unix. Bash | |
bb70624e | 251 | is concerned with @sc{posix} 1003.2, the Shell and Tools Standard. |
ccc6cda3 JA |
252 | |
253 | @item blank | |
254 | A space or tab character. | |
255 | ||
256 | @item builtin | |
257 | @cindex builtin | |
258 | A command that is implemented internally by the shell itself, rather | |
259 | than by an executable program somewhere in the file system. | |
260 | ||
261 | @item control operator | |
262 | @cindex control operator | |
263 | A @code{word} that performs a control function. It is a @code{newline} | |
264 | or one of the following: | |
265 | @samp{||}, @samp{&&}, @samp{&}, @samp{;}, @samp{;;}, | |
266 | @samp{|}, @samp{(}, or @samp{)}. | |
267 | ||
268 | @item exit status | |
269 | @cindex exit status | |
270 | The value returned by a command to its caller. | |
271 | ||
272 | @item field | |
273 | @cindex field | |
274 | A unit of text that is the result of one of the shell expansions. After | |
275 | expansion, when executing a command, the resulting fields are used as | |
276 | the command name and arguments. | |
277 | ||
278 | @item filename | |
279 | @cindex filename | |
280 | A string of characters used to identify a file. | |
281 | ||
282 | @item job | |
283 | @cindex job | |
284 | A set of processes comprising a pipeline, and any processes descended | |
285 | from it, that are all in the same process group. | |
286 | ||
287 | @item job control | |
288 | @cindex job control | |
d166f048 JA |
289 | A mechanism by which users can selectively stop (suspend) and restart |
290 | (resume) execution of processes. | |
ccc6cda3 JA |
291 | |
292 | @item metacharacter | |
293 | @cindex metacharacter | |
294 | A character that, when unquoted, separates words. A metacharacter is | |
295 | a @code{blank} or one of the following characters: | |
296 | @samp{|}, @samp{&}, @samp{;}, @samp{(}, @samp{)}, @samp{<}, or | |
297 | @samp{>}. | |
298 | ||
299 | @item name | |
300 | @cindex name | |
301 | @cindex identifier | |
302 | A @code{word} consisting solely of letters, numbers, and underscores, | |
303 | and beginning with a letter or underscore. @code{Name}s are used as | |
304 | shell variable and function names. | |
305 | Also referred to as an @code{identifier}. | |
306 | ||
307 | @item operator | |
308 | @cindex operator, shell | |
309 | A @code{control operator} or a @code{redirection operator}. | |
310 | @xref{Redirections}, for a list of redirection operators. | |
311 | ||
312 | @item process group | |
313 | @cindex process group | |
314 | A collection of related processes each having the same process | |
bb70624e | 315 | group @sc{id}. |
ccc6cda3 JA |
316 | |
317 | @item process group ID | |
318 | @cindex process group ID | |
319 | A unique identifer that represents a @code{process group} | |
320 | during its lifetime. | |
321 | ||
322 | @item reserved word | |
323 | @cindex reserved word | |
324 | A @code{word} that has a special meaning to the shell. Most reserved | |
325 | words introduce shell flow control constructs, such as @code{for} and | |
326 | @code{while}. | |
327 | ||
328 | @item return status | |
329 | @cindex return status | |
330 | A synonym for @code{exit status}. | |
331 | ||
332 | @item signal | |
333 | @cindex signal | |
bb70624e | 334 | A mechanism by which a process may be notified by the kernel |
ccc6cda3 JA |
335 | of an event occurring in the system. |
336 | ||
337 | @item special builtin | |
338 | @cindex special builtin | |
339 | A shell builtin command that has been classified as special by the | |
bb70624e | 340 | @sc{posix} 1003.2 standard. |
ccc6cda3 JA |
341 | |
342 | @item token | |
343 | @cindex token | |
344 | A sequence of characters considered a single unit by the shell. It is | |
345 | either a @code{word} or an @code{operator}. | |
346 | ||
347 | @item word | |
348 | @cindex word | |
349 | A @code{token} that is not an @code{operator}. | |
350 | @end table | |
351 | ||
352 | @node Basic Shell Features | |
353 | @chapter Basic Shell Features | |
354 | @cindex Bourne shell | |
355 | ||
356 | Bash is an acronym for @samp{Bourne-Again SHell}. | |
357 | The Bourne shell is | |
358 | the traditional Unix shell originally written by Stephen Bourne. | |
359 | All of the Bourne shell builtin commands are available in Bash, | |
bb70624e | 360 | and the rules for evaluation and quoting are taken from the @sc{posix} |
ccc6cda3 JA |
361 | 1003.2 specification for the `standard' Unix shell. |
362 | ||
cce855bc | 363 | This chapter briefly summarizes the shell's `building blocks': |
ccc6cda3 JA |
364 | commands, control structures, shell functions, shell @i{parameters}, |
365 | shell expansions, | |
366 | @i{redirections}, which are a way to direct input and output from | |
367 | and to named files, and how the shell executes commands. | |
368 | ||
369 | @menu | |
370 | * Shell Syntax:: What your input means to the shell. | |
cce855bc | 371 | * Shell Commands:: The types of commands you can use. |
ccc6cda3 JA |
372 | * Shell Functions:: Grouping commands by name. |
373 | * Shell Parameters:: Special shell variables. | |
374 | * Shell Expansions:: How Bash expands variables and the various | |
375 | expansions available. | |
376 | * Redirections:: A way to control where input and output go. | |
377 | * Executing Commands:: What happens when you run a command. | |
378 | * Shell Scripts:: Executing files of shell commands. | |
379 | @end menu | |
380 | ||
381 | @node Shell Syntax | |
382 | @section Shell Syntax | |
383 | @menu | |
384 | * Shell Operation:: The basic operation of the shell. | |
385 | ||
386 | * Quoting:: How to remove the special meaning from characters. | |
387 | ||
388 | * Comments:: How to specify comments. | |
389 | @end menu | |
390 | ||
bb70624e JA |
391 | When the shell reads input, it proceeds through a |
392 | sequence of operations. If the input indicates the beginning of a | |
393 | comment, the shell ignores the comment symbol (@samp{#}), and the rest | |
394 | of that line. | |
395 | ||
396 | Otherwise, roughly speaking, the shell reads its input and | |
397 | divides the input into words and operators, employing the quoting rules | |
398 | to select which meanings to assign various words and characters. | |
399 | ||
400 | The shell then parses these tokens into commands and other constructs, | |
401 | removes the special meaning of certain words or characters, expands | |
402 | others, redirects input and output as needed, executes the specified | |
403 | command, waits for the command's exit status, and makes that exit status | |
404 | available for further inspection or processing. | |
405 | ||
ccc6cda3 JA |
406 | @node Shell Operation |
407 | @subsection Shell Operation | |
408 | ||
409 | The following is a brief description of the shell's operation when it | |
410 | reads and executes a command. Basically, the shell does the | |
411 | following: | |
412 | ||
413 | @enumerate | |
414 | @item | |
415 | Reads its input from a file (@pxref{Shell Scripts}), from a string | |
28ef6c31 | 416 | supplied as an argument to the @option{-c} invocation option |
ccc6cda3 JA |
417 | (@pxref{Invoking Bash}), or from the user's terminal. |
418 | ||
419 | @item | |
420 | Breaks the input into words and operators, obeying the quoting rules | |
cce855bc | 421 | described in @ref{Quoting}. These tokens are separated by |
ccc6cda3 JA |
422 | @code{metacharacters}. Alias expansion is performed by this step |
423 | (@pxref{Aliases}). | |
424 | ||
425 | @item | |
cce855bc JA |
426 | Parses the tokens into simple and compound commands |
427 | (@pxref{Shell Commands}). | |
ccc6cda3 JA |
428 | |
429 | @item | |
430 | Performs the various shell expansions (@pxref{Shell Expansions}), breaking | |
431 | the expanded tokens into lists of filenames (@pxref{Filename Expansion}) | |
432 | and commands and arguments. | |
433 | ||
434 | @item | |
435 | Performs any necessary redirections (@pxref{Redirections}) and removes | |
436 | the redirection operators and their operands from the argument list. | |
437 | ||
438 | @item | |
439 | Executes the command (@pxref{Executing Commands}). | |
440 | ||
441 | @item | |
442 | Optionally waits for the command to complete and collects its exit | |
cce855bc | 443 | status (@pxref{Exit Status}). |
ccc6cda3 JA |
444 | |
445 | @end enumerate | |
446 | ||
447 | @node Quoting | |
448 | @subsection Quoting | |
449 | @cindex quoting | |
450 | @menu | |
451 | * Escape Character:: How to remove the special meaning from a single | |
452 | character. | |
453 | * Single Quotes:: How to inhibit all interpretation of a sequence | |
454 | of characters. | |
455 | * Double Quotes:: How to suppress most of the interpretation of a | |
456 | sequence of characters. | |
457 | * ANSI-C Quoting:: How to expand ANSI-C sequences in quoted strings. | |
458 | ||
459 | * Locale Translation:: How to translate strings into different languages. | |
460 | @end menu | |
461 | ||
462 | Quoting is used to remove the special meaning of certain | |
463 | characters or words to the shell. Quoting can be used to | |
464 | disable special treatment for special characters, to prevent | |
465 | reserved words from being recognized as such, and to prevent | |
466 | parameter expansion. | |
467 | ||
cce855bc JA |
468 | Each of the shell metacharacters (@pxref{Definitions}) |
469 | has special meaning to the shell and must be quoted if it is to | |
bb70624e JA |
470 | represent itself. |
471 | When the command history expansion facilities are being used, the | |
472 | @var{history expansion} character, usually @samp{!}, must be quoted | |
28ef6c31 | 473 | to prevent history expansion. @xref{Bash History Facilities}, for |
bb70624e JA |
474 | more details concerning history expansion. |
475 | There are three quoting mechanisms: the | |
ccc6cda3 JA |
476 | @var{escape character}, single quotes, and double quotes. |
477 | ||
478 | @node Escape Character | |
479 | @subsubsection Escape Character | |
480 | A non-quoted backslash @samp{\} is the Bash escape character. | |
481 | It preserves the literal value of the next character that follows, | |
482 | with the exception of @code{newline}. If a @code{\newline} pair | |
cce855bc JA |
483 | appears, and the backslash itself is not quoted, the @code{\newline} |
484 | is treated as a line continuation (that is, it is removed from | |
485 | the input stream and effectively ignored). | |
ccc6cda3 JA |
486 | |
487 | @node Single Quotes | |
488 | @subsubsection Single Quotes | |
489 | ||
bb70624e | 490 | Enclosing characters in single quotes (@samp{'}) preserves the literal value |
ccc6cda3 JA |
491 | of each character within the quotes. A single quote may not occur |
492 | between single quotes, even when preceded by a backslash. | |
493 | ||
494 | @node Double Quotes | |
495 | @subsubsection Double Quotes | |
496 | ||
bb70624e | 497 | Enclosing characters in double quotes (@samp{"}) preserves the literal value |
ccc6cda3 JA |
498 | of all characters within the quotes, with the exception of |
499 | @samp{$}, @samp{`}, and @samp{\}. | |
500 | The characters @samp{$} and @samp{`} | |
cce855bc JA |
501 | retain their special meaning within double quotes (@pxref{Shell Expansions}). |
502 | The backslash retains its special meaning only when followed by one of | |
503 | the following characters: | |
ccc6cda3 | 504 | @samp{$}, @samp{`}, @samp{"}, @samp{\}, or @code{newline}. |
cce855bc JA |
505 | Within double quotes, backslashes that are followed by one of these |
506 | characters are removed. Backslashes preceding characters without a | |
507 | special meaning are left unmodified. | |
ccc6cda3 JA |
508 | A double quote may be quoted within double quotes by preceding it with |
509 | a backslash. | |
510 | ||
511 | The special parameters @samp{*} and @samp{@@} have special meaning | |
512 | when in double quotes (@pxref{Shell Parameter Expansion}). | |
513 | ||
514 | @node ANSI-C Quoting | |
515 | @subsubsection ANSI-C Quoting | |
516 | @cindex quoting, ANSI | |
517 | ||
518 | Words of the form @code{$'@var{string}'} are treated specially. The | |
519 | word expands to @var{string}, with backslash-escaped characters replaced | |
28ef6c31 | 520 | as specified by the ANSI C standard. Backslash escape sequences, if |
ccc6cda3 JA |
521 | present, are decoded as follows: |
522 | ||
523 | @table @code | |
524 | @item \a | |
525 | alert (bell) | |
526 | @item \b | |
527 | backspace | |
528 | @item \e | |
529 | an escape character (not ANSI C) | |
530 | @item \f | |
531 | form feed | |
532 | @item \n | |
533 | newline | |
534 | @item \r | |
535 | carriage return | |
536 | @item \t | |
537 | horizontal tab | |
538 | @item \v | |
539 | vertical tab | |
540 | @item \\ | |
541 | backslash | |
bb70624e JA |
542 | @item \' |
543 | single quote | |
ccc6cda3 | 544 | @item \@var{nnn} |
cce855bc JA |
545 | the character whose @code{ASCII} code is the octal value @var{nnn} |
546 | (one to three digits) | |
547 | @item \x@var{nnn} | |
548 | the character whose @code{ASCII} code is the hexadecimal value @var{nnn} | |
549 | (one to three digits) | |
ccc6cda3 JA |
550 | @end table |
551 | ||
552 | @noindent | |
bb70624e JA |
553 | The expanded result is single-quoted, as if the dollar sign had not |
554 | been present. | |
ccc6cda3 JA |
555 | |
556 | @node Locale Translation | |
557 | @subsubsection Locale-Specific Translation | |
558 | @cindex localization | |
559 | ||
560 | A double-quoted string preceded by a dollar sign (@samp{$}) will cause | |
561 | the string to be translated according to the current locale. | |
562 | If the current locale is @code{C} or @code{POSIX}, the dollar sign | |
563 | is ignored. | |
564 | If the string is translated and replaced, the replacement is | |
565 | double-quoted. | |
566 | ||
28ef6c31 JA |
567 | Some systems use the message catalog selected by the @env{LC_MESSAGES} |
568 | shell variable. Others create the name of the message catalog from the | |
569 | value of the @env{TEXTDOMAIN} shell variable, possibly adding a | |
570 | suffix of @samp{.mo}. If you use the @env{TEXTDOMAIN} variable, you | |
571 | may need to set the @env{TEXTDOMAINDIR} variable to the location of | |
572 | the message catalog files. | |
573 | ||
ccc6cda3 JA |
574 | @node Comments |
575 | @subsection Comments | |
576 | @cindex comments, shell | |
577 | ||
578 | In a non-interactive shell, or an interactive shell in which the | |
579 | @code{interactive_comments} option to the @code{shopt} | |
580 | builtin is enabled (@pxref{Bash Builtins}), | |
581 | a word beginning with @samp{#} | |
582 | causes that word and all remaining characters on that line to | |
583 | be ignored. An interactive shell without the @code{interactive_comments} | |
584 | option enabled does not allow comments. The @code{interactive_comments} | |
585 | option is on by default in interactive shells. | |
bb70624e | 586 | @xref{Interactive Shells}, for a description of what makes |
cce855bc JA |
587 | a shell interactive. |
588 | ||
589 | @node Shell Commands | |
590 | @section Shell Commands | |
591 | @cindex commands, shell | |
bb70624e JA |
592 | |
593 | A simple shell command such as @code{echo a b c} consists of the command | |
594 | itself followed by arguments, separated by spaces. | |
595 | ||
596 | More complex shell commands are composed of simple commands arranged together | |
597 | in a variety of ways: in a pipeline in which the output of one command | |
598 | becomes the input of a second, in a loop or conditional construct, or in | |
599 | some other grouping. | |
600 | ||
cce855bc JA |
601 | @menu |
602 | * Simple Commands:: The most common type of command. | |
603 | * Pipelines:: Connecting the input and output of several | |
604 | commands. | |
605 | * Lists:: How to execute commands sequentially. | |
606 | * Looping Constructs:: Shell commands for iterative action. | |
607 | * Conditional Constructs:: Shell commands for conditional execution. | |
608 | * Command Grouping:: Ways to group commands. | |
609 | @end menu | |
ccc6cda3 JA |
610 | |
611 | @node Simple Commands | |
cce855bc | 612 | @subsection Simple Commands |
ccc6cda3 JA |
613 | @cindex commands, simple |
614 | ||
cce855bc | 615 | A simple command is the kind of command encountered most often. |
ccc6cda3 | 616 | It's just a sequence of words separated by @code{blank}s, terminated |
cce855bc | 617 | by one of the shell's control operators (@pxref{Definitions}). The |
bb70624e JA |
618 | first word generally specifies a command to be executed, with the |
619 | rest of the words being that command's arguments. | |
ccc6cda3 JA |
620 | |
621 | The return status (@pxref{Exit Status}) of a simple command is | |
622 | its exit status as provided | |
bb70624e JA |
623 | by the @sc{posix} 1003.1 @code{waitpid} function, or 128+@var{n} if |
624 | the command was terminated by signal @var{n}. | |
ccc6cda3 JA |
625 | |
626 | @node Pipelines | |
cce855bc | 627 | @subsection Pipelines |
ccc6cda3 JA |
628 | @cindex pipeline |
629 | @cindex commands, pipelines | |
630 | ||
631 | A @code{pipeline} is a sequence of simple commands separated by | |
632 | @samp{|}. | |
633 | ||
634 | @rwindex time | |
635 | @rwindex ! | |
636 | @cindex command timing | |
637 | The format for a pipeline is | |
638 | @example | |
639 | [@code{time} [@code{-p}]] [@code{!}] @var{command1} [@code{|} @var{command2} @dots{}] | |
640 | @end example | |
641 | ||
642 | @noindent | |
643 | The output of each command in the pipeline is connected to the input of | |
644 | the next command. That is, each command reads the previous command's | |
645 | output. | |
646 | ||
647 | The reserved word @code{time} causes timing statistics | |
648 | to be printed for the pipeline once it finishes. | |
cce855bc JA |
649 | The statistics currently consist of elapsed (wall-clock) time and |
650 | user and system time consumed by the command's execution. | |
28ef6c31 | 651 | The @option{-p} option changes the output format to that specified |
bb70624e | 652 | by @sc{posix}. |
28ef6c31 | 653 | The @env{TIMEFORMAT} variable may be set to a format string that |
ccc6cda3 JA |
654 | specifies how the timing information should be displayed. |
655 | @xref{Bash Variables}, for a description of the available formats. | |
cce855bc JA |
656 | The use of @code{time} as a reserved word permits the timing of |
657 | shell builtins, shell functions, and pipelines. An external | |
658 | @code{time} command cannot time these easily. | |
659 | ||
660 | If the pipeline is not executed asynchronously (@pxref{Lists}), the | |
661 | shell waits for all commands in the pipeline to complete. | |
ccc6cda3 | 662 | |
cce855bc JA |
663 | Each command in a pipeline is executed in its own subshell |
664 | (@pxref{Command Execution Environment}). The exit | |
ccc6cda3 JA |
665 | status of a pipeline is the exit status of the last command in the |
666 | pipeline. If the reserved word @samp{!} precedes the pipeline, the | |
cce855bc | 667 | exit status is the logical negation of the exit status of the last command. |
ccc6cda3 JA |
668 | |
669 | @node Lists | |
cce855bc | 670 | @subsection Lists of Commands |
ccc6cda3 JA |
671 | @cindex commands, lists |
672 | ||
673 | A @code{list} is a sequence of one or more pipelines separated by one | |
674 | of the operators @samp{;}, @samp{&}, @samp{&&}, or @samp{||}, | |
675 | and optionally terminated by one of @samp{;}, @samp{&}, or a | |
676 | @code{newline}. | |
677 | ||
678 | Of these list operators, @samp{&&} and @samp{||} | |
679 | have equal precedence, followed by @samp{;} and @samp{&}, | |
680 | which have equal precedence. | |
681 | ||
682 | If a command is terminated by the control operator @samp{&}, | |
cce855bc JA |
683 | the shell executes the command asynchronously in a subshell. |
684 | This is known as executing the command in the @var{background}. | |
685 | The shell does not wait for the command to finish, and the return | |
686 | status is 0 (true). | |
bb70624e JA |
687 | When job control is not active (@pxref{Job Control}), |
688 | the standard input for asynchronous commands, in the absence of any | |
cce855bc JA |
689 | explicit redirections, is redirected from @code{/dev/null}. |
690 | ||
691 | Commands separated by a @samp{;} are executed sequentially; the shell | |
692 | waits for each command to terminate in turn. The return status is the | |
ccc6cda3 JA |
693 | exit status of the last command executed. |
694 | ||
695 | The control operators @samp{&&} and @samp{||} | |
bb70624e JA |
696 | denote @sc{and} lists and @sc{or} lists, respectively. |
697 | An @sc{and} list has the form | |
ccc6cda3 | 698 | @example |
bb70624e | 699 | @var{command1} && @var{command2} |
ccc6cda3 JA |
700 | @end example |
701 | ||
702 | @noindent | |
bb70624e | 703 | @var{command2} is executed if, and only if, @var{command1} |
ccc6cda3 JA |
704 | returns an exit status of zero. |
705 | ||
bb70624e | 706 | An @sc{or} list has the form |
ccc6cda3 | 707 | @example |
bb70624e | 708 | @var{command1} || @var{command2} |
ccc6cda3 JA |
709 | @end example |
710 | ||
711 | @noindent | |
bb70624e | 712 | @var{command2} is executed if, and only if, @var{command1} |
ccc6cda3 JA |
713 | returns a non-zero exit status. |
714 | ||
715 | The return status of | |
bb70624e | 716 | @sc{and} and @sc{or} lists is the exit status of the last command |
ccc6cda3 JA |
717 | executed in the list. |
718 | ||
719 | @node Looping Constructs | |
cce855bc | 720 | @subsection Looping Constructs |
ccc6cda3 JA |
721 | @cindex commands, looping |
722 | ||
ccc6cda3 JA |
723 | Bash supports the following looping constructs. |
724 | ||
bb70624e | 725 | Note that wherever a @samp{;} appears in the description of a |
cce855bc JA |
726 | command's syntax, it may be replaced with one or more newlines. |
727 | ||
ccc6cda3 JA |
728 | @table @code |
729 | @item until | |
730 | @rwindex until | |
731 | @rwindex do | |
732 | @rwindex done | |
733 | The syntax of the @code{until} command is: | |
734 | @example | |
735 | until @var{test-commands}; do @var{consequent-commands}; done | |
736 | @end example | |
cce855bc | 737 | Execute @var{consequent-commands} as long as |
ccc6cda3 | 738 | @var{test-commands} has an exit status which is not zero. |
cce855bc JA |
739 | The return status is the exit status of the last command executed |
740 | in @var{consequent-commands}, or zero if none was executed. | |
ccc6cda3 JA |
741 | |
742 | @item while | |
743 | @rwindex while | |
744 | The syntax of the @code{while} command is: | |
745 | @example | |
746 | while @var{test-commands}; do @var{consequent-commands}; done | |
747 | @end example | |
748 | ||
cce855bc | 749 | Execute @var{consequent-commands} as long as |
ccc6cda3 | 750 | @var{test-commands} has an exit status of zero. |
cce855bc JA |
751 | The return status is the exit status of the last command executed |
752 | in @var{consequent-commands}, or zero if none was executed. | |
ccc6cda3 JA |
753 | |
754 | @item for | |
755 | @rwindex for | |
756 | The syntax of the @code{for} command is: | |
757 | ||
758 | @example | |
759 | for @var{name} [in @var{words} @dots{}]; do @var{commands}; done | |
760 | @end example | |
cce855bc JA |
761 | Expand @var{words}, and execute @var{commands} once for each member |
762 | in the resultant list, with @var{name} bound to the current member. | |
bb70624e JA |
763 | If @samp{in @var{words}} is not present, the @code{for} command |
764 | executes the @var{commands} once for each positional parameter that is | |
765 | set, as if @samp{in "$@@"} had been specified | |
766 | (@pxref{Special Parameters}). | |
cce855bc JA |
767 | The return status is the exit status of the last command that executes. |
768 | If there are no items in the expansion of @var{words}, no commands are | |
769 | executed, and the return status is zero. | |
bb70624e JA |
770 | |
771 | An alternate form of the @code{for} command is also supported: | |
772 | ||
773 | @example | |
774 | for (( @var{expr1} ; @var{expr2} ; @var{expr3} )) ; do @var{commands} ; done | |
775 | @end example | |
776 | First, the arithmetic expression @var{expr1} is evaluated according | |
777 | to the rules described below (@pxref{Shell Arithmetic}). | |
778 | The arithmetic expression @var{expr2} is then evaluated repeatedly | |
779 | until it evaluates to zero. | |
780 | Each time @var{expr2} evaluates to a non-zero value, @var{commands} are | |
781 | executed and the arithmetic expression @var{expr3} is evaluated. | |
782 | If any expression is omitted, it behaves as if it evaluates to 1. | |
783 | The return value is the exit status of the last command in @var{list} | |
784 | that is executed, or false if any of the expressions is invalid. | |
785 | ||
ccc6cda3 JA |
786 | @end table |
787 | ||
788 | The @code{break} and @code{continue} builtins (@pxref{Bourne Shell Builtins}) | |
789 | may be used to control loop execution. | |
790 | ||
791 | @node Conditional Constructs | |
cce855bc | 792 | @subsection Conditional Constructs |
ccc6cda3 JA |
793 | @cindex commands, conditional |
794 | ||
795 | @table @code | |
796 | @item if | |
797 | @rwindex if | |
798 | @rwindex then | |
799 | @rwindex else | |
800 | @rwindex elif | |
801 | @rwindex fi | |
802 | The syntax of the @code{if} command is: | |
803 | ||
804 | @example | |
805 | if @var{test-commands}; then | |
806 | @var{consequent-commands}; | |
807 | [elif @var{more-test-commands}; then | |
808 | @var{more-consequents};] | |
809 | [else @var{alternate-consequents};] | |
810 | fi | |
811 | @end example | |
812 | ||
cce855bc JA |
813 | The @var{test-commands} list is executed, and if its return status is zero, |
814 | the @var{consequent-commands} list is executed. | |
815 | If @var{test-commands} returns a non-zero status, each @code{elif} list | |
816 | is executed in turn, and if its exit status is zero, | |
ccc6cda3 JA |
817 | the corresponding @var{more-consequents} is executed and the |
818 | command completes. | |
819 | If @samp{else @var{alternate-consequents}} is present, and | |
820 | the final command in the final @code{if} or @code{elif} clause | |
cce855bc JA |
821 | has a non-zero exit status, then @var{alternate-consequents} is executed. |
822 | The return status is the exit status of the last command executed, or | |
823 | zero if no condition tested true. | |
ccc6cda3 JA |
824 | |
825 | @item case | |
826 | @rwindex case | |
827 | @rwindex in | |
828 | @rwindex esac | |
829 | The syntax of the @code{case} command is: | |
830 | ||
831 | @example | |
cce855bc | 832 | @code{case @var{word} in [ [(] @var{pattern} [| @var{pattern}]@dots{}) @var{command-list} ;;]@dots{} esac} |
ccc6cda3 JA |
833 | @end example |
834 | ||
cce855bc JA |
835 | @code{case} will selectively execute the @var{command-list} corresponding to |
836 | the first @var{pattern} that matches @var{word}. | |
837 | The @samp{|} is used to separate multiple patterns, and the @samp{)} | |
838 | operator terminates a pattern list. | |
839 | A list of patterns and an associated command-list is known | |
840 | as a @var{clause}. Each clause must be terminated with @samp{;;}. | |
841 | The @var{word} undergoes tilde expansion, parameter expansion, command | |
842 | substitution, arithmetic expansion, and quote removal before matching is | |
843 | attempted. Each @var{pattern} undergoes tilde expansion, parameter | |
844 | expansion, command substitution, and arithmetic expansion. | |
845 | ||
846 | There may be an arbitrary number of @code{case} clauses, each terminated | |
847 | by a @samp{;;}. The first pattern that matches determines the | |
848 | command-list that is executed. | |
ccc6cda3 JA |
849 | |
850 | Here is an example using @code{case} in a script that could be used to | |
851 | describe one interesting feature of an animal: | |
852 | ||
853 | @example | |
854 | echo -n "Enter the name of an animal: " | |
855 | read ANIMAL | |
856 | echo -n "The $ANIMAL has " | |
857 | case $ANIMAL in | |
858 | horse | dog | cat) echo -n "four";; | |
859 | man | kangaroo ) echo -n "two";; | |
860 | *) echo -n "an unknown number of";; | |
861 | esac | |
862 | echo " legs." | |
863 | @end example | |
864 | ||
cce855bc JA |
865 | @noindent |
866 | The return status is zero if no @var{pattern} is matched. Otherwise, the | |
867 | return status is the exit status of the @var{command-list} executed. | |
868 | ||
869 | @item select | |
870 | @rwindex select | |
871 | ||
872 | The @code{select} construct allows the easy generation of menus. | |
873 | It has almost the same syntax as the @code{for} command: | |
874 | ||
875 | @example | |
876 | select @var{name} [in @var{words} @dots{}]; do @var{commands}; done | |
877 | @end example | |
878 | ||
879 | The list of words following @code{in} is expanded, generating a list | |
880 | of items. The set of expanded words is printed on the standard | |
881 | error output stream, each preceded by a number. If the | |
882 | @samp{in @var{words}} is omitted, the positional parameters are printed, | |
883 | as if @samp{in "$@@"} had been specifed. | |
28ef6c31 | 884 | The @env{PS3} prompt is then displayed and a line is read from the |
cce855bc JA |
885 | standard input. |
886 | If the line consists of a number corresponding to one of the displayed | |
887 | words, then the value of @var{name} is set to that word. | |
888 | If the line is empty, the words and prompt are displayed again. | |
889 | If @code{EOF} is read, the @code{select} command completes. | |
890 | Any other value read causes @var{name} to be set to null. | |
28ef6c31 | 891 | The line read is saved in the variable @env{REPLY}. |
cce855bc JA |
892 | |
893 | The @var{commands} are executed after each selection until a | |
894 | @code{break} or @code{return} command is executed, at which | |
895 | point the @code{select} command completes. | |
896 | ||
897 | Here is an example that allows the user to pick a filename from the | |
898 | current directory, and displays the name and index of the file | |
899 | selected. | |
900 | ||
901 | @example | |
902 | select fname in *; | |
903 | do | |
904 | echo you picked $fname \($REPLY\) | |
905 | break; | |
906 | done | |
907 | @end example | |
908 | ||
ccc6cda3 JA |
909 | @item ((@dots{})) |
910 | @example | |
911 | (( @var{expression} )) | |
912 | @end example | |
913 | ||
cce855bc JA |
914 | The arithmetic @var{expression} is evaluated according to the rules |
915 | described below (@pxref{Shell Arithmetic}). | |
ccc6cda3 JA |
916 | If the value of the expression is non-zero, the return status is 0; |
917 | otherwise the return status is 1. This is exactly equivalent to | |
918 | @example | |
919 | let "@var{expression}" | |
920 | @end example | |
cce855bc JA |
921 | @noindent |
922 | @xref{Bash Builtins}, for a full description of the @code{let} builtin. | |
923 | ||
924 | @item [[@dots{}]] | |
925 | @rwindex [[ | |
926 | @rwindex ]] | |
927 | @example | |
928 | [[ @var{expression} ]] | |
929 | @end example | |
930 | ||
931 | Return a status of 0 or 1 depending on the evaluation of | |
932 | the conditional expression @var{expression}. | |
933 | Expressions are composed of the primaries described below in | |
934 | @ref{Bash Conditional Expressions}. | |
935 | Word splitting and filename expansion are not performed on the words | |
936 | between the @samp{[[} and @samp{]]}; tilde expansion, parameter and | |
937 | variable expansion, arithmetic expansion, command substitution, process | |
938 | substitution, and quote removal are performed. | |
939 | ||
940 | When the @samp{==} and @samp{!=} operators are used, the string to the | |
941 | right of the operator is considered a pattern and matched according | |
942 | to the rules described below in @ref{Pattern Matching}. | |
943 | The return value is 0 if the string matches or does not match | |
944 | the pattern, respectively, and 1 otherwise. | |
945 | Any part of the pattern may be quoted to force it to be matched as a | |
946 | string. | |
947 | ||
948 | Expressions may be combined using the following operators, listed | |
949 | in decreasing order of precedence: | |
950 | ||
951 | @table @code | |
952 | @item ( @var{expression} ) | |
953 | Returns the value of @var{expression}. | |
954 | This may be used to override the normal precedence of operators. | |
ccc6cda3 | 955 | |
cce855bc JA |
956 | @item ! @var{expression} |
957 | True if @var{expression} is false. | |
958 | ||
959 | @item @var{expression1} && @var{expression2} | |
960 | True if both @var{expression1} and @var{expression2} are true. | |
961 | ||
962 | @item @var{expression1} || @var{expression2} | |
963 | True if either @var{expression1} or @var{expression2} is true. | |
ccc6cda3 | 964 | @end table |
cce855bc | 965 | @noindent |
bb70624e | 966 | The @code{&&} and @code{||} commands do not execute @var{expression2} if the |
cce855bc JA |
967 | value of @var{expression1} is sufficient to determine the return |
968 | value of the entire conditional expression. | |
ccc6cda3 | 969 | |
cce855bc | 970 | @end table |
ccc6cda3 JA |
971 | |
972 | @node Command Grouping | |
cce855bc | 973 | @subsection Grouping Commands |
ccc6cda3 JA |
974 | @cindex commands, grouping |
975 | ||
976 | Bash provides two ways to group a list of commands to be executed | |
977 | as a unit. When commands are grouped, redirections may be applied | |
978 | to the entire command list. For example, the output of all the | |
979 | commands in the list may be redirected to a single stream. | |
980 | ||
981 | @table @code | |
982 | @item () | |
983 | @example | |
984 | ( @var{list} ) | |
985 | @end example | |
986 | ||
987 | Placing a list of commands between parentheses causes a subshell | |
cce855bc JA |
988 | to be created, and each of the commands in @var{list} to be executed |
989 | in that subshell. Since the @var{list} is executed in a subshell, | |
990 | variable assignments do not remain in effect after the subshell completes. | |
ccc6cda3 JA |
991 | |
992 | @item @{@} | |
993 | @rwindex @{ | |
994 | @rwindex @} | |
995 | @example | |
996 | @{ @var{list}; @} | |
997 | @end example | |
998 | ||
999 | Placing a list of commands between curly braces causes the list to | |
1000 | be executed in the current shell context. No subshell is created. | |
cce855bc | 1001 | The semicolon (or newline) following @var{list} is required. |
ccc6cda3 JA |
1002 | @end table |
1003 | ||
1004 | In addition to the creation of a subshell, there is a subtle difference | |
1005 | between these two constructs due to historical reasons. The braces | |
1006 | are @code{reserved words}, so they must be separated from the @var{list} | |
1007 | by @code{blank}s. The parentheses are @code{operators}, and are | |
1008 | recognized as separate tokens by the shell even if they are not separated | |
d166f048 | 1009 | from the @var{list} by whitespace. |
ccc6cda3 JA |
1010 | |
1011 | The exit status of both of these constructs is the exit status of | |
1012 | @var{list}. | |
1013 | ||
1014 | @node Shell Functions | |
1015 | @section Shell Functions | |
1016 | @cindex shell function | |
1017 | @cindex functions, shell | |
1018 | ||
1019 | Shell functions are a way to group commands for later execution | |
1020 | using a single name for the group. They are executed just like | |
bb70624e JA |
1021 | a "regular" command. |
1022 | When the name of a shell function is used as a simple command name, | |
1023 | the list of commands associated with that function name is executed. | |
1024 | Shell functions are executed in the current | |
ccc6cda3 JA |
1025 | shell context; no new process is created to interpret them. |
1026 | ||
1027 | Functions are declared using this syntax: | |
1028 | @rwindex function | |
1029 | @example | |
1030 | [ @code{function} ] @var{name} () @{ @var{command-list}; @} | |
1031 | @end example | |
1032 | ||
1033 | This defines a shell function named @var{name}. The reserved | |
cce855bc JA |
1034 | word @code{function} is optional. |
1035 | If the @code{function} reserved | |
1036 | word is supplied, the parentheses are optional. | |
1037 | The @var{body} of the function is the @var{command-list} between @{ and @}. | |
1038 | This list is executed whenever @var{name} is specified as the | |
ccc6cda3 JA |
1039 | name of a command. The exit status of a function is |
1040 | the exit status of the last command executed in the body. | |
1041 | ||
bb70624e JA |
1042 | Note that for historical reasons, the curly braces that surround |
1043 | the body of the function must be separated from the body by | |
1044 | @code{blank}s or newlines. | |
1045 | This is because the braces are reserved words and are only recognized | |
1046 | as such when they are separated by whitespace. | |
1047 | Also, the @var{command-list} must be terminated with a semicolon | |
1048 | or a newline. | |
1049 | ||
ccc6cda3 JA |
1050 | When a function is executed, the arguments to the |
1051 | function become the positional parameters | |
1052 | during its execution (@pxref{Positional Parameters}). | |
d166f048 JA |
1053 | The special parameter @samp{#} that expands to the number of |
1054 | positional parameters is updated to reflect the change. | |
1055 | Positional parameter @code{0} is unchanged. | |
28ef6c31 | 1056 | The @env{FUNCNAME} variable is set to the name of the function |
bb70624e | 1057 | while the function is executing. |
ccc6cda3 JA |
1058 | |
1059 | If the builtin command @code{return} | |
1060 | is executed in a function, the function completes and | |
1061 | execution resumes with the next command after the function | |
1062 | call. When a function completes, the values of the | |
1063 | positional parameters and the special parameter @samp{#} | |
cce855bc | 1064 | are restored to the values they had prior to the function's |
ccc6cda3 | 1065 | execution. If a numeric argument is given to @code{return}, |
cce855bc JA |
1066 | that is the function's return status; otherwise the functions's |
1067 | return status is the exit status of the last command executed | |
1068 | before the @code{return}. | |
ccc6cda3 JA |
1069 | |
1070 | Variables local to the function may be declared with the | |
1071 | @code{local} builtin. These variables are visible only to | |
1072 | the function and the commands it invokes. | |
1073 | ||
1074 | Functions may be recursive. No limit is placed on the number of | |
1075 | recursive calls. | |
1076 | ||
1077 | @node Shell Parameters | |
1078 | @section Shell Parameters | |
1079 | @cindex parameters | |
1080 | @cindex variable, shell | |
1081 | @cindex shell variable | |
1082 | ||
1083 | @menu | |
1084 | * Positional Parameters:: The shell's command-line arguments. | |
1085 | * Special Parameters:: Parameters with special meanings. | |
1086 | @end menu | |
1087 | ||
1088 | A @var{parameter} is an entity that stores values. | |
1089 | It can be a @code{name}, a number, or one of the special characters | |
1090 | listed below. | |
1091 | For the shell's purposes, a @var{variable} is a parameter denoted by a | |
1092 | @code{name}. | |
1093 | ||
1094 | A parameter is set if it has been assigned a value. The null string is | |
1095 | a valid value. Once a variable is set, it may be unset only by using | |
1096 | the @code{unset} builtin command. | |
1097 | ||
1098 | A variable may be assigned to by a statement of the form | |
1099 | @example | |
1100 | @var{name}=[@var{value}] | |
1101 | @end example | |
1102 | @noindent | |
1103 | If @var{value} | |
1104 | is not given, the variable is assigned the null string. All | |
1105 | @var{value}s undergo tilde expansion, parameter and variable expansion, | |
1106 | command substitution, arithmetic expansion, and quote | |
cce855bc JA |
1107 | removal (detailed below). If the variable has its @code{integer} |
1108 | attribute set (see the description of the @code{declare} builtin in | |
ccc6cda3 JA |
1109 | @ref{Bash Builtins}), then @var{value} |
1110 | is subject to arithmetic expansion even if the @code{$((@dots{}))} | |
cce855bc | 1111 | expansion is not used (@pxref{Arithmetic Expansion}). |
ccc6cda3 JA |
1112 | Word splitting is not performed, with the exception |
1113 | of @code{"$@@"} as explained below. | |
1114 | Filename expansion is not performed. | |
1115 | ||
1116 | @node Positional Parameters | |
1117 | @subsection Positional Parameters | |
1118 | @cindex parameters, positional | |
1119 | ||
cce855bc | 1120 | A @var{positional parameter} is a parameter denoted by one or more |
ccc6cda3 JA |
1121 | digits, other than the single digit @code{0}. Positional parameters are |
1122 | assigned from the shell's arguments when it is invoked, | |
cce855bc | 1123 | and may be reassigned using the @code{set} builtin command. |
bb70624e JA |
1124 | Positional parameter @code{N} may be referenced as @code{$@{N@}}, or |
1125 | as @code{$N} when @code{N} consists of a single digit. | |
1126 | Positional parameters may not be assigned to with assignment statements. | |
1127 | The @code{set} and @code{shift} builtins are used to set and | |
1128 | unset them (@pxref{Shell Builtin Commands}). | |
1129 | The positional parameters are | |
ccc6cda3 JA |
1130 | temporarily replaced when a shell function is executed |
1131 | (@pxref{Shell Functions}). | |
1132 | ||
1133 | When a positional parameter consisting of more than a single | |
1134 | digit is expanded, it must be enclosed in braces. | |
1135 | ||
1136 | @node Special Parameters | |
1137 | @subsection Special Parameters | |
1138 | @cindex parameters, special | |
1139 | ||
1140 | The shell treats several parameters specially. These parameters may | |
1141 | only be referenced; assignment to them is not allowed. | |
1142 | ||
1143 | @vtable @code | |
1144 | ||
1145 | @item * | |
1146 | Expands to the positional parameters, starting from one. When the | |
1147 | expansion occurs within double quotes, it expands to a single word | |
1148 | with the value of each parameter separated by the first character | |
28ef6c31 | 1149 | of the @env{IFS} |
ccc6cda3 JA |
1150 | special variable. That is, @code{"$*"} is equivalent |
1151 | to @code{"$1@var{c}$2@var{c}@dots{}"}, where @var{c} | |
1152 | is the first character of the value of the @code{IFS} | |
d166f048 | 1153 | variable. |
28ef6c31 JA |
1154 | If @env{IFS} is unset, the parameters are separated by spaces. |
1155 | If @env{IFS} is null, the parameters are joined without intervening | |
d166f048 JA |
1156 | separators. |
1157 | ||
ccc6cda3 JA |
1158 | |
1159 | @item @@ | |
1160 | Expands to the positional parameters, starting from one. When the | |
cce855bc | 1161 | expansion occurs within double quotes, each parameter expands to a |
ccc6cda3 JA |
1162 | separate word. That is, @code{"$@@"} is equivalent to |
1163 | @code{"$1" "$2" @dots{}}. | |
1164 | When there are no positional parameters, @code{"$@@"} and | |
1165 | @code{$@@} | |
1166 | expand to nothing (i.e., they are removed). | |
1167 | ||
1168 | @item # | |
1169 | Expands to the number of positional parameters in decimal. | |
1170 | ||
1171 | @item ? | |
1172 | Expands to the exit status of the most recently executed foreground | |
1173 | pipeline. | |
1174 | ||
1175 | @item - | |
bb70624e JA |
1176 | (A hyphen.) Expands to the current option flags as specified upon |
1177 | invocation, by the @code{set} | |
ccc6cda3 | 1178 | builtin command, or those set by the shell itself |
28ef6c31 | 1179 | (such as the @option{-i} option). |
ccc6cda3 JA |
1180 | |
1181 | @item $ | |
bb70624e JA |
1182 | Expands to the process @sc{id} of the shell. In a @code{()} subshell, it |
1183 | expands to the process @sc{id} of the invoking shell, not the subshell. | |
ccc6cda3 JA |
1184 | |
1185 | @item ! | |
bb70624e | 1186 | Expands to the process @sc{id} of the most recently executed background |
ccc6cda3 JA |
1187 | (asynchronous) command. |
1188 | ||
1189 | @item 0 | |
1190 | Expands to the name of the shell or shell script. This is set at | |
cce855bc JA |
1191 | shell initialization. If Bash is invoked with a file of commands |
1192 | (@pxref{Shell Scripts}), @code{$0} is set to the name of that file. | |
28ef6c31 | 1193 | If Bash is started with the @option{-c} option (@pxref{Invoking Bash}), |
cce855bc | 1194 | then @code{$0} is set to the first argument after the string to be |
ccc6cda3 JA |
1195 | executed, if one is present. Otherwise, it is set |
1196 | to the filename used to invoke Bash, as given by argument zero. | |
1197 | ||
1198 | @item _ | |
bb70624e | 1199 | (An underscore.) |
ccc6cda3 JA |
1200 | At shell startup, set to the absolute filename of the shell or shell |
1201 | script being executed as passed in the argument list. | |
1202 | Subsequently, expands to the last argument to the previous command, | |
1203 | after expansion. | |
cce855bc | 1204 | Also set to the full pathname of each command executed and placed in |
ccc6cda3 JA |
1205 | the environment exported to that command. |
1206 | When checking mail, this parameter holds the name of the mail file. | |
1207 | @end vtable | |
1208 | ||
1209 | @node Shell Expansions | |
1210 | @section Shell Expansions | |
1211 | @cindex expansion | |
1212 | ||
1213 | Expansion is performed on the command line after it has been split into | |
1214 | @code{token}s. There are seven kinds of expansion performed: | |
1215 | @itemize @bullet | |
1216 | @item brace expansion | |
1217 | @item tilde expansion | |
1218 | @item parameter and variable expansion | |
1219 | @item command substitution | |
1220 | @item arithmetic expansion | |
1221 | @item word splitting | |
1222 | @item filename expansion | |
1223 | @end itemize | |
1224 | ||
1225 | @menu | |
cce855bc JA |
1226 | * Brace Expansion:: Expansion of expressions within braces. |
1227 | * Tilde Expansion:: Expansion of the ~ character. | |
ccc6cda3 JA |
1228 | * Shell Parameter Expansion:: How Bash expands variables to their values. |
1229 | * Command Substitution:: Using the output of a command as an argument. | |
cce855bc | 1230 | * Arithmetic Expansion:: How to use arithmetic in shell expansions. |
ccc6cda3 JA |
1231 | * Process Substitution:: A way to write and read to and from a |
1232 | command. | |
1233 | * Word Splitting:: How the results of expansion are split into separate | |
1234 | arguments. | |
1235 | * Filename Expansion:: A shorthand for specifying filenames matching patterns. | |
1236 | * Quote Removal:: How and when quote characters are removed from | |
1237 | words. | |
1238 | @end menu | |
1239 | ||
ccc6cda3 JA |
1240 | The order of expansions is: brace expansion, tilde expansion, |
1241 | parameter, variable, and arithmetic expansion and | |
1242 | command substitution | |
1243 | (done in a left-to-right fashion), word splitting, and filename | |
1244 | expansion. | |
1245 | ||
1246 | On systems that can support it, there is an additional expansion | |
1247 | available: @var{process substitution}. This is performed at the | |
cce855bc | 1248 | same time as parameter, variable, and arithmetic expansion and |
ccc6cda3 JA |
1249 | command substitution. |
1250 | ||
1251 | Only brace expansion, word splitting, and filename expansion | |
1252 | can change the number of words of the expansion; other expansions | |
1253 | expand a single word to a single word. | |
1254 | The only exceptions to this are the expansions of | |
d166f048 | 1255 | @code{"$@@"} (@pxref{Special Parameters}) and @code{"$@{@var{name}[@@]@}"} |
ccc6cda3 JA |
1256 | (@pxref{Arrays}). |
1257 | ||
1258 | After all expansions, @code{quote removal} (@pxref{Quote Removal}) | |
1259 | is performed. | |
1260 | ||
cce855bc JA |
1261 | @node Brace Expansion |
1262 | @subsection Brace Expansion | |
1263 | @cindex brace expansion | |
1264 | @cindex expansion, brace | |
1265 | ||
bb70624e JA |
1266 | Brace expansion is a mechanism by which arbitrary strings may be generated. |
1267 | This mechanism is similar to | |
cce855bc | 1268 | @var{filename expansion} (@pxref{Filename Expansion}), |
bb70624e JA |
1269 | but the file names generated need not exist. |
1270 | Patterns to be brace expanded take the form of an optional @var{preamble}, | |
1271 | followed by a series of comma-separated strings between a pair of braces, | |
1272 | followed by an optional @var{postscript}. | |
1273 | The preamble is prefixed to each string contained within the braces, and | |
1274 | the postscript is then appended to each resulting string, expanding left | |
1275 | to right. | |
1276 | ||
1277 | Brace expansions may be nested. | |
1278 | The results of each expanded string are not sorted; left to right order | |
1279 | is preserved. | |
cce855bc JA |
1280 | For example, |
1281 | @example | |
1282 | bash$ echo a@{d,c,b@}e | |
1283 | ade ace abe | |
1284 | @end example | |
1285 | ||
1286 | Brace expansion is performed before any other expansions, | |
1287 | and any characters special to other expansions are preserved | |
1288 | in the result. It is strictly textual. Bash | |
1289 | does not apply any syntactic interpretation to the context of the | |
1290 | expansion or the text between the braces. | |
bb70624e JA |
1291 | To avoid conflicts with parameter expansion, the string @samp{$@{} |
1292 | is not considered eligible for brace expansion. | |
cce855bc JA |
1293 | |
1294 | A correctly-formed brace expansion must contain unquoted opening | |
1295 | and closing braces, and at least one unquoted comma. | |
1296 | Any incorrectly formed brace expansion is left unchanged. | |
1297 | ||
1298 | This construct is typically used as shorthand when the common | |
1299 | prefix of the strings to be generated is longer than in the | |
1300 | above example: | |
1301 | @example | |
1302 | mkdir /usr/local/src/bash/@{old,new,dist,bugs@} | |
1303 | @end example | |
1304 | or | |
1305 | @example | |
1306 | chown root /usr/@{ucb/@{ex,edit@},lib/@{ex?.?*,how_ex@}@} | |
1307 | @end example | |
1308 | ||
1309 | @node Tilde Expansion | |
1310 | @subsection Tilde Expansion | |
1311 | @cindex tilde expansion | |
1312 | @cindex expansion, tilde | |
1313 | ||
1314 | If a word begins with an unquoted tilde character (@samp{~}), all of the | |
1315 | characters up to the first unquoted slash (or all characters, | |
1316 | if there is no unquoted slash) are considered a @var{tilde-prefix}. | |
1317 | If none of the characters in the tilde-prefix are quoted, the | |
1318 | characters in the tilde-prefix following the tilde are treated as a | |
1319 | possible @var{login name}. | |
1320 | If this login name is the null string, the tilde is replaced with the | |
28ef6c31 JA |
1321 | value of the @env{HOME} shell variable. |
1322 | If @env{HOME} is unset, the home directory of the user executing the | |
cce855bc JA |
1323 | shell is substituted instead. |
1324 | Otherwise, the tilde-prefix is replaced with the home directory | |
1325 | associated with the specified login name. | |
1326 | ||
1327 | If the tilde-prefix is @samp{~+}, the value of | |
28ef6c31 | 1328 | the shell variable @env{PWD} replaces the tilde-prefix. |
cce855bc | 1329 | If the tilde-prefix is @samp{~-}, the value of the shell variable |
28ef6c31 | 1330 | @env{OLDPWD}, if it is set, is substituted. |
cce855bc JA |
1331 | |
1332 | If the characters following the tilde in the tilde-prefix consist of a | |
1333 | number @var{N}, optionally prefixed by a @samp{+} or a @samp{-}, | |
1334 | the tilde-prefix is replaced with the | |
1335 | corresponding element from the directory stack, as it would be displayed | |
1336 | by the @code{dirs} builtin invoked with the characters following tilde | |
1337 | in the tilde-prefix as an argument (@pxref{The Directory Stack}). | |
1338 | If the tilde-prefix, sans the tilde, consists of a number without a | |
1339 | leading @samp{+} or @samp{-}, @samp{+} is assumed. | |
1340 | ||
1341 | If the login name is invalid, or the tilde expansion fails, the word is | |
1342 | left unchanged. | |
1343 | ||
1344 | Each variable assignment is checked for unquoted tilde-prefixes immediately | |
1345 | following a @samp{:} or @samp{=}. | |
1346 | In these cases, tilde expansion is also performed. | |
1347 | Consequently, one may use file names with tildes in assignments to | |
28ef6c31 | 1348 | @env{PATH}, @env{MAILPATH}, and @env{CDPATH}, |
cce855bc JA |
1349 | and the shell assigns the expanded value. |
1350 | ||
1351 | The following table shows how Bash treats unquoted tilde-prefixes: | |
1352 | ||
1353 | @table @code | |
1354 | @item ~ | |
1355 | The value of @code{$HOME} | |
1356 | @item ~/foo | |
1357 | @file{$HOME/foo} | |
1358 | ||
1359 | @item ~fred/foo | |
1360 | The subdirectory @code{foo} of the home directory of the user | |
1361 | @code{fred} | |
1362 | ||
1363 | @item ~+/foo | |
1364 | @file{$PWD/foo} | |
1365 | ||
1366 | @item ~-/foo | |
1367 | @file{$@{OLDPWD-'~-'@}/foo} | |
1368 | ||
1369 | @item ~@var{N} | |
1370 | The string that would be displayed by @samp{dirs +@var{N}} | |
1371 | ||
1372 | @item ~+@var{N} | |
1373 | The string that would be displayed by @samp{dirs +@var{N}} | |
1374 | ||
1375 | @item ~-@var{N} | |
1376 | The string that would be displayed by @samp{dirs -@var{N}} | |
1377 | ||
1378 | @end table | |
1379 | ||
ccc6cda3 JA |
1380 | @node Shell Parameter Expansion |
1381 | @subsection Shell Parameter Expansion | |
1382 | @cindex parameter expansion | |
1383 | @cindex expansion, parameter | |
1384 | ||
1385 | The @samp{$} character introduces parameter expansion, | |
1386 | command substitution, or arithmetic expansion. The parameter name | |
1387 | or symbol to be expanded may be enclosed in braces, which | |
1388 | are optional but serve to protect the variable to be expanded from | |
1389 | characters immediately following it which could be | |
1390 | interpreted as part of the name. | |
1391 | ||
cce855bc JA |
1392 | When braces are used, the matching ending brace is the first @samp{@}} |
1393 | not escaped by a backslash or within a quoted string, and not within an | |
1394 | embedded arithmetic expansion, command substitution, or parameter | |
1395 | expansion. | |
1396 | ||
ccc6cda3 JA |
1397 | The basic form of parameter expansion is $@{@var{parameter}@}. |
1398 | The value of @var{parameter} is substituted. The braces are required | |
1399 | when @var{parameter} | |
1400 | is a positional parameter with more than one digit, | |
1401 | or when @var{parameter} | |
1402 | is followed by a character that is not to be | |
1403 | interpreted as part of its name. | |
1404 | ||
1405 | If the first character of @var{parameter} is an exclamation point, | |
1406 | a level of variable indirection is introduced. | |
1407 | Bash uses the value of the variable formed from the rest of | |
1408 | @var{parameter} as the name of the variable; this variable is then | |
d166f048 | 1409 | expanded and that value is used in the rest of the substitution, rather |
ccc6cda3 JA |
1410 | than the value of @var{parameter} itself. |
1411 | This is known as @code{indirect expansion}. | |
bb70624e JA |
1412 | The exception to this is the expansion of $@{!@var{prefix*@}} |
1413 | described below. | |
ccc6cda3 JA |
1414 | |
1415 | In each of the cases below, @var{word} is subject to tilde expansion, | |
1416 | parameter expansion, command substitution, and arithmetic expansion. | |
bb70624e | 1417 | |
ccc6cda3 JA |
1418 | When not performing substring expansion, Bash tests for a parameter |
1419 | that is unset or null; omitting the colon results in a test only for a | |
bb70624e JA |
1420 | parameter that is unset. Put another way, if the colon is included, |
1421 | the operator tests for both existence and that the value is not null; | |
1422 | if the colon is omitted, the operator tests only for existence. | |
ccc6cda3 JA |
1423 | |
1424 | @table @code | |
1425 | ||
1426 | @item $@{@var{parameter}:@minus{}@var{word}@} | |
1427 | If @var{parameter} is unset or null, the expansion of | |
1428 | @var{word} is substituted. Otherwise, the value of | |
1429 | @var{parameter} is substituted. | |
1430 | ||
1431 | @item $@{@var{parameter}:=@var{word}@} | |
1432 | If @var{parameter} | |
1433 | is unset or null, the expansion of @var{word} | |
1434 | is assigned to @var{parameter}. | |
1435 | The value of @var{parameter} | |
1436 | is then substituted. Positional parameters and special parameters may | |
1437 | not be assigned to in this way. | |
1438 | ||
1439 | @item $@{@var{parameter}:?@var{word}@} | |
1440 | If @var{parameter} | |
1441 | is null or unset, the expansion of @var{word} (or a message | |
1442 | to that effect if @var{word} | |
1443 | is not present) is written to the standard error and the shell, if it | |
1444 | is not interactive, exits. Otherwise, the value of @var{parameter} is | |
1445 | substituted. | |
1446 | ||
1447 | @item $@{@var{parameter}:+@var{word}@} | |
1448 | If @var{parameter} | |
1449 | is null or unset, nothing is substituted, otherwise the expansion of | |
1450 | @var{word} is substituted. | |
1451 | ||
1452 | @item $@{@var{parameter}:@var{offset}@} | |
1453 | @itemx $@{@var{parameter}:@var{offset}:@var{length}@} | |
bb70624e | 1454 | Expands to up to @var{length} characters of @var{parameter} |
cce855bc | 1455 | starting at the character specified by @var{offset}. |
ccc6cda3 | 1456 | If @var{length} is omitted, expands to the substring of |
bb70624e | 1457 | @var{parameter} starting at the character specified by @var{offset}. |
ccc6cda3 | 1458 | @var{length} and @var{offset} are arithmetic expressions |
cce855bc | 1459 | (@pxref{Shell Arithmetic}). |
ccc6cda3 JA |
1460 | This is referred to as Substring Expansion. |
1461 | ||
1462 | @var{length} must evaluate to a number greater than or equal to zero. | |
1463 | If @var{offset} evaluates to a number less than zero, the value | |
1464 | is used as an offset from the end of the value of @var{parameter}. | |
1465 | If @var{parameter} is @samp{@@}, the result is @var{length} positional | |
1466 | parameters beginning at @var{offset}. | |
1467 | If @var{parameter} is an array name indexed by @samp{@@} or @samp{*}, | |
1468 | the result is the @var{length} | |
cce855bc JA |
1469 | members of the array beginning with @code{$@{@var{parameter}[@var{offset}]@}}. |
1470 | Substring indexing is zero-based unless the positional parameters | |
1471 | are used, in which case the indexing starts at 1. | |
ccc6cda3 | 1472 | |
bb70624e JA |
1473 | @item $@{!@var{prefix}*@} |
1474 | Expands to the names of variables whose names begin with @var{prefix}, | |
28ef6c31 | 1475 | separated by the first character of the @env{IFS} special variable. |
bb70624e | 1476 | |
ccc6cda3 | 1477 | @item $@{#@var{parameter}@} |
cce855bc JA |
1478 | The length in characters of the expanded value of @var{parameter} is |
1479 | substituted. | |
1480 | If @var{parameter} is @samp{*} or @samp{@@}, the value substituted | |
1481 | is the number of positional parameters. | |
1482 | If @var{parameter} is an array name subscripted by @samp{*} or @samp{@@}, | |
1483 | the value substituted is the number of elements in the array. | |
ccc6cda3 JA |
1484 | |
1485 | @item $@{@var{parameter}#@var{word}@} | |
1486 | @itemx $@{@var{parameter}##@var{word}@} | |
1487 | The @var{word} | |
1488 | is expanded to produce a pattern just as in filename | |
1489 | expansion (@pxref{Filename Expansion}). If the pattern matches | |
cce855bc JA |
1490 | the beginning of the expanded value of @var{parameter}, |
1491 | then the result of the expansion is the expanded value of @var{parameter} | |
ccc6cda3 JA |
1492 | with the shortest matching pattern (the @samp{#} case) or the |
1493 | longest matching pattern (the @samp{##} case) deleted. | |
1494 | If @var{parameter} is @samp{@@} or @samp{*}, | |
1495 | the pattern removal operation is applied to each positional | |
1496 | parameter in turn, and the expansion is the resultant list. | |
1497 | If @var{parameter} is an array variable subscripted with | |
1498 | @samp{@@} or @samp{*}, | |
1499 | the pattern removal operation is applied to each member of the | |
1500 | array in turn, and the expansion is the resultant list. | |
1501 | ||
1502 | @item $@{@var{parameter}%@var{word}@} | |
1503 | @itemx $@{@var{parameter}%%@var{word}@} | |
1504 | The @var{word} is expanded to produce a pattern just as in | |
1505 | filename expansion. | |
cce855bc JA |
1506 | If the pattern matches a trailing portion of the expanded value of |
1507 | @var{parameter}, then the result of the expansion is the value of | |
1508 | @var{parameter} with the shortest matching pattern (the @samp{%} case) | |
1509 | or the longest matching pattern (the @samp{%%} case) deleted. | |
ccc6cda3 JA |
1510 | If @var{parameter} is @samp{@@} or @samp{*}, |
1511 | the pattern removal operation is applied to each positional | |
1512 | parameter in turn, and the expansion is the resultant list. | |
1513 | If @var{parameter} | |
1514 | is an array variable subscripted with @samp{@@} or @samp{*}, | |
1515 | the pattern removal operation is applied to each member of the | |
1516 | array in turn, and the expansion is the resultant list. | |
1517 | ||
1518 | @item $@{@var{parameter}/@var{pattern}/@var{string}@} | |
1519 | @itemx $@{@var{parameter}//@var{pattern}/@var{string}@} | |
1520 | ||
1521 | The @var{pattern} is expanded to produce a pattern just as in | |
1522 | filename expansion. | |
1523 | @var{Parameter} is expanded and the longest match of @var{pattern} | |
1524 | against its value is replaced with @var{string}. | |
1525 | In the first form, only the first match is replaced. | |
1526 | The second form causes all matches of @var{pattern} to be | |
1527 | replaced with @var{string}. | |
1528 | If @var{pattern} begins with @samp{#}, it must match at the beginning | |
b72432fd | 1529 | of the expanded value of @var{parameter}. |
ccc6cda3 | 1530 | If @var{pattern} begins with @samp{%}, it must match at the end |
b72432fd | 1531 | of the expanded value of @var{parameter}. |
ccc6cda3 JA |
1532 | If @var{string} is null, matches of @var{pattern} are deleted |
1533 | and the @code{/} following @var{pattern} may be omitted. | |
1534 | If @var{parameter} is @samp{@@} or @samp{*}, | |
1535 | the substitution operation is applied to each positional | |
1536 | parameter in turn, and the expansion is the resultant list. | |
1537 | If @var{parameter} | |
1538 | is an array variable subscripted with @samp{@@} or @samp{*}, | |
1539 | the substitution operation is applied to each member of the | |
1540 | array in turn, and the expansion is the resultant list. | |
1541 | ||
1542 | @end table | |
1543 | ||
1544 | @node Command Substitution | |
1545 | @subsection Command Substitution | |
1546 | @cindex command substitution | |
1547 | ||
1548 | Command substitution allows the output of a command to replace | |
bb70624e JA |
1549 | the command itself. |
1550 | Command substitution occurs when a command is enclosed as follows: | |
ccc6cda3 JA |
1551 | @example |
1552 | $(@var{command}) | |
1553 | @end example | |
1554 | @noindent | |
1555 | or | |
1556 | @example | |
1557 | `@var{command}` | |
1558 | @end example | |
1559 | ||
1560 | @noindent | |
1561 | Bash performs the expansion by executing @var{command} and | |
1562 | replacing the command substitution with the standard output of the | |
1563 | command, with any trailing newlines deleted. | |
cce855bc JA |
1564 | Embedded newlines are not deleted, but they may be removed during |
1565 | word splitting. | |
1566 | The command substitution @code{$(cat @var{file})} can be | |
1567 | replaced by the equivalent but faster @code{$(< @var{file})}. | |
ccc6cda3 JA |
1568 | |
1569 | When the old-style backquote form of substitution is used, | |
1570 | backslash retains its literal meaning except when followed by | |
cce855bc JA |
1571 | @samp{$}, @samp{`}, or @samp{\}. |
1572 | The first backquote not preceded by a backslash terminates the | |
1573 | command substitution. | |
ccc6cda3 JA |
1574 | When using the @code{$(@var{command})} form, all characters between |
1575 | the parentheses make up the command; none are treated specially. | |
1576 | ||
cce855bc JA |
1577 | Command substitutions may be nested. To nest when using the backquoted |
1578 | form, escape the inner backquotes with backslashes. | |
ccc6cda3 JA |
1579 | |
1580 | If the substitution appears within double quotes, word splitting and | |
1581 | filename expansion are not performed on the results. | |
1582 | ||
cce855bc JA |
1583 | @node Arithmetic Expansion |
1584 | @subsection Arithmetic Expansion | |
1585 | @cindex expansion, arithmetic | |
1586 | @cindex arithmetic expansion | |
1587 | ||
1588 | Arithmetic expansion allows the evaluation of an arithmetic expression | |
1589 | and the substitution of the result. The format for arithmetic expansion is: | |
1590 | ||
1591 | @example | |
1592 | $(( @var{expression} )) | |
1593 | @end example | |
1594 | ||
1595 | The expression is treated as if it were within double quotes, but | |
1596 | a double quote inside the parentheses is not treated specially. | |
1597 | All tokens in the expression undergo parameter expansion, command | |
1598 | substitution, and quote removal. | |
1599 | Arithmetic substitutions may be nested. | |
1600 | ||
1601 | The evaluation is performed according to the rules listed below | |
1602 | (@pxref{Shell Arithmetic}). | |
1603 | If the expression is invalid, Bash prints a message indicating | |
1604 | failure to the standard error and no substitution occurs. | |
1605 | ||
ccc6cda3 JA |
1606 | @node Process Substitution |
1607 | @subsection Process Substitution | |
1608 | @cindex process substitution | |
1609 | ||
1610 | Process substitution is supported on systems that support named | |
bb70624e | 1611 | pipes (@sc{fifo}s) or the @file{/dev/fd} method of naming open files. |
ccc6cda3 JA |
1612 | It takes the form of |
1613 | @example | |
1614 | <(@var{list}) | |
1615 | @end example | |
1616 | @noindent | |
1617 | or | |
1618 | @example | |
1619 | >(@var{list}) | |
1620 | @end example | |
1621 | @noindent | |
1622 | The process @var{list} is run with its input or output connected to a | |
bb70624e | 1623 | @sc{fifo} or some file in @file{/dev/fd}. The name of this file is |
ccc6cda3 JA |
1624 | passed as an argument to the current command as the result of the |
1625 | expansion. If the @code{>(@var{list})} form is used, writing to | |
1626 | the file will provide input for @var{list}. If the | |
1627 | @code{<(@var{list})} form is used, the file passed as an | |
1628 | argument should be read to obtain the output of @var{list}. | |
bb70624e JA |
1629 | Note that no space may appear between the @code{<} or @code{>} |
1630 | and the left parenthesis, otherwise the construct would be interpreted | |
1631 | as a redirection. | |
ccc6cda3 | 1632 | |
cce855bc JA |
1633 | When available, process substitution is performed simultaneously with |
1634 | parameter and variable expansion, command substitution, and arithmetic | |
1635 | expansion. | |
ccc6cda3 JA |
1636 | |
1637 | @node Word Splitting | |
1638 | @subsection Word Splitting | |
1639 | @cindex word splitting | |
1640 | ||
1641 | The shell scans the results of parameter expansion, command substitution, | |
1642 | and arithmetic expansion that did not occur within double quotes for | |
1643 | word splitting. | |
1644 | ||
28ef6c31 | 1645 | The shell treats each character of @env{$IFS} |
ccc6cda3 JA |
1646 | as a delimiter, and splits the results of the other |
1647 | expansions into words on these characters. If | |
28ef6c31 JA |
1648 | @env{IFS} is unset, or its value is exactly @code{<space><tab><newline>}, |
1649 | the default, then any sequence of @env{IFS} | |
1650 | characters serves to delimit words. If @env{IFS} | |
ccc6cda3 JA |
1651 | has a value other than the default, then sequences of |
1652 | the whitespace characters @code{space} and @code{tab} | |
1653 | are ignored at the beginning and end of the | |
1654 | word, as long as the whitespace character is in the | |
28ef6c31 JA |
1655 | value of @env{IFS} (an @env{IFS} whitespace character). |
1656 | Any character in @env{IFS} that is not @env{IFS} | |
1657 | whitespace, along with any adjacent @env{IFS} | |
1658 | whitespace characters, delimits a field. A sequence of @env{IFS} | |
ccc6cda3 | 1659 | whitespace characters is also treated as a delimiter. |
28ef6c31 | 1660 | If the value of @env{IFS} is null, no word splitting occurs. |
ccc6cda3 JA |
1661 | |
1662 | Explicit null arguments (@code{""} or @code{''}) are retained. | |
1663 | Unquoted implicit null arguments, resulting from the expansion of | |
bb70624e | 1664 | parameters that have no values, are removed. |
ccc6cda3 JA |
1665 | If a parameter with no value is expanded within double quotes, a |
1666 | null argument results and is retained. | |
1667 | ||
1668 | Note that if no expansion occurs, no splitting | |
1669 | is performed. | |
1670 | ||
1671 | @node Filename Expansion | |
1672 | @subsection Filename Expansion | |
cce855bc JA |
1673 | @menu |
1674 | * Pattern Matching:: How the shell matches patterns. | |
1675 | @end menu | |
ccc6cda3 JA |
1676 | @cindex expansion, filename |
1677 | @cindex expansion, pathname | |
1678 | @cindex filename expansion | |
1679 | @cindex pathname expansion | |
1680 | ||
28ef6c31 | 1681 | After word splitting, unless the @option{-f} option has been set |
cce855bc | 1682 | (@pxref{The Set Builtin}), Bash scans each word for the characters |
bb70624e | 1683 | @samp{*}, @samp{?}, and @samp{[}. |
ccc6cda3 JA |
1684 | If one of these characters appears, then the word is |
1685 | regarded as a @var{pattern}, | |
1686 | and replaced with an alphabetically sorted list of | |
1687 | file names matching the pattern. If no matching file names are found, | |
1688 | and the shell option @code{nullglob} is disabled, the word is left | |
cce855bc JA |
1689 | unchanged. |
1690 | If the @code{nullglob} option is set, and no matches are found, the word | |
1691 | is removed. | |
1692 | If the shell option @code{nocaseglob} is enabled, the match is performed | |
1693 | without regard to the case of alphabetic characters. | |
1694 | ||
1695 | When a pattern is used for filename generation, the character @samp{.} | |
ccc6cda3 | 1696 | at the start of a filename or immediately following a slash |
cce855bc JA |
1697 | must be matched explicitly, unless the shell option @code{dotglob} is set. |
1698 | When matching a file name, the slash character must always be | |
1699 | matched explicitly. | |
ccc6cda3 | 1700 | In other cases, the @samp{.} character is not treated specially. |
cce855bc | 1701 | |
ccc6cda3 | 1702 | See the description of @code{shopt} in @ref{Bash Builtins}, |
cce855bc JA |
1703 | for a description of the @code{nocaseglob}, @code{nullglob}, |
1704 | and @code{dotglob} options. | |
ccc6cda3 | 1705 | |
28ef6c31 | 1706 | The @env{GLOBIGNORE} |
ccc6cda3 | 1707 | shell variable may be used to restrict the set of filenames matching a |
28ef6c31 | 1708 | pattern. If @env{GLOBIGNORE} |
ccc6cda3 | 1709 | is set, each matching filename that also matches one of the patterns in |
28ef6c31 | 1710 | @env{GLOBIGNORE} is removed from the list of matches. The filenames |
ccc6cda3 | 1711 | @file{.} and @file{..} |
28ef6c31 JA |
1712 | are always ignored, even when @env{GLOBIGNORE} |
1713 | is set. However, setting @env{GLOBIGNORE} has the effect of | |
ccc6cda3 JA |
1714 | enabling the @code{dotglob} |
1715 | shell option, so all other filenames beginning with a | |
1716 | @samp{.} will match. | |
1717 | To get the old behavior of ignoring filenames beginning with a | |
28ef6c31 JA |
1718 | @samp{.}, make @samp{.*} one of the patterns in @env{GLOBIGNORE}. |
1719 | The @code{dotglob} option is disabled when @env{GLOBIGNORE} | |
ccc6cda3 JA |
1720 | is unset. |
1721 | ||
cce855bc JA |
1722 | @node Pattern Matching |
1723 | @subsubsection Pattern Matching | |
1724 | @cindex pattern matching | |
1725 | @cindex matching, pattern | |
1726 | ||
1727 | Any character that appears in a pattern, other than the special pattern | |
bb70624e | 1728 | characters described below, matches itself. The @sc{nul} character may not |
cce855bc JA |
1729 | occur in a pattern. The special pattern characters must be quoted if |
1730 | they are to be matched literally. | |
1731 | ||
ccc6cda3 JA |
1732 | The special pattern characters have the following meanings: |
1733 | @table @code | |
1734 | @item * | |
1735 | Matches any string, including the null string. | |
1736 | @item ? | |
1737 | Matches any single character. | |
1738 | @item [@dots{}] | |
1739 | Matches any one of the enclosed characters. A pair of characters | |
28ef6c31 JA |
1740 | separated by a hyphen denotes a @var{range expression}; |
1741 | any character that sorts between those two characters, inclusive, | |
1742 | using the current locale's collating sequence and character set, | |
ccc6cda3 JA |
1743 | is matched. If the first character following the |
1744 | @samp{[} is a @samp{!} or a @samp{^} | |
1745 | then any character not enclosed is matched. A @samp{@minus{}} | |
1746 | may be matched by including it as the first or last character | |
1747 | in the set. A @samp{]} may be matched by including it as the first | |
1748 | character in the set. | |
28ef6c31 JA |
1749 | The sorting order of characters in range expressions is determined by |
1750 | the current locale and the value of the @env{LC_COLLATE} shell variable, | |
1751 | if set. | |
1752 | ||
1753 | For example, in the default C locale, @samp{[a-dx-z]} is equivalent to | |
1754 | @samp{[abcdxyz]}. Many locales sort characters in dictionary order, and in | |
1755 | these locales @samp{[a-dx-z]} is typically not equivalent to @samp{[abcdxyz]}; | |
1756 | it might be equivalent to @samp{[aBbCcDdxXyYz]}, for example. To obtain | |
1757 | the traditional interpretation of ranges in bracket expressions, you can | |
1758 | force the use of the C locale by setting the @env{LC_COLLATE} or | |
1759 | @env{LC_ALL} environment variable to the value @samp{C}. | |
cce855bc JA |
1760 | |
1761 | Within @samp{[} and @samp{]}, @var{character classes} can be specified | |
1762 | using the syntax | |
1763 | @code{[:}@var{class}@code{:]}, where @var{class} is one of the | |
bb70624e | 1764 | following classes defined in the @sc{posix} 1003.2 standard: |
cce855bc JA |
1765 | @example |
1766 | alnum alpha ascii blank cntrl digit graph lower | |
1767 | print punct space upper xdigit | |
1768 | @end example | |
1769 | @noindent | |
1770 | A character class matches any character belonging to that class. | |
1771 | ||
1772 | Within @samp{[} and @samp{]}, an @var{equivalence class} can be | |
1773 | specified using the syntax @code{[=}@var{c}@code{=]}, which | |
1774 | matches all characters with the same collation weight (as defined | |
1775 | by the current locale) as the character @var{c}. | |
1776 | ||
1777 | Within @samp{[} and @samp{]}, the syntax @code{[.}@var{symbol}@code{.]} | |
1778 | matches the collating symbol @var{symbol}. | |
1779 | @end table | |
1780 | ||
1781 | If the @code{extglob} shell option is enabled using the @code{shopt} | |
1782 | builtin, several extended pattern matching operators are recognized. | |
1783 | In the following description, a @var{pattern-list} is a list of one | |
1784 | or more patterns separated by a @samp{|}. | |
1785 | Composite patterns may be formed using one or more of the following | |
1786 | sub-patterns: | |
1787 | ||
1788 | @table @code | |
1789 | @item ?(@var{pattern-list}) | |
1790 | Matches zero or one occurrence of the given patterns. | |
1791 | ||
1792 | @item *(@var{pattern-list}) | |
1793 | Matches zero or more occurrences of the given patterns. | |
1794 | ||
1795 | @item +(@var{pattern-list}) | |
1796 | Matches one or more occurrences of the given patterns. | |
1797 | ||
1798 | @item @@(@var{pattern-list}) | |
1799 | Matches exactly one of the given patterns. | |
1800 | ||
1801 | @item !(@var{pattern-list}) | |
1802 | Matches anything except one of the given patterns. | |
ccc6cda3 JA |
1803 | @end table |
1804 | ||
1805 | @node Quote Removal | |
1806 | @subsection Quote Removal | |
1807 | ||
1808 | After the preceding expansions, all unquoted occurrences of the | |
1809 | characters @samp{\}, @samp{'}, and @samp{"} that did not | |
1810 | result from one of the above expansions are removed. | |
1811 | ||
1812 | @node Redirections | |
1813 | @section Redirections | |
1814 | @cindex redirection | |
1815 | ||
1816 | Before a command is executed, its input and output | |
1817 | may be @var{redirected} | |
1818 | using a special notation interpreted by the shell. | |
1819 | Redirection may also be used to open and close files for the | |
1820 | current shell execution environment. The following redirection | |
1821 | operators may precede or appear anywhere within a | |
1822 | simple command or may follow a command. | |
1823 | Redirections are processed in the order they appear, from | |
1824 | left to right. | |
1825 | ||
1826 | In the following descriptions, if the file descriptor number is | |
1827 | omitted, and the first character of the redirection operator is | |
1828 | @samp{<}, the redirection refers to the standard input (file | |
1829 | descriptor 0). If the first character of the redirection operator | |
1830 | is @samp{>}, the redirection refers to the standard output (file | |
1831 | descriptor 1). | |
1832 | ||
cce855bc JA |
1833 | The word following the redirection operator in the following |
1834 | descriptions, unless otherwise noted, is subjected to brace expansion, | |
1835 | tilde expansion, parameter expansion, command substitution, arithmetic | |
bb70624e | 1836 | expansion, quote removal, filename expansion, and word splitting. |
cce855bc | 1837 | If it expands to more than one word, Bash reports an error. |
ccc6cda3 JA |
1838 | |
1839 | Note that the order of redirections is significant. For example, | |
1840 | the command | |
1841 | @example | |
1842 | ls > @var{dirlist} 2>&1 | |
1843 | @end example | |
1844 | @noindent | |
bb70624e JA |
1845 | directs both standard output (file descriptor 1) and standard error |
1846 | (file descriptor 2) to the file @var{dirlist}, while the command | |
ccc6cda3 JA |
1847 | @example |
1848 | ls 2>&1 > @var{dirlist} | |
1849 | @end example | |
1850 | @noindent | |
1851 | directs only the standard output to file @var{dirlist}, | |
1852 | because the standard error was duplicated as standard output | |
1853 | before the standard output was redirected to @var{dirlist}. | |
1854 | ||
bb70624e JA |
1855 | Bash handles several filenames specially when they are used in |
1856 | redirections, as described in the following table: | |
1857 | ||
1858 | @table @code | |
1859 | @item /dev/fd/@var{fd} | |
1860 | If @var{fd} is a valid integer, file descriptor @var{fd} is duplicated. | |
1861 | ||
1862 | @item /dev/stdin | |
1863 | File descriptor 0 is duplicated. | |
1864 | ||
1865 | @item /dev/stdout | |
1866 | File descriptor 1 is duplicated. | |
1867 | ||
1868 | @item /dev/stderr | |
1869 | File descriptor 2 is duplicated. | |
1870 | ||
1871 | @item /dev/tcp/@var{host}/@var{port} | |
1872 | If @var{host} is a valid hostname or Internet address, and @var{port} | |
1873 | is an integer port number, Bash attempts to open a TCP connection | |
1874 | to the corresponding socket. | |
1875 | ||
1876 | @item /dev/udp/@var{host}/@var{port} | |
1877 | If @var{host} is a valid hostname or Internet address, and @var{port} | |
1878 | is an integer port number, Bash attempts to open a UDP connection | |
1879 | to the corresponding socket. | |
1880 | ||
1881 | @end table | |
1882 | ||
cce855bc JA |
1883 | A failure to open or create a file causes the redirection to fail. |
1884 | ||
ccc6cda3 JA |
1885 | @subsection Redirecting Input |
1886 | Redirection of input causes the file whose name results from | |
1887 | the expansion of @var{word} | |
1888 | to be opened for reading on file descriptor @code{n}, | |
1889 | or the standard input (file descriptor 0) if @code{n} | |
1890 | is not specified. | |
1891 | ||
1892 | The general format for redirecting input is: | |
1893 | @example | |
1894 | [n]<@var{word} | |
1895 | @end example | |
1896 | ||
1897 | @subsection Redirecting Output | |
1898 | Redirection of output causes the file whose name results from | |
1899 | the expansion of @var{word} | |
1900 | to be opened for writing on file descriptor @code{n}, | |
1901 | or the standard output (file descriptor 1) if @code{n} | |
1902 | is not specified. If the file does not exist it is created; | |
1903 | if it does exist it is truncated to zero size. | |
1904 | ||
1905 | The general format for redirecting output is: | |
1906 | @example | |
1907 | [n]>[|]@var{word} | |
1908 | @end example | |
1909 | ||
cce855bc JA |
1910 | If the redirection operator is @samp{>}, and the @code{noclobber} |
1911 | option to the @code{set} builtin has been enabled, the redirection | |
bb70624e | 1912 | will fail if the file whose name results from the expansion of |
cce855bc JA |
1913 | @var{word} exists and is a regular file. |
1914 | If the redirection operator is @samp{>|}, or the redirection operator is | |
1915 | @samp{>} and the @code{noclobber} option is not enabled, the redirection | |
1916 | is attempted even if the file named by @var{word} exists. | |
ccc6cda3 JA |
1917 | |
1918 | @subsection Appending Redirected Output | |
1919 | Redirection of output in this fashion | |
1920 | causes the file whose name results from | |
1921 | the expansion of @var{word} | |
1922 | to be opened for appending on file descriptor @code{n}, | |
1923 | or the standard output (file descriptor 1) if @code{n} | |
1924 | is not specified. If the file does not exist it is created. | |
1925 | ||
1926 | The general format for appending output is: | |
1927 | @example | |
1928 | [n]>>@var{word} | |
1929 | @end example | |
1930 | ||
1931 | @subsection Redirecting Standard Output and Standard Error | |
1932 | Bash allows both the | |
1933 | standard output (file descriptor 1) and | |
1934 | the standard error output (file descriptor 2) | |
1935 | to be redirected to the file whose name is the | |
1936 | expansion of @var{word} with this construct. | |
1937 | ||
1938 | There are two formats for redirecting standard output and | |
1939 | standard error: | |
1940 | @example | |
1941 | &>@var{word} | |
1942 | @end example | |
1943 | @noindent | |
1944 | and | |
1945 | @example | |
1946 | >&@var{word} | |
1947 | @end example | |
1948 | @noindent | |
1949 | Of the two forms, the first is preferred. | |
1950 | This is semantically equivalent to | |
1951 | @example | |
1952 | >@var{word} 2>&1 | |
1953 | @end example | |
1954 | ||
1955 | @subsection Here Documents | |
1956 | This type of redirection instructs the shell to read input from the | |
1957 | current source until a line containing only @var{word} | |
1958 | (with no trailing blanks) is seen. All of | |
1959 | the lines read up to that point are then used as the standard | |
1960 | input for a command. | |
1961 | ||
1962 | The format of here-documents is as follows: | |
1963 | @example | |
1964 | <<[@minus{}]@var{word} | |
1965 | @var{here-document} | |
1966 | @var{delimiter} | |
1967 | @end example | |
1968 | ||
bb70624e JA |
1969 | No parameter expansion, command substitution, arithmetic expansion, |
1970 | or filename expansion is performed on | |
ccc6cda3 JA |
1971 | @var{word}. If any characters in @var{word} are quoted, the |
1972 | @var{delimiter} is the result of quote removal on @var{word}, | |
cce855bc JA |
1973 | and the lines in the here-document are not expanded. |
1974 | If @var{word} is unquoted, | |
ccc6cda3 JA |
1975 | all lines of the here-document are subjected to parameter expansion, |
1976 | command substitution, and arithmetic expansion. In the latter | |
bb70624e | 1977 | case, the character sequence @code{\newline} is ignored, and @samp{\} |
ccc6cda3 JA |
1978 | must be used to quote the characters |
1979 | @samp{\}, @samp{$}, and @samp{`}. | |
1980 | ||
1981 | If the redirection operator is @samp{<<-}, | |
1982 | then all leading tab characters are stripped from input lines and the | |
1983 | line containing @var{delimiter}. | |
1984 | This allows here-documents within shell scripts to be indented in a | |
1985 | natural fashion. | |
1986 | ||
1987 | @subsection Duplicating File Descriptors | |
1988 | The redirection operator | |
1989 | @example | |
1990 | [n]<&@var{word} | |
1991 | @end example | |
1992 | @noindent | |
1993 | is used to duplicate input file descriptors. | |
1994 | If @var{word} | |
1995 | expands to one or more digits, the file descriptor denoted by @code{n} | |
cce855bc JA |
1996 | is made to be a copy of that file descriptor. |
1997 | If the digits in @var{word} do not specify a file descriptor open for | |
1998 | input, a redirection error occurs. | |
1999 | If @var{word} | |
ccc6cda3 JA |
2000 | evaluates to @samp{-}, file descriptor @code{n} is closed. If |
2001 | @code{n} is not specified, the standard input (file descriptor 0) is used. | |
2002 | ||
2003 | The operator | |
2004 | @example | |
2005 | [n]>&@var{word} | |
2006 | @end example | |
2007 | @noindent | |
2008 | is used similarly to duplicate output file descriptors. If | |
2009 | @code{n} | |
2010 | is not specified, the standard output (file descriptor 1) is used. | |
cce855bc JA |
2011 | If the digits in @var{word} do not specify a file descriptor open for |
2012 | output, a redirection error occurs. | |
ccc6cda3 JA |
2013 | As a special case, if @code{n} is omitted, and @var{word} does not |
2014 | expand to one or more digits, the standard output and standard | |
2015 | error are redirected as described previously. | |
2016 | ||
2017 | @subsection Opening File Descriptors for Reading and Writing | |
2018 | The redirection operator | |
2019 | @example | |
2020 | [n]<>@var{word} | |
2021 | @end example | |
2022 | @noindent | |
2023 | causes the file whose name is the expansion of @var{word} | |
2024 | to be opened for both reading and writing on file descriptor | |
2025 | @code{n}, or on file descriptor 0 if @code{n} | |
2026 | is not specified. If the file does not exist, it is created. | |
2027 | ||
2028 | @node Executing Commands | |
2029 | @section Executing Commands | |
2030 | ||
2031 | @menu | |
cce855bc JA |
2032 | * Simple Command Expansion:: How Bash expands simple commands before |
2033 | executing them. | |
2034 | ||
ccc6cda3 JA |
2035 | * Command Search and Execution:: How Bash finds commands and runs them. |
2036 | ||
cce855bc JA |
2037 | * Command Execution Environment:: The environment in which Bash |
2038 | executes commands that are not | |
2039 | shell builtins. | |
2040 | ||
ccc6cda3 JA |
2041 | * Environment:: The environment given to a command. |
2042 | ||
2043 | * Exit Status:: The status returned by commands and how Bash | |
2044 | interprets it. | |
2045 | ||
2046 | * Signals:: What happens when Bash or a command it runs | |
2047 | receives a signal. | |
cce855bc | 2048 | |
ccc6cda3 JA |
2049 | @end menu |
2050 | ||
cce855bc JA |
2051 | @node Simple Command Expansion |
2052 | @subsection Simple Command Expansion | |
2053 | @cindex command expansion | |
2054 | ||
2055 | When a simple command is executed, the shell performs the following | |
2056 | expansions, assignments, and redirections, from left to right. | |
2057 | ||
2058 | @enumerate | |
2059 | @item | |
2060 | The words that the parser has marked as variable assignments (those | |
2061 | preceding the command name) and redirections are saved for later | |
2062 | processing. | |
2063 | ||
2064 | @item | |
2065 | The words that are not variable assignments or redirections are | |
2066 | expanded (@pxref{Shell Expansions}). | |
2067 | If any words remain after expansion, the first word | |
2068 | is taken to be the name of the command and the remaining words are | |
2069 | the arguments. | |
2070 | ||
2071 | @item | |
2072 | Redirections are performed as described above (@pxref{Redirections}). | |
2073 | ||
2074 | @item | |
2075 | The text after the @samp{=} in each variable assignment undergoes tilde | |
2076 | expansion, parameter expansion, command substitution, arithmetic expansion, | |
2077 | and quote removal before being assigned to the variable. | |
2078 | @end enumerate | |
2079 | ||
2080 | If no command name results, the variable assignments affect the current | |
2081 | shell environment. Otherwise, the variables are added to the environment | |
2082 | of the executed command and do not affect the current shell environment. | |
2083 | If any of the assignments attempts to assign a value to a readonly variable, | |
2084 | an error occurs, and the command exits with a non-zero status. | |
2085 | ||
2086 | If no command name results, redirections are performed, but do not | |
2087 | affect the current shell environment. A redirection error causes the | |
2088 | command to exit with a non-zero status. | |
2089 | ||
2090 | If there is a command name left after expansion, execution proceeds as | |
2091 | described below. Otherwise, the command exits. If one of the expansions | |
2092 | contained a command substitution, the exit status of the command is | |
2093 | the exit status of the last command substitution performed. If there | |
2094 | were no command substitutions, the command exits with a status of zero. | |
2095 | ||
ccc6cda3 JA |
2096 | @node Command Search and Execution |
2097 | @subsection Command Search and Execution | |
2098 | @cindex command execution | |
2099 | @cindex command search | |
2100 | ||
2101 | After a command has been split into words, if it results in a | |
2102 | simple command and an optional list of arguments, the following | |
2103 | actions are taken. | |
2104 | ||
2105 | @enumerate | |
2106 | @item | |
2107 | If the command name contains no slashes, the shell attempts to | |
2108 | locate it. If there exists a shell function by that name, that | |
bb70624e | 2109 | function is invoked as described in @ref{Shell Functions}. |
ccc6cda3 JA |
2110 | |
2111 | @item | |
2112 | If the name does not match a function, the shell searches for | |
2113 | it in the list of shell builtins. If a match is found, that | |
2114 | builtin is invoked. | |
2115 | ||
2116 | @item | |
2117 | If the name is neither a shell function nor a builtin, | |
2118 | and contains no slashes, Bash searches each element of | |
28ef6c31 | 2119 | @env{$PATH} for a directory containing an executable file |
ccc6cda3 | 2120 | by that name. Bash uses a hash table to remember the full |
28ef6c31 | 2121 | pathnames of executable files to avoid multiple @env{PATH} searches |
cce855bc | 2122 | (see the description of @code{hash} in @ref{Bourne Shell Builtins}). |
28ef6c31 | 2123 | A full search of the directories in @env{$PATH} |
ccc6cda3 JA |
2124 | is performed only if the command is not found in the hash table. |
2125 | If the search is unsuccessful, the shell prints an error | |
cce855bc | 2126 | message and returns an exit status of 127. |
ccc6cda3 JA |
2127 | |
2128 | @item | |
2129 | If the search is successful, or if the command name contains | |
cce855bc JA |
2130 | one or more slashes, the shell executes the named program in |
2131 | a separate execution environment. | |
ccc6cda3 JA |
2132 | Argument 0 is set to the name given, and the remaining arguments |
2133 | to the command are set to the arguments supplied, if any. | |
2134 | ||
2135 | @item | |
2136 | If this execution fails because the file is not in executable | |
cce855bc JA |
2137 | format, and the file is not a directory, it is assumed to be a |
2138 | @var{shell script} and the shell executes it as described in | |
2139 | @ref{Shell Scripts}. | |
2140 | ||
2141 | @item | |
2142 | If the command was not begun asynchronously, the shell waits for | |
2143 | the command to complete and collects its exit status. | |
2144 | ||
ccc6cda3 JA |
2145 | @end enumerate |
2146 | ||
cce855bc JA |
2147 | @node Command Execution Environment |
2148 | @subsection Command Execution Environment | |
2149 | @cindex execution environment | |
2150 | ||
2151 | The shell has an @var{execution environment}, which consists of the | |
2152 | following: | |
2153 | ||
2154 | @itemize @bullet | |
2155 | @item | |
2156 | open files inherited by the shell at invocation, as modified by | |
2157 | redirections supplied to the @code{exec} builtin | |
2158 | ||
2159 | @item | |
2160 | the current working directory as set by @code{cd}, @code{pushd}, or | |
2161 | @code{popd}, or inherited by the shell at invocation | |
2162 | ||
2163 | @item | |
2164 | the file creation mode mask as set by @code{umask} or inherited from | |
2165 | the shell's parent | |
2166 | ||
2167 | @item | |
2168 | current traps set by @code{trap} | |
2169 | ||
2170 | @item | |
2171 | shell parameters that are set by variable assignment or with @code{set} | |
2172 | or inherited from the shell's parent in the environment | |
2173 | ||
2174 | @item | |
2175 | shell functions defined during execution or inherited from the shell's | |
2176 | parent in the environment | |
2177 | ||
2178 | @item | |
2179 | options enabled at invocation (either by default or with command-line | |
2180 | arguments) or by @code{set} | |
2181 | ||
2182 | @item | |
2183 | options enabled by @code{shopt} | |
2184 | ||
2185 | @item | |
2186 | shell aliases defined with @code{alias} (@pxref{Aliases}) | |
2187 | ||
2188 | @item | |
bb70624e | 2189 | various process @sc{id}s, including those of background jobs |
cce855bc | 2190 | (@pxref{Lists}), the value of @code{$$}, and the value of |
28ef6c31 | 2191 | @env{$PPID} |
cce855bc JA |
2192 | |
2193 | @end itemize | |
2194 | ||
2195 | When a simple command other than a builtin or shell function | |
2196 | is to be executed, it | |
2197 | is invoked in a separate execution environment that consists of | |
2198 | the following. Unless otherwise noted, the values are inherited | |
2199 | from the shell. | |
2200 | ||
2201 | @itemize @bullet | |
2202 | @item | |
2203 | the shell's open files, plus any modifications and additions specified | |
2204 | by redirections to the command | |
2205 | ||
2206 | @item | |
2207 | the current working directory | |
2208 | ||
2209 | @item | |
2210 | the file creation mode mask | |
2211 | ||
2212 | @item | |
2213 | shell variables marked for export, along with variables exported for | |
2214 | the command, passed in the environment (@pxref{Environment}) | |
2215 | ||
2216 | @item | |
2217 | traps caught by the shell are reset to the values inherited from the | |
2218 | shell's parent, and traps ignored by the shell are ignored | |
2219 | ||
2220 | @end itemize | |
2221 | ||
2222 | A command invoked in this separate environment cannot affect the | |
2223 | shell's execution environment. | |
2224 | ||
2225 | Command substitution and asynchronous commands are invoked in a | |
2226 | subshell environment that is a duplicate of the shell environment, | |
2227 | except that traps caught by the shell are reset to the values | |
2228 | that the shell inherited from its parent at invocation. Builtin | |
2229 | commands that are invoked as part of a pipeline are also executed | |
2230 | in a subshell environment. Changes made to the subshell environment | |
2231 | cannot affect the shell's execution environment. | |
2232 | ||
ccc6cda3 JA |
2233 | @node Environment |
2234 | @subsection Environment | |
2235 | @cindex environment | |
2236 | ||
2237 | When a program is invoked it is given an array of strings | |
2238 | called the @var{environment}. | |
2239 | This is a list of name-value pairs, of the form @code{name=value}. | |
2240 | ||
bb70624e JA |
2241 | Bash provides several ways to manipulate the environment. |
2242 | On invocation, the shell scans its own environment and | |
ccc6cda3 JA |
2243 | creates a parameter for each name found, automatically marking |
2244 | it for @var{export} | |
2245 | to child processes. Executed commands inherit the environment. | |
2246 | The @code{export} and @samp{declare -x} | |
2247 | commands allow parameters and functions to be added to and | |
2248 | deleted from the environment. If the value of a parameter | |
2249 | in the environment is modified, the new value becomes part | |
2250 | of the environment, replacing the old. The environment | |
2251 | inherited by any executed command consists of the shell's | |
2252 | initial environment, whose values may be modified in the shell, | |
cce855bc JA |
2253 | less any pairs removed by the @code{unset} and @samp{export -n} |
2254 | commands, plus any additions via the @code{export} and | |
2255 | @samp{declare -x} commands. | |
ccc6cda3 JA |
2256 | |
2257 | The environment for any simple command | |
2258 | or function may be augmented temporarily by prefixing it with | |
2259 | parameter assignments, as described in @ref{Shell Parameters}. | |
2260 | These assignment statements affect only the environment seen | |
2261 | by that command. | |
2262 | ||
28ef6c31 | 2263 | If the @option{-k} option is set (@pxref{The Set Builtin}), then all |
ccc6cda3 JA |
2264 | parameter assignments are placed in the environment for a command, |
2265 | not just those that precede the command name. | |
2266 | ||
2267 | When Bash invokes an external command, the variable @samp{$_} | |
2268 | is set to the full path name of the command and passed to that | |
2269 | command in its environment. | |
2270 | ||
2271 | @node Exit Status | |
2272 | @subsection Exit Status | |
2273 | @cindex exit status | |
2274 | ||
cce855bc | 2275 | For the shell's purposes, a command which exits with a |
ccc6cda3 JA |
2276 | zero exit status has succeeded. |
2277 | A non-zero exit status indicates failure. | |
2278 | This seemingly counter-intuitive scheme is used so there | |
2279 | is one well-defined way to indicate success and a variety of | |
2280 | ways to indicate various failure modes. | |
bb70624e JA |
2281 | When a command terminates on a fatal signal whose number is @var{N}, |
2282 | Bash uses the value 128+@var{N} as the exit status. | |
ccc6cda3 JA |
2283 | |
2284 | If a command is not found, the child process created to | |
2285 | execute it returns a status of 127. If a command is found | |
2286 | but is not executable, the return status is 126. | |
2287 | ||
cce855bc JA |
2288 | If a command fails because of an error during expansion or redirection, |
2289 | the exit status is greater than zero. | |
2290 | ||
ccc6cda3 JA |
2291 | The exit status is used by the Bash conditional commands |
2292 | (@pxref{Conditional Constructs}) and some of the list | |
2293 | constructs (@pxref{Lists}). | |
2294 | ||
2295 | All of the Bash builtins return an exit status of zero if they succeed | |
2296 | and a non-zero status on failure, so they may be used by the | |
2297 | conditional and list constructs. | |
cce855bc | 2298 | All builtins return an exit status of 2 to indicate incorrect usage. |
ccc6cda3 JA |
2299 | |
2300 | @node Signals | |
2301 | @subsection Signals | |
2302 | @cindex signal handling | |
2303 | ||
cce855bc | 2304 | When Bash is interactive, in the absence of any traps, it ignores |
ccc6cda3 JA |
2305 | @code{SIGTERM} (so that @samp{kill 0} does not kill an interactive shell), |
2306 | and @code{SIGINT} | |
2307 | is caught and handled (so that the @code{wait} builtin is interruptible). | |
2308 | When Bash receives a @code{SIGINT}, it breaks out of any executing loops. | |
2309 | In all cases, Bash ignores @code{SIGQUIT}. | |
2310 | If job control is in effect (@pxref{Job Control}), Bash | |
2311 | ignores @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}. | |
2312 | ||
cce855bc JA |
2313 | Commands started by Bash have signal handlers set to the |
2314 | values inherited by the shell from its parent. | |
2315 | When job control is not in effect, asynchronous commands | |
2316 | ignore @code{SIGINT} and @code{SIGQUIT} as well. | |
2317 | Commands run as a result of | |
2318 | command substitution ignore the keyboard-generated job control signals | |
ccc6cda3 JA |
2319 | @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}. |
2320 | ||
2321 | The shell exits by default upon receipt of a @code{SIGHUP}. | |
cce855bc JA |
2322 | Before exiting, it resends the @code{SIGHUP} to all jobs, running |
2323 | or stopped. | |
2324 | Stopped jobs are sent @code{SIGCONT} to ensure that they receive | |
2325 | the @code{SIGHUP}. | |
2326 | To prevent the shell from sending the @code{SIGHUP} signal to a | |
2327 | particular job, it should be removed | |
2328 | from the jobs table with the @code{disown} | |
2329 | builtin (@pxref{Job Control Builtins}) or marked | |
2330 | to not receive @code{SIGHUP} using @code{disown -h}. | |
2331 | ||
2332 | If the @code{huponexit} shell option has been set with @code{shopt} | |
2333 | (@pxref{Bash Builtins}), Bash sends a @code{SIGHUP} to all jobs when | |
2334 | an interactive login shell exits. | |
2335 | ||
2336 | When Bash receives a signal for which a trap has been set while waiting | |
2337 | for a command to complete, the trap will not be executed until the | |
2338 | command completes. | |
2339 | When Bash is waiting for an asynchronous | |
2340 | command via the @code{wait} builtin, the reception of a signal for | |
2341 | which a trap has been set will cause the @code{wait} builtin to return | |
2342 | immediately with an exit status greater than 128, immediately after | |
2343 | which the trap is executed. | |
ccc6cda3 JA |
2344 | |
2345 | @node Shell Scripts | |
2346 | @section Shell Scripts | |
2347 | @cindex shell script | |
2348 | ||
2349 | A shell script is a text file containing shell commands. When such | |
2350 | a file is used as the first non-option argument when invoking Bash, | |
28ef6c31 | 2351 | and neither the @option{-c} nor @option{-s} option is supplied |
ccc6cda3 JA |
2352 | (@pxref{Invoking Bash}), |
2353 | Bash reads and executes commands from the file, then exits. This | |
2354 | mode of operation creates a non-interactive shell. When Bash runs | |
2355 | a shell script, it sets the special parameter @code{0} to the name | |
2356 | of the file, rather than the name of the shell, and the positional | |
2357 | parameters are set to the remaining arguments, if any are given. | |
2358 | If no additional arguments are supplied, the positional parameters | |
2359 | are unset. | |
2360 | ||
2361 | A shell script may be made executable by using the @code{chmod} command | |
2362 | to turn on the execute bit. When Bash finds such a file while | |
28ef6c31 | 2363 | searching the @env{$PATH} for a command, it spawns a subshell to |
ccc6cda3 JA |
2364 | execute it. In other words, executing |
2365 | @example | |
2366 | filename @var{arguments} | |
2367 | @end example | |
2368 | @noindent | |
2369 | is equivalent to executing | |
2370 | @example | |
2371 | bash filename @var{arguments} | |
2372 | @end example | |
2373 | ||
2374 | @noindent | |
2375 | if @code{filename} is an executable shell script. | |
2376 | This subshell reinitializes itself, so that the effect is as if a | |
cce855bc JA |
2377 | new shell had been invoked to interpret the script, with the |
2378 | exception that the locations of commands remembered by the parent | |
2379 | (see the description of @code{hash} in @ref{Bourne Shell Builtins}) | |
2380 | are retained by the child. | |
ccc6cda3 | 2381 | |
bb70624e | 2382 | Most versions of Unix make this a part of the operating system's command |
ccc6cda3 JA |
2383 | execution mechanism. If the first line of a script begins with |
2384 | the two characters @samp{#!}, the remainder of the line specifies | |
bb70624e JA |
2385 | an interpreter for the program. |
2386 | Thus, you can specify Bash, @code{awk}, Perl, or some other | |
2387 | interpreter and write the rest of the script file in that language. | |
2388 | ||
2389 | The arguments to the interpreter | |
ccc6cda3 JA |
2390 | consist of a single optional argument following the interpreter |
2391 | name on the first line of the script file, followed by the name of | |
2392 | the script file, followed by the rest of the arguments. Bash | |
2393 | will perform this action on operating systems that do not handle it | |
2394 | themselves. Note that some older versions of Unix limit the interpreter | |
2395 | name and argument to a maximum of 32 characters. | |
2396 | ||
bb70624e JA |
2397 | Bash scripts often begin with @code{#! /bin/bash} (assuming that |
2398 | Bash has been installed in @file{/bin}), since this ensures that | |
2399 | Bash will be used to interpret the script, even if it is executed | |
2400 | under another shell. | |
2401 | ||
2402 | @node Shell Builtin Commands | |
2403 | @chapter Shell Builtin Commands | |
ccc6cda3 JA |
2404 | |
2405 | @menu | |
2406 | * Bourne Shell Builtins:: Builtin commands inherited from the Bourne | |
2407 | Shell. | |
bb70624e JA |
2408 | * Bash Builtins:: Table of builtins specific to Bash. |
2409 | * The Set Builtin:: This builtin is so overloaded it | |
2410 | deserves its own section. | |
2411 | * Special Builtins:: Builtin commands classified specially by | |
2412 | POSIX.2. | |
ccc6cda3 JA |
2413 | @end menu |
2414 | ||
bb70624e JA |
2415 | Builtin commands are contained within the shell itself. |
2416 | When the name of a builtin command is used as the first word of | |
2417 | a simple command (@pxref{Simple Commands}), the shell executes | |
2418 | the command directly, without invoking another program. | |
2419 | Builtin commands are necessary to implement functionality impossible | |
2420 | or inconvenient to obtain with separate utilities. | |
2421 | ||
2422 | This section briefly the builtins which Bash inherits from | |
2423 | the Bourne Shell, as well as the builtin commands which are unique | |
2424 | to or have been extended in Bash. | |
2425 | ||
2426 | Several builtin commands are described in other chapters: builtin | |
2427 | commands which provide the Bash interface to the job control | |
2428 | facilities (@pxref{Job Control Builtins}), the directory stack | |
2429 | (@pxref{Directory Stack Builtins}), the command history | |
2430 | (@pxref{Bash History Builtins}), and the programmable completion | |
2431 | facilities (@pxref{Programmable Completion Builtins}). | |
2432 | ||
2433 | Many of the builtins have been extended by @sc{posix} or Bash. | |
ccc6cda3 JA |
2434 | |
2435 | @node Bourne Shell Builtins | |
2436 | @section Bourne Shell Builtins | |
2437 | ||
bb70624e JA |
2438 | The following shell builtin commands are inherited from the Bourne Shell. |
2439 | These commands are implemented as specified by the @sc{posix} 1003.2 standard. | |
ccc6cda3 JA |
2440 | |
2441 | @table @code | |
bb70624e | 2442 | @item : @r{(a colon)} |
ccc6cda3 JA |
2443 | @btindex : |
2444 | @example | |
2445 | : [@var{arguments}] | |
2446 | @end example | |
2447 | Do nothing beyond expanding @var{arguments} and performing redirections. | |
cce855bc | 2448 | The return status is zero. |
ccc6cda3 | 2449 | |
bb70624e | 2450 | @item . @r{(a period)} |
ccc6cda3 JA |
2451 | @btindex . |
2452 | @example | |
b72432fd | 2453 | . @var{filename} [@var{arguments}] |
ccc6cda3 JA |
2454 | @end example |
2455 | Read and execute commands from the @var{filename} argument in the | |
cce855bc | 2456 | current shell context. If @var{filename} does not contain a slash, |
28ef6c31 JA |
2457 | the @env{PATH} variable is used to find @var{filename}. |
2458 | When Bash is not in @sc{posix} mode, the current directory is searched | |
2459 | if @var{filename} is not found in @env{$PATH}. | |
b72432fd JA |
2460 | If any @var{arguments} are supplied, they become the positional |
2461 | parameters when @var{filename} is executed. Otherwise the positional | |
2462 | parameters are unchanged. | |
cce855bc JA |
2463 | The return status is the exit status of the last command executed, or |
2464 | zero if no commands are executed. If @var{filename} is not found, or | |
2465 | cannot be read, the return status is non-zero. | |
bb70624e | 2466 | This builtin is equivalent to @code{source}. |
ccc6cda3 JA |
2467 | |
2468 | @item break | |
2469 | @btindex break | |
2470 | @example | |
2471 | break [@var{n}] | |
2472 | @end example | |
2473 | Exit from a @code{for}, @code{while}, @code{until}, or @code{select} loop. | |
2474 | If @var{n} is supplied, the @var{n}th enclosing loop is exited. | |
cce855bc JA |
2475 | @var{n} must be greater than or equal to 1. |
2476 | The return status is zero unless @var{n} is not greater than or equal to 1. | |
ccc6cda3 JA |
2477 | |
2478 | @item cd | |
2479 | @btindex cd | |
2480 | @example | |
2481 | cd [-LP] [@var{directory}] | |
2482 | @end example | |
2483 | Change the current working directory to @var{directory}. If @var{directory} | |
28ef6c31 JA |
2484 | is not given, the value of the @env{HOME} shell variable is used. If the |
2485 | shell variable @env{CDPATH} exists, it is used as a search path. If | |
2486 | @var{directory} begins with a slash, @env{CDPATH} is not used. | |
2487 | The @option{-P} option means | |
cce855bc | 2488 | to not follow symbolic links; symbolic links are followed by default |
28ef6c31 JA |
2489 | or with the @option{-L} option. |
2490 | If @var{directory} is @samp{-}, it is equivalent to @env{$OLDPWD}. | |
cce855bc JA |
2491 | The return status is zero if the directory is successfully changed, |
2492 | non-zero otherwise. | |
ccc6cda3 JA |
2493 | |
2494 | @item continue | |
2495 | @btindex continue | |
2496 | @example | |
2497 | continue [@var{n}] | |
2498 | @end example | |
2499 | Resume the next iteration of an enclosing @code{for}, @code{while}, | |
2500 | @code{until}, or @code{select} loop. | |
cce855bc JA |
2501 | If @var{n} is supplied, the execution of the @var{n}th enclosing loop |
2502 | is resumed. | |
2503 | @var{n} must be greater than or equal to 1. | |
2504 | The return status is zero unless @var{n} is not greater than or equal to 1. | |
ccc6cda3 JA |
2505 | |
2506 | @item eval | |
2507 | @btindex eval | |
2508 | @example | |
2509 | eval [@var{arguments}] | |
2510 | @end example | |
cce855bc JA |
2511 | The arguments are concatenated together into a single command, which is |
2512 | then read and executed, and its exit status returned as the exit status | |
2513 | of @code{eval}. | |
2514 | If there are no arguments or only empty arguments, the return status is | |
2515 | zero. | |
ccc6cda3 JA |
2516 | |
2517 | @item exec | |
2518 | @btindex exec | |
2519 | @example | |
cce855bc | 2520 | exec [-cl] [-a @var{name}] [@var{command} [@var{arguments}]] |
ccc6cda3 JA |
2521 | @end example |
2522 | If @var{command} | |
cce855bc | 2523 | is supplied, it replaces the shell without creating a new process. |
28ef6c31 | 2524 | If the @option{-l} option is supplied, the shell places a dash at the |
bb70624e | 2525 | beginning of the zeroth arg passed to @var{command}. |
ccc6cda3 | 2526 | This is what the @code{login} program does. |
28ef6c31 | 2527 | The @option{-c} option causes @var{command} to be executed with an empty |
cce855bc | 2528 | environment. |
28ef6c31 | 2529 | If @option{-a} is supplied, the shell passes @var{name} as the zeroth |
cce855bc | 2530 | argument to @var{command}. |
ccc6cda3 | 2531 | If no @var{command} is specified, redirections may be used to affect |
cce855bc JA |
2532 | the current shell environment. If there are no redirection errors, the |
2533 | return status is zero; otherwise the return status is non-zero. | |
ccc6cda3 JA |
2534 | |
2535 | @item exit | |
2536 | @btindex exit | |
2537 | @example | |
2538 | exit [@var{n}] | |
2539 | @end example | |
2540 | Exit the shell, returning a status of @var{n} to the shell's parent. | |
bb70624e | 2541 | If @var{n} is omitted, the exit status is that of the last command executed. |
cce855bc | 2542 | Any trap on @code{EXIT} is executed before the shell terminates. |
ccc6cda3 JA |
2543 | |
2544 | @item export | |
2545 | @btindex export | |
2546 | @example | |
2547 | export [-fn] [-p] [@var{name}[=@var{value}]] | |
2548 | @end example | |
2549 | Mark each @var{name} to be passed to child processes | |
28ef6c31 | 2550 | in the environment. If the @option{-f} option is supplied, the @var{name}s |
cce855bc | 2551 | refer to shell functions; otherwise the names refer to shell variables. |
28ef6c31 JA |
2552 | The @option{-n} option means to no longer mark each @var{name} for export. |
2553 | If no @var{names} are supplied, or if the @option{-p} option is given, a | |
ccc6cda3 | 2554 | list of exported names is displayed. |
28ef6c31 | 2555 | The @option{-p} option displays output in a form that may be reused as input. |
cce855bc | 2556 | The return status is zero unless an invalid option is supplied, one of |
28ef6c31 | 2557 | the names is not a valid shell variable name, or @option{-f} is supplied |
cce855bc | 2558 | with a name that is not a shell function. |
ccc6cda3 JA |
2559 | |
2560 | @item getopts | |
2561 | @btindex getopts | |
2562 | @example | |
2563 | getopts @var{optstring} @var{name} [@var{args}] | |
2564 | @end example | |
2565 | @code{getopts} is used by shell scripts to parse positional parameters. | |
bb70624e JA |
2566 | @var{optstring} contains the option characters to be recognized; if a |
2567 | character is followed by a colon, the option is expected to have an | |
ccc6cda3 | 2568 | argument, which should be separated from it by white space. |
bb70624e JA |
2569 | The colon (@samp{:}) and question mark (@samp{?}) may not be |
2570 | used as option characters. | |
ccc6cda3 JA |
2571 | Each time it is invoked, @code{getopts} |
2572 | places the next option in the shell variable @var{name}, initializing | |
2573 | @var{name} if it does not exist, | |
2574 | and the index of the next argument to be processed into the | |
28ef6c31 JA |
2575 | variable @env{OPTIND}. |
2576 | @env{OPTIND} is initialized to 1 each time the shell or a shell script | |
cce855bc JA |
2577 | is invoked. |
2578 | When an option requires an argument, | |
28ef6c31 JA |
2579 | @code{getopts} places that argument into the variable @env{OPTARG}. |
2580 | The shell does not reset @env{OPTIND} automatically; it must be manually | |
cce855bc JA |
2581 | reset between multiple calls to @code{getopts} within the same shell |
2582 | invocation if a new set of parameters is to be used. | |
2583 | ||
2584 | When the end of options is encountered, @code{getopts} exits with a | |
2585 | return value greater than zero. | |
28ef6c31 | 2586 | @env{OPTIND} is set to the index of the first non-option argument, |
cce855bc JA |
2587 | and @code{name} is set to @samp{?}. |
2588 | ||
2589 | @code{getopts} | |
2590 | normally parses the positional parameters, but if more arguments are | |
2591 | given in @var{args}, @code{getopts} parses those instead. | |
ccc6cda3 JA |
2592 | |
2593 | @code{getopts} can report errors in two ways. If the first character of | |
2594 | @var{optstring} is a colon, @var{silent} | |
2595 | error reporting is used. In normal operation diagnostic messages | |
cce855bc | 2596 | are printed when invalid options or missing option arguments are |
ccc6cda3 | 2597 | encountered. |
28ef6c31 | 2598 | If the variable @env{OPTERR} |
cce855bc | 2599 | is set to 0, no error messages will be displayed, even if the first |
ccc6cda3 JA |
2600 | character of @code{optstring} is not a colon. |
2601 | ||
cce855bc | 2602 | If an invalid option is seen, |
ccc6cda3 | 2603 | @code{getopts} places @samp{?} into @var{name} and, if not silent, |
28ef6c31 | 2604 | prints an error message and unsets @env{OPTARG}. |
ccc6cda3 | 2605 | If @code{getopts} is silent, the option character found is placed in |
28ef6c31 | 2606 | @env{OPTARG} and no diagnostic message is printed. |
ccc6cda3 JA |
2607 | |
2608 | If a required argument is not found, and @code{getopts} | |
2609 | is not silent, a question mark (@samp{?}) is placed in @var{name}, | |
2610 | @code{OPTARG} is unset, and a diagnostic message is printed. | |
2611 | If @code{getopts} is silent, then a colon (@samp{:}) is placed in | |
28ef6c31 | 2612 | @var{name} and @env{OPTARG} is set to the option character found. |
ccc6cda3 | 2613 | |
ccc6cda3 JA |
2614 | @item hash |
2615 | @btindex hash | |
2616 | @example | |
2617 | hash [-r] [-p @var{filename}] [@var{name}] | |
2618 | @end example | |
cce855bc JA |
2619 | Remember the full pathnames of commands specified as @var{name} arguments, |
2620 | so they need not be searched for on subsequent invocations. | |
2621 | The commands are found by searching through the directories listed in | |
28ef6c31 JA |
2622 | @env{$PATH}. |
2623 | The @option{-p} option inhibits the path search, and @var{filename} is | |
cce855bc | 2624 | used as the location of @var{name}. |
28ef6c31 | 2625 | The @option{-r} option causes the shell to forget all remembered locations. |
cce855bc JA |
2626 | If no arguments are given, information about remembered commands is printed. |
2627 | The return status is zero unless a @var{name} is not found or an invalid | |
2628 | option is supplied. | |
ccc6cda3 JA |
2629 | |
2630 | @item pwd | |
2631 | @btindex pwd | |
2632 | @example | |
2633 | pwd [-LP] | |
2634 | @end example | |
bb70624e | 2635 | Print the absolute pathname of the current working directory. |
28ef6c31 | 2636 | If the @option{-P} option is supplied, the pathname printed will not |
cce855bc | 2637 | contain symbolic links. |
28ef6c31 | 2638 | If the @option{-L} option is supplied, the pathname printed may contain |
cce855bc JA |
2639 | symbolic links. |
2640 | The return status is zero unless an error is encountered while | |
2641 | determining the name of the current directory or an invalid option | |
2642 | is supplied. | |
ccc6cda3 JA |
2643 | |
2644 | @item readonly | |
2645 | @btindex readonly | |
2646 | @example | |
2647 | readonly [-apf] [@var{name}] @dots{} | |
2648 | @end example | |
cce855bc JA |
2649 | Mark each @var{name} as readonly. |
2650 | The values of these names may not be changed by subsequent assignment. | |
28ef6c31 | 2651 | If the @option{-f} option is supplied, each @var{name} refers to a shell |
cce855bc | 2652 | function. |
28ef6c31 JA |
2653 | The @option{-a} option means each @var{name} refers to an array variable. |
2654 | If no @var{name} arguments are given, or if the @option{-p} | |
ccc6cda3 | 2655 | option is supplied, a list of all readonly names is printed. |
28ef6c31 | 2656 | The @option{-p} option causes output to be displayed in a format that |
cce855bc JA |
2657 | may be reused as input. |
2658 | The return status is zero unless an invalid option is supplied, one of | |
2659 | the @var{name} arguments is not a valid shell variable or function name, | |
28ef6c31 | 2660 | or the @option{-f} option is supplied with a name that is not a shell function. |
ccc6cda3 JA |
2661 | |
2662 | @item return | |
2663 | @btindex return | |
2664 | @example | |
2665 | return [@var{n}] | |
2666 | @end example | |
cce855bc | 2667 | Cause a shell function to exit with the return value @var{n}. |
bb70624e JA |
2668 | If @var{n} is not supplied, the return value is the exit status of the |
2669 | last command executed in the function. | |
cce855bc | 2670 | This may also be used to terminate execution of a script being executed |
bb70624e JA |
2671 | with the @code{.} (or @code{source}) builtin, returning either @var{n} or |
2672 | the exit status of the last command executed within the script as the exit | |
2673 | status of the script. | |
cce855bc | 2674 | The return status is false if @code{return} is used outside a function |
bb70624e | 2675 | and not during the execution of a script by @code{.} or @code{source}. |
ccc6cda3 JA |
2676 | |
2677 | @item shift | |
2678 | @btindex shift | |
2679 | @example | |
2680 | shift [@var{n}] | |
2681 | @end example | |
cce855bc JA |
2682 | Shift the positional parameters to the left by @var{n}. |
2683 | The positional parameters from @var{n}+1 @dots{} @code{$#} are | |
2684 | renamed to @code{$1} @dots{} @code{$#}-@var{n}+1. | |
2685 | Parameters represented by the numbers @code{$#} to @var{n}+1 are unset. | |
2686 | @var{n} must be a non-negative number less than or equal to @code{$#}. | |
2687 | If @var{n} is zero or greater than @code{$#}, the positional parameters | |
2688 | are not changed. | |
bb70624e | 2689 | If @var{n} is not supplied, it is assumed to be 1. |
cce855bc JA |
2690 | The return status is zero unless @var{n} is greater than @code{$#} or |
2691 | less than zero, non-zero otherwise. | |
ccc6cda3 JA |
2692 | |
2693 | @item test | |
2694 | @itemx [ | |
2695 | @btindex test | |
2696 | @btindex [ | |
cce855bc JA |
2697 | Evaluate a conditional expression @var{expr}. |
2698 | Each operator and operand must be a separate argument. | |
2699 | Expressions are composed of the primaries described below in | |
2700 | @ref{Bash Conditional Expressions}. | |
2701 | ||
bb70624e JA |
2702 | When the @code{[} form is used, the last argument to the command must |
2703 | be a @code{]}. | |
2704 | ||
cce855bc JA |
2705 | Expressions may be combined using the following operators, listed in |
2706 | decreasing order of precedence. | |
2707 | ||
2708 | @table @code | |
2709 | @item ! @var{expr} | |
2710 | True if @var{expr} is false. | |
2711 | ||
2712 | @item ( @var{expr} ) | |
2713 | Returns the value of @var{expr}. | |
2714 | This may be used to override the normal precedence of operators. | |
2715 | ||
2716 | @item @var{expr1} -a @var{expr2} | |
2717 | True if both @var{expr1} and @var{expr2} are true. | |
2718 | ||
2719 | @item @var{expr1} -o @var{expr2} | |
2720 | True if either @var{expr1} or @var{expr2} is true. | |
2721 | @end table | |
2722 | ||
2723 | The @code{test} and @code{[} builtins evaluate conditional | |
2724 | expressions using a set of rules based on the number of arguments. | |
2725 | ||
2726 | @table @asis | |
2727 | @item 0 arguments | |
2728 | The expression is false. | |
2729 | ||
2730 | @item 1 argument | |
2731 | The expression is true if and only if the argument is not null. | |
2732 | ||
2733 | @item 2 arguments | |
2734 | If the first argument is @samp{!}, the expression is true if and | |
2735 | only if the second argument is null. | |
2736 | If the first argument is one of the unary conditional operators | |
2737 | (@pxref{Bash Conditional Expressions}), the expression | |
2738 | is true if the unary test is true. | |
2739 | If the first argument is not a valid unary operator, the expression is | |
2740 | false. | |
2741 | ||
2742 | @item 3 arguments | |
2743 | If the second argument is one of the binary conditional | |
2744 | operators (@pxref{Bash Conditional Expressions}), the | |
2745 | result of the expression is the result of the binary test using the | |
2746 | first and third arguments as operands. | |
2747 | If the first argument is @samp{!}, the value is the negation of | |
2748 | the two-argument test using the second and third arguments. | |
2749 | If the first argument is exactly @samp{(} and the third argument is | |
2750 | exactly @samp{)}, the result is the one-argument test of the second | |
2751 | argument. | |
2752 | Otherwise, the expression is false. | |
2753 | The @samp{-a} and @samp{-o} operators are considered binary operators | |
2754 | in this case. | |
2755 | ||
2756 | @item 4 arguments | |
2757 | If the first argument is @samp{!}, the result is the negation of | |
2758 | the three-argument expression composed of the remaining arguments. | |
2759 | Otherwise, the expression is parsed and evaluated according to | |
2760 | precedence using the rules listed above. | |
2761 | ||
2762 | @item 5 or more arguments | |
2763 | The expression is parsed and evaluated according to precedence | |
2764 | using the rules listed above. | |
2765 | @end table | |
ccc6cda3 JA |
2766 | |
2767 | @item times | |
2768 | @btindex times | |
2769 | @example | |
2770 | times | |
2771 | @end example | |
2772 | Print out the user and system times used by the shell and its children. | |
cce855bc | 2773 | The return status is zero. |
ccc6cda3 JA |
2774 | |
2775 | @item trap | |
2776 | @btindex trap | |
2777 | @example | |
d166f048 | 2778 | trap [-lp] [@var{arg}] [@var{sigspec} @dots{}] |
ccc6cda3 JA |
2779 | @end example |
2780 | The commands in @var{arg} are to be read and executed when the | |
2781 | shell receives signal @var{sigspec}. If @var{arg} is absent or | |
2782 | equal to @samp{-}, all specified signals are reset to the values | |
2783 | they had when the shell was started. | |
d166f048 JA |
2784 | If @var{arg} is the null string, then the signal specified by |
2785 | each @var{sigspec} is ignored by the shell and commands it invokes. | |
28ef6c31 | 2786 | If @var{arg} is not present and @option{-p} has been supplied, |
bb70624e JA |
2787 | the shell displays the trap commands associated with each @var{sigspec}. |
2788 | If no arguments are supplied, or | |
28ef6c31 | 2789 | only @option{-p} is given, @code{trap} prints the list of commands |
cce855bc JA |
2790 | associated with each signal number in a form that may be reused as |
2791 | shell input. | |
d166f048 JA |
2792 | Each @var{sigspec} is either a signal name such as @code{SIGINT} (with |
2793 | or without the @code{SIG} prefix) or a signal number. | |
2794 | If a @var{sigspec} | |
2795 | is @code{0} or @code{EXIT}, @var{arg} is executed when the shell exits. | |
2796 | If a @var{sigspec} is @code{DEBUG}, the command @var{arg} is executed | |
ccc6cda3 | 2797 | after every simple command. |
28ef6c31 | 2798 | The @option{-l} option causes the shell to print a list of signal names |
ccc6cda3 JA |
2799 | and their corresponding numbers. |
2800 | ||
2801 | Signals ignored upon entry to the shell cannot be trapped or reset. | |
2802 | Trapped signals are reset to their original values in a child | |
2803 | process when it is created. | |
2804 | ||
cce855bc JA |
2805 | The return status is zero unless a @var{sigspec} does not specify a |
2806 | valid signal. | |
2807 | ||
ccc6cda3 JA |
2808 | @item umask |
2809 | @btindex umask | |
2810 | @example | |
cce855bc | 2811 | umask [-p] [-S] [@var{mode}] |
ccc6cda3 JA |
2812 | @end example |
2813 | Set the shell process's file creation mask to @var{mode}. If | |
2814 | @var{mode} begins with a digit, it is interpreted as an octal number; | |
2815 | if not, it is interpreted as a symbolic mode mask similar | |
2816 | to that accepted by the @code{chmod} command. If @var{mode} is | |
28ef6c31 | 2817 | omitted, the current value of the mask is printed. If the @option{-S} |
ccc6cda3 JA |
2818 | option is supplied without a @var{mode} argument, the mask is printed |
2819 | in a symbolic format. | |
28ef6c31 | 2820 | If the @option{-p} option is supplied, and @var{mode} |
cce855bc JA |
2821 | is omitted, the output is in a form that may be reused as input. |
2822 | The return status is zero if the mode is successfully changed or if | |
2823 | no @var{mode} argument is supplied, and non-zero otherwise. | |
ccc6cda3 | 2824 | |
bb70624e JA |
2825 | Note that when the mode is interpreted as an octal number, each number |
2826 | of the umask is subtracted from @code{7}. Thus, a umask of @code{022} | |
2827 | results in permissions of @code{755}. | |
2828 | ||
ccc6cda3 JA |
2829 | @item unset |
2830 | @btindex unset | |
2831 | @example | |
2832 | unset [-fv] [@var{name}] | |
2833 | @end example | |
2834 | Each variable or function @var{name} is removed. | |
28ef6c31 | 2835 | If no options are supplied, or the @option{-v} option is given, each |
ccc6cda3 | 2836 | @var{name} refers to a shell variable. |
28ef6c31 | 2837 | If the @option{-f} option is given, the @var{name}s refer to shell |
ccc6cda3 | 2838 | functions, and the function definition is removed. |
cce855bc JA |
2839 | Readonly variables and functions may not be unset. |
2840 | The return status is zero unless a @var{name} does not exist or is | |
2841 | readonly. | |
ccc6cda3 JA |
2842 | @end table |
2843 | ||
bb70624e JA |
2844 | @node Bash Builtins |
2845 | @section Bash Builtin Commands | |
ccc6cda3 | 2846 | |
bb70624e JA |
2847 | This section describes builtin commands which are unique to |
2848 | or have been extended in Bash. | |
2849 | Some of these commands are specified in the @sc{posix} 1003.2 standard. | |
ccc6cda3 | 2850 | |
bb70624e | 2851 | @table @code |
ccc6cda3 | 2852 | |
bb70624e JA |
2853 | @item alias |
2854 | @btindex alias | |
2855 | @example | |
2856 | alias [@code{-p}] [@var{name}[=@var{value}] @dots{}] | |
2857 | @end example | |
ccc6cda3 | 2858 | |
28ef6c31 | 2859 | Without arguments or with the @option{-p} option, @code{alias} prints |
bb70624e JA |
2860 | the list of aliases on the standard output in a form that allows |
2861 | them to be reused as input. | |
2862 | If arguments are supplied, an alias is defined for each @var{name} | |
2863 | whose @var{value} is given. If no @var{value} is given, the name | |
2864 | and value of the alias is printed. | |
2865 | Aliases are described in @ref{Aliases}. | |
ccc6cda3 | 2866 | |
bb70624e JA |
2867 | @item bind |
2868 | @btindex bind | |
2869 | @example | |
2870 | bind [-m @var{keymap}] [-lpsvPSV] | |
2871 | bind [-m @var{keymap}] [-q @var{function}] [-u @var{function}] [-r @var{keyseq}] | |
2872 | bind [-m @var{keymap}] -f @var{filename} | |
2873 | bind [-m @var{keymap}] -x @var{keyseq:shell-command} | |
2874 | bind [-m @var{keymap}] @var{keyseq:function-name} | |
2875 | @end example | |
ccc6cda3 | 2876 | |
bb70624e JA |
2877 | Display current Readline (@pxref{Command Line Editing}) |
2878 | key and function bindings, or | |
2879 | bind a key sequence to a Readline function or macro. The | |
2880 | binding syntax accepted is identical to that of | |
2881 | a Readline initialization file (@pxref{Readline Init File}), | |
2882 | but each binding must be passed as a separate argument: e.g., | |
2883 | @samp{"\C-x\C-r":re-read-init-file}. | |
2884 | Options, if supplied, have the following meanings: | |
cce855bc | 2885 | |
bb70624e JA |
2886 | @table @code |
2887 | @item -m @var{keymap} | |
2888 | Use @var{keymap} as the keymap to be affected by | |
2889 | the subsequent bindings. Acceptable @var{keymap} | |
2890 | names are | |
2891 | @code{emacs}, | |
2892 | @code{emacs-standard}, | |
2893 | @code{emacs-meta}, | |
2894 | @code{emacs-ctlx}, | |
2895 | @code{vi}, | |
28ef6c31 | 2896 | @code{vi-move}, |
bb70624e JA |
2897 | @code{vi-command}, and |
2898 | @code{vi-insert}. | |
2899 | @code{vi} is equivalent to @code{vi-command}; | |
2900 | @code{emacs} is equivalent to @code{emacs-standard}. | |
cce855bc | 2901 | |
bb70624e JA |
2902 | @item -l |
2903 | List the names of all Readline functions. | |
cce855bc | 2904 | |
bb70624e JA |
2905 | @item -p |
2906 | Display Readline function names and bindings in such a way that they | |
2907 | can be used as input or in a Readline initialization file. | |
cce855bc | 2908 | |
bb70624e JA |
2909 | @item -P |
2910 | List current Readline function names and bindings. | |
ccc6cda3 | 2911 | |
bb70624e JA |
2912 | @item -v |
2913 | Display Readline variable names and values in such a way that they | |
2914 | can be used as input or in a Readline initialization file. | |
ccc6cda3 | 2915 | |
bb70624e JA |
2916 | @item -V |
2917 | List current Readline variable names and values. | |
ccc6cda3 | 2918 | |
bb70624e JA |
2919 | @item -s |
2920 | Display Readline key sequences bound to macros and the strings they output | |
2921 | in such a way that they can be used as input or in a Readline | |
2922 | initialization file. | |
ccc6cda3 | 2923 | |
bb70624e JA |
2924 | @item -S |
2925 | Display Readline key sequences bound to macros and the strings they output. | |
ccc6cda3 | 2926 | |
bb70624e JA |
2927 | @item -f @var{filename} |
2928 | Read key bindings from @var{filename}. | |
ccc6cda3 | 2929 | |
bb70624e JA |
2930 | @item -q @var{function} |
2931 | Query about which keys invoke the named @var{function}. | |
ccc6cda3 | 2932 | |
bb70624e JA |
2933 | @item -u @var{function} |
2934 | Unbind all keys bound to the named @var{function}. | |
cce855bc | 2935 | |
bb70624e JA |
2936 | @item -r @var{keyseq} |
2937 | Remove any current binding for @var{keyseq}. | |
ccc6cda3 | 2938 | |
bb70624e JA |
2939 | @item -x @var{keyseq:shell-command} |
2940 | Cause @var{shell-command} to be executed whenever @var{keyseq} is | |
2941 | entered. | |
ccc6cda3 | 2942 | |
bb70624e | 2943 | @end table |
ccc6cda3 | 2944 | |
bb70624e JA |
2945 | @noindent |
2946 | The return status is zero unless an invalid option is supplied or an | |
2947 | error occurs. | |
ccc6cda3 | 2948 | |
bb70624e JA |
2949 | @item builtin |
2950 | @btindex builtin | |
2951 | @example | |
2952 | builtin [@var{shell-builtin} [@var{args}]] | |
2953 | @end example | |
2954 | Run a shell builtin, passing it @var{args}, and return its exit status. | |
2955 | This is useful when defining a shell function with the same | |
2956 | name as a shell builtin, retaining the functionality of the builtin within | |
2957 | the function. | |
2958 | The return status is non-zero if @var{shell-builtin} is not a shell | |
2959 | builtin command. | |
ccc6cda3 | 2960 | |
bb70624e JA |
2961 | @item command |
2962 | @btindex command | |
2963 | @example | |
2964 | command [-pVv] @var{command} [@var{arguments} @dots{}] | |
2965 | @end example | |
2966 | Runs @var{command} with @var{arguments} ignoring any shell function | |
2967 | named @var{command}. | |
2968 | Only shell builtin commands or commands found by searching the | |
28ef6c31 | 2969 | @env{PATH} are executed. |
bb70624e JA |
2970 | If there is a shell function named @code{ls}, running @samp{command ls} |
2971 | within the function will execute the external command @code{ls} | |
2972 | instead of calling the function recursively. | |
28ef6c31 | 2973 | The @option{-p} option means to use a default value for @env{PATH} |
bb70624e JA |
2974 | that is guaranteed to find all of the standard utilities. |
2975 | The return status in this case is 127 if @var{command} cannot be | |
2976 | found or an error occurred, and the exit status of @var{command} | |
2977 | otherwise. | |
cce855bc | 2978 | |
28ef6c31 JA |
2979 | If either the @option{-V} or @option{-v} option is supplied, a |
2980 | description of @var{command} is printed. The @option{-v} option | |
bb70624e | 2981 | causes a single word indicating the command or file name used to |
28ef6c31 | 2982 | invoke @var{command} to be displayed; the @option{-V} option produces |
bb70624e JA |
2983 | a more verbose description. In this case, the return status is |
2984 | zero if @var{command} is found, and non-zero if not. | |
cce855bc | 2985 | |
bb70624e JA |
2986 | @item declare |
2987 | @btindex declare | |
2988 | @example | |
2989 | declare [-afFrxi] [-p] [@var{name}[=@var{value}]] | |
2990 | @end example | |
ccc6cda3 | 2991 | |
bb70624e JA |
2992 | Declare variables and give them attributes. If no @var{name}s |
2993 | are given, then display the values of variables instead. | |
ccc6cda3 | 2994 | |
28ef6c31 JA |
2995 | The @option{-p} option will display the attributes and values of each |
2996 | @var{name}. When @option{-p} is used, additional options are ignored. | |
2997 | The @option{-F} option inhibits the display of function definitions; | |
2998 | only the function name and attributes are printed. @option{-F} implies | |
2999 | @option{-f}. The following options can be used to restrict output | |
bb70624e JA |
3000 | to variables with the specified attributes or to give variables |
3001 | attributes: | |
cce855bc | 3002 | |
bb70624e JA |
3003 | @table @code |
3004 | @item -a | |
3005 | Each @var{name} is an array variable (@pxref{Arrays}). | |
cce855bc | 3006 | |
bb70624e JA |
3007 | @item -f |
3008 | Use function names only. | |
ccc6cda3 | 3009 | |
bb70624e JA |
3010 | @item -i |
3011 | The variable is to be treated as | |
3012 | an integer; arithmetic evaluation (@pxref{Shell Arithmetic}) is | |
3013 | performed when the variable is assigned a value. | |
ccc6cda3 | 3014 | |
bb70624e JA |
3015 | @item -r |
3016 | Make @var{name}s readonly. These names cannot then be assigned values | |
3017 | by subsequent assignment statements or unset. | |
ccc6cda3 | 3018 | |
bb70624e JA |
3019 | @item -x |
3020 | Mark each @var{name} for export to subsequent commands via | |
3021 | the environment. | |
3022 | @end table | |
ccc6cda3 | 3023 | |
bb70624e JA |
3024 | Using @samp{+} instead of @samp{-} turns off the attribute instead. |
3025 | When used in a function, @code{declare} makes each @var{name} local, | |
3026 | as with the @code{local} command. | |
ccc6cda3 | 3027 | |
bb70624e JA |
3028 | The return status is zero unless an invalid option is encountered, |
3029 | an attempt is made to define a function using @samp{-f foo=bar}, | |
3030 | an attempt is made to assign a value to a readonly variable, | |
3031 | an attempt is made to assign a value to an array variable without | |
3032 | using the compound assignment syntax (@pxref{Arrays}), | |
3033 | one of the @var{names} is not a valid shell variable name, | |
3034 | an attempt is made to turn off readonly status for a readonly variable, | |
3035 | an attempt is made to turn off array status for an array variable, | |
28ef6c31 | 3036 | or an attempt is made to display a non-existent function with @option{-f}. |
ccc6cda3 | 3037 | |
bb70624e JA |
3038 | @item echo |
3039 | @btindex echo | |
3040 | @example | |
3041 | echo [-neE] [@var{arg} @dots{}] | |
3042 | @end example | |
3043 | Output the @var{arg}s, separated by spaces, terminated with a | |
3044 | newline. | |
3045 | The return status is always 0. | |
28ef6c31 JA |
3046 | If @option{-n} is specified, the trailing newline is suppressed. |
3047 | If the @option{-e} option is given, interpretation of the following | |
bb70624e | 3048 | backslash-escaped characters is enabled. |
28ef6c31 | 3049 | The @option{-E} option disables the interpretation of these escape characters, |
bb70624e JA |
3050 | even on systems where they are interpreted by default. |
3051 | The @code{xpg_echo} shell option may be used to | |
3052 | dynamically determine whether or not @code{echo} expands these | |
3053 | escape characters by default. | |
3054 | @code{echo} interprets the following escape sequences: | |
3055 | @table @code | |
3056 | @item \a | |
3057 | alert (bell) | |
3058 | @item \b | |
3059 | backspace | |
3060 | @item \c | |
3061 | suppress trailing newline | |
3062 | @item \e | |
3063 | escape | |
3064 | @item \f | |
3065 | form feed | |
3066 | @item \n | |
3067 | new line | |
3068 | @item \r | |
3069 | carriage return | |
3070 | @item \t | |
3071 | horizontal tab | |
3072 | @item \v | |
3073 | vertical tab | |
3074 | @item \\ | |
3075 | backslash | |
3076 | @item \@var{nnn} | |
3077 | the character whose @code{ASCII} code is the octal value @var{nnn} | |
3078 | (one to three digits) | |
3079 | @item \x@var{nnn} | |
3080 | the character whose @code{ASCII} code is the hexadecimal value @var{nnn} | |
3081 | (one to three digits) | |
3082 | @end table | |
ccc6cda3 | 3083 | |
bb70624e JA |
3084 | @item enable |
3085 | @btindex enable | |
3086 | @example | |
3087 | enable [-n] [-p] [-f @var{filename}] [-ads] [@var{name} @dots{}] | |
3088 | @end example | |
3089 | Enable and disable builtin shell commands. | |
3090 | Disabling a builtin allows a disk command which has the same name | |
3091 | as a shell builtin to be executed without specifying a full pathname, | |
3092 | even though the shell normally searches for builtins before disk commands. | |
28ef6c31 | 3093 | If @option{-n} is used, the @var{name}s become disabled. Otherwise |
bb70624e | 3094 | @var{name}s are enabled. For example, to use the @code{test} binary |
28ef6c31 | 3095 | found via @env{$PATH} instead of the shell builtin version, type |
bb70624e | 3096 | @samp{enable -n test}. |
ccc6cda3 | 3097 | |
28ef6c31 | 3098 | If the @option{-p} option is supplied, or no @var{name} arguments appear, |
bb70624e JA |
3099 | a list of shell builtins is printed. With no other arguments, the list |
3100 | consists of all enabled shell builtins. | |
28ef6c31 | 3101 | The @option{-a} option means to list |
bb70624e | 3102 | each builtin with an indication of whether or not it is enabled. |
ccc6cda3 | 3103 | |
28ef6c31 | 3104 | The @option{-f} option means to load the new builtin command @var{name} |
bb70624e | 3105 | from shared object @var{filename}, on systems that support dynamic loading. |
28ef6c31 | 3106 | The @option{-d} option will delete a builtin loaded with @option{-f}. |
ccc6cda3 | 3107 | |
bb70624e | 3108 | If there are no options, a list of the shell builtins is displayed. |
28ef6c31 JA |
3109 | The @option{-s} option restricts @code{enable} to the @sc{posix} special |
3110 | builtins. If @option{-s} is used with @option{-f}, the new builtin becomes | |
bb70624e | 3111 | a special builtin (@pxref{Special Builtins}). |
ccc6cda3 | 3112 | |
bb70624e JA |
3113 | The return status is zero unless a @var{name} is not a shell builtin |
3114 | or there is an error loading a new builtin from a shared object. | |
cce855bc | 3115 | |
bb70624e JA |
3116 | @item help |
3117 | @btindex help | |
3118 | @example | |
3119 | help [-s] [@var{pattern}] | |
3120 | @end example | |
3121 | Display helpful information about builtin commands. | |
3122 | If @var{pattern} is specified, @code{help} gives detailed help | |
3123 | on all commands matching @var{pattern}, otherwise a list of | |
3124 | the builtins is printed. | |
28ef6c31 | 3125 | The @option{-s} option restricts the information displayed to a short |
bb70624e JA |
3126 | usage synopsis. |
3127 | The return status is zero unless no command matches @var{pattern}. | |
ccc6cda3 | 3128 | |
bb70624e JA |
3129 | @item let |
3130 | @btindex let | |
3131 | @example | |
3132 | let @var{expression} [@var{expression}] | |
3133 | @end example | |
3134 | The @code{let} builtin allows arithmetic to be performed on shell | |
3135 | variables. Each @var{expression} is evaluated according to the | |
3136 | rules given below in @ref{Shell Arithmetic}. If the | |
3137 | last @var{expression} evaluates to 0, @code{let} returns 1; | |
3138 | otherwise 0 is returned. | |
ccc6cda3 | 3139 | |
bb70624e JA |
3140 | @item local |
3141 | @btindex local | |
3142 | @example | |
3143 | local [@var{option}] @var{name}[=@var{value}] | |
3144 | @end example | |
3145 | For each argument, a local variable named @var{name} is created, | |
3146 | and assigned @var{value}. | |
3147 | The @var{option} can be any of the options accepted by @code{declare}. | |
3148 | @code{local} can only be used within a function; it makes the variable | |
3149 | @var{name} have a visible scope restricted to that function and its | |
3150 | children. The return status is zero unless @code{local} is used outside | |
3151 | a function, an invalid @var{name} is supplied, or @var{name} is a | |
3152 | readonly variable. | |
ccc6cda3 | 3153 | |
bb70624e JA |
3154 | @item logout |
3155 | @btindex logout | |
3156 | @example | |
3157 | logout [@var{n}] | |
3158 | @end example | |
3159 | Exit a login shell, returning a status of @var{n} to the shell's | |
3160 | parent. | |
cce855bc | 3161 | |
bb70624e JA |
3162 | @item printf |
3163 | @btindex printf | |
3164 | @example | |
3165 | @code{printf} @var{format} [@var{arguments}] | |
3166 | @end example | |
3167 | Write the formatted @var{arguments} to the standard output under the | |
3168 | control of the @var{format}. | |
3169 | The @var{format} is a character string which contains three types of objects: | |
3170 | plain characters, which are simply copied to standard output, character | |
3171 | escape sequences, which are converted and copied to the standard output, and | |
3172 | format specifications, each of which causes printing of the next successive | |
3173 | @var{argument}. | |
3174 | In addition to the standard @code{printf(1)} formats, @samp{%b} causes | |
3175 | @code{printf} to expand backslash escape sequences in the corresponding | |
3176 | @var{argument}, and @samp{%q} causes @code{printf} to output the | |
3177 | corresponding @var{argument} in a format that can be reused as shell input. | |
cce855bc | 3178 | |
bb70624e JA |
3179 | The @var{format} is reused as necessary to consume all of the @var{arguments}. |
3180 | If the @var{format} requires more @var{arguments} than are supplied, the | |
3181 | extra format specifications behave as if a zero value or null string, as | |
3182 | appropriate, had been supplied. The return value is zero on success, | |
3183 | non-zero on failure. | |
ccc6cda3 | 3184 | |
bb70624e JA |
3185 | @item read |
3186 | @btindex read | |
3187 | @example | |
3188 | read [-ers] [-a @var{aname}] [-p @var{prompt}] [-t @var{timeout}] [-n @var{nchars}] [-d @var{delim}] [@var{name} @dots{}] | |
3189 | @end example | |
3190 | One line is read from the standard input, and the first word | |
3191 | is assigned to the first @var{name}, the second word to the second @var{name}, | |
3192 | and so on, with leftover words and their intervening separators assigned | |
3193 | to the last @var{name}. | |
3194 | If there are fewer words read from the standard input than names, | |
3195 | the remaining names are assigned empty values. | |
28ef6c31 | 3196 | The characters in the value of the @env{IFS} variable |
bb70624e JA |
3197 | are used to split the line into words. |
3198 | The backslash character @samp{\} may be used to remove any special | |
3199 | meaning for the next character read and for line continuation. | |
3200 | If no names are supplied, the line read is assigned to the | |
28ef6c31 | 3201 | variable @env{REPLY}. |
bb70624e JA |
3202 | The return code is zero, unless end-of-file is encountered or @code{read} |
3203 | times out. | |
3204 | Options, if supplied, have the following meanings: | |
ccc6cda3 | 3205 | |
bb70624e JA |
3206 | @table @code |
3207 | @item -a @var{aname} | |
3208 | The words are assigned to sequential indices of the array variable | |
3209 | @var{aname}, starting at 0. | |
3210 | All elements are removed from @var{aname} before the assignment. | |
3211 | Other @var{name} arguments are ignored. | |
ccc6cda3 | 3212 | |
bb70624e JA |
3213 | @item -d @var{delim} |
3214 | The first character of @var{delim} is used to terminate the input line, | |
3215 | rather than newline. | |
ccc6cda3 | 3216 | |
bb70624e JA |
3217 | @item -e |
3218 | Readline (@pxref{Command Line Editing}) is used to obtain the line. | |
ccc6cda3 | 3219 | |
bb70624e JA |
3220 | @item -n @var{nchars} |
3221 | @code{read} returns after reading @var{nchars} characters rather than | |
3222 | waiting for a complete line of input. | |
ccc6cda3 | 3223 | |
bb70624e JA |
3224 | @item -p @var{prompt} |
3225 | Display @var{prompt}, without a trailing newline, before attempting | |
3226 | to read any input. | |
3227 | The prompt is displayed only if input is coming from a terminal. | |
ccc6cda3 | 3228 | |
bb70624e JA |
3229 | @item -r |
3230 | If this option is given, backslash does not act as an escape character. | |
3231 | The backslash is considered to be part of the line. | |
3232 | In particular, a backslash-newline pair may not be used as a line | |
3233 | continuation. | |
ccc6cda3 | 3234 | |
bb70624e JA |
3235 | @item -s |
3236 | Silent mode. If input is coming from a terminal, characters are | |
3237 | not echoed. | |
ccc6cda3 | 3238 | |
bb70624e JA |
3239 | @item -t @var{timeout} |
3240 | Cause @code{read} to time out and return failure if a complete line of | |
3241 | input is not read within @var{timeout} seconds. | |
3242 | This option has no effect if @code{read} is not reading input from the | |
3243 | terminal or a pipe. | |
ccc6cda3 | 3244 | |
bb70624e | 3245 | @end table |
ccc6cda3 | 3246 | |
bb70624e JA |
3247 | @item shopt |
3248 | @btindex shopt | |
3249 | @example | |
3250 | shopt [-pqsu] [-o] [@var{optname} @dots{}] | |
3251 | @end example | |
3252 | Toggle the values of variables controlling optional shell behavior. | |
28ef6c31 | 3253 | With no options, or with the @option{-p} option, a list of all settable |
bb70624e | 3254 | options is displayed, with an indication of whether or not each is set. |
28ef6c31 | 3255 | The @option{-p} option causes output to be displayed in a form that |
bb70624e JA |
3256 | may be reused as input. |
3257 | Other options have the following meanings: | |
cce855bc | 3258 | |
bb70624e JA |
3259 | @table @code |
3260 | @item -s | |
3261 | Enable (set) each @var{optname}. | |
cce855bc | 3262 | |
bb70624e JA |
3263 | @item -u |
3264 | Disable (unset) each @var{optname}. | |
ccc6cda3 | 3265 | |
bb70624e JA |
3266 | @item -q |
3267 | Suppresses normal output; the return status | |
3268 | indicates whether the @var{optname} is set or unset. | |
28ef6c31 | 3269 | If multiple @var{optname} arguments are given with @option{-q}, |
bb70624e JA |
3270 | the return status is zero if all @var{optnames} are enabled; |
3271 | non-zero otherwise. | |
ccc6cda3 | 3272 | |
bb70624e JA |
3273 | @item -o |
3274 | Restricts the values of | |
28ef6c31 | 3275 | @var{optname} to be those defined for the @option{-o} option to the |
bb70624e JA |
3276 | @code{set} builtin (@pxref{The Set Builtin}). |
3277 | @end table | |
cce855bc | 3278 | |
28ef6c31 | 3279 | If either @option{-s} or @option{-u} |
bb70624e JA |
3280 | is used with no @var{optname} arguments, the display is limited to |
3281 | those options which are set or unset, respectively. | |
ccc6cda3 | 3282 | |
bb70624e JA |
3283 | Unless otherwise noted, the @code{shopt} options are disabled (off) |
3284 | by default. | |
cce855bc | 3285 | |
bb70624e JA |
3286 | The return status when listing options is zero if all @var{optnames} |
3287 | are enabled, non-zero otherwise. When setting or unsetting options, | |
3288 | the return status is zero unless an @var{optname} is not a valid shell | |
3289 | option. | |
ccc6cda3 | 3290 | |
bb70624e JA |
3291 | The list of @code{shopt} options is: |
3292 | @table @code | |
3293 | @item cdable_vars | |
3294 | If this is set, an argument to the @code{cd} | |
3295 | builtin command that | |
3296 | is not a directory is assumed to be the name of a variable whose | |
3297 | value is the directory to change to. | |
ccc6cda3 | 3298 | |
bb70624e JA |
3299 | @item cdspell |
3300 | If set, minor errors in the spelling of a directory component in a | |
3301 | @code{cd} command will be corrected. | |
3302 | The errors checked for are transposed characters, | |
3303 | a missing character, and a character too many. | |
3304 | If a correction is found, the corrected path is printed, | |
3305 | and the command proceeds. | |
3306 | This option is only used by interactive shells. | |
ccc6cda3 | 3307 | |
bb70624e JA |
3308 | @item checkhash |
3309 | If this is set, Bash checks that a command found in the hash | |
3310 | table exists before trying to execute it. If a hashed command no | |
3311 | longer exists, a normal path search is performed. | |
ccc6cda3 | 3312 | |
bb70624e JA |
3313 | @item checkwinsize |
3314 | If set, Bash checks the window size after each command | |
3315 | and, if necessary, updates the values of | |
28ef6c31 | 3316 | @env{LINES} and @env{COLUMNS}. |
ccc6cda3 | 3317 | |
bb70624e JA |
3318 | @item cmdhist |
3319 | If set, Bash | |
3320 | attempts to save all lines of a multiple-line | |
3321 | command in the same history entry. This allows | |
3322 | easy re-editing of multi-line commands. | |
cce855bc | 3323 | |
bb70624e JA |
3324 | @item dotglob |
3325 | If set, Bash includes filenames beginning with a `.' in | |
3326 | the results of filename expansion. | |
ccc6cda3 | 3327 | |
bb70624e JA |
3328 | @item execfail |
3329 | If this is set, a non-interactive shell will not exit if | |
3330 | it cannot execute the file specified as an argument to the @code{exec} | |
3331 | builtin command. An interactive shell does not exit if @code{exec} | |
3332 | fails. | |
cce855bc | 3333 | |
bb70624e JA |
3334 | @item expand_aliases |
3335 | If set, aliases are expanded as described below under Aliases, | |
3336 | @ref{Aliases}. | |
3337 | This option is enabled by default for interactive shells. | |
ccc6cda3 | 3338 | |
bb70624e JA |
3339 | @item extglob |
3340 | If set, the extended pattern matching features described above | |
3341 | (@pxref{Pattern Matching}) are enabled. | |
ccc6cda3 | 3342 | |
bb70624e JA |
3343 | @item histappend |
3344 | If set, the history list is appended to the file named by the value | |
28ef6c31 | 3345 | of the @env{HISTFILE} |
bb70624e | 3346 | variable when the shell exits, rather than overwriting the file. |
ccc6cda3 | 3347 | |
bb70624e JA |
3348 | @item histreedit |
3349 | If set, and Readline | |
3350 | is being used, a user is given the opportunity to re-edit a | |
3351 | failed history substitution. | |
ccc6cda3 | 3352 | |
bb70624e JA |
3353 | @item histverify |
3354 | If set, and Readline | |
3355 | is being used, the results of history substitution are not immediately | |
3356 | passed to the shell parser. Instead, the resulting line is loaded into | |
3357 | the Readline editing buffer, allowing further modification. | |
ccc6cda3 | 3358 | |
bb70624e JA |
3359 | @item hostcomplete |
3360 | If set, and Readline is being used, Bash will attempt to perform | |
3361 | hostname completion when a word containing a @samp{@@} is being | |
3362 | completed (@pxref{Commands For Completion}). This option is enabled | |
3363 | by default. | |
ccc6cda3 | 3364 | |
bb70624e JA |
3365 | @item huponexit |
3366 | If set, Bash will send @code{SIGHUP} to all jobs when an interactive | |
3367 | login shell exits (@pxref{Signals}). | |
cce855bc | 3368 | |
bb70624e JA |
3369 | @item interactive_comments |
3370 | Allow a word beginning with @samp{#} | |
3371 | to cause that word and all remaining characters on that | |
3372 | line to be ignored in an interactive shell. | |
3373 | This option is enabled by default. | |
ccc6cda3 | 3374 | |
bb70624e JA |
3375 | @item lithist |
3376 | If enabled, and the @code{cmdhist} | |
3377 | option is enabled, multi-line commands are saved to the history with | |
3378 | embedded newlines rather than using semicolon separators where possible. | |
ccc6cda3 | 3379 | |
bb70624e JA |
3380 | @item mailwarn |
3381 | If set, and a file that Bash is checking for mail has been | |
3382 | accessed since the last time it was checked, the message | |
3383 | @code{"The mail in @var{mailfile} has been read"} is displayed. | |
ccc6cda3 | 3384 | |
bb70624e JA |
3385 | @item no_empty_cmd_completion |
3386 | If set, and Readline is being used, Bash will not attempt to search | |
28ef6c31 | 3387 | the @env{PATH} for possible completions when completion is attempted |
bb70624e | 3388 | on an empty line. |
ccc6cda3 | 3389 | |
bb70624e JA |
3390 | @item nocaseglob |
3391 | If set, Bash matches filenames in a case-insensitive fashion when | |
3392 | performing filename expansion. | |
ccc6cda3 | 3393 | |
bb70624e JA |
3394 | @item nullglob |
3395 | If set, Bash allows filename patterns which match no | |
3396 | files to expand to a null string, rather than themselves. | |
ccc6cda3 | 3397 | |
bb70624e JA |
3398 | @item progcomp |
3399 | If set, the programmable completion facilities | |
3400 | (@pxref{Programmable Completion}) are enabled. | |
3401 | This option is enabled by default. | |
ccc6cda3 | 3402 | |
bb70624e JA |
3403 | @item promptvars |
3404 | If set, prompt strings undergo variable and parameter expansion after | |
3405 | being expanded (@pxref{Printing a Prompt}). | |
3406 | This option is enabled by default. | |
ccc6cda3 | 3407 | |
bb70624e JA |
3408 | @item restricted_shell |
3409 | The shell sets this option if it is started in restricted mode | |
3410 | (@pxref{The Restricted Shell}). | |
3411 | The value may not be changed. | |
3412 | This is not reset when the startup files are executed, allowing | |
3413 | the startup files to discover whether or not a shell is restricted. | |
ccc6cda3 | 3414 | |
bb70624e JA |
3415 | @item shift_verbose |
3416 | If this is set, the @code{shift} | |
3417 | builtin prints an error message when the shift count exceeds the | |
3418 | number of positional parameters. | |
ccc6cda3 | 3419 | |
bb70624e | 3420 | @item sourcepath |
28ef6c31 | 3421 | If set, the @code{source} builtin uses the value of @env{PATH} |
bb70624e JA |
3422 | to find the directory containing the file supplied as an argument. |
3423 | This option is enabled by default. | |
ccc6cda3 | 3424 | |
bb70624e JA |
3425 | @item xpg_echo |
3426 | If set, the @code{echo} builtin expands backslash-escape sequences | |
3427 | by default. | |
ccc6cda3 | 3428 | |
bb70624e | 3429 | @end table |
ccc6cda3 | 3430 | |
bb70624e JA |
3431 | @noindent |
3432 | The return status when listing options is zero if all @var{optnames} | |
3433 | are enabled, non-zero otherwise. | |
3434 | When setting or unsetting options, the return status is zero unless an | |
3435 | @var{optname} is not a valid shell option. | |
ccc6cda3 | 3436 | |
bb70624e JA |
3437 | @item source |
3438 | @btindex source | |
3439 | @example | |
3440 | source @var{filename} | |
3441 | @end example | |
3442 | A synonym for @code{.} (@pxref{Bourne Shell Builtins}). | |
ccc6cda3 | 3443 | |
bb70624e JA |
3444 | @item type |
3445 | @btindex type | |
3446 | @example | |
3447 | type [-atp] [@var{name} @dots{}] | |
3448 | @end example | |
3449 | For each @var{name}, indicate how it would be interpreted if used as a | |
3450 | command name. | |
ccc6cda3 | 3451 | |
28ef6c31 | 3452 | If the @option{-t} option is used, @code{type} prints a single word |
bb70624e JA |
3453 | which is one of @samp{alias}, @samp{function}, @samp{builtin}, |
3454 | @samp{file} or @samp{keyword}, | |
3455 | if @var{name} is an alias, shell function, shell builtin, | |
3456 | disk file, or shell reserved word, respectively. | |
3457 | If the @var{name} is not found, then nothing is printed, and | |
3458 | @code{type} returns a failure status. | |
ccc6cda3 | 3459 | |
28ef6c31 JA |
3460 | If the @option{-p} option is used, @code{type} either returns the name |
3461 | of the disk file that would be executed, or nothing if @option{-t} | |
bb70624e JA |
3462 | would not return @samp{file}. |
3463 | ||
28ef6c31 | 3464 | If the @option{-a} option is used, @code{type} returns all of the places |
bb70624e | 3465 | that contain an executable named @var{file}. |
28ef6c31 | 3466 | This includes aliases and functions, if and only if the @option{-p} option |
bb70624e JA |
3467 | is not also used. |
3468 | ||
3469 | The return status is zero if any of the @var{names} are found, non-zero | |
3470 | if none are found. | |
ccc6cda3 | 3471 | |
bb70624e JA |
3472 | @item typeset |
3473 | @btindex typeset | |
ccc6cda3 | 3474 | @example |
bb70624e | 3475 | typeset [-afFrxi] [-p] [@var{name}[=@var{value}]] |
ccc6cda3 | 3476 | @end example |
bb70624e JA |
3477 | The @code{typeset} command is supplied for compatibility with the Korn |
3478 | shell; however, it has been deprecated in favor of the @code{declare} | |
3479 | builtin command. | |
ccc6cda3 | 3480 | |
bb70624e JA |
3481 | @item ulimit |
3482 | @btindex ulimit | |
3483 | @example | |
3484 | ulimit [-acdflmnpstuvSH] [@var{limit}] | |
3485 | @end example | |
3486 | @code{ulimit} provides control over the resources available to processes | |
3487 | started by the shell, on systems that allow such control. If an | |
3488 | option is given, it is interpreted as follows: | |
ccc6cda3 | 3489 | @table @code |
bb70624e JA |
3490 | @item -S |
3491 | Change and report the soft limit associated with a resource. | |
ccc6cda3 | 3492 | |
bb70624e JA |
3493 | @item -H |
3494 | Change and report the hard limit associated with a resource. | |
ccc6cda3 | 3495 | |
bb70624e JA |
3496 | @item -a |
3497 | All current limits are reported. | |
ccc6cda3 | 3498 | |
bb70624e JA |
3499 | @item -c |
3500 | The maximum size of core files created. | |
ccc6cda3 | 3501 | |
bb70624e JA |
3502 | @item -d |
3503 | The maximum size of a process's data segment. | |
ccc6cda3 | 3504 | |
bb70624e JA |
3505 | @item -f |
3506 | The maximum size of files created by the shell. | |
ccc6cda3 | 3507 | |
bb70624e JA |
3508 | @item -l |
3509 | The maximum size that may be locked into memory. | |
ccc6cda3 | 3510 | |
bb70624e JA |
3511 | @item -m |
3512 | The maximum resident set size. | |
ccc6cda3 | 3513 | |
bb70624e JA |
3514 | @item -n |
3515 | The maximum number of open file descriptors. | |
ccc6cda3 | 3516 | |
bb70624e JA |
3517 | @item -p |
3518 | The pipe buffer size. | |
ccc6cda3 | 3519 | |
bb70624e JA |
3520 | @item -s |
3521 | The maximum stack size. | |
ccc6cda3 | 3522 | |
bb70624e JA |
3523 | @item -t |
3524 | The maximum amount of cpu time in seconds. | |
ccc6cda3 | 3525 | |
bb70624e JA |
3526 | @item -u |
3527 | The maximum number of processes available to a single user. | |
ccc6cda3 | 3528 | |
bb70624e JA |
3529 | @item -v |
3530 | The maximum amount of virtual memory available to the process. | |
ccc6cda3 | 3531 | |
bb70624e | 3532 | @end table |
ccc6cda3 | 3533 | |
bb70624e JA |
3534 | If @var{limit} is given, it is the new value of the specified resource. |
3535 | Otherwise, the current value of the soft limit for the specified resource | |
28ef6c31 JA |
3536 | is printed, unless the @option{-H} option is supplied. |
3537 | When setting new limits, if neither @option{-H} nor @option{-S} is supplied, | |
bb70624e | 3538 | both the hard and soft limits are set. |
28ef6c31 JA |
3539 | If no option is given, then @option{-f} is assumed. Values are in 1024-byte |
3540 | increments, except for @option{-t}, which is in seconds, @option{-p}, | |
3541 | which is in units of 512-byte blocks, and @option{-n} and @option{-u}, which | |
bb70624e | 3542 | are unscaled values. |
ccc6cda3 | 3543 | |
bb70624e JA |
3544 | The return status is zero unless an invalid option is supplied, a |
3545 | non-numeric argument other than @code{unlimited} is supplied as a | |
3546 | @var{limit}, or an error occurs while setting a new limit. | |
ccc6cda3 | 3547 | |
bb70624e JA |
3548 | @item unalias |
3549 | @btindex unalias | |
3550 | @example | |
3551 | unalias [-a] [@var{name} @dots{} ] | |
3552 | @end example | |
ccc6cda3 | 3553 | |
28ef6c31 | 3554 | Remove each @var{name} from the list of aliases. If @option{-a} is |
bb70624e JA |
3555 | supplied, all aliases are removed. |
3556 | Aliases are described in @ref{Aliases}. | |
cce855bc | 3557 | |
ccc6cda3 JA |
3558 | @end table |
3559 | ||
bb70624e JA |
3560 | @node The Set Builtin |
3561 | @section The Set Builtin | |
ccc6cda3 | 3562 | |
bb70624e | 3563 | This builtin is so complicated that it deserves its own section. |
ccc6cda3 | 3564 | |
bb70624e JA |
3565 | @table @code |
3566 | @item set | |
3567 | @btindex set | |
3568 | @example | |
3569 | set [--abefhkmnptuvxBCHP] [-o @var{option}] [@var{argument} @dots{}] | |
3570 | @end example | |
ccc6cda3 | 3571 | |
bb70624e JA |
3572 | If no options or arguments are supplied, @code{set} displays the names |
3573 | and values of all shell variables and functions, sorted according to the | |
3574 | current locale, in a format that may be reused as input. | |
ccc6cda3 | 3575 | |
bb70624e JA |
3576 | When options are supplied, they set or unset shell attributes. |
3577 | Options, if specified, have the following meanings: | |
ccc6cda3 | 3578 | |
bb70624e JA |
3579 | @table @code |
3580 | @item -a | |
28ef6c31 JA |
3581 | Mark variables and function which are modified or created for export |
3582 | to the environment of subsequent commands. | |
ccc6cda3 | 3583 | |
bb70624e JA |
3584 | @item -b |
3585 | Cause the status of terminated background jobs to be reported | |
3586 | immediately, rather than before printing the next primary prompt. | |
ccc6cda3 | 3587 | |
bb70624e JA |
3588 | @item -e |
3589 | Exit immediately if a simple command (@pxref{Simple Commands}) exits | |
3590 | with a non-zero status, unless the command that fails is part of an | |
3591 | @code{until} or @code{while} loop, part of an @code{if} statement, | |
3592 | part of a @code{&&} or @code{||} list, or if the command's return | |
3593 | status is being inverted using @code{!}. | |
ccc6cda3 | 3594 | |
bb70624e JA |
3595 | @item -f |
3596 | Disable file name generation (globbing). | |
ccc6cda3 | 3597 | |
bb70624e JA |
3598 | @item -h |
3599 | Locate and remember (hash) commands as they are looked up for execution. | |
3600 | This option is enabled by default. | |
ccc6cda3 | 3601 | |
bb70624e JA |
3602 | @item -k |
3603 | All arguments in the form of assignment statements are placed | |
3604 | in the environment for a command, not just those that precede | |
3605 | the command name. | |
ccc6cda3 | 3606 | |
bb70624e JA |
3607 | @item -m |
3608 | Job control is enabled (@pxref{Job Control}). | |
ccc6cda3 | 3609 | |
bb70624e JA |
3610 | @item -n |
3611 | Read commands but do not execute them; this may be used to check a | |
3612 | script for syntax errors. | |
3613 | This option is ignored by interactive shells. | |
b72432fd | 3614 | |
bb70624e | 3615 | @item -o @var{option-name} |
ccc6cda3 | 3616 | |
bb70624e | 3617 | Set the option corresponding to @var{option-name}: |
ccc6cda3 | 3618 | |
bb70624e JA |
3619 | @table @code |
3620 | @item allexport | |
3621 | Same as @code{-a}. | |
ccc6cda3 | 3622 | |
bb70624e JA |
3623 | @item braceexpand |
3624 | Same as @code{-B}. | |
ccc6cda3 | 3625 | |
bb70624e JA |
3626 | @item emacs |
3627 | Use an @code{emacs}-style line editing interface (@pxref{Command Line Editing}). | |
d166f048 | 3628 | |
bb70624e JA |
3629 | @item errexit |
3630 | Same as @code{-e}. | |
d166f048 | 3631 | |
bb70624e JA |
3632 | @item hashall |
3633 | Same as @code{-h}. | |
ccc6cda3 | 3634 | |
bb70624e JA |
3635 | @item histexpand |
3636 | Same as @code{-H}. | |
ccc6cda3 | 3637 | |
bb70624e JA |
3638 | @item history |
3639 | Enable command history, as described in @ref{Bash History Facilities}. | |
3640 | This option is on by default in interactive shells. | |
ccc6cda3 | 3641 | |
bb70624e JA |
3642 | @item ignoreeof |
3643 | An interactive shell will not exit upon reading EOF. | |
ccc6cda3 | 3644 | |
bb70624e JA |
3645 | @item keyword |
3646 | Same as @code{-k}. | |
ccc6cda3 | 3647 | |
bb70624e JA |
3648 | @item monitor |
3649 | Same as @code{-m}. | |
ccc6cda3 | 3650 | |
bb70624e JA |
3651 | @item noclobber |
3652 | Same as @code{-C}. | |
ccc6cda3 | 3653 | |
bb70624e JA |
3654 | @item noexec |
3655 | Same as @code{-n}. | |
ccc6cda3 | 3656 | |
bb70624e JA |
3657 | @item noglob |
3658 | Same as @code{-f}. | |
ccc6cda3 | 3659 | |
bb70624e JA |
3660 | @item notify |
3661 | Same as @code{-b}. | |
ccc6cda3 | 3662 | |
bb70624e JA |
3663 | @item nounset |
3664 | Same as @code{-u}. | |
ccc6cda3 | 3665 | |
bb70624e JA |
3666 | @item onecmd |
3667 | Same as @code{-t}. | |
ccc6cda3 | 3668 | |
bb70624e JA |
3669 | @item physical |
3670 | Same as @code{-P}. | |
ccc6cda3 | 3671 | |
bb70624e JA |
3672 | @item posix |
3673 | Change the behavior of Bash where the default operation differs | |
3674 | from the @sc{posix} 1003.2 standard to match the standard | |
3675 | (@pxref{Bash POSIX Mode}). | |
3676 | This is intended to make Bash behave as a strict superset of that | |
3677 | standard. | |
ccc6cda3 | 3678 | |
bb70624e JA |
3679 | @item privileged |
3680 | Same as @code{-p}. | |
cce855bc | 3681 | |
bb70624e JA |
3682 | @item verbose |
3683 | Same as @code{-v}. | |
ccc6cda3 | 3684 | |
bb70624e JA |
3685 | @item vi |
3686 | Use a @code{vi}-style line editing interface. | |
ccc6cda3 | 3687 | |
bb70624e JA |
3688 | @item xtrace |
3689 | Same as @code{-x}. | |
ccc6cda3 JA |
3690 | @end table |
3691 | ||
bb70624e JA |
3692 | @item -p |
3693 | Turn on privileged mode. | |
28ef6c31 | 3694 | In this mode, the @env{$BASH_ENV} and @env{$ENV} files are not |
bb70624e | 3695 | processed, shell functions are not inherited from the environment, |
28ef6c31 | 3696 | and the @env{SHELLOPTS} variable, if it appears in the environment, |
bb70624e JA |
3697 | is ignored. |
3698 | If the shell is started with the effective user (group) id not equal to the | |
3699 | real user (group) id, and the @code{-p} option is not supplied, these actions | |
3700 | are taken and the effective user id is set to the real user id. | |
3701 | If the @code{-p} option is supplied at startup, the effective user id is | |
3702 | not reset. | |
3703 | Turning this option off causes the effective user | |
3704 | and group ids to be set to the real user and group ids. | |
cce855bc | 3705 | |
bb70624e JA |
3706 | @item -t |
3707 | Exit after reading and executing one command. | |
ccc6cda3 | 3708 | |
bb70624e JA |
3709 | @item -u |
3710 | Treat unset variables as an error when performing parameter expansion. | |
3711 | An error message will be written to the standard error, and a non-interactive | |
3712 | shell will exit. | |
ccc6cda3 | 3713 | |
bb70624e JA |
3714 | @item -v |
3715 | Print shell input lines as they are read. | |
ccc6cda3 | 3716 | |
bb70624e JA |
3717 | @item -x |
3718 | Print a trace of simple commands and their arguments after they are | |
3719 | expanded and before they are executed. | |
ccc6cda3 | 3720 | |
bb70624e JA |
3721 | @item -B |
3722 | The shell will perform brace expansion (@pxref{Brace Expansion}). | |
3723 | This option is on by default. | |
ccc6cda3 | 3724 | |
bb70624e JA |
3725 | @item -C |
3726 | Prevent output redirection using @samp{>}, @samp{>&}, and @samp{<>} | |
3727 | from overwriting existing files. | |
ccc6cda3 | 3728 | |
bb70624e JA |
3729 | @item -H |
3730 | Enable @samp{!} style history substitution (@pxref{History Interaction}). | |
3731 | This option is on by default for interactive shells. | |
ccc6cda3 | 3732 | |
bb70624e JA |
3733 | @item -P |
3734 | If set, do not follow symbolic links when performing commands such as | |
3735 | @code{cd} which change the current directory. The physical directory | |
3736 | is used instead. By default, Bash follows | |
3737 | the logical chain of directories when performing commands | |
3738 | which change the current directory. | |
ccc6cda3 | 3739 | |
bb70624e JA |
3740 | For example, if @file{/usr/sys} is a symbolic link to @file{/usr/local/sys} |
3741 | then: | |
3742 | @example | |
3743 | $ cd /usr/sys; echo $PWD | |
3744 | /usr/sys | |
3745 | $ cd ..; pwd | |
3746 | /usr | |
3747 | @end example | |
ccc6cda3 | 3748 | |
bb70624e JA |
3749 | @noindent |
3750 | If @code{set -P} is on, then: | |
3751 | @example | |
3752 | $ cd /usr/sys; echo $PWD | |
3753 | /usr/local/sys | |
3754 | $ cd ..; pwd | |
3755 | /usr/local | |
3756 | @end example | |
ccc6cda3 | 3757 | |
bb70624e JA |
3758 | @item -- |
3759 | If no arguments follow this option, then the positional parameters are | |
3760 | unset. Otherwise, the positional parameters are set to the | |
3761 | @var{arguments}, even if some of them begin with a @samp{-}. | |
3762 | ||
3763 | @item - | |
3764 | Signal the end of options, cause all remaining @var{arguments} | |
28ef6c31 JA |
3765 | to be assigned to the positional parameters. The @option{-x} |
3766 | and @option{-v} options are turned off. | |
bb70624e | 3767 | If there are no arguments, the positional parameters remain unchanged. |
ccc6cda3 JA |
3768 | @end table |
3769 | ||
bb70624e JA |
3770 | Using @samp{+} rather than @samp{-} causes these options to be |
3771 | turned off. The options can also be used upon invocation of the | |
3772 | shell. The current set of options may be found in @code{$-}. | |
cce855bc | 3773 | |
bb70624e JA |
3774 | The remaining N @var{arguments} are positional parameters and are |
3775 | assigned, in order, to @code{$1}, @code{$2}, @dots{} @code{$N}. | |
3776 | The special parameter @code{#} is set to N. | |
ccc6cda3 | 3777 | |
bb70624e | 3778 | The return status is always zero unless an invalid option is supplied. |
ccc6cda3 JA |
3779 | @end table |
3780 | ||
bb70624e JA |
3781 | @node Special Builtins |
3782 | @section Special Builtins | |
3783 | @cindex special builtin | |
cce855bc | 3784 | |
bb70624e JA |
3785 | For historical reasons, the @sc{posix} 1003.2 standard has classified |
3786 | several builtin commands as @emph{special}. | |
3787 | When Bash is executing in @sc{posix} mode, the special builtins | |
3788 | differ from other builtin commands in three respects: | |
ccc6cda3 | 3789 | |
bb70624e JA |
3790 | @enumerate |
3791 | @item | |
3792 | Special builtins are found before shell functions during command lookup. | |
cce855bc | 3793 | |
bb70624e JA |
3794 | @item |
3795 | If a special builtin returns an error status, a non-interactive shell exits. | |
cce855bc | 3796 | |
bb70624e JA |
3797 | @item |
3798 | Assignment statements preceding the command stay in effect in the shell | |
3799 | environment after the command completes. | |
3800 | @end enumerate | |
ccc6cda3 | 3801 | |
bb70624e JA |
3802 | When Bash is not executing in @sc{posix} mode, these builtins behave no |
3803 | differently than the rest of the Bash builtin commands. | |
3804 | The Bash @sc{posix} mode is described in @ref{Bash POSIX Mode}. | |
ccc6cda3 | 3805 | |
bb70624e | 3806 | These are the @sc{posix} special builtins: |
ccc6cda3 | 3807 | @example |
bb70624e JA |
3808 | @w{break : . continue eval exec exit export readonly return set} |
3809 | @w{shift trap unset} | |
ccc6cda3 | 3810 | @end example |
ccc6cda3 | 3811 | |
bb70624e JA |
3812 | @node Shell Variables |
3813 | @chapter Shell Variables | |
cce855bc | 3814 | |
bb70624e JA |
3815 | @menu |
3816 | * Bourne Shell Variables:: Variables which Bash uses in the same way | |
3817 | as the Bourne Shell. | |
3818 | * Bash Variables:: List of variables that exist in Bash. | |
3819 | @end menu | |
cce855bc | 3820 | |
bb70624e JA |
3821 | This chapter describes the shell variables that Bash uses. |
3822 | Bash automatically assigns default values to a number of variables. | |
ccc6cda3 | 3823 | |
bb70624e JA |
3824 | @node Bourne Shell Variables |
3825 | @section Bourne Shell Variables | |
ccc6cda3 | 3826 | |
bb70624e JA |
3827 | Bash uses certain shell variables in the same way as the Bourne shell. |
3828 | In some cases, Bash assigns a default value to the variable. | |
ccc6cda3 | 3829 | |
bb70624e | 3830 | @vtable @code |
ccc6cda3 | 3831 | |
bb70624e JA |
3832 | @item CDPATH |
3833 | A colon-separated list of directories used as a search path for | |
3834 | the @code{cd} builtin command. | |
ccc6cda3 | 3835 | |
bb70624e JA |
3836 | @item HOME |
3837 | The current user's home directory; the default for the @code{cd} builtin | |
3838 | command. | |
3839 | The value of this variable is also used by tilde expansion | |
3840 | (@pxref{Tilde Expansion}). | |
ccc6cda3 | 3841 | |
bb70624e JA |
3842 | @item IFS |
3843 | A list of characters that separate fields; used when the shell splits | |
3844 | words as part of expansion. | |
ccc6cda3 | 3845 | |
bb70624e | 3846 | @item MAIL |
28ef6c31 | 3847 | If this parameter is set to a filename and the @env{MAILPATH} variable |
bb70624e JA |
3848 | is not set, Bash informs the user of the arrival of mail in |
3849 | the specified file. | |
ccc6cda3 | 3850 | |
bb70624e JA |
3851 | @item MAILPATH |
3852 | A colon-separated list of filenames which the shell periodically checks | |
3853 | for new mail. | |
3854 | Each list entry can specify the message that is printed when new mail | |
3855 | arrives in the mail file by separating the file name from the message with | |
3856 | a @samp{?}. | |
3857 | When used in the text of the message, @code{$_} expands to the name of | |
3858 | the current mail file. | |
ccc6cda3 | 3859 | |
bb70624e JA |
3860 | @item OPTARG |
3861 | The value of the last option argument processed by the @code{getopts} builtin. | |
ccc6cda3 | 3862 | |
bb70624e JA |
3863 | @item OPTIND |
3864 | The index of the last option argument processed by the @code{getopts} builtin. | |
ccc6cda3 | 3865 | |
bb70624e JA |
3866 | @item PATH |
3867 | A colon-separated list of directories in which the shell looks for | |
3868 | commands. | |
ccc6cda3 | 3869 | |
bb70624e JA |
3870 | @item PS1 |
3871 | The primary prompt string. The default value is @samp{\s-\v\$ }. | |
3872 | @xref{Printing a Prompt}, for the complete list of escape | |
28ef6c31 | 3873 | sequences that are expanded before @env{PS1} is displayed. |
ccc6cda3 | 3874 | |
bb70624e JA |
3875 | @item PS2 |
3876 | The secondary prompt string. The default value is @samp{> }. | |
ccc6cda3 | 3877 | |
bb70624e | 3878 | @end vtable |
ccc6cda3 | 3879 | |
bb70624e JA |
3880 | @node Bash Variables |
3881 | @section Bash Variables | |
ccc6cda3 | 3882 | |
bb70624e JA |
3883 | These variables are set or used by Bash, but other shells |
3884 | do not normally treat them specially. | |
ccc6cda3 | 3885 | |
bb70624e JA |
3886 | A few variables used by Bash are described in different chapters: |
3887 | variables for controlling the job control facilities | |
3888 | (@pxref{Job Control Variables}). | |
ccc6cda3 | 3889 | |
bb70624e | 3890 | @vtable @code |
cce855bc | 3891 | |
bb70624e JA |
3892 | @item BASH |
3893 | The full pathname used to execute the current instance of Bash. | |
cce855bc | 3894 | |
bb70624e JA |
3895 | @item BASH_ENV |
3896 | If this variable is set when Bash is invoked to execute a shell | |
3897 | script, its value is expanded and used as the name of a startup file | |
3898 | to read before executing the script. @xref{Bash Startup Files}. | |
ccc6cda3 | 3899 | |
bb70624e JA |
3900 | @item BASH_VERSION |
3901 | The version number of the current instance of Bash. | |
ccc6cda3 | 3902 | |
bb70624e JA |
3903 | @item BASH_VERSINFO |
3904 | A readonly array variable (@pxref{Arrays}) | |
3905 | whose members hold version information for this instance of Bash. | |
3906 | The values assigned to the array members are as follows: | |
ccc6cda3 | 3907 | |
bb70624e | 3908 | @table @code |
ccc6cda3 | 3909 | |
bb70624e JA |
3910 | @item BASH_VERSINFO[0] |
3911 | The major version number (the @var{release}). | |
cce855bc | 3912 | |
bb70624e JA |
3913 | @item BASH_VERSINFO[1] |
3914 | The minor version number (the @var{version}). | |
ccc6cda3 | 3915 | |
bb70624e JA |
3916 | @item BASH_VERSINFO[2] |
3917 | The patch level. | |
ccc6cda3 | 3918 | |
bb70624e JA |
3919 | @item BASH_VERSINFO[3] |
3920 | The build version. | |
ccc6cda3 | 3921 | |
bb70624e JA |
3922 | @item BASH_VERSINFO[4] |
3923 | The release status (e.g., @var{beta1}). | |
cce855bc | 3924 | |
bb70624e | 3925 | @item BASH_VERSINFO[5] |
28ef6c31 | 3926 | The value of @env{MACHTYPE}. |
ccc6cda3 | 3927 | |
bb70624e | 3928 | @end table |
ccc6cda3 | 3929 | |
bb70624e JA |
3930 | @item COMP_WORDS |
3931 | An array variable consisting of the individual | |
3932 | words in the current command line. | |
3933 | This variable is available only in shell functions invoked by the | |
3934 | programmable completion facilities (@pxref{Programmable Completion}). | |
3935 | ||
3936 | @item COMP_CWORD | |
28ef6c31 | 3937 | An index into @env{$@{COMP_WORDS@}} of the word containing the current |
bb70624e JA |
3938 | cursor position. |
3939 | This variable is available only in shell functions invoked by the | |
3940 | programmable completion facilities (@pxref{Programmable Completion}). | |
3941 | ||
3942 | @item COMP_LINE | |
3943 | The current command line. | |
3944 | This variable is available only in shell functions and external | |
3945 | commands invoked by the | |
3946 | programmable completion facilities (@pxref{Programmable Completion}). | |
3947 | ||
3948 | @item COMP_POINT | |
3949 | The index of the current cursor position relative to the beginning of | |
3950 | the current command. | |
3951 | If the current cursor position is at the end of the current command, | |
3952 | the value of this variable is equal to @code{$@{#COMP_LINE@}}. | |
3953 | This variable is available only in shell functions and external | |
3954 | commands invoked by the | |
3955 | programmable completion facilities (@pxref{Programmable Completion}). | |
3956 | ||
3957 | @item COMPREPLY | |
3958 | An array variable from which Bash reads the possible completions | |
3959 | generated by a shell function invoked by the programmable completion | |
3960 | facility (@pxref{Programmable Completion}). | |
b72432fd | 3961 | |
bb70624e JA |
3962 | @item DIRSTACK |
3963 | An array variable containing the current contents of the directory stack. | |
3964 | Directories appear in the stack in the order they are displayed by the | |
3965 | @code{dirs} builtin. | |
3966 | Assigning to members of this array variable may be used to modify | |
3967 | directories already in the stack, but the @code{pushd} and @code{popd} | |
3968 | builtins must be used to add and remove directories. | |
3969 | Assignment to this variable will not change the current directory. | |
28ef6c31 | 3970 | If @env{DIRSTACK} is unset, it loses its special properties, even if |
bb70624e | 3971 | it is subsequently reset. |
ccc6cda3 | 3972 | |
bb70624e JA |
3973 | @item EUID |
3974 | The numeric effective user id of the current user. This variable | |
3975 | is readonly. | |
ccc6cda3 | 3976 | |
bb70624e | 3977 | @item FCEDIT |
28ef6c31 | 3978 | The editor used as a default by the @option{-e} option to the @code{fc} |
bb70624e | 3979 | builtin command. |
cce855bc | 3980 | |
bb70624e JA |
3981 | @item FIGNORE |
3982 | A colon-separated list of suffixes to ignore when performing | |
3983 | filename completion. | |
3984 | A file name whose suffix matches one of the entries in | |
28ef6c31 | 3985 | @env{FIGNORE} |
bb70624e JA |
3986 | is excluded from the list of matched file names. A sample |
3987 | value is @samp{.o:~} | |
cce855bc | 3988 | |
bb70624e JA |
3989 | @item GLOBIGNORE |
3990 | A colon-separated list of patterns defining the set of filenames to | |
3991 | be ignored by filename expansion. | |
3992 | If a filename matched by a filename expansion pattern also matches one | |
28ef6c31 | 3993 | of the patterns in @env{GLOBIGNORE}, it is removed from the list |
bb70624e | 3994 | of matches. |
ccc6cda3 | 3995 | |
bb70624e JA |
3996 | @item GROUPS |
3997 | An array variable containing the list of groups of which the current | |
3998 | user is a member. | |
28ef6c31 JA |
3999 | Assignments to @env{GROUPS} have no effect and return an error status. |
4000 | If @env{GROUPS} is unset, it loses its special properties, even if it is | |
bb70624e | 4001 | subsequently reset. |
ccc6cda3 | 4002 | |
bb70624e JA |
4003 | @item histchars |
4004 | Up to three characters which control history expansion, quick | |
4005 | substitution, and tokenization (@pxref{History Interaction}). | |
4006 | The first character is the | |
4007 | @var{history expansion} character, that is, the character which signifies the | |
4008 | start of a history expansion, normally @samp{!}. The second character is the | |
4009 | character which signifies `quick substitution' when seen as the first | |
4010 | character on a line, normally @samp{^}. The optional third character is the | |
4011 | character which indicates that the remainder of the line is a comment when | |
4012 | found as the first character of a word, usually @samp{#}. The history | |
4013 | comment character causes history substitution to be skipped for the | |
4014 | remaining words on the line. It does not necessarily cause the shell | |
4015 | parser to treat the rest of the line as a comment. | |
ccc6cda3 | 4016 | |
bb70624e JA |
4017 | @item HISTCMD |
4018 | The history number, or index in the history list, of the current | |
28ef6c31 | 4019 | command. If @env{HISTCMD} is unset, it loses its special properties, |
bb70624e | 4020 | even if it is subsequently reset. |
ccc6cda3 | 4021 | |
bb70624e JA |
4022 | @item FUNCNAME |
4023 | The name of any currently-executing shell function. | |
4024 | This variable exists only when a shell function is executing. | |
28ef6c31 JA |
4025 | Assignments to @env{FUNCNAME} have no effect and return an error status. |
4026 | If @env{FUNCNAME} is unset, it loses its special properties, even if | |
bb70624e | 4027 | it is subsequently reset. |
cce855bc | 4028 | |
bb70624e JA |
4029 | @item HISTCONTROL |
4030 | A value of @samp{ignorespace} means to not enter lines which | |
4031 | begin with a space or tab into the history list. | |
4032 | A value of @samp{ignoredups} means to not enter lines which match the last | |
4033 | entered line. | |
4034 | A value of @samp{ignoreboth} combines the two options. | |
4035 | Unset, or set to any other value than those above, means to save | |
4036 | all lines on the history list. | |
4037 | The second and subsequent lines of a multi-line compound command are | |
4038 | not tested, and are added to the history regardless of the value of | |
28ef6c31 | 4039 | @env{HISTCONTROL}. |
ccc6cda3 | 4040 | |
bb70624e JA |
4041 | @item HISTIGNORE |
4042 | A colon-separated list of patterns used to decide which command | |
4043 | lines should be saved on the history list. Each pattern is | |
4044 | anchored at the beginning of the line and must match the complete | |
4045 | line (no implicit @samp{*} is appended). Each pattern is tested | |
28ef6c31 | 4046 | against the line after the checks specified by @env{HISTCONTROL} |
bb70624e JA |
4047 | are applied. In addition to the normal shell pattern matching |
4048 | characters, @samp{&} matches the previous history line. @samp{&} | |
4049 | may be escaped using a backslash; the backslash is removed | |
4050 | before attempting a match. | |
4051 | The second and subsequent lines of a multi-line compound command are | |
4052 | not tested, and are added to the history regardless of the value of | |
28ef6c31 | 4053 | @env{HISTIGNORE}. |
ccc6cda3 | 4054 | |
28ef6c31 | 4055 | @env{HISTIGNORE} subsumes the function of @env{HISTCONTROL}. A |
bb70624e JA |
4056 | pattern of @samp{&} is identical to @code{ignoredups}, and a |
4057 | pattern of @samp{[ ]*} is identical to @code{ignorespace}. | |
4058 | Combining these two patterns, separating them with a colon, | |
4059 | provides the functionality of @code{ignoreboth}. | |
ccc6cda3 | 4060 | |
bb70624e JA |
4061 | @item HISTFILE |
4062 | The name of the file to which the command history is saved. The | |
4063 | default value is @file{~/.bash_history}. | |
ccc6cda3 | 4064 | |
bb70624e JA |
4065 | @item HISTSIZE |
4066 | The maximum number of commands to remember on the history list. | |
4067 | The default value is 500. | |
ccc6cda3 | 4068 | |
bb70624e JA |
4069 | @item HISTFILESIZE |
4070 | The maximum number of lines contained in the history file. When this | |
4071 | variable is assigned a value, the history file is truncated, if | |
4072 | necessary, to contain no more than that number of lines. | |
4073 | The history file is also truncated to this size after | |
4074 | writing it when an interactive shell exits. | |
4075 | The default value is 500. | |
ccc6cda3 | 4076 | |
bb70624e JA |
4077 | @item HOSTFILE |
4078 | Contains the name of a file in the same format as @file{/etc/hosts} that | |
4079 | should be read when the shell needs to complete a hostname. | |
4080 | The list of possible hostname completions may be changed while the shell | |
4081 | is running; | |
4082 | the next time hostname completion is attempted after the | |
4083 | value is changed, Bash adds the contents of the new file to the | |
4084 | existing list. | |
28ef6c31 | 4085 | If @env{HOSTFILE} is set, but has no value, Bash attempts to read |
bb70624e | 4086 | @file{/etc/hosts} to obtain the list of possible hostname completions. |
28ef6c31 | 4087 | When @env{HOSTFILE} is unset, the hostname list is cleared. |
ccc6cda3 | 4088 | |
bb70624e JA |
4089 | @item HOSTNAME |
4090 | The name of the current host. | |
ccc6cda3 | 4091 | |
bb70624e JA |
4092 | @item HOSTTYPE |
4093 | A string describing the machine Bash is running on. | |
ccc6cda3 | 4094 | |
bb70624e JA |
4095 | @item IGNOREEOF |
4096 | Controls the action of the shell on receipt of an @code{EOF} character | |
4097 | as the sole input. If set, the value denotes the number | |
4098 | of consecutive @code{EOF} characters that can be read as the | |
4099 | first character on an input line | |
4100 | before the shell will exit. If the variable exists but does not | |
4101 | have a numeric value (or has no value) then the default is 10. | |
4102 | If the variable does not exist, then @code{EOF} signifies the end of | |
4103 | input to the shell. This is only in effect for interactive shells. | |
ccc6cda3 | 4104 | |
bb70624e JA |
4105 | @item INPUTRC |
4106 | The name of the Readline initialization file, overriding the default | |
4107 | of @file{~/.inputrc}. | |
ccc6cda3 | 4108 | |
bb70624e JA |
4109 | @item LANG |
4110 | Used to determine the locale category for any category not specifically | |
4111 | selected with a variable starting with @code{LC_}. | |
ccc6cda3 | 4112 | |
bb70624e | 4113 | @item LC_ALL |
28ef6c31 | 4114 | This variable overrides the value of @env{LANG} and any other |
bb70624e | 4115 | @code{LC_} variable specifying a locale category. |
ccc6cda3 | 4116 | |
bb70624e JA |
4117 | @item LC_COLLATE |
4118 | This variable determines the collation order used when sorting the | |
4119 | results of filename expansion, and | |
4120 | determines the behavior of range expressions, equivalence classes, | |
4121 | and collating sequences within filename expansion and pattern matching | |
4122 | (@pxref{Filename Expansion}). | |
ccc6cda3 | 4123 | |
bb70624e JA |
4124 | @item LC_CTYPE |
4125 | This variable determines the interpretation of characters and the | |
4126 | behavior of character classes within filename expansion and pattern | |
4127 | matching (@pxref{Filename Expansion}). | |
ccc6cda3 | 4128 | |
bb70624e JA |
4129 | @item LC_MESSAGES |
4130 | This variable determines the locale used to translate double-quoted | |
4131 | strings preceded by a @samp{$} (@pxref{Locale Translation}). | |
ccc6cda3 | 4132 | |
bb70624e JA |
4133 | @item LC_NUMERIC |
4134 | This variable determines the locale category used for number formatting. | |
ccc6cda3 | 4135 | |
28ef6c31 JA |
4136 | @item LINES |
4137 | Used by the @code{select} builtin command to determine the column length | |
4138 | for printing selection lists. Automatically set upon receipt of a | |
4139 | @code{SIGWINCH}. | |
4140 | ||
4141 | @item COLUMNS | |
4142 | Used by the @code{select} builtin command to determine the terminal width | |
4143 | when printing selection lists. Automatically set upon receipt of a | |
4144 | @code{SIGWINCH}. | |
4145 | ||
bb70624e JA |
4146 | @item LINENO |
4147 | The line number in the script or shell function currently executing. | |
cce855bc | 4148 | |
bb70624e JA |
4149 | @item MACHTYPE |
4150 | A string that fully describes the system type on which Bash | |
4151 | is executing, in the standard @sc{gnu} @var{cpu-company-system} format. | |
ccc6cda3 | 4152 | |
bb70624e JA |
4153 | @item MAILCHECK |
4154 | How often (in seconds) that the shell should check for mail in the | |
28ef6c31 JA |
4155 | files specified in the @env{MAILPATH} or @env{MAIL} variables. |
4156 | The default is 60 seconds. When it is time to check | |
4157 | for mail, the shell does so before displaying the primary prompt. | |
4158 | If this variable is unset, or set to a value that is not a number | |
4159 | greater than or equal to zero, the shell disables mail checking. | |
ccc6cda3 | 4160 | |
bb70624e JA |
4161 | @item OLDPWD |
4162 | The previous working directory as set by the @code{cd} builtin. | |
ccc6cda3 | 4163 | |
bb70624e JA |
4164 | @item OPTERR |
4165 | If set to the value 1, Bash displays error messages | |
4166 | generated by the @code{getopts} builtin command. | |
ccc6cda3 | 4167 | |
bb70624e JA |
4168 | @item OSTYPE |
4169 | A string describing the operating system Bash is running on. | |
cce855bc | 4170 | |
bb70624e JA |
4171 | @item PIPESTATUS |
4172 | An array variable (@pxref{Arrays}) | |
4173 | containing a list of exit status values from the processes | |
4174 | in the most-recently-executed foreground pipeline (which may | |
4175 | contain only a single command). | |
cce855bc | 4176 | |
bb70624e JA |
4177 | @item PPID |
4178 | The process @sc{id} of the shell's parent process. This variable | |
4179 | is readonly. | |
ccc6cda3 | 4180 | |
bb70624e JA |
4181 | @item PROMPT_COMMAND |
4182 | If set, the value is interpreted as a command to execute | |
28ef6c31 | 4183 | before the printing of each primary prompt (@env{$PS1}). |
ccc6cda3 | 4184 | |
bb70624e JA |
4185 | @item PS3 |
4186 | The value of this variable is used as the prompt for the | |
4187 | @code{select} command. If this variable is not set, the | |
4188 | @code{select} command prompts with @samp{#? } | |
ccc6cda3 | 4189 | |
bb70624e JA |
4190 | @item PS4 |
4191 | The value is the prompt printed before the command line is echoed | |
28ef6c31 JA |
4192 | when the @option{-x} option is set (@pxref{The Set Builtin}). |
4193 | The first character of @env{PS4} is replicated multiple times, as | |
bb70624e JA |
4194 | necessary, to indicate multiple levels of indirection. |
4195 | The default is @samp{+ }. | |
ccc6cda3 | 4196 | |
bb70624e JA |
4197 | @item PWD |
4198 | The current working directory as set by the @code{cd} builtin. | |
ccc6cda3 | 4199 | |
bb70624e JA |
4200 | @item RANDOM |
4201 | Each time this parameter is referenced, a random integer | |
4202 | between 0 and 32767 is generated. Assigning a value to this | |
4203 | variable seeds the random number generator. | |
ccc6cda3 | 4204 | |
bb70624e JA |
4205 | @item REPLY |
4206 | The default variable for the @code{read} builtin. | |
ccc6cda3 | 4207 | |
bb70624e JA |
4208 | @item SECONDS |
4209 | This variable expands to the number of seconds since the | |
4210 | shell was started. Assignment to this variable resets | |
4211 | the count to the value assigned, and the expanded value | |
4212 | becomes the value assigned plus the number of seconds | |
4213 | since the assignment. | |
ccc6cda3 | 4214 | |
bb70624e JA |
4215 | @item SHELLOPTS |
4216 | A colon-separated list of enabled shell options. Each word in | |
28ef6c31 | 4217 | the list is a valid argument for the @option{-o} option to the |
bb70624e | 4218 | @code{set} builtin command (@pxref{The Set Builtin}). |
28ef6c31 | 4219 | The options appearing in @env{SHELLOPTS} are those reported |
bb70624e JA |
4220 | as @samp{on} by @samp{set -o}. |
4221 | If this variable is in the environment when Bash | |
4222 | starts up, each shell option in the list will be enabled before | |
4223 | reading any startup files. This variable is readonly. | |
ccc6cda3 | 4224 | |
bb70624e JA |
4225 | @item SHLVL |
4226 | Incremented by one each time a new instance of Bash is started. This is | |
4227 | intended to be a count of how deeply your Bash shells are nested. | |
ccc6cda3 | 4228 | |
bb70624e JA |
4229 | @item TIMEFORMAT |
4230 | The value of this parameter is used as a format string specifying | |
4231 | how the timing information for pipelines prefixed with the @code{time} | |
4232 | reserved word should be displayed. | |
4233 | The @samp{%} character introduces an | |
4234 | escape sequence that is expanded to a time value or other | |
4235 | information. | |
4236 | The escape sequences and their meanings are as | |
4237 | follows; the braces denote optional portions. | |
ccc6cda3 | 4238 | |
bb70624e | 4239 | @table @code |
ccc6cda3 | 4240 | |
bb70624e JA |
4241 | @item %% |
4242 | A literal @samp{%}. | |
ccc6cda3 | 4243 | |
bb70624e JA |
4244 | @item %[@var{p}][l]R |
4245 | The elapsed time in seconds. | |
ccc6cda3 | 4246 | |
bb70624e JA |
4247 | @item %[@var{p}][l]U |
4248 | The number of CPU seconds spent in user mode. | |
ccc6cda3 | 4249 | |
bb70624e JA |
4250 | @item %[@var{p}][l]S |
4251 | The number of CPU seconds spent in system mode. | |
ccc6cda3 | 4252 | |
bb70624e JA |
4253 | @item %P |
4254 | The CPU percentage, computed as (%U + %S) / %R. | |
4255 | @end table | |
ccc6cda3 | 4256 | |
bb70624e JA |
4257 | The optional @var{p} is a digit specifying the precision, the number of |
4258 | fractional digits after a decimal point. | |
4259 | A value of 0 causes no decimal point or fraction to be output. | |
4260 | At most three places after the decimal point may be specified; values | |
4261 | of @var{p} greater than 3 are changed to 3. | |
4262 | If @var{p} is not specified, the value 3 is used. | |
ccc6cda3 | 4263 | |
bb70624e JA |
4264 | The optional @code{l} specifies a longer format, including minutes, of |
4265 | the form @var{MM}m@var{SS}.@var{FF}s. | |
4266 | The value of @var{p} determines whether or not the fraction is included. | |
ccc6cda3 | 4267 | |
bb70624e JA |
4268 | If this variable is not set, Bash acts as if it had the value |
4269 | @example | |
4270 | @code{$'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS'} | |
4271 | @end example | |
4272 | If the value is null, no timing information is displayed. | |
4273 | A trailing newline is added when the format string is displayed. | |
ccc6cda3 | 4274 | |
bb70624e JA |
4275 | @item TMOUT |
4276 | If set to a value greater than zero, the value is interpreted as | |
4277 | the number of seconds to wait for input after issuing the primary | |
4278 | prompt when the shell is interactive. | |
4279 | Bash terminates after that number of seconds if input does | |
4280 | not arrive. | |
ccc6cda3 | 4281 | |
bb70624e JA |
4282 | @item UID |
4283 | The numeric real user id of the current user. This variable is readonly. | |
ccc6cda3 | 4284 | |
bb70624e | 4285 | @end vtable |
ccc6cda3 | 4286 | |
bb70624e JA |
4287 | @node Bash Features |
4288 | @chapter Bash Features | |
ccc6cda3 | 4289 | |
bb70624e | 4290 | This section describes features unique to Bash. |
ccc6cda3 | 4291 | |
bb70624e JA |
4292 | @menu |
4293 | * Invoking Bash:: Command line options that you can give | |
4294 | to Bash. | |
4295 | * Bash Startup Files:: When and how Bash executes scripts. | |
4296 | * Interactive Shells:: What an interactive shell is. | |
4297 | * Bash Conditional Expressions:: Primitives used in composing expressions for | |
4298 | the @code{test} builtin. | |
4299 | * Shell Arithmetic:: Arithmetic on shell variables. | |
4300 | * Aliases:: Substituting one command for another. | |
4301 | * Arrays:: Array Variables. | |
4302 | * The Directory Stack:: History of visited directories. | |
4303 | * Printing a Prompt:: Controlling the PS1 string. | |
4304 | * The Restricted Shell:: A more controlled mode of shell execution. | |
4305 | * Bash POSIX Mode:: Making Bash behave more closely to what | |
4306 | the POSIX standard specifies. | |
4307 | @end menu | |
ccc6cda3 | 4308 | |
bb70624e JA |
4309 | @node Invoking Bash |
4310 | @section Invoking Bash | |
ccc6cda3 | 4311 | |
bb70624e JA |
4312 | @example |
4313 | bash [long-opt] [-ir] [-abefhkmnptuvxdBCDHP] [-o @var{option}] [@var{argument} @dots{}] | |
4314 | bash [long-opt] [-abefhkmnptuvxdBCDHP] [-o @var{option}] -c @var{string} [@var{argument} @dots{}] | |
4315 | bash [long-opt] -s [-abefhkmnptuvxdBCDHP] [-o @var{option}] [@var{argument} @dots{}] | |
4316 | @end example | |
ccc6cda3 | 4317 | |
bb70624e JA |
4318 | In addition to the single-character shell command-line options |
4319 | (@pxref{The Set Builtin}), there are several multi-character | |
4320 | options that you can use. These options must appear on the command | |
4321 | line before the single-character options in order for them | |
4322 | to be recognized. | |
ccc6cda3 | 4323 | |
bb70624e JA |
4324 | @table @code |
4325 | @item --dump-po-strings | |
4326 | A list of all double-quoted strings preceded by @samp{$} | |
4327 | is printed on the standard ouput | |
4328 | in the @sc{gnu} @code{gettext} PO (portable object) file format. | |
28ef6c31 | 4329 | Equivalent to @option{-D} except for the output format. |
ccc6cda3 | 4330 | |
bb70624e | 4331 | @item --dump-strings |
28ef6c31 | 4332 | Equivalent to @option{-D}. |
ccc6cda3 | 4333 | |
bb70624e JA |
4334 | @item --help |
4335 | Display a usage message on standard output and exit sucessfully. | |
ccc6cda3 | 4336 | |
28ef6c31 JA |
4337 | @item --init-file @var{filename} |
4338 | @itemx --rcfile @var{filename} | |
4339 | Execute commands from @var{filename} (instead of @file{~/.bashrc}) | |
4340 | in an interactive shell. | |
4341 | ||
bb70624e | 4342 | @item --login |
28ef6c31 JA |
4343 | Make this shell act as if it had been directly invoked by login. |
4344 | When the shell is interactive, this is equivalent to starting a | |
4345 | login shell with @samp{exec -l bash}. | |
4346 | When the shell is not interactive, the login shell startup files will | |
4347 | be executed. | |
4348 | @samp{exec bash --login} | |
bb70624e JA |
4349 | will replace the current shell with a Bash login shell. |
4350 | @xref{Bash Startup Files}, for a description of the special behavior | |
4351 | of a login shell. | |
ccc6cda3 | 4352 | |
bb70624e JA |
4353 | @item --noediting |
4354 | Do not use the @sc{gnu} Readline library (@pxref{Command Line Editing}) | |
4355 | to read command lines when the shell is interactive. | |
ccc6cda3 | 4356 | |
bb70624e JA |
4357 | @item --noprofile |
4358 | Don't load the system-wide startup file @file{/etc/profile} | |
4359 | or any of the personal initialization files | |
4360 | @file{~/.bash_profile}, @file{~/.bash_login}, or @file{~/.profile} | |
4361 | when Bash is invoked as a login shell. | |
ccc6cda3 | 4362 | |
bb70624e JA |
4363 | @item --norc |
4364 | Don't read the @file{~/.bashrc} initialization file in an | |
4365 | interactive shell. This is on by default if the shell is | |
4366 | invoked as @code{sh}. | |
ccc6cda3 | 4367 | |
bb70624e JA |
4368 | @item --posix |
4369 | Change the behavior of Bash where the default operation differs | |
4370 | from the @sc{posix} 1003.2 standard to match the standard. This | |
4371 | is intended to make Bash behave as a strict superset of that | |
4372 | standard. @xref{Bash POSIX Mode}, for a description of the Bash | |
4373 | @sc{posix} mode. | |
ccc6cda3 | 4374 | |
bb70624e JA |
4375 | @item --restricted |
4376 | Make the shell a restricted shell (@pxref{The Restricted Shell}). | |
ccc6cda3 | 4377 | |
bb70624e | 4378 | @item --verbose |
28ef6c31 | 4379 | Equivalent to @option{-v}. Print shell input lines as they're read. |
ccc6cda3 | 4380 | |
bb70624e JA |
4381 | @item --version |
4382 | Show version information for this instance of | |
4383 | Bash on the standard output and exit successfully. | |
ccc6cda3 | 4384 | |
ccc6cda3 JA |
4385 | @end table |
4386 | ||
bb70624e JA |
4387 | There are several single-character options that may be supplied at |
4388 | invocation which are not available with the @code{set} builtin. | |
cce855bc | 4389 | |
bb70624e JA |
4390 | @table @code |
4391 | @item -c @var{string} | |
4392 | Read and execute commands from @var{string} after processing the | |
4393 | options, then exit. Any remaining arguments are assigned to the | |
4394 | positional parameters, starting with @code{$0}. | |
ccc6cda3 | 4395 | |
bb70624e JA |
4396 | @item -i |
4397 | Force the shell to run interactively. Interactive shells are | |
4398 | described in @ref{Interactive Shells}. | |
ccc6cda3 | 4399 | |
bb70624e JA |
4400 | @item -r |
4401 | Make the shell a restricted shell (@pxref{The Restricted Shell}). | |
ccc6cda3 | 4402 | |
bb70624e JA |
4403 | @item -s |
4404 | If this option is present, or if no arguments remain after option | |
4405 | processing, then commands are read from the standard input. | |
4406 | This option allows the positional parameters to be set | |
4407 | when invoking an interactive shell. | |
4408 | ||
4409 | @item -D | |
4410 | A list of all double-quoted strings preceded by @samp{$} | |
4411 | is printed on the standard ouput. | |
4412 | These are the strings that | |
4413 | are subject to language translation when the current locale | |
4414 | is not @code{C} or @code{POSIX} (@pxref{Locale Translation}). | |
28ef6c31 | 4415 | This implies the @option{-n} option; no commands will be executed. |
bb70624e JA |
4416 | |
4417 | @item -- | |
4418 | A @code{--} signals the end of options and disables further option | |
4419 | processing. | |
4420 | Any arguments after the @code{--} are treated as filenames and arguments. | |
4421 | ||
4422 | @end table | |
4423 | ||
4424 | @cindex interactive shell | |
4425 | An @emph{interactive} shell is one started without non-option arguments, | |
28ef6c31 JA |
4426 | unless @option{-s} is specified, |
4427 | without specifying the @option{-c} option, and whose input and output are both | |
bb70624e | 4428 | connected to terminals (as determined by @code{isatty(3)}), or one |
28ef6c31 | 4429 | started with the @option{-i} option. @xref{Interactive Shells}, for more |
bb70624e JA |
4430 | information. |
4431 | ||
4432 | If arguments remain after option processing, and neither the | |
28ef6c31 | 4433 | @option{-c} nor the @option{-s} |
bb70624e JA |
4434 | option has been supplied, the first argument is assumed to |
4435 | be the name of a file containing shell commands (@pxref{Shell Scripts}). | |
4436 | When Bash is invoked in this fashion, @code{$0} | |
4437 | is set to the name of the file, and the positional parameters | |
4438 | are set to the remaining arguments. | |
4439 | Bash reads and executes commands from this file, then exits. | |
4440 | Bash's exit status is the exit status of the last command executed | |
4441 | in the script. If no commands are executed, the exit status is 0. | |
4442 | ||
4443 | @node Bash Startup Files | |
4444 | @section Bash Startup Files | |
4445 | @cindex startup files | |
4446 | ||
4447 | This section describs how Bash executes its startup files. | |
4448 | If any of the files exist but cannot be read, Bash reports an error. | |
4449 | Tildes are expanded in file names as described above under | |
4450 | Tilde Expansion (@pxref{Tilde Expansion}). | |
4451 | ||
4452 | Interactive shells are described in @ref{Interactive Shells}. | |
4453 | ||
28ef6c31 | 4454 | @subsubheading Invoked as an interactive login shell, or with @option{--login} |
bb70624e JA |
4455 | |
4456 | When Bash is invoked as an interactive login shell, or as a | |
28ef6c31 | 4457 | non-interactive shell with the @option{--login} option, it first reads and |
bb70624e JA |
4458 | executes commands from the file @file{/etc/profile}, if that file exists. |
4459 | After reading that file, it looks for @file{~/.bash_profile}, | |
4460 | @file{~/.bash_login}, and @file{~/.profile}, in that order, and reads | |
4461 | and executes commands from the first one that exists and is readable. | |
28ef6c31 | 4462 | The @option{--noprofile} option may be used when the shell is started to |
bb70624e JA |
4463 | inhibit this behavior. |
4464 | ||
4465 | When a login shell exits, Bash reads and executes commands from | |
4466 | the file @file{~/.bash_logout}, if it exists. | |
4467 | ||
4468 | @subsubheading Invoked as an interactive non-login shell | |
4469 | ||
4470 | When an interactive shell that is not a login shell is started, Bash | |
4471 | reads and executes commands from @file{~/.bashrc}, if that file exists. | |
28ef6c31 JA |
4472 | This may be inhibited by using the @option{--norc} option. |
4473 | The @option{--rcfile @var{file}} option will force Bash to read and | |
bb70624e JA |
4474 | execute commands from @var{file} instead of @file{~/.bashrc}. |
4475 | ||
4476 | So, typically, your @file{~/.bash_profile} contains the line | |
4477 | @example | |
4478 | @code{if [ -f ~/.bashrc ]; then . ~/.bashrc; fi} | |
4479 | @end example | |
4480 | @noindent | |
4481 | after (or before) any login-specific initializations. | |
4482 | ||
4483 | @subsubheading Invoked non-interactively | |
4484 | ||
4485 | When Bash is started non-interactively, to run a shell script, | |
28ef6c31 | 4486 | for example, it looks for the variable @env{BASH_ENV} in the environment, |
bb70624e JA |
4487 | expands its value if it appears there, and uses the expanded value as |
4488 | the name of a file to read and execute. Bash behaves as if the | |
4489 | following command were executed: | |
4490 | @example | |
4491 | @code{if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi} | |
4492 | @end example | |
4493 | @noindent | |
28ef6c31 | 4494 | but the value of the @env{PATH} variable is not used to search for the |
bb70624e JA |
4495 | file name. |
4496 | ||
28ef6c31 JA |
4497 | As noted above, if a non-interactive shell is invoked with the |
4498 | @option{--login} option, Bash attempts to read and execute commands from the | |
4499 | login shell startup files. | |
4500 | ||
bb70624e JA |
4501 | @subsubheading Invoked with name @code{sh} |
4502 | ||
4503 | If Bash is invoked with the name @code{sh}, it tries to mimic the | |
4504 | startup behavior of historical versions of @code{sh} as closely as | |
4505 | possible, while conforming to the @sc{posix} standard as well. | |
4506 | ||
4507 | When invoked as an interactive login shell, or as a non-interactive | |
28ef6c31 | 4508 | shell with the @option{--login} option, it first attempts to read |
bb70624e JA |
4509 | and execute commands from @file{/etc/profile} and @file{~/.profile}, in |
4510 | that order. | |
28ef6c31 | 4511 | The @option{--noprofile} option may be used to inhibit this behavior. |
bb70624e | 4512 | When invoked as an interactive shell with the name @code{sh}, Bash |
28ef6c31 | 4513 | looks for the variable @env{ENV}, expands its value if it is defined, |
bb70624e JA |
4514 | and uses the expanded value as the name of a file to read and execute. |
4515 | Since a shell invoked as @code{sh} does not attempt to read and execute | |
28ef6c31 | 4516 | commands from any other startup files, the @option{--rcfile} option has |
bb70624e JA |
4517 | no effect. |
4518 | A non-interactive shell invoked with the name @code{sh} does not attempt | |
4519 | to read any other startup files. | |
4520 | ||
4521 | When invoked as @code{sh}, Bash enters @sc{posix} mode after | |
4522 | the startup files are read. | |
4523 | ||
4524 | @subsubheading Invoked in @sc{posix} mode | |
4525 | ||
4526 | When Bash is started in @sc{posix} mode, as with the | |
28ef6c31 | 4527 | @option{--posix} command line option, it follows the @sc{posix} standard |
bb70624e | 4528 | for startup files. |
28ef6c31 | 4529 | In this mode, interactive shells expand the @env{ENV} variable |
bb70624e JA |
4530 | and commands are read and executed from the file whose name is the |
4531 | expanded value. | |
4532 | No other startup files are read. | |
4533 | ||
4534 | @subsubheading Invoked by remote shell daemon | |
4535 | ||
4536 | Bash attempts to determine when it is being run by the remote shell | |
4537 | daemon, usually @code{rshd}. If Bash determines it is being run by | |
4538 | rshd, it reads and executes commands from @file{~/.bashrc}, if that | |
4539 | file exists and is readable. | |
4540 | It will not do this if invoked as @code{sh}. | |
28ef6c31 JA |
4541 | The @option{--norc} option may be used to inhibit this behavior, and the |
4542 | @option{--rcfile} option may be used to force another file to be read, but | |
bb70624e JA |
4543 | @code{rshd} does not generally invoke the shell with those options or |
4544 | allow them to be specified. | |
4545 | ||
4546 | @subsubheading Invoked with unequal effective and real @sc{uid/gid}s | |
4547 | ||
4548 | If Bash is started with the effective user (group) id not equal to the | |
4549 | real user (group) id, and the @code{-p} option is not supplied, no startup | |
4550 | files are read, shell functions are not inherited from the environment, | |
28ef6c31 | 4551 | the @env{SHELLOPTS} variable, if it appears in the environment, is ignored, |
bb70624e JA |
4552 | and the effective user id is set to the real user id. |
4553 | If the @code{-p} option is supplied at invocation, the startup behavior is | |
4554 | the same, but the effective user id is not reset. | |
4555 | ||
4556 | @node Interactive Shells | |
4557 | @section Interactive Shells | |
4558 | @cindex interactive shell | |
4559 | @cindex shell, interactive | |
4560 | ||
4561 | @menu | |
4562 | * What is an Interactive Shell?:: What determines whether a shell is Interactive. | |
4563 | * Is this Shell Interactive?:: How to tell if a shell is interactive. | |
4564 | * Interactive Shell Behavior:: What changes in a interactive shell? | |
4565 | @end menu | |
4566 | ||
4567 | @node What is an Interactive Shell? | |
4568 | @subsection What is an Interactive Shell? | |
4569 | ||
4570 | An interactive shell | |
28ef6c31 JA |
4571 | is one started without non-option arguments, unless @option{-s} is |
4572 | specified, without specifiying the @option{-c} option, and | |
bb70624e JA |
4573 | whose input and output are both |
4574 | connected to terminals (as determined by @code{isatty(3)}), | |
28ef6c31 | 4575 | or one started with the @option{-i} option. |
bb70624e JA |
4576 | |
4577 | An interactive shell generally reads from and writes to a user's | |
4578 | terminal. | |
4579 | ||
28ef6c31 | 4580 | The @option{-s} invocation option may be used to set the positional parameters |
bb70624e JA |
4581 | when an interactive shell is started. |
4582 | ||
4583 | @node Is this Shell Interactive? | |
4584 | @subsection Is this Shell Interactive? | |
4585 | ||
4586 | To determine within a startup script whether or not Bash is | |
4587 | running interactively, | |
4588 | test the value of the @samp{-} special parameter. | |
4589 | It contains @code{i} when the shell is interactive. For example: | |
4590 | ||
4591 | @example | |
4592 | case "$-" in | |
4593 | *i*) echo This shell is interactive ;; | |
4594 | *) echo This shell is not interactive ;; | |
4595 | esac | |
4596 | @end example | |
4597 | ||
4598 | Alternatively, startup scripts may examine the variable | |
28ef6c31 | 4599 | @env{PS1}; it is unset in non-interactive shells, and set in |
bb70624e JA |
4600 | interactive shells. Thus: |
4601 | ||
4602 | @example | |
4603 | if [ -z "$PS1" ]; then | |
4604 | echo This shell is not interactive | |
4605 | else | |
4606 | echo This shell is interactive | |
4607 | fi | |
4608 | @end example | |
4609 | ||
4610 | @node Interactive Shell Behavior | |
4611 | @subsection Interactive Shell Behavior | |
4612 | ||
4613 | When the shell is running interactively, it changes its behavior in | |
4614 | several ways. | |
4615 | ||
4616 | @enumerate | |
4617 | @item | |
4618 | Startup files are read and executed as described in @ref{Bash Startup Files}. | |
4619 | ||
4620 | @item | |
4621 | Job Control (@pxref{Job Control}) is enabled by default. When job | |
4622 | control is in effect, Bash ignores the keyboard-generated job control | |
4623 | signals @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}. | |
4624 | ||
4625 | @item | |
28ef6c31 JA |
4626 | Bash expands and displays @env{PS1} before reading the first line |
4627 | of a command, and expands and displays @env{PS2} before reading the | |
bb70624e JA |
4628 | second and subsequent lines of a multi-line command. |
4629 | ||
4630 | @item | |
28ef6c31 JA |
4631 | Bash executes the value of the @env{PROMPT_COMMAND} variable as a command |
4632 | before printing the primary prompt, @env{$PS1} | |
bb70624e JA |
4633 | (@pxref{Bash Variables}). |
4634 | ||
4635 | @item | |
4636 | Readline (@pxref{Command Line Editing}) is used to read commands from | |
4637 | the user's terminal. | |
4638 | ||
4639 | @item | |
4640 | Bash inspects the value of the @code{ignoreeof} option to @code{set -o} | |
4641 | instead of exiting immediately when it receives an @code{EOF} on its | |
4642 | standard input when reading a command (@pxref{The Set Builtin}). | |
4643 | ||
4644 | @item | |
4645 | Command history (@pxref{Bash History Facilities}) | |
4646 | and history expansion (@pxref{History Interaction}) | |
4647 | are enabled by default. | |
28ef6c31 | 4648 | Bash will save the command history to the file named by @env{$HISTFILE} |
bb70624e JA |
4649 | when an interactive shell exits. |
4650 | ||
4651 | @item | |
4652 | Alias expansion (@pxref{Aliases}) is performed by default. | |
4653 | ||
4654 | @item | |
4655 | In the absence of any traps, Bash ignores @code{SIGTERM} | |
4656 | (@pxref{Signals}). | |
4657 | ||
4658 | @item | |
4659 | In the absence of any traps, @code{SIGINT} is caught and handled | |
4660 | ((@pxref{Signals}). | |
4661 | @code{SIGINT} will interrupt some shell builtins. | |
4662 | ||
4663 | @item | |
4664 | An interactive login shell sends a @code{SIGHUP} to all jobs on exit | |
4665 | if the @code{hupoxexit} shell option has been enabled (@pxref{Signals}). | |
4666 | ||
4667 | @item | |
28ef6c31 | 4668 | The @option{-n} invocation option is ignored, and @samp{set -n} has |
bb70624e JA |
4669 | no effect (@pxref{The Set Builtin}). |
4670 | ||
4671 | @item | |
4672 | Bash will check for mail periodically, depending on the values of the | |
28ef6c31 | 4673 | @env{MAIL}, @env{MAILPATH}, and @env{MAILCHECK} shell variables |
bb70624e JA |
4674 | (@pxref{Bash Variables}). |
4675 | ||
4676 | @item | |
4677 | Expansion errors due to references to unbound shell variables after | |
4678 | @samp{set -u} has been enabled will not cause the shell to exit | |
4679 | (@pxref{The Set Builtin}). | |
4680 | ||
4681 | @item | |
4682 | The shell will not exit on expansion errors caused by @var{var} being unset | |
4683 | or null in @code{$@{@var{var}:?@var{word}@}} expansions | |
4684 | (@pxref{Shell Parameter Expansion}). | |
4685 | ||
4686 | @item | |
4687 | Redirection errors encountered by shell builtins will not cause the | |
4688 | shell to exit. | |
4689 | ||
4690 | @item | |
4691 | When running in @sc{posix} mode, a special builtin returning an error | |
4692 | status will not cause the shell to exit (@pxref{Bash POSIX Mode}). | |
4693 | @item | |
4694 | A failed @code{exec} will not cause the shell to exit | |
4695 | (@pxref{Bourne Shell Builtins}). | |
4696 | ||
4697 | @item | |
4698 | Parser syntax errors will not cause the shell to exit. | |
4699 | ||
4700 | @item | |
4701 | Simple spelling correction for directory arguments to the @code{cd} | |
4702 | builtin is enabled by default (see the description of the @code{cdspell} | |
4703 | option to the @code{shopt} builtin in @ref{Bash Builtins}). | |
4704 | ||
4705 | @item | |
28ef6c31 | 4706 | The shell will check the value of the @env{TMOUT} variable and exit |
bb70624e | 4707 | if a command is not read within the specified number of seconds after |
28ef6c31 | 4708 | printing @env{$PS1} (@pxref{Bash Variables}). |
bb70624e JA |
4709 | |
4710 | @end enumerate | |
4711 | ||
4712 | @node Bash Conditional Expressions | |
4713 | @section Bash Conditional Expressions | |
4714 | @cindex expressions, conditional | |
4715 | ||
4716 | Conditional expressions are used by the @code{[[} compound command | |
4717 | and the @code{test} and @code{[} builtin commands. | |
4718 | ||
4719 | Expressions may be unary or binary. | |
4720 | Unary expressions are often used to examine the status of a file. | |
4721 | There are string operators and numeric comparison operators as well. | |
4722 | If the @var{file} argument to one of the primaries is of the form | |
4723 | @file{/dev/fd/@var{N}}, then file descriptor @var{N} is checked. | |
4724 | If the @var{file} argument to one of the primaries is one of | |
4725 | @file{/dev/stdin}, @file{/dev/stdout}, or @file{/dev/stderr}, file | |
4726 | descriptor 0, 1, or 2, respectively, is checked. | |
ccc6cda3 JA |
4727 | |
4728 | @table @code | |
cce855bc JA |
4729 | @item -a @var{file} |
4730 | True if @var{file} exists. | |
4731 | ||
ccc6cda3 JA |
4732 | @item -b @var{file} |
4733 | True if @var{file} exists and is a block special file. | |
4734 | ||
4735 | @item -c @var{file} | |
4736 | True if @var{file} exists and is a character special file. | |
4737 | ||
4738 | @item -d @var{file} | |
4739 | True if @var{file} exists and is a directory. | |
4740 | ||
4741 | @item -e @var{file} | |
4742 | True if @var{file} exists. | |
4743 | ||
4744 | @item -f @var{file} | |
4745 | True if @var{file} exists and is a regular file. | |
4746 | ||
4747 | @item -g @var{file} | |
cce855bc | 4748 | True if @var{file} exists and its set-group-id bit is set. |
ccc6cda3 | 4749 | |
b72432fd JA |
4750 | @item -h @var{file} |
4751 | True if @var{file} exists and is a symbolic link. | |
4752 | ||
ccc6cda3 | 4753 | @item -k @var{file} |
cce855bc | 4754 | True if @var{file} exists and its "sticky" bit is set. |
ccc6cda3 JA |
4755 | |
4756 | @item -p @var{file} | |
cce855bc | 4757 | True if @var{file} exists and is a named pipe (FIFO). |
ccc6cda3 JA |
4758 | |
4759 | @item -r @var{file} | |
4760 | True if @var{file} exists and is readable. | |
4761 | ||
4762 | @item -s @var{file} | |
4763 | True if @var{file} exists and has a size greater than zero. | |
4764 | ||
ccc6cda3 | 4765 | @item -t @var{fd} |
cce855bc | 4766 | True if file descriptor @var{fd} is open and refers to a terminal. |
ccc6cda3 JA |
4767 | |
4768 | @item -u @var{file} | |
4769 | True if @var{file} exists and its set-user-id bit is set. | |
4770 | ||
4771 | @item -w @var{file} | |
4772 | True if @var{file} exists and is writable. | |
4773 | ||
4774 | @item -x @var{file} | |
4775 | True if @var{file} exists and is executable. | |
4776 | ||
4777 | @item -O @var{file} | |
4778 | True if @var{file} exists and is owned by the effective user id. | |
4779 | ||
4780 | @item -G @var{file} | |
4781 | True if @var{file} exists and is owned by the effective group id. | |
4782 | ||
cce855bc JA |
4783 | @item -L @var{file} |
4784 | True if @var{file} exists and is a symbolic link. | |
4785 | ||
4786 | @item -S @var{file} | |
4787 | True if @var{file} exists and is a socket. | |
4788 | ||
4789 | @item -N @var{file} | |
4790 | True if @var{file} exists and has been modified since it was last read. | |
4791 | ||
ccc6cda3 JA |
4792 | @item @var{file1} -nt @var{file2} |
4793 | True if @var{file1} is newer (according to | |
4794 | modification date) than @var{file2}. | |
4795 | ||
4796 | @item @var{file1} -ot @var{file2} | |
4797 | True if @var{file1} is older than @var{file2}. | |
4798 | ||
4799 | @item @var{file1} -ef @var{file2} | |
4800 | True if @var{file1} and @var{file2} have the same device and | |
4801 | inode numbers. | |
4802 | ||
4803 | @item -o @var{optname} | |
4804 | True if shell option @var{optname} is enabled. | |
28ef6c31 | 4805 | The list of options appears in the description of the @option{-o} |
ccc6cda3 JA |
4806 | option to the @code{set} builtin (@pxref{The Set Builtin}). |
4807 | ||
4808 | @item -z @var{string} | |
4809 | True if the length of @var{string} is zero. | |
4810 | ||
4811 | @item -n @var{string} | |
4812 | @itemx @var{string} | |
4813 | True if the length of @var{string} is non-zero. | |
4814 | ||
cce855bc JA |
4815 | @item @var{string1} == @var{string2} |
4816 | True if the strings are equal. | |
4817 | @samp{=} may be used in place of @samp{==}. | |
ccc6cda3 JA |
4818 | |
4819 | @item @var{string1} != @var{string2} | |
4820 | True if the strings are not equal. | |
4821 | ||
4822 | @item @var{string1} < @var{string2} | |
cce855bc JA |
4823 | True if @var{string1} sorts before @var{string2} lexicographically |
4824 | in the current locale. | |
ccc6cda3 JA |
4825 | |
4826 | @item @var{string1} > @var{string2} | |
cce855bc JA |
4827 | True if @var{string1} sorts after @var{string2} lexicographically |
4828 | in the current locale. | |
ccc6cda3 JA |
4829 | |
4830 | @item @var{arg1} OP @var{arg2} | |
4831 | @code{OP} is one of | |
4832 | @samp{-eq}, @samp{-ne}, @samp{-lt}, @samp{-le}, @samp{-gt}, or @samp{-ge}. | |
4833 | These arithmetic binary operators return true if @var{arg1} | |
4834 | is equal to, not equal to, less than, less than or equal to, | |
4835 | greater than, or greater than or equal to @var{arg2}, | |
4836 | respectively. @var{Arg1} and @var{arg2} | |
4837 | may be positive or negative integers. | |
4838 | ||
4839 | @end table | |
4840 | ||
bb70624e JA |
4841 | @node Shell Arithmetic |
4842 | @section Shell Arithmetic | |
4843 | @cindex arithmetic, shell | |
4844 | @cindex shell arithmetic | |
4845 | @cindex expressions, arithmetic | |
4846 | @cindex evaluation, arithmetic | |
4847 | @cindex arithmetic evaluation | |
ccc6cda3 | 4848 | |
bb70624e JA |
4849 | The shell allows arithmetic expressions to be evaluated, as one of |
4850 | the shell expansions or by the @code{let} builtin. | |
ccc6cda3 | 4851 | |
bb70624e JA |
4852 | Evaluation is done in long integers with no check for overflow, |
4853 | though division by 0 is trapped and flagged as an error. | |
4854 | The operators and their precedence and associativity are the same | |
4855 | as in the C language. | |
4856 | The following list of operators is grouped into levels of | |
4857 | equal-precedence operators. | |
4858 | The levels are listed in order of decreasing precedence. | |
cce855bc | 4859 | |
bb70624e | 4860 | @table @code |
d166f048 | 4861 | |
bb70624e JA |
4862 | @item @var{id}++ @var{id}-- |
4863 | variable post-increment and post-decrement | |
cce855bc | 4864 | |
bb70624e JA |
4865 | @item ++@var{id} --@var{id} |
4866 | variable pre-increment and pre-decrement | |
ccc6cda3 | 4867 | |
bb70624e JA |
4868 | @item - + |
4869 | unary minus and plus | |
ccc6cda3 | 4870 | |
bb70624e JA |
4871 | @item ! ~ |
4872 | logical and bitwise negation | |
ccc6cda3 | 4873 | |
bb70624e JA |
4874 | @item ** |
4875 | exponentiation | |
ccc6cda3 | 4876 | |
bb70624e JA |
4877 | @item * / % |
4878 | multiplication, division, remainder | |
ccc6cda3 | 4879 | |
bb70624e JA |
4880 | @item + - |
4881 | addition, subtraction | |
cce855bc | 4882 | |
bb70624e JA |
4883 | @item << >> |
4884 | left and right bitwise shifts | |
cce855bc | 4885 | |
bb70624e JA |
4886 | @item <= >= < > |
4887 | comparison | |
ccc6cda3 | 4888 | |
bb70624e JA |
4889 | @item == != |
4890 | equality and inequality | |
ccc6cda3 | 4891 | |
bb70624e JA |
4892 | @item & |
4893 | bitwise AND | |
ccc6cda3 | 4894 | |
bb70624e JA |
4895 | @item ^ |
4896 | bitwise exclusive OR | |
ccc6cda3 | 4897 | |
bb70624e JA |
4898 | @item | |
4899 | bitwise OR | |
cce855bc | 4900 | |
bb70624e JA |
4901 | @item && |
4902 | logical AND | |
cce855bc | 4903 | |
bb70624e JA |
4904 | @item || |
4905 | logical OR | |
cce855bc | 4906 | |
bb70624e JA |
4907 | @item expr ? expr : expr |
4908 | conditional evaluation | |
cce855bc | 4909 | |
bb70624e JA |
4910 | @item = *= /= %= += -= <<= >>= &= ^= |= |
4911 | assignment | |
cce855bc | 4912 | |
bb70624e JA |
4913 | @item expr1 , expr2 |
4914 | comma | |
4915 | @end table | |
ccc6cda3 | 4916 | |
bb70624e JA |
4917 | Shell variables are allowed as operands; parameter expansion is |
4918 | performed before the expression is evaluated. | |
4919 | Within an expression, shell variables may also be referenced by name | |
4920 | without using the parameter expansion syntax. | |
4921 | The value of a variable is evaluated as an arithmetic expression | |
4922 | when it is referenced. | |
4923 | A shell variable need not have its integer attribute turned on | |
4924 | to be used in an expression. | |
ccc6cda3 | 4925 | |
bb70624e JA |
4926 | Constants with a leading 0 are interpreted as octal numbers. |
4927 | A leading @samp{0x} or @samp{0X} denotes hexadecimal. Otherwise, | |
4928 | numbers take the form [@var{base}@code{#}]@var{n}, where @var{base} | |
4929 | is a decimal number between 2 and 64 representing the arithmetic | |
4930 | base, and @var{n} is a number in that base. If @var{base}@code{#} is | |
4931 | omitted, then base 10 is used. | |
4932 | The digits greater than 9 are represented by the lowercase letters, | |
4933 | the uppercase letters, @samp{_}, and @samp{@@}, in that order. | |
4934 | If @var{base} is less than or equal to 36, lowercase and uppercase | |
4935 | letters may be used interchangably to represent numbers between 10 | |
4936 | and 35. | |
ccc6cda3 | 4937 | |
bb70624e JA |
4938 | Operators are evaluated in order of precedence. Sub-expressions in |
4939 | parentheses are evaluated first and may override the precedence | |
4940 | rules above. | |
ccc6cda3 | 4941 | |
bb70624e JA |
4942 | @node Aliases |
4943 | @section Aliases | |
4944 | @cindex alias expansion | |
ccc6cda3 | 4945 | |
bb70624e JA |
4946 | @var{Aliases} allow a string to be substituted for a word when it is used |
4947 | as the first word of a simple command. | |
4948 | The shell maintains a list of aliases that may be set and unset with | |
4949 | the @code{alias} and @code{unalias} builtin commands. | |
ccc6cda3 | 4950 | |
bb70624e JA |
4951 | The first word of each simple command, if unquoted, is checked to see |
4952 | if it has an alias. | |
4953 | If so, that word is replaced by the text of the alias. | |
4954 | The alias name and the replacement text may contain any valid | |
4955 | shell input, including shell metacharacters, with the exception | |
4956 | that the alias name may not contain @samp{=}. | |
4957 | The first word of the replacement text is tested for | |
4958 | aliases, but a word that is identical to an alias being expanded | |
4959 | is not expanded a second time. This means that one may alias | |
4960 | @code{ls} to @code{"ls -F"}, | |
4961 | for instance, and Bash does not try to recursively expand the | |
4962 | replacement text. If the last character of the alias value is a | |
4963 | space or tab character, then the next command word following the | |
4964 | alias is also checked for alias expansion. | |
ccc6cda3 | 4965 | |
bb70624e JA |
4966 | Aliases are created and listed with the @code{alias} |
4967 | command, and removed with the @code{unalias} command. | |
ccc6cda3 | 4968 | |
bb70624e JA |
4969 | There is no mechanism for using arguments in the replacement text, |
4970 | as in @code{csh}. | |
4971 | If arguments are needed, a shell function should be used | |
4972 | (@pxref{Shell Functions}). | |
ccc6cda3 | 4973 | |
bb70624e JA |
4974 | Aliases are not expanded when the shell is not interactive, |
4975 | unless the @code{expand_aliases} shell option is set using | |
4976 | @code{shopt} (@pxref{Bash Builtins}). | |
ccc6cda3 | 4977 | |
bb70624e JA |
4978 | The rules concerning the definition and use of aliases are |
4979 | somewhat confusing. Bash | |
4980 | always reads at least one complete line | |
4981 | of input before executing any | |
4982 | of the commands on that line. Aliases are expanded when a | |
4983 | command is read, not when it is executed. Therefore, an | |
4984 | alias definition appearing on the same line as another | |
4985 | command does not take effect until the next line of input is read. | |
4986 | The commands following the alias definition | |
4987 | on that line are not affected by the new alias. | |
4988 | This behavior is also an issue when functions are executed. | |
4989 | Aliases are expanded when a function definition is read, | |
4990 | not when the function is executed, because a function definition | |
4991 | is itself a compound command. As a consequence, aliases | |
4992 | defined in a function are not available until after that | |
4993 | function is executed. To be safe, always put | |
4994 | alias definitions on a separate line, and do not use @code{alias} | |
4995 | in compound commands. | |
ccc6cda3 | 4996 | |
bb70624e | 4997 | For almost every purpose, shell functions are preferred over aliases. |
ccc6cda3 | 4998 | |
bb70624e JA |
4999 | @node Arrays |
5000 | @section Arrays | |
5001 | @cindex arrays | |
d166f048 | 5002 | |
bb70624e JA |
5003 | Bash provides one-dimensional array variables. Any variable may be used as |
5004 | an array; the @code{declare} builtin will explicitly declare an array. | |
5005 | There is no maximum | |
5006 | limit on the size of an array, nor any requirement that members | |
5007 | be indexed or assigned contiguously. Arrays are zero-based. | |
ccc6cda3 | 5008 | |
bb70624e JA |
5009 | An array is created automatically if any variable is assigned to using |
5010 | the syntax | |
5011 | @example | |
5012 | name[@var{subscript}]=@var{value} | |
5013 | @end example | |
ccc6cda3 | 5014 | |
bb70624e JA |
5015 | @noindent |
5016 | The @var{subscript} | |
5017 | is treated as an arithmetic expression that must evaluate to a number | |
5018 | greater than or equal to zero. To explicitly declare an array, use | |
5019 | @example | |
5020 | declare -a @var{name} | |
5021 | @end example | |
5022 | @noindent | |
5023 | The syntax | |
5024 | @example | |
5025 | declare -a @var{name}[@var{subscript}] | |
5026 | @end example | |
5027 | @noindent | |
5028 | is also accepted; the @var{subscript} is ignored. Attributes may be | |
5029 | specified for an array variable using the @code{declare} and | |
5030 | @code{readonly} builtins. Each attribute applies to all members of | |
5031 | an array. | |
ccc6cda3 | 5032 | |
bb70624e JA |
5033 | Arrays are assigned to using compound assignments of the form |
5034 | @example | |
5035 | name=(value@var{1} @dots{} value@var{n}) | |
5036 | @end example | |
5037 | @noindent | |
5038 | where each | |
5039 | @var{value} is of the form @code{[[@var{subscript}]=]}@var{string}. If | |
5040 | the optional subscript is supplied, that index is assigned to; | |
5041 | otherwise the index of the element assigned is the last index assigned | |
5042 | to by the statement plus one. Indexing starts at zero. | |
5043 | This syntax is also accepted by the @code{declare} | |
5044 | builtin. Individual array elements may be assigned to using the | |
5045 | @code{name[}@var{subscript}@code{]=}@var{value} syntax introduced above. | |
cce855bc | 5046 | |
bb70624e JA |
5047 | Any element of an array may be referenced using |
5048 | @code{$@{name[}@var{subscript}@code{]@}}. | |
5049 | The braces are required to avoid | |
5050 | conflicts with the shell's filename expansion operators. If the | |
5051 | @var{subscript} is @samp{@@} or @samp{*}, the word expands to all members | |
5052 | of the array @var{name}. These subscripts differ only when the word | |
5053 | appears within double quotes. If the word is double-quoted, | |
5054 | @code{$@{name[*]@}} expands to a single word with | |
5055 | the value of each array member separated by the first character of the | |
28ef6c31 | 5056 | @env{IFS} variable, and @code{$@{name[@@]@}} expands each element of |
bb70624e JA |
5057 | @var{name} to a separate word. When there are no array members, |
5058 | @code{$@{name[@@]@}} expands to nothing. This is analogous to the | |
5059 | expansion of the special parameters @samp{@@} and @samp{*}. | |
5060 | @code{$@{#name[}@var{subscript}@code{]@}} expands to the length of | |
5061 | @code{$@{name[}@var{subscript}@code{]@}}. | |
5062 | If @var{subscript} is @samp{@@} or | |
5063 | @samp{*}, the expansion is the number of elements in the array. | |
5064 | Referencing an array variable without a subscript is equivalent to | |
5065 | referencing element zero. | |
ccc6cda3 | 5066 | |
bb70624e JA |
5067 | The @code{unset} builtin is used to destroy arrays. |
5068 | @code{unset} @var{name[subscript]} | |
5069 | destroys the array element at index @var{subscript}. | |
5070 | @code{unset} @var{name}, where @var{name} is an array, removes the | |
5071 | entire array. A subscript of @samp{*} or @samp{@@} also removes the | |
5072 | entire array. | |
ccc6cda3 | 5073 | |
bb70624e | 5074 | The @code{declare}, @code{local}, and @code{readonly} |
28ef6c31 | 5075 | builtins each accept a @option{-a} |
bb70624e | 5076 | option to specify an array. The @code{read} |
28ef6c31 | 5077 | builtin accepts a @option{-a} |
bb70624e JA |
5078 | option to assign a list of words read from the standard input |
5079 | to an array, and can read values from the standard input into | |
5080 | individual array elements. The @code{set} and @code{declare} | |
5081 | builtins display array values in a way that allows them to be | |
5082 | reused as input. | |
ccc6cda3 | 5083 | |
bb70624e JA |
5084 | @node The Directory Stack |
5085 | @section The Directory Stack | |
5086 | @cindex directory stack | |
ccc6cda3 | 5087 | |
bb70624e JA |
5088 | @menu |
5089 | * Directory Stack Builtins:: Bash builtin commands to manipulate | |
5090 | the directory stack. | |
5091 | @end menu | |
ccc6cda3 | 5092 | |
bb70624e JA |
5093 | The directory stack is a list of recently-visited directories. The |
5094 | @code{pushd} builtin adds directories to the stack as it changes | |
5095 | the current directory, and the @code{popd} builtin removes specified | |
5096 | directories from the stack and changes the current directory to | |
5097 | the directory removed. The @code{dirs} builtin displays the contents | |
5098 | of the directory stack. | |
ccc6cda3 | 5099 | |
bb70624e | 5100 | The contents of the directory stack are also visible |
28ef6c31 | 5101 | as the value of the @env{DIRSTACK} shell variable. |
ccc6cda3 | 5102 | |
bb70624e JA |
5103 | @node Directory Stack Builtins |
5104 | @subsection Directory Stack Builtins | |
ccc6cda3 | 5105 | |
bb70624e | 5106 | @table @code |
ccc6cda3 | 5107 | |
bb70624e JA |
5108 | @item dirs |
5109 | @btindex dirs | |
5110 | @example | |
5111 | dirs [+@var{N} | -@var{N}] [-clpv] | |
5112 | @end example | |
5113 | Display the list of currently remembered directories. Directories | |
5114 | are added to the list with the @code{pushd} command; the | |
5115 | @code{popd} command removes directories from the list. | |
5116 | @table @code | |
5117 | @item +@var{N} | |
5118 | Displays the @var{N}th directory (counting from the left of the | |
5119 | list printed by @code{dirs} when invoked without options), starting | |
5120 | with zero. | |
5121 | @item -@var{N} | |
5122 | Displays the @var{N}th directory (counting from the right of the | |
5123 | list printed by @code{dirs} when invoked without options), starting | |
5124 | with zero. | |
5125 | @item -c | |
5126 | Clears the directory stack by deleting all of the elements. | |
5127 | @item -l | |
5128 | Produces a longer listing; the default listing format uses a | |
5129 | tilde to denote the home directory. | |
5130 | @item -p | |
5131 | Causes @code{dirs} to print the directory stack with one entry per | |
5132 | line. | |
5133 | @item -v | |
5134 | Causes @code{dirs} to print the directory stack with one entry per | |
5135 | line, prefixing each entry with its index in the stack. | |
5136 | @end table | |
5137 | ||
5138 | @item popd | |
5139 | @btindex popd | |
5140 | @example | |
5141 | popd [+@var{N} | -@var{N}] [-n] | |
5142 | @end example | |
5143 | ||
5144 | Remove the top entry from the directory stack, and @code{cd} | |
5145 | to the new top directory. | |
5146 | When no arguments are given, @code{popd} | |
5147 | removes the top directory from the stack and | |
5148 | performs a @code{cd} to the new top directory. The | |
5149 | elements are numbered from 0 starting at the first directory listed with | |
5150 | @code{dirs}; i.e., @code{popd} is equivalent to @code{popd +0}. | |
5151 | @table @code | |
5152 | @item +@var{N} | |
5153 | Removes the @var{N}th directory (counting from the left of the | |
5154 | list printed by @code{dirs}), starting with zero. | |
5155 | @item -@var{N} | |
5156 | Removes the @var{N}th directory (counting from the right of the | |
5157 | list printed by @code{dirs}), starting with zero. | |
5158 | @item -n | |
5159 | Suppresses the normal change of directory when removing directories | |
5160 | from the stack, so that only the stack is manipulated. | |
5161 | @end table | |
5162 | ||
5163 | @btindex pushd | |
5164 | @item pushd | |
5165 | @example | |
5166 | pushd [@var{dir} | @var{+N} | @var{-N}] [-n] | |
5167 | @end example | |
5168 | ||
5169 | Save the current directory on the top of the directory stack | |
5170 | and then @code{cd} to @var{dir}. | |
5171 | With no arguments, @code{pushd} exchanges the top two directories. | |
5172 | ||
5173 | @table @code | |
5174 | @item +@var{N} | |
5175 | Brings the @var{N}th directory (counting from the left of the | |
5176 | list printed by @code{dirs}, starting with zero) to the top of | |
5177 | the list by rotating the stack. | |
5178 | @item -@var{N} | |
5179 | Brings the @var{N}th directory (counting from the right of the | |
5180 | list printed by @code{dirs}, starting with zero) to the top of | |
5181 | the list by rotating the stack. | |
5182 | @item -n | |
5183 | Suppresses the normal change of directory when adding directories | |
5184 | to the stack, so that only the stack is manipulated. | |
5185 | @item @var{dir} | |
5186 | Makes the current working directory be the top of the stack, and then | |
5187 | executes the equivalent of `@code{cd} @var{dir}'. | |
5188 | @code{cd}s to @var{dir}. | |
5189 | @end table | |
5190 | ||
5191 | @end table | |
5192 | ||
5193 | @node Printing a Prompt | |
5194 | @section Controlling the Prompt | |
5195 | @cindex prompting | |
ccc6cda3 | 5196 | |
28ef6c31 JA |
5197 | The value of the variable @env{PROMPT_COMMAND} is examined just before |
5198 | Bash prints each primary prompt. If @env{PROMPT_COMMAND} is set and | |
bb70624e JA |
5199 | has a non-null value, then the |
5200 | value is executed just as if it had been typed on the command line. | |
ccc6cda3 | 5201 | |
bb70624e JA |
5202 | In addition, the following table describes the special characters which |
5203 | can appear in the prompt variables: | |
ccc6cda3 | 5204 | |
bb70624e JA |
5205 | @table @code |
5206 | @item \a | |
5207 | A bell character. | |
5208 | @item \d | |
5209 | The date, in "Weekday Month Date" format (e.g., "Tue May 26"). | |
5210 | @item \e | |
5211 | An escape character. | |
5212 | @item \h | |
5213 | The hostname, up to the first `.'. | |
5214 | @item \H | |
5215 | The hostname. | |
5216 | @item \j | |
5217 | The number of jobs currently managed by the shell. | |
5218 | @item \l | |
5219 | The basename of the shell's terminal device name. | |
5220 | @item \n | |
5221 | A newline. | |
5222 | @item \r | |
5223 | A carriage return. | |
5224 | @item \s | |
5225 | The name of the shell, the basename of @code{$0} (the portion | |
5226 | following the final slash). | |
5227 | @item \t | |
5228 | The time, in 24-hour HH:MM:SS format. | |
5229 | @item \T | |
5230 | The time, in 12-hour HH:MM:SS format. | |
5231 | @item \@@ | |
5232 | The time, in 12-hour am/pm format. | |
5233 | @item \u | |
5234 | The username of the current user. | |
5235 | @item \v | |
5236 | The version of Bash (e.g., 2.00) | |
5237 | @item \V | |
5238 | The release of Bash, version + patchlevel (e.g., 2.00.0) | |
5239 | @item \w | |
5240 | The current working directory. | |
5241 | @item \W | |
28ef6c31 | 5242 | The basename of @env{$PWD}. |
bb70624e JA |
5243 | @item \! |
5244 | The history number of this command. | |
5245 | @item \# | |
5246 | The command number of this command. | |
5247 | @item \$ | |
5248 | If the effective uid is 0, @code{#}, otherwise @code{$}. | |
5249 | @item \@var{nnn} | |
5250 | The character whose ASCII code is the octal value @var{nnn}. | |
5251 | @item \\ | |
5252 | A backslash. | |
5253 | @item \[ | |
5254 | Begin a sequence of non-printing characters. This could be used to | |
5255 | embed a terminal control sequence into the prompt. | |
5256 | @item \] | |
5257 | End a sequence of non-printing characters. | |
5258 | @end table | |
ccc6cda3 | 5259 | |
bb70624e JA |
5260 | The command number and the history number are usually different: |
5261 | the history number of a command is its position in the history | |
5262 | list, which may include commands restored from the history file | |
5263 | (@pxref{Bash History Facilities}), while the command number is | |
5264 | the position in the sequence of commands executed during the current | |
5265 | shell session. | |
ccc6cda3 | 5266 | |
bb70624e JA |
5267 | After the string is decoded, it is expanded via |
5268 | parameter expansion, command substitution, arithmetic | |
5269 | expansion, and quote removal, subject to the value of the | |
5270 | @code{promptvars} shell option (@pxref{Bash Builtins}). | |
ccc6cda3 | 5271 | |
bb70624e JA |
5272 | @node The Restricted Shell |
5273 | @section The Restricted Shell | |
5274 | @cindex restricted shell | |
ccc6cda3 | 5275 | |
bb70624e | 5276 | If Bash is started with the name @code{rbash}, or the |
28ef6c31 | 5277 | @option{--restricted} |
bb70624e JA |
5278 | option is supplied at invocation, the shell becomes restricted. |
5279 | A restricted shell is used to | |
5280 | set up an environment more controlled than the standard shell. | |
5281 | A restricted shell behaves identically to @code{bash} | |
5282 | with the exception that the following are disallowed: | |
5283 | @itemize @bullet | |
5284 | @item | |
5285 | Changing directories with the @code{cd} builtin. | |
5286 | @item | |
28ef6c31 JA |
5287 | Setting or unsetting the values of the @env{SHELL}, @env{PATH}, |
5288 | @env{ENV}, or @env{BASH_ENV} variables. | |
bb70624e JA |
5289 | @item |
5290 | Specifying command names containing slashes. | |
5291 | @item | |
5292 | Specifying a filename containing a slash as an argument to the @code{.} | |
5293 | builtin command. | |
5294 | @item | |
28ef6c31 | 5295 | Specifying a filename containing a slash as an argument to the @option{-p} |
bb70624e JA |
5296 | option to the @code{hash} builtin command. |
5297 | @item | |
5298 | Importing function definitions from the shell environment at startup. | |
5299 | @item | |
28ef6c31 | 5300 | Parsing the value of @env{SHELLOPTS} from the shell environment at startup. |
bb70624e JA |
5301 | @item |
5302 | Redirecting output using the @samp{>}, @samp{>|}, @samp{<>}, @samp{>&}, | |
5303 | @samp{&>}, and @samp{>>} redirection operators. | |
5304 | @item | |
5305 | Using the @code{exec} builtin to replace the shell with another command. | |
5306 | @item | |
5307 | Adding or deleting builtin commands with the | |
28ef6c31 | 5308 | @option{-f} and @option{-d} options to the @code{enable} builtin. |
bb70624e | 5309 | @item |
28ef6c31 | 5310 | Specifying the @option{-p} option to the @code{command} builtin. |
bb70624e JA |
5311 | @item |
5312 | Turning off restricted mode with @samp{set +r} or @samp{set +o restricted}. | |
5313 | @end itemize | |
cce855bc | 5314 | |
bb70624e JA |
5315 | @node Bash POSIX Mode |
5316 | @section Bash POSIX Mode | |
5317 | @cindex POSIX Mode | |
cce855bc | 5318 | |
28ef6c31 | 5319 | Starting Bash with the @option{--posix} command-line option or executing |
bb70624e JA |
5320 | @samp{set -o posix} while Bash is running will cause Bash to conform more |
5321 | closely to the @sc{posix} 1003.2 standard by changing the behavior to | |
5322 | match that specified by @sc{posix} in areas where the Bash default differs. | |
ccc6cda3 | 5323 | |
bb70624e | 5324 | The following list is what's changed when `@sc{posix} mode' is in effect: |
ccc6cda3 | 5325 | |
bb70624e JA |
5326 | @enumerate |
5327 | @item | |
5328 | When a command in the hash table no longer exists, Bash will re-search | |
28ef6c31 | 5329 | @env{$PATH} to find the new location. This is also available with |
bb70624e | 5330 | @samp{shopt -s checkhash}. |
ccc6cda3 | 5331 | |
bb70624e | 5332 | @item |
28ef6c31 JA |
5333 | The message printed by the job control code and builtins when a job |
5334 | exits with a non-zero status is `Done(status)'. | |
ccc6cda3 | 5335 | |
bb70624e JA |
5336 | @item |
5337 | The message printed by the job control code and builtins when a job | |
28ef6c31 JA |
5338 | is stopped is `Stopped(@var{signame})', where @var{signame} is, for |
5339 | example, @code{SIGTSTP}. | |
ccc6cda3 | 5340 | |
bb70624e JA |
5341 | @item |
5342 | Reserved words may not be aliased. | |
ccc6cda3 | 5343 | |
bb70624e | 5344 | @item |
28ef6c31 | 5345 | The @sc{posix} 1003.2 @env{PS1} and @env{PS2} expansions of @samp{!} to |
bb70624e | 5346 | the history number and @samp{!!} to @samp{!} are enabled, |
28ef6c31 JA |
5347 | and parameter expansion is performed on the values of @env{PS1} and |
5348 | @env{PS2} regardless of the setting of the @code{promptvars} option. | |
ccc6cda3 | 5349 | |
bb70624e JA |
5350 | @item |
5351 | Interactive comments are enabled by default. (Bash has them on by | |
5352 | default anyway.) | |
d166f048 | 5353 | |
bb70624e | 5354 | @item |
28ef6c31 | 5355 | The @sc{posix} 1003.2 startup files are executed (@env{$ENV}) rather than |
bb70624e | 5356 | the normal Bash files. |
ccc6cda3 | 5357 | |
bb70624e JA |
5358 | @item |
5359 | Tilde expansion is only performed on assignments preceding a command | |
5360 | name, rather than on all assignment statements on the line. | |
cce855bc | 5361 | |
bb70624e JA |
5362 | @item |
5363 | The default history file is @file{~/.sh_history} (this is the | |
28ef6c31 | 5364 | default value of @env{$HISTFILE}). |
ccc6cda3 | 5365 | |
bb70624e JA |
5366 | @item |
5367 | The output of @samp{kill -l} prints all the signal names on a single line, | |
5368 | separated by spaces. | |
ccc6cda3 | 5369 | |
bb70624e JA |
5370 | @item |
5371 | Non-interactive shells exit if @var{filename} in @code{.} @var{filename} | |
5372 | is not found. | |
ccc6cda3 | 5373 | |
bb70624e JA |
5374 | @item |
5375 | Non-interactive shells exit if a syntax error in an arithmetic expansion | |
5376 | results in an invalid expression. | |
ccc6cda3 | 5377 | |
bb70624e JA |
5378 | @item |
5379 | Redirection operators do not perform filename expansion on the word | |
5380 | in the redirection unless the shell is interactive. | |
ccc6cda3 | 5381 | |
bb70624e JA |
5382 | @item |
5383 | Redirection operators do not perform word splitting on the word in the | |
5384 | redirection. | |
ccc6cda3 | 5385 | |
bb70624e JA |
5386 | @item |
5387 | Function names must be valid shell @code{name}s. That is, they may not | |
5388 | contain characters other than letters, digits, and underscores, and | |
5389 | may not start with a digit. Declaring a function with an invalid name | |
5390 | causes a fatal syntax error in non-interactive shells. | |
ccc6cda3 | 5391 | |
bb70624e JA |
5392 | @item |
5393 | @sc{posix} 1003.2 `special' builtins are found before shell functions | |
5394 | during command lookup. | |
cce855bc | 5395 | |
bb70624e JA |
5396 | @item |
5397 | If a @sc{posix} 1003.2 special builtin returns an error status, a | |
5398 | non-interactive shell exits. The fatal errors are those listed in | |
5399 | the POSIX.2 standard, and include things like passing incorrect options, | |
5400 | redirection errors, variable assignment errors for assignments preceding | |
5401 | the command name, and so on. | |
ccc6cda3 | 5402 | |
bb70624e JA |
5403 | @item |
5404 | If the @code{cd} builtin finds a directory to change to | |
28ef6c31 JA |
5405 | using @env{$CDPATH}, the |
5406 | value it assigns to the @env{PWD} variable does not contain any | |
bb70624e JA |
5407 | symbolic links, as if @samp{cd -P} had been executed. |
5408 | ||
5409 | @item | |
28ef6c31 | 5410 | If @env{CDPATH} is set, the @code{cd} builtin will not implicitly |
bb70624e JA |
5411 | append the current directory to it. This means that @code{cd} will |
5412 | fail if no valid directory name can be constructed from | |
28ef6c31 | 5413 | any of the entries in @env{$CDPATH}, even if the a directory with |
bb70624e JA |
5414 | the same name as the name given as an argument to @code{cd} exists |
5415 | in the current directory. | |
ccc6cda3 | 5416 | |
bb70624e JA |
5417 | @item |
5418 | A non-interactive shell exits with an error status if a variable | |
5419 | assignment error occurs when no command name follows the assignment | |
5420 | statements. | |
5421 | A variable assignment error occurs, for example, when trying to assign | |
5422 | a value to a readonly variable. | |
ccc6cda3 | 5423 | |
bb70624e JA |
5424 | @item |
5425 | A non-interactive shell exits with an error status if the iteration | |
5426 | variable in a @code{for} statement or the selection variable in a | |
5427 | @code{select} statement is a readonly variable. | |
ccc6cda3 | 5428 | |
bb70624e JA |
5429 | @item |
5430 | Process substitution is not available. | |
ccc6cda3 | 5431 | |
bb70624e JA |
5432 | @item |
5433 | Assignment statements preceding @sc{posix} 1003.2 special builtins | |
5434 | persist in the shell environment after the builtin completes. | |
ccc6cda3 | 5435 | |
28ef6c31 JA |
5436 | @item |
5437 | Assignment statements preceding shell function calls persist in the | |
5438 | shell environment after the function returns, as if a @sc{posix} | |
5439 | special builtin command had been executed. | |
5440 | ||
bb70624e JA |
5441 | @item |
5442 | The @code{export} and @code{readonly} builtin commands display their | |
5443 | output in the format required by @sc{posix} 1003.2. | |
ccc6cda3 | 5444 | |
28ef6c31 JA |
5445 | @item |
5446 | The @code{trap} builtin displays signal names without the leading | |
5447 | @code{SIG}. | |
5448 | ||
5449 | @item | |
5450 | The @code{.} and @code{source} builtins do not search the current directory | |
5451 | for the filename argument if it is not found by searching @env{PATH}. | |
5452 | ||
5453 | @item | |
5454 | Subshells spawned to execute command substitutions inherit the value of | |
5455 | the @option{-e} option from the parent shell. When not in @sc{posix} mode, | |
5456 | Bash clears the @option{-e} option in such subshells. | |
5457 | ||
5458 | @item | |
5459 | Alias expansion is always enabled, even in non-interactive shells. | |
5460 | ||
5461 | @item | |
5462 | When the @code{set} builtin is invoked without options, it does not display | |
5463 | shell function names and definitions. | |
5464 | ||
bb70624e | 5465 | @end enumerate |
ccc6cda3 | 5466 | |
bb70624e JA |
5467 | There is other @sc{posix} 1003.2 behavior that Bash does not implement. |
5468 | Specifically: | |
ccc6cda3 | 5469 | |
bb70624e JA |
5470 | @enumerate |
5471 | @item | |
5472 | Assignment statements affect the execution environment of all | |
5473 | builtins, not just special ones. | |
28ef6c31 JA |
5474 | |
5475 | @item | |
5476 | When a subshell is created to execute a shell script with execute permission, | |
5477 | but without a leading @samp{#!}, Bash sets @code{$0} to the full pathname of | |
5478 | the script as found by searching @code{$PATH}, rather than the command as | |
5479 | typed by the user. | |
5480 | ||
5481 | @item | |
5482 | When using @samp{.} to source a shell script found in @code{$PATH}, bash | |
5483 | checks execute permission bits rather than read permission bits, just as | |
5484 | if it were searching for a command. | |
5485 | ||
bb70624e | 5486 | @end enumerate |
ccc6cda3 | 5487 | |
bb70624e JA |
5488 | @node Job Control |
5489 | @chapter Job Control | |
ccc6cda3 | 5490 | |
bb70624e JA |
5491 | This chapter discusses what job control is, how it works, and how |
5492 | Bash allows you to access its facilities. | |
ccc6cda3 | 5493 | |
bb70624e JA |
5494 | @menu |
5495 | * Job Control Basics:: How job control works. | |
5496 | * Job Control Builtins:: Bash builtin commands used to interact | |
5497 | with job control. | |
5498 | * Job Control Variables:: Variables Bash uses to customize job | |
5499 | control. | |
5500 | @end menu | |
ccc6cda3 | 5501 | |
bb70624e JA |
5502 | @node Job Control Basics |
5503 | @section Job Control Basics | |
5504 | @cindex job control | |
5505 | @cindex foreground | |
5506 | @cindex background | |
5507 | @cindex suspending jobs | |
ccc6cda3 | 5508 | |
bb70624e JA |
5509 | Job control |
5510 | refers to the ability to selectively stop (suspend) | |
5511 | the execution of processes and continue (resume) | |
5512 | their execution at a later point. A user typically employs | |
5513 | this facility via an interactive interface supplied jointly | |
5514 | by the system's terminal driver and Bash. | |
ccc6cda3 | 5515 | |
bb70624e JA |
5516 | The shell associates a @var{job} with each pipeline. It keeps a |
5517 | table of currently executing jobs, which may be listed with the | |
5518 | @code{jobs} command. When Bash starts a job | |
5519 | asynchronously, it prints a line that looks | |
5520 | like: | |
5521 | @example | |
5522 | [1] 25647 | |
5523 | @end example | |
5524 | @noindent | |
5525 | indicating that this job is job number 1 and that the process @sc{id} | |
5526 | of the last process in the pipeline associated with this job is | |
5527 | 25647. All of the processes in a single pipeline are members of | |
5528 | the same job. Bash uses the @var{job} abstraction as the | |
5529 | basis for job control. | |
ccc6cda3 | 5530 | |
bb70624e JA |
5531 | To facilitate the implementation of the user interface to job |
5532 | control, the operating system maintains the notion of a current terminal | |
5533 | process group @sc{id}. Members of this process group (processes whose | |
5534 | process group @sc{id} is equal to the current terminal process group | |
5535 | @sc{id}) receive keyboard-generated signals such as @code{SIGINT}. | |
5536 | These processes are said to be in the foreground. Background | |
5537 | processes are those whose process group @sc{id} differs from the | |
5538 | terminal's; such processes are immune to keyboard-generated | |
5539 | signals. Only foreground processes are allowed to read from or | |
5540 | write to the terminal. Background processes which attempt to | |
5541 | read from (write to) the terminal are sent a @code{SIGTTIN} | |
5542 | (@code{SIGTTOU}) signal by the terminal driver, which, unless | |
5543 | caught, suspends the process. | |
ccc6cda3 | 5544 | |
bb70624e JA |
5545 | If the operating system on which Bash is running supports |
5546 | job control, Bash contains facilities to use it. Typing the | |
5547 | @var{suspend} character (typically @samp{^Z}, Control-Z) while a | |
5548 | process is running causes that process to be stopped and returns | |
5549 | control to Bash. Typing the @var{delayed suspend} character | |
5550 | (typically @samp{^Y}, Control-Y) causes the process to be stopped | |
5551 | when it attempts to read input from the terminal, and control to | |
5552 | be returned to Bash. The user then manipulates the state of | |
5553 | this job, using the @code{bg} command to continue it in the | |
5554 | background, the @code{fg} command to continue it in the | |
5555 | foreground, or the @code{kill} command to kill it. A @samp{^Z} | |
5556 | takes effect immediately, and has the additional side effect of | |
5557 | causing pending output and typeahead to be discarded. | |
ccc6cda3 | 5558 | |
bb70624e JA |
5559 | There are a number of ways to refer to a job in the shell. The |
5560 | character @samp{%} introduces a job name. | |
cce855bc | 5561 | |
bb70624e JA |
5562 | Job number @code{n} may be referred to as @samp{%n}. |
5563 | The symbols @samp{%%} and | |
5564 | @samp{%+} refer to the shell's notion of the current job, which | |
5565 | is the last job stopped while it was in the foreground or started | |
5566 | in the background. The | |
5567 | previous job may be referenced using @samp{%-}. In output | |
5568 | pertaining to jobs (e.g., the output of the @code{jobs} command), | |
5569 | the current job is always flagged with a @samp{+}, and the | |
5570 | previous job with a @samp{-}. | |
cce855bc | 5571 | |
bb70624e JA |
5572 | A job may also be referred to |
5573 | using a prefix of the name used to start it, or using a substring | |
5574 | that appears in its command line. For example, @samp{%ce} refers | |
5575 | to a stopped @code{ce} job. Using @samp{%?ce}, on the | |
5576 | other hand, refers to any job containing the string @samp{ce} in | |
5577 | its command line. If the prefix or substring matches more than one job, | |
5578 | Bash reports an error. | |
cce855bc | 5579 | |
bb70624e JA |
5580 | Simply naming a job can be used to bring it into the foreground: |
5581 | @samp{%1} is a synonym for @samp{fg %1}, bringing job 1 from the | |
5582 | background into the foreground. Similarly, @samp{%1 &} resumes | |
5583 | job 1 in the background, equivalent to @samp{bg %1} | |
cce855bc | 5584 | |
bb70624e JA |
5585 | The shell learns immediately whenever a job changes state. |
5586 | Normally, Bash waits until it is about to print a prompt | |
5587 | before reporting changes in a job's status so as to not interrupt | |
5588 | any other output. If the | |
28ef6c31 | 5589 | the @option{-b} option to the @code{set} builtin is enabled, |
bb70624e | 5590 | Bash reports such changes immediately (@pxref{The Set Builtin}). |
ccc6cda3 | 5591 | |
bb70624e JA |
5592 | If an attempt to exit Bash is while jobs are stopped, the |
5593 | shell prints a message warning that there are stopped jobs. | |
5594 | The @code{jobs} command may then be used to inspect their status. | |
5595 | If a second attempt to exit is made without an intervening command, | |
5596 | Bash does not print another warning, and the stopped jobs are terminated. | |
ccc6cda3 | 5597 | |
bb70624e JA |
5598 | @node Job Control Builtins |
5599 | @section Job Control Builtins | |
ccc6cda3 JA |
5600 | |
5601 | @table @code | |
5602 | ||
bb70624e JA |
5603 | @item bg |
5604 | @btindex bg | |
ccc6cda3 | 5605 | @example |
bb70624e | 5606 | bg [@var{jobspec}] |
ccc6cda3 | 5607 | @end example |
bb70624e JA |
5608 | Resume the suspended job @var{jobspec} in the background, as if it |
5609 | had been started with @samp{&}. | |
5610 | If @var{jobspec} is not supplied, the current job is used. | |
5611 | The return status is zero unless it is run when job control is not | |
5612 | enabled, or, when run with job control enabled, if @var{jobspec} was | |
5613 | not found or @var{jobspec} specifies a job that was started without | |
5614 | job control. | |
cce855bc | 5615 | |
bb70624e JA |
5616 | @item fg |
5617 | @btindex fg | |
5618 | @example | |
5619 | fg [@var{jobspec}] | |
5620 | @end example | |
5621 | Resume the job @var{jobspec} in the foreground and make it the current job. | |
5622 | If @var{jobspec} is not supplied, the current job is used. | |
5623 | The return status is that of the command placed into the foreground, | |
5624 | or non-zero if run when job control is disabled or, when run with | |
5625 | job control enabled, @var{jobspec} does not specify a valid job or | |
5626 | @var{jobspec} specifies a job that was started without job control. | |
cce855bc | 5627 | |
bb70624e JA |
5628 | @item jobs |
5629 | @btindex jobs | |
cce855bc | 5630 | @example |
bb70624e JA |
5631 | jobs [-lnprs] [@var{jobspec}] |
5632 | jobs -x @var{command} [@var{arguments}] | |
cce855bc JA |
5633 | @end example |
5634 | ||
bb70624e JA |
5635 | The first form lists the active jobs. The options have the |
5636 | following meanings: | |
5637 | ||
5638 | @table @code | |
5639 | @item -l | |
5640 | List process @sc{id}s in addition to the normal information. | |
5641 | ||
5642 | @item -n | |
5643 | Display information only about jobs that have changed status since | |
5644 | the user was last notified of their status. | |
5645 | ||
5646 | @item -p | |
5647 | List only the process @sc{id} of the job's process group leader. | |
5648 | ||
5649 | @item -r | |
5650 | Restrict output to running jobs. | |
5651 | ||
5652 | @item -s | |
5653 | Restrict output to stopped jobs. | |
ccc6cda3 JA |
5654 | @end table |
5655 | ||
bb70624e JA |
5656 | If @var{jobspec} is given, |
5657 | output is restricted to information about that job. | |
5658 | If @var{jobspec} is not supplied, the status of all jobs is | |
5659 | listed. | |
ccc6cda3 | 5660 | |
28ef6c31 | 5661 | If the @option{-x} option is supplied, @code{jobs} replaces any |
bb70624e JA |
5662 | @var{jobspec} found in @var{command} or @var{arguments} with the |
5663 | corresponding process group @sc{id}, and executes @var{command}, | |
5664 | passing it @var{argument}s, returning its exit status. | |
ccc6cda3 | 5665 | |
bb70624e JA |
5666 | @item kill |
5667 | @btindex kill | |
ccc6cda3 | 5668 | @example |
bb70624e JA |
5669 | kill [-s @var{sigspec}] [-n @var{signum}] [-@var{sigspec}] @var{jobspec} or @var{pid} |
5670 | kill -l [@var{exit_status}] | |
ccc6cda3 | 5671 | @end example |
bb70624e JA |
5672 | Send a signal specified by @var{sigspec} or @var{signum} to the process |
5673 | named by job specification @var{jobspec} or process @sc{id} @var{pid}. | |
5674 | @var{sigspec} is either a signal name such as @code{SIGINT} (with or without | |
5675 | the @code{SIG} prefix) or a signal number; @var{signum} is a signal number. | |
5676 | If @var{sigspec} and @var{signum} are not present, @code{SIGTERM} is used. | |
28ef6c31 JA |
5677 | The @option{-l} option lists the signal names. |
5678 | If any arguments are supplied when @option{-l} is given, the names of the | |
bb70624e JA |
5679 | signals corresponding to the arguments are listed, and the return status |
5680 | is zero. | |
5681 | @var{exit_status} is a number specifying a signal number or the exit | |
5682 | status of a process terminated by a signal. | |
5683 | The return status is zero if at least one signal was successfully sent, | |
5684 | or non-zero if an error occurs or an invalid option is encountered. | |
ccc6cda3 | 5685 | |
bb70624e JA |
5686 | @item wait |
5687 | @btindex wait | |
ccc6cda3 | 5688 | @example |
bb70624e | 5689 | wait [@var{jobspec} or @var{pid}] |
ccc6cda3 | 5690 | @end example |
bb70624e JA |
5691 | Wait until the child process specified by process @sc{id} @var{pid} or job |
5692 | specification @var{jobspec} exits and return the exit status of the last | |
5693 | command waited for. | |
5694 | If a job spec is given, all processes in the job are waited for. | |
5695 | If no arguments are given, all currently active child processes are | |
5696 | waited for, and the return status is zero. | |
5697 | If neither @var{jobspec} nor @var{pid} specifies an active child process | |
5698 | of the shell, the return status is 127. | |
5699 | ||
5700 | @item disown | |
5701 | @btindex disown | |
ccc6cda3 | 5702 | @example |
bb70624e | 5703 | disown [-ar] [-h] [@var{jobspec} @dots{}] |
ccc6cda3 | 5704 | @end example |
bb70624e JA |
5705 | Without options, each @var{jobspec} is removed from the table of |
5706 | active jobs. | |
28ef6c31 | 5707 | If the @option{-h} option is given, the job is not removed from the table, |
bb70624e JA |
5708 | but is marked so that @code{SIGHUP} is not sent to the job if the shell |
5709 | receives a @code{SIGHUP}. | |
28ef6c31 | 5710 | If @var{jobspec} is not present, and neither the @option{-a} nor @option{-r} |
bb70624e | 5711 | option is supplied, the current job is used. |
28ef6c31 JA |
5712 | If no @var{jobspec} is supplied, the @option{-a} option means to remove or |
5713 | mark all jobs; the @option{-r} option without a @var{jobspec} | |
bb70624e | 5714 | argument restricts operation to running jobs. |
ccc6cda3 | 5715 | |
bb70624e JA |
5716 | @item suspend |
5717 | @btindex suspend | |
ccc6cda3 | 5718 | @example |
bb70624e | 5719 | suspend [-f] |
ccc6cda3 | 5720 | @end example |
bb70624e | 5721 | Suspend the execution of this shell until it receives a |
28ef6c31 | 5722 | @code{SIGCONT} signal. The @option{-f} option means to suspend |
bb70624e | 5723 | even if the shell is a login shell. |
ccc6cda3 | 5724 | |
bb70624e | 5725 | @end table |
ccc6cda3 | 5726 | |
bb70624e JA |
5727 | When job control is not active, the @code{kill} and @code{wait} |
5728 | builtins do not accept @var{jobspec} arguments. They must be | |
5729 | supplied process @sc{id}s. | |
ccc6cda3 | 5730 | |
bb70624e JA |
5731 | @node Job Control Variables |
5732 | @section Job Control Variables | |
ccc6cda3 | 5733 | |
bb70624e | 5734 | @vtable @code |
cce855bc | 5735 | |
bb70624e JA |
5736 | @item auto_resume |
5737 | This variable controls how the shell interacts with the user and | |
5738 | job control. If this variable exists then single word simple | |
5739 | commands without redirections are treated as candidates for resumption | |
5740 | of an existing job. There is no ambiguity allowed; if there is | |
5741 | more than one job beginning with the string typed, then | |
5742 | the most recently accessed job will be selected. | |
5743 | The name of a stopped job, in this context, is the command line | |
5744 | used to start it. If this variable is set to the value @samp{exact}, | |
5745 | the string supplied must match the name of a stopped job exactly; | |
5746 | if set to @samp{substring}, | |
5747 | the string supplied needs to match a substring of the name of a | |
5748 | stopped job. The @samp{substring} value provides functionality | |
5749 | analogous to the @samp{%?} job @sc{id} (@pxref{Job Control Basics}). | |
5750 | If set to any other value, the supplied string must | |
5751 | be a prefix of a stopped job's name; this provides functionality | |
5752 | analogous to the @samp{%} job @sc{id}. | |
cce855bc | 5753 | |
bb70624e | 5754 | @end vtable |
cce855bc | 5755 | |
bb70624e JA |
5756 | @set readline-appendix |
5757 | @set history-appendix | |
5758 | @cindex Readline, how to use | |
5759 | @include rluser.texinfo | |
5760 | @cindex History, how to use | |
5761 | @include hsuser.texinfo | |
5762 | @clear readline-appendix | |
5763 | @clear history-appendix | |
cce855bc | 5764 | |
bb70624e JA |
5765 | @node Installing Bash |
5766 | @chapter Installing Bash | |
cce855bc | 5767 | |
bb70624e JA |
5768 | This chapter provides basic instructions for installing Bash on |
5769 | the various supported platforms. The distribution supports the | |
5770 | @sc{gnu} operating systems, nearly every version of Unix, and several | |
5771 | non-Unix systems such as BeOS and Interix. | |
5772 | Other independent ports exist for | |
5773 | @sc{ms-dos}, @sc{os/2}, Windows @sc{95/98}, and Windows @sc{nt}. | |
cce855bc | 5774 | |
bb70624e JA |
5775 | @menu |
5776 | * Basic Installation:: Installation instructions. | |
cce855bc | 5777 | |
bb70624e JA |
5778 | * Compilers and Options:: How to set special options for various |
5779 | systems. | |
cce855bc | 5780 | |
bb70624e JA |
5781 | * Compiling For Multiple Architectures:: How to compile Bash for more |
5782 | than one kind of system from | |
5783 | the same source tree. | |
cce855bc | 5784 | |
bb70624e | 5785 | * Installation Names:: How to set the various paths used by the installation. |
cce855bc | 5786 | |
bb70624e | 5787 | * Specifying the System Type:: How to configure Bash for a particular system. |
cce855bc | 5788 | |
bb70624e JA |
5789 | * Sharing Defaults:: How to share default configuration values among GNU |
5790 | programs. | |
ccc6cda3 | 5791 | |
bb70624e JA |
5792 | * Operation Controls:: Options recognized by the configuration program. |
5793 | ||
5794 | * Optional Features:: How to enable and disable optional features when | |
5795 | building Bash. | |
5796 | @end menu | |
ccc6cda3 | 5797 | |
bb70624e JA |
5798 | @node Basic Installation |
5799 | @section Basic Installation | |
5800 | @cindex installation | |
5801 | @cindex configuration | |
5802 | @cindex Bash installation | |
5803 | @cindex Bash configuration | |
ccc6cda3 | 5804 | |
bb70624e | 5805 | These are installation instructions for Bash. |
ccc6cda3 | 5806 | |
bb70624e | 5807 | The simplest way to compile Bash is: |
ccc6cda3 | 5808 | |
bb70624e | 5809 | @enumerate |
ccc6cda3 | 5810 | @item |
bb70624e JA |
5811 | @code{cd} to the directory containing the source code and type |
5812 | @samp{./configure} to configure Bash for your system. If you're | |
5813 | using @code{csh} on an old version of System V, you might need to | |
5814 | type @samp{sh ./configure} instead to prevent @code{csh} from trying | |
5815 | to execute @code{configure} itself. | |
5816 | ||
5817 | Running @code{configure} takes some time. | |
5818 | While running, it prints messages telling which features it is | |
5819 | checking for. | |
5820 | ||
ccc6cda3 | 5821 | @item |
bb70624e JA |
5822 | Type @samp{make} to compile Bash and build the @code{bashbug} bug |
5823 | reporting script. | |
5824 | ||
ccc6cda3 | 5825 | @item |
bb70624e JA |
5826 | Optionally, type @samp{make tests} to run the Bash test suite. |
5827 | ||
ccc6cda3 | 5828 | @item |
bb70624e JA |
5829 | Type @samp{make install} to install @code{bash} and @code{bashbug}. |
5830 | This will also install the manual pages and Info file. | |
ccc6cda3 | 5831 | |
bb70624e | 5832 | @end enumerate |
ccc6cda3 | 5833 | |
bb70624e JA |
5834 | The @code{configure} shell script attempts to guess correct |
5835 | values for various system-dependent variables used during | |
5836 | compilation. It uses those values to create a @file{Makefile} in | |
5837 | each directory of the package (the top directory, the | |
5838 | @file{builtins}, @file{doc}, and @file{support} directories, | |
5839 | each directory under @file{lib}, and several others). It also creates a | |
5840 | @file{config.h} file containing system-dependent definitions. | |
5841 | Finally, it creates a shell script named @code{config.status} that you | |
5842 | can run in the future to recreate the current configuration, a | |
5843 | file @file{config.cache} that saves the results of its tests to | |
5844 | speed up reconfiguring, and a file @file{config.log} containing | |
5845 | compiler output (useful mainly for debugging @code{configure}). | |
5846 | If at some point | |
5847 | @file{config.cache} contains results you don't want to keep, you | |
5848 | may remove or edit it. | |
ccc6cda3 | 5849 | |
bb70624e JA |
5850 | To find out more about the options and arguments that the |
5851 | @code{configure} script understands, type | |
ccc6cda3 | 5852 | |
bb70624e JA |
5853 | @example |
5854 | bash-2.04$ ./configure --help | |
5855 | @end example | |
ccc6cda3 | 5856 | |
bb70624e JA |
5857 | @noindent |
5858 | at the Bash prompt in your Bash source directory. | |
ccc6cda3 | 5859 | |
bb70624e JA |
5860 | If you need to do unusual things to compile Bash, please |
5861 | try to figure out how @code{configure} could check whether or not | |
5862 | to do them, and mail diffs or instructions to | |
5863 | @email{bash-maintainers@@gnu.org} so they can be | |
5864 | considered for the next release. | |
ccc6cda3 | 5865 | |
bb70624e JA |
5866 | The file @file{configure.in} is used to create @code{configure} |
5867 | by a program called Autoconf. You only need | |
5868 | @file{configure.in} if you want to change it or regenerate | |
5869 | @code{configure} using a newer version of Autoconf. If | |
5870 | you do this, make sure you are using Autoconf version 2.10 or | |
5871 | newer. | |
ccc6cda3 | 5872 | |
bb70624e JA |
5873 | If you need to change @file{configure.in} or regenerate |
5874 | @code{configure}, you will need to create two files: | |
5875 | @file{_distribution} and @file{_patchlevel}. @file{_distribution} | |
5876 | should contain the major and minor version numbers of the Bash | |
5877 | distribution, for example @samp{2.01}. @file{_patchlevel} should | |
5878 | contain the patch level of the Bash distribution, @samp{0} for | |
5879 | example. The script @file{support/mkconffiles} has been provided | |
5880 | to automate the creation of these files. | |
ccc6cda3 | 5881 | |
bb70624e JA |
5882 | You can remove the program binaries and object files from the |
5883 | source code directory by typing @samp{make clean}. To also remove the | |
5884 | files that @code{configure} created (so you can compile Bash for | |
5885 | a different kind of computer), type @samp{make distclean}. | |
ccc6cda3 | 5886 | |
bb70624e JA |
5887 | @node Compilers and Options |
5888 | @section Compilers and Options | |
ccc6cda3 | 5889 | |
bb70624e JA |
5890 | Some systems require unusual options for compilation or linking |
5891 | that the @code{configure} script does not know about. You can | |
5892 | give @code{configure} initial values for variables by setting | |
5893 | them in the environment. Using a Bourne-compatible shell, you | |
5894 | can do that on the command line like this: | |
ccc6cda3 | 5895 | |
bb70624e JA |
5896 | @example |
5897 | CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure | |
5898 | @end example | |
ccc6cda3 | 5899 | |
bb70624e | 5900 | On systems that have the @code{env} program, you can do it like this: |
ccc6cda3 | 5901 | |
bb70624e JA |
5902 | @example |
5903 | env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure | |
5904 | @end example | |
ccc6cda3 | 5905 | |
bb70624e JA |
5906 | The configuration process uses GCC to build Bash if it |
5907 | is available. | |
cce855bc | 5908 | |
bb70624e JA |
5909 | @node Compiling For Multiple Architectures |
5910 | @section Compiling For Multiple Architectures | |
ccc6cda3 | 5911 | |
bb70624e JA |
5912 | You can compile Bash for more than one kind of computer at the |
5913 | same time, by placing the object files for each architecture in their | |
5914 | own directory. To do this, you must use a version of @code{make} that | |
5915 | supports the @code{VPATH} variable, such as GNU @code{make}. | |
5916 | @code{cd} to the | |
5917 | directory where you want the object files and executables to go and run | |
5918 | the @code{configure} script from the source directory. You may need to | |
28ef6c31 | 5919 | supply the @option{--srcdir=PATH} argument to tell @code{configure} where the |
bb70624e JA |
5920 | source files are. @code{configure} automatically checks for the |
5921 | source code in the directory that @code{configure} is in and in `..'. | |
ccc6cda3 | 5922 | |
bb70624e JA |
5923 | If you have to use a @code{make} that does not supports the @code{VPATH} |
5924 | variable, you can compile Bash for one architecture at a | |
5925 | time in the source code directory. After you have installed | |
5926 | Bash for one architecture, use @samp{make distclean} before | |
5927 | reconfiguring for another architecture. | |
ccc6cda3 | 5928 | |
bb70624e JA |
5929 | Alternatively, if your system supports symbolic links, you can use the |
5930 | @file{support/mkclone} script to create a build tree which has | |
5931 | symbolic links back to each file in the source directory. Here's an | |
5932 | example that creates a build directory in the current directory from a | |
5933 | source directory @file{/usr/gnu/src/bash-2.0}: | |
5934 | ||
5935 | @example | |
5936 | bash /usr/gnu/src/bash-2.0/support/mkclone -s /usr/gnu/src/bash-2.0 . | |
5937 | @end example | |
5938 | ||
5939 | @noindent | |
5940 | The @code{mkclone} script requires Bash, so you must have already built | |
5941 | Bash for at least one architecture before you can create build | |
5942 | directories for other architectures. | |
5943 | ||
5944 | @node Installation Names | |
5945 | @section Installation Names | |
ccc6cda3 | 5946 | |
bb70624e JA |
5947 | By default, @samp{make install} will install into |
5948 | @file{/usr/local/bin}, @file{/usr/local/man}, etc. You can | |
5949 | specify an installation prefix other than @file{/usr/local} by | |
28ef6c31 | 5950 | giving @code{configure} the option @option{--prefix=@var{PATH}}. |
ccc6cda3 | 5951 | |
bb70624e JA |
5952 | You can specify separate installation prefixes for |
5953 | architecture-specific files and architecture-independent files. | |
5954 | If you give @code{configure} the option | |
28ef6c31 | 5955 | @option{--exec-prefix=@var{PATH}}, @samp{make install} will use |
bb70624e JA |
5956 | @var{PATH} as the prefix for installing programs and libraries. |
5957 | Documentation and other data files will still use the regular prefix. | |
cce855bc | 5958 | |
bb70624e JA |
5959 | @node Specifying the System Type |
5960 | @section Specifying the System Type | |
ccc6cda3 | 5961 | |
bb70624e JA |
5962 | There may be some features @code{configure} can not figure out |
5963 | automatically, but needs to determine by the type of host Bash | |
5964 | will run on. Usually @code{configure} can figure that | |
5965 | out, but if it prints a message saying it can not guess the host | |
28ef6c31 | 5966 | type, give it the @option{--host=TYPE} option. @samp{TYPE} can |
bb70624e JA |
5967 | either be a short name for the system type, such as @samp{sun4}, |
5968 | or a canonical name with three fields: @samp{CPU-COMPANY-SYSTEM} | |
5969 | (e.g., @samp{sparc-sun-sunos4.1.2}). | |
ccc6cda3 | 5970 | |
bb70624e JA |
5971 | See the file @file{support/config.sub} for the possible |
5972 | values of each field. | |
ccc6cda3 | 5973 | |
bb70624e JA |
5974 | @node Sharing Defaults |
5975 | @section Sharing Defaults | |
ccc6cda3 | 5976 | |
bb70624e JA |
5977 | If you want to set default values for @code{configure} scripts to |
5978 | share, you can create a site shell script called | |
5979 | @code{config.site} that gives default values for variables like | |
5980 | @code{CC}, @code{cache_file}, and @code{prefix}. @code{configure} | |
5981 | looks for @file{PREFIX/share/config.site} if it exists, then | |
5982 | @file{PREFIX/etc/config.site} if it exists. Or, you can set the | |
5983 | @code{CONFIG_SITE} environment variable to the location of the site | |
5984 | script. A warning: the Bash @code{configure} looks for a site script, | |
5985 | but not all @code{configure} scripts do. | |
d166f048 | 5986 | |
bb70624e JA |
5987 | @node Operation Controls |
5988 | @section Operation Controls | |
ccc6cda3 | 5989 | |
bb70624e JA |
5990 | @code{configure} recognizes the following options to control how it |
5991 | operates. | |
ccc6cda3 | 5992 | |
bb70624e | 5993 | @table @code |
ccc6cda3 | 5994 | |
bb70624e JA |
5995 | @item --cache-file=@var{file} |
5996 | Use and save the results of the tests in | |
5997 | @var{file} instead of @file{./config.cache}. Set @var{file} to | |
5998 | @file{/dev/null} to disable caching, for debugging | |
5999 | @code{configure}. | |
ccc6cda3 | 6000 | |
bb70624e JA |
6001 | @item --help |
6002 | Print a summary of the options to @code{configure}, and exit. | |
ccc6cda3 | 6003 | |
bb70624e JA |
6004 | @item --quiet |
6005 | @itemx --silent | |
6006 | @itemx -q | |
6007 | Do not print messages saying which checks are being made. | |
ccc6cda3 | 6008 | |
bb70624e JA |
6009 | @item --srcdir=@var{dir} |
6010 | Look for the Bash source code in directory @var{dir}. Usually | |
6011 | @code{configure} can determine that directory automatically. | |
ccc6cda3 | 6012 | |
bb70624e JA |
6013 | @item --version |
6014 | Print the version of Autoconf used to generate the @code{configure} | |
6015 | script, and exit. | |
6016 | @end table | |
ccc6cda3 | 6017 | |
bb70624e JA |
6018 | @code{configure} also accepts some other, not widely used, boilerplate |
6019 | options. @samp{configure --help} prints the complete list. | |
ccc6cda3 | 6020 | |
bb70624e JA |
6021 | @node Optional Features |
6022 | @section Optional Features | |
ccc6cda3 | 6023 | |
28ef6c31 | 6024 | The Bash @code{configure} has a number of @option{--enable-@var{feature}} |
bb70624e | 6025 | options, where @var{feature} indicates an optional part of Bash. |
28ef6c31 | 6026 | There are also several @option{--with-@var{package}} options, |
bb70624e JA |
6027 | where @var{package} is something like @samp{bash-malloc} or @samp{purify}. |
6028 | To turn off the default use of a package, use | |
28ef6c31 JA |
6029 | @option{--without-@var{package}}. To configure Bash without a feature |
6030 | that is enabled by default, use @option{--disable-@var{feature}}. | |
ccc6cda3 | 6031 | |
28ef6c31 JA |
6032 | Here is a complete list of the @option{--enable-} and |
6033 | @option{--with-} options that the Bash @code{configure} recognizes. | |
ccc6cda3 | 6034 | |
bb70624e JA |
6035 | @table @code |
6036 | @item --with-afs | |
6037 | Define if you are using the Andrew File System from Transarc. | |
ccc6cda3 | 6038 | |
bb70624e JA |
6039 | @item --with-bash-malloc |
6040 | Use the Bash version of | |
6041 | @code{malloc} in @file{lib/malloc/malloc.c}. This is not the same | |
6042 | @code{malloc} that appears in @sc{gnu} libc, but an older version | |
6043 | derived from the 4.2 @sc{bsd} @code{malloc}. This @code{malloc} is | |
6044 | very fast, but wastes some space on each allocation. | |
6045 | This option is enabled by default. | |
6046 | The @file{NOTES} file contains a list of systems for | |
6047 | which this should be turned off, and @code{configure} disables this | |
6048 | option automatically for a number of systems. | |
ccc6cda3 | 6049 | |
bb70624e JA |
6050 | @item --with-curses |
6051 | Use the curses library instead of the termcap library. This should | |
6052 | be supplied if your system has an inadequate or incomplete termcap | |
6053 | database. | |
ccc6cda3 | 6054 | |
bb70624e JA |
6055 | @item --with-glibc-malloc |
6056 | Use the @sc{gnu} libc version of @code{malloc} in | |
6057 | @file{lib/malloc/gmalloc.c}. This is not the version of @code{malloc} | |
6058 | that appears in glibc version 2, but a modified version of the | |
6059 | @code{malloc} from glibc version 1. This is somewhat slower than the | |
6060 | default @code{malloc}, but wastes less space on a per-allocation | |
6061 | basis, and will return memory to the operating system under | |
6062 | certain circumstances. | |
ccc6cda3 | 6063 | |
bb70624e JA |
6064 | @item --with-gnu-malloc |
6065 | A synonym for @code{--with-bash-malloc}. | |
ccc6cda3 | 6066 | |
bb70624e JA |
6067 | @item --with-installed-readline |
6068 | Define this to make Bash link with a locally-installed version of Readline | |
6069 | rather than the version in @file{lib/readline}. This works only with | |
6070 | Readline 4.1 and later versions. | |
ccc6cda3 | 6071 | |
bb70624e JA |
6072 | @item --with-purify |
6073 | Define this to use the Purify memory allocation checker from Rational | |
6074 | Software. | |
ccc6cda3 | 6075 | |
bb70624e JA |
6076 | @item --enable-minimal-config |
6077 | This produces a shell with minimal features, close to the historical | |
6078 | Bourne shell. | |
6079 | @end table | |
ccc6cda3 | 6080 | |
28ef6c31 | 6081 | There are several @option{--enable-} options that alter how Bash is |
bb70624e | 6082 | compiled and linked, rather than changing run-time features. |
ccc6cda3 JA |
6083 | |
6084 | @table @code | |
bb70624e JA |
6085 | @item --enable-profiling |
6086 | This builds a Bash binary that produces profiling information to be | |
6087 | processed by @code{gprof} each time it is executed. | |
ccc6cda3 | 6088 | |
bb70624e JA |
6089 | @item --enable-static-link |
6090 | This causes Bash to be linked statically, if @code{gcc} is being used. | |
6091 | This could be used to build a version to use as root's shell. | |
6092 | @end table | |
6093 | ||
6094 | The @samp{minimal-config} option can be used to disable all of | |
6095 | the following options, but it is processed first, so individual | |
6096 | options may be enabled using @samp{enable-@var{feature}}. | |
6097 | ||
6098 | All of the following options except for @samp{disabled-builtins} and | |
6099 | @samp{xpg-echo-default} are | |
6100 | enabled by default, unless the operating system does not provide the | |
6101 | necessary support. | |
6102 | ||
6103 | @table @code | |
6104 | @item --enable-alias | |
6105 | Allow alias expansion and include the @code{alias} and @code{unalias} | |
6106 | builtins (@pxref{Aliases}). | |
ccc6cda3 | 6107 | |
bb70624e JA |
6108 | @item --enable-arith-for-command |
6109 | Include support for the alternate form of the @code{for} command | |
6110 | that behaves like the C language @code{for} statement | |
6111 | (@pxref{Looping Constructs}). | |
ccc6cda3 | 6112 | |
bb70624e JA |
6113 | @item --enable-array-variables |
6114 | Include support for one-dimensional array shell variables | |
6115 | (@pxref{Arrays}). | |
ccc6cda3 | 6116 | |
bb70624e JA |
6117 | @item --enable-bang-history |
6118 | Include support for @code{csh}-like history substitution | |
6119 | (@pxref{History Interaction}). | |
ccc6cda3 | 6120 | |
bb70624e JA |
6121 | @item --enable-brace-expansion |
6122 | Include @code{csh}-like brace expansion | |
6123 | ( @code{b@{a,b@}c} @expansion{} @code{bac bbc} ). | |
6124 | See @ref{Brace Expansion}, for a complete description. | |
ccc6cda3 | 6125 | |
bb70624e JA |
6126 | @item --enable-command-timing |
6127 | Include support for recognizing @code{time} as a reserved word and for | |
6128 | displaying timing statistics for the pipeline following @code{time} | |
6129 | (@pxref{Pipelines}). | |
6130 | This allows pipelines as well as shell builtins and functions to be timed. | |
ccc6cda3 | 6131 | |
bb70624e JA |
6132 | @item --enable-cond-command |
6133 | Include support for the @code{[[} conditional command | |
6134 | (@pxref{Conditional Constructs}). | |
ccc6cda3 | 6135 | |
bb70624e JA |
6136 | @item --enable-directory-stack |
6137 | Include support for a @code{csh}-like directory stack and the | |
6138 | @code{pushd}, @code{popd}, and @code{dirs} builtins | |
6139 | (@pxref{The Directory Stack}). | |
ccc6cda3 | 6140 | |
bb70624e JA |
6141 | @item --enable-disabled-builtins |
6142 | Allow builtin commands to be invoked via @samp{builtin xxx} | |
6143 | even after @code{xxx} has been disabled using @samp{enable -n xxx}. | |
6144 | See @ref{Bash Builtins}, for details of the @code{builtin} and | |
6145 | @code{enable} builtin commands. | |
ccc6cda3 | 6146 | |
bb70624e JA |
6147 | @item --enable-dparen-arithmetic |
6148 | Include support for the @code{((@dots{}))} command | |
6149 | (@pxref{Conditional Constructs}). | |
ccc6cda3 | 6150 | |
bb70624e JA |
6151 | @item --enable-extended-glob |
6152 | Include support for the extended pattern matching features described | |
6153 | above under @ref{Pattern Matching}. | |
ccc6cda3 | 6154 | |
bb70624e JA |
6155 | @item --enable-help-builtin |
6156 | Include the @code{help} builtin, which displays help on shell builtins and | |
6157 | variables (@pxref{Bash Builtins}). | |
ccc6cda3 | 6158 | |
bb70624e JA |
6159 | @item --enable-history |
6160 | Include command history and the @code{fc} and @code{history} | |
6161 | builtin commands (@pxref{Bash History Facilities}). | |
ccc6cda3 | 6162 | |
bb70624e JA |
6163 | @item --enable-job-control |
6164 | This enables the job control features (@pxref{Job Control}), | |
6165 | if the operating system supports them. | |
ccc6cda3 | 6166 | |
bb70624e JA |
6167 | @item --enable-net-redirections |
6168 | This enables the special handling of filenames of the form | |
6169 | @code{/dev/tcp/@var{host}/@var{port}} and | |
6170 | @code{/dev/udp/@var{host}/@var{port}} | |
6171 | when used in redirections (@pxref{Redirections}). | |
ccc6cda3 | 6172 | |
bb70624e JA |
6173 | @item --enable-process-substitution |
6174 | This enables process substitution (@pxref{Process Substitution}) if | |
6175 | the operating system provides the necessary support. | |
ccc6cda3 | 6176 | |
bb70624e JA |
6177 | @item --enable-prompt-string-decoding |
6178 | Turn on the interpretation of a number of backslash-escaped characters | |
28ef6c31 | 6179 | in the @env{$PS1}, @env{$PS2}, @env{$PS3}, and @env{$PS4} prompt |
bb70624e JA |
6180 | strings. See @ref{Printing a Prompt}, for a complete list of prompt |
6181 | string escape sequences. | |
ccc6cda3 | 6182 | |
bb70624e JA |
6183 | @item --enable-progcomp |
6184 | Enable the programmable completion facilities | |
6185 | (@pxref{Programmable Completion}). | |
6186 | If Readline is not enabled, this option has no effect. | |
ccc6cda3 | 6187 | |
bb70624e JA |
6188 | @item --enable-readline |
6189 | Include support for command-line editing and history with the Bash | |
6190 | version of the Readline library (@pxref{Command Line Editing}). | |
ccc6cda3 | 6191 | |
bb70624e JA |
6192 | @item --enable-restricted |
6193 | Include support for a @dfn{restricted shell}. If this is enabled, Bash, | |
6194 | when called as @code{rbash}, enters a restricted mode. See | |
6195 | @ref{The Restricted Shell}, for a description of restricted mode. | |
ccc6cda3 | 6196 | |
bb70624e JA |
6197 | @item --enable-select |
6198 | Include the @code{select} builtin, which allows the generation of simple | |
6199 | menus (@pxref{Conditional Constructs}). | |
ccc6cda3 | 6200 | |
bb70624e JA |
6201 | @item --enable-usg-echo-default |
6202 | A synonym for @code{--enable-xpg-echo-default}. | |
ccc6cda3 | 6203 | |
bb70624e JA |
6204 | @item --enable-xpg-echo-default |
6205 | Make the @code{echo} builtin expand backslash-escaped characters by default, | |
28ef6c31 | 6206 | without requiring the @option{-e} option. |
bb70624e JA |
6207 | This sets the default value of the @code{xpg_echo} shell option to @code{on}, |
6208 | which makes the Bash @code{echo} behave more like the version specified in | |
6209 | the Single Unix Specification, version 2. | |
6210 | @xref{Bash Builtins}, for a description of the escape sequences that | |
6211 | @code{echo} recognizes. | |
ccc6cda3 | 6212 | |
bb70624e | 6213 | @end table |
ccc6cda3 | 6214 | |
bb70624e JA |
6215 | The file @file{config-top.h} contains C Preprocessor |
6216 | @samp{#define} statements for options which are not settable from | |
6217 | @code{configure}. | |
6218 | Some of these are not meant to be changed; beware of the consequences if | |
6219 | you do. | |
6220 | Read the comments associated with each definition for more | |
6221 | information about its effect. | |
ccc6cda3 | 6222 | |
bb70624e JA |
6223 | @node Reporting Bugs |
6224 | @appendix Reporting Bugs | |
ccc6cda3 | 6225 | |
bb70624e JA |
6226 | Please report all bugs you find in Bash. |
6227 | But first, you should | |
6228 | make sure that it really is a bug, and that it appears in the latest | |
6229 | version of Bash that you have. | |
ccc6cda3 | 6230 | |
bb70624e JA |
6231 | Once you have determined that a bug actually exists, use the |
6232 | @code{bashbug} command to submit a bug report. | |
6233 | If you have a fix, you are encouraged to mail that as well! | |
6234 | Suggestions and `philosophical' bug reports may be mailed | |
6235 | to @email{bug-bash@@gnu.org} or posted to the Usenet | |
6236 | newsgroup @code{gnu.bash.bug}. | |
ccc6cda3 | 6237 | |
bb70624e JA |
6238 | All bug reports should include: |
6239 | @itemize @bullet | |
6240 | @item | |
6241 | The version number of Bash. | |
6242 | @item | |
6243 | The hardware and operating system. | |
6244 | @item | |
6245 | The compiler used to compile Bash. | |
6246 | @item | |
6247 | A description of the bug behaviour. | |
6248 | @item | |
6249 | A short script or `recipe' which exercises the bug and may be used | |
6250 | to reproduce it. | |
6251 | @end itemize | |
ccc6cda3 | 6252 | |
bb70624e JA |
6253 | @noindent |
6254 | @code{bashbug} inserts the first three items automatically into | |
6255 | the template it provides for filing a bug report. | |
ccc6cda3 | 6256 | |
bb70624e JA |
6257 | Please send all reports concerning this manual to |
6258 | @email{chet@@po.CWRU.Edu}. | |
ccc6cda3 | 6259 | |
bb70624e JA |
6260 | @node Major Differences From The Bourne Shell |
6261 | @appendix Major Differences From The Bourne Shell | |
d166f048 | 6262 | |
bb70624e JA |
6263 | Bash implements essentially the same grammar, parameter and |
6264 | variable expansion, redirection, and quoting as the Bourne Shell. | |
6265 | Bash uses the @sc{posix} 1003.2 standard as the specification of | |
6266 | how these features are to be implemented. There are some | |
6267 | differences between the traditional Bourne shell and Bash; this | |
6268 | section quickly details the differences of significance. A | |
6269 | number of these differences are explained in greater depth in | |
6270 | previous sections. | |
28ef6c31 | 6271 | This section uses the version of @code{sh} included in SVR4.2 as |
bb70624e | 6272 | the baseline reference. |
ccc6cda3 | 6273 | |
bb70624e | 6274 | @itemize @bullet |
ccc6cda3 | 6275 | |
ccc6cda3 | 6276 | @item |
bb70624e | 6277 | Bash is @sc{posix}-conformant, even where the @sc{posix} specification |
28ef6c31 | 6278 | differs from traditional @code{sh} behavior (@pxref{Bash POSIX Mode}). |
ccc6cda3 JA |
6279 | |
6280 | @item | |
bb70624e | 6281 | Bash has multi-character invocation options (@pxref{Invoking Bash}). |
ccc6cda3 JA |
6282 | |
6283 | @item | |
bb70624e JA |
6284 | Bash has command-line editing (@pxref{Command Line Editing}) and |
6285 | the @code{bind} builtin. | |
ccc6cda3 JA |
6286 | |
6287 | @item | |
bb70624e JA |
6288 | Bash provides a programmable word completion mechanism |
6289 | (@pxref{Programmable Completion}), and two builtin commands, | |
6290 | @code{complete} and @code{compgen}, to manipulate it. | |
ccc6cda3 | 6291 | |
bb70624e JA |
6292 | @item |
6293 | Bash has command history (@pxref{Bash History Facilities}) and the | |
6294 | @code{history} and @code{fc} builtins to manipulate it. | |
ccc6cda3 | 6295 | |
bb70624e JA |
6296 | @item |
6297 | Bash implements @code{csh}-like history expansion | |
6298 | (@pxref{History Interaction}). | |
ccc6cda3 | 6299 | |
bb70624e JA |
6300 | @item |
6301 | Bash has one-dimensional array variables (@pxref{Arrays}), and the | |
6302 | appropriate variable expansions and assignment syntax to use them. | |
6303 | Several of the Bash builtins take options to act on arrays. | |
6304 | Bash provides a number of built-in array variables. | |
ccc6cda3 | 6305 | |
bb70624e JA |
6306 | @item |
6307 | The @code{$'@dots{}'} quoting syntax, which expands ANSI-C | |
6308 | backslash-escaped characters in the text between the single quotes, | |
6309 | is supported (@pxref{ANSI-C Quoting}). | |
ccc6cda3 | 6310 | |
bb70624e JA |
6311 | @item |
6312 | Bash supports the @code{$"@dots{}"} quoting syntax to do | |
6313 | locale-specific translation of the characters between the double | |
28ef6c31 | 6314 | quotes. The @option{-D}, @option{--dump-strings}, and @option{--dump-po-strings} |
bb70624e JA |
6315 | invocation options list the translatable strings found in a script |
6316 | (@pxref{Locale Translation}). | |
ccc6cda3 | 6317 | |
bb70624e JA |
6318 | @item |
6319 | Bash implements the @code{!} keyword to negate the return value of | |
6320 | a pipeline (@pxref{Pipelines}). | |
6321 | Very useful when an @code{if} statement needs to act only if a test fails. | |
ccc6cda3 | 6322 | |
bb70624e JA |
6323 | @item |
6324 | Bash has the @code{time} reserved word and command timing (@pxref{Pipelines}). | |
6325 | The display of the timing statistics may be controlled with the | |
28ef6c31 | 6326 | @env{TIMEFORMAT} variable. |
ccc6cda3 | 6327 | |
bb70624e JA |
6328 | @item |
6329 | Bash implements the @code{for (( @var{expr1} ; @var{expr2} ; @var{expr3} ))} | |
6330 | arithmetic for command, similar to the C language (@pxref{Looping Constructs}). | |
ccc6cda3 | 6331 | |
bb70624e JA |
6332 | @item |
6333 | Bash includes the @code{select} compound command, which allows the | |
6334 | generation of simple menus (@pxref{Conditional Constructs}). | |
ccc6cda3 | 6335 | |
bb70624e JA |
6336 | @item |
6337 | Bash includes the @code{[[} compound command, which makes conditional | |
6338 | testing part of the shell grammar (@pxref{Conditional Constructs}). | |
ccc6cda3 | 6339 | |
bb70624e JA |
6340 | @item |
6341 | Bash includes brace expansion (@pxref{Brace Expansion}) and tilde | |
6342 | expansion (@pxref{Tilde Expansion}). | |
ccc6cda3 | 6343 | |
bb70624e JA |
6344 | @item |
6345 | Bash implements command aliases and the @code{alias} and @code{unalias} | |
6346 | builtins (@pxref{Aliases}). | |
ccc6cda3 | 6347 | |
bb70624e JA |
6348 | @item |
6349 | Bash provides shell arithmetic, the @code{((} compound command | |
6350 | (@pxref{Conditional Constructs}), | |
6351 | and arithmetic expansion (@pxref{Shell Arithmetic}). | |
ccc6cda3 | 6352 | |
bb70624e JA |
6353 | @item |
6354 | Variables present in the shell's initial environment are automatically | |
6355 | exported to child processes. The Bourne shell does not normally do | |
6356 | this unless the variables are explicitly marked using the @code{export} | |
6357 | command. | |
ccc6cda3 | 6358 | |
bb70624e JA |
6359 | @item |
6360 | Bash includes the @sc{posix} pattern removal @samp{%}, @samp{#}, @samp{%%} | |
6361 | and @samp{##} expansions to remove leading or trailing substrings from | |
6362 | variable values (@pxref{Shell Parameter Expansion}). | |
ccc6cda3 | 6363 | |
bb70624e JA |
6364 | @item |
6365 | The expansion @code{$@{#xx@}}, which returns the length of @code{$@{xx@}}, | |
6366 | is supported (@pxref{Shell Parameter Expansion}). | |
ccc6cda3 | 6367 | |
bb70624e JA |
6368 | @item |
6369 | The expansion @code{$@{var:}@var{offset}@code{[:}@var{length}@code{]@}}, | |
6370 | which expands to the substring of @code{var}'s value of length | |
6371 | @var{length}, beginning at @var{offset}, is present | |
6372 | (@pxref{Shell Parameter Expansion}). | |
ccc6cda3 | 6373 | |
bb70624e JA |
6374 | @item |
6375 | The expansion | |
6376 | @code{$@{var/[/]}@var{pattern}@code{[/}@var{replacement}@code{]@}}, | |
6377 | which matches @var{pattern} and replaces it with @var{replacement} in | |
6378 | the value of @code{var}, is available (@pxref{Shell Parameter Expansion}). | |
ccc6cda3 | 6379 | |
bb70624e JA |
6380 | @item |
6381 | The expansion @code{$@{!@var{prefix@}*}} expansion, which expands to | |
6382 | the names of all shell variables whose names begin with @var{prefix}, | |
6383 | is available (@pxref{Shell Parameter Expansion}). | |
ccc6cda3 | 6384 | |
bb70624e JA |
6385 | @item |
6386 | Bash has @var{indirect} variable expansion using @code{$@{!word@}} | |
6387 | (@pxref{Shell Parameter Expansion}). | |
ccc6cda3 | 6388 | |
bb70624e JA |
6389 | @item |
6390 | Bash can expand positional parameters beyond @code{$9} using | |
6391 | @code{$@{@var{num}@}}. | |
ccc6cda3 | 6392 | |
bb70624e JA |
6393 | @item |
6394 | The @sc{posix} @code{$()} form of command substitution | |
6395 | is implemented (@pxref{Command Substitution}), | |
6396 | and preferred to the Bourne shell's @code{``} (which | |
6397 | is also implemented for backwards compatibility). | |
ccc6cda3 | 6398 | |
bb70624e JA |
6399 | @item |
6400 | Bash has process substitution (@pxref{Process Substitution}). | |
ccc6cda3 | 6401 | |
bb70624e JA |
6402 | @item |
6403 | Bash automatically assigns variables that provide information about the | |
28ef6c31 JA |
6404 | current user (@env{UID}, @env{EUID}, and @env{GROUPS}), the current host |
6405 | (@env{HOSTTYPE}, @env{OSTYPE}, @env{MACHTYPE}, and @env{HOSTNAME}), | |
6406 | and the instance of Bash that is running (@env{BASH}, | |
6407 | @env{BASH_VERSION}, and @env{BASH_VERSINFO}). @xref{Bash Variables}, | |
bb70624e | 6408 | for details. |
ccc6cda3 | 6409 | |
bb70624e | 6410 | @item |
28ef6c31 | 6411 | The @env{IFS} variable is used to split only the results of expansion, |
bb70624e JA |
6412 | not all words (@pxref{Word Splitting}). |
6413 | This closes a longstanding shell security hole. | |
ccc6cda3 | 6414 | |
bb70624e JA |
6415 | @item |
6416 | Bash implements the full set of @sc{posix} 1003.2 filename expansion operators, | |
6417 | including @var{character classes}, @var{equivalence classes}, and | |
6418 | @var{collating symbols} (@pxref{Filename Expansion}). | |
ccc6cda3 | 6419 | |
bb70624e JA |
6420 | @item |
6421 | Bash implements extended pattern matching features when the @code{extglob} | |
6422 | shell option is enabled (@pxref{Pattern Matching}). | |
ccc6cda3 | 6423 | |
bb70624e JA |
6424 | @item |
6425 | It is possible to have a variable and a function with the same name; | |
6426 | @code{sh} does not separate the two name spaces. | |
ccc6cda3 | 6427 | |
bb70624e JA |
6428 | @item |
6429 | Bash functions are permitted to have local variables using the | |
6430 | @code{local} builtin, and thus useful recursive functions may be written | |
6431 | (@pxref{Bash Builtins}). | |
ccc6cda3 | 6432 | |
bb70624e JA |
6433 | @item |
6434 | Variable assignments preceding commands affect only that command, even | |
6435 | builtins and functions (@pxref{Environment}). | |
6436 | In @code{sh}, all variable assignments | |
6437 | preceding commands are global unless the command is executed from the | |
6438 | file system. | |
ccc6cda3 | 6439 | |
bb70624e JA |
6440 | @item |
6441 | Bash performs filename expansion on filenames specified as operands | |
6442 | to input and output redirection operators (@pxref{Redirections}). | |
ccc6cda3 | 6443 | |
bb70624e JA |
6444 | @item |
6445 | Bash contains the @samp{<>} redirection operator, allowing a file to be | |
6446 | opened for both reading and writing, and the @samp{&>} redirection | |
6447 | operator, for directing standard output and standard error to the same | |
6448 | file (@pxref{Redirections}). | |
ccc6cda3 | 6449 | |
bb70624e JA |
6450 | @item |
6451 | Bash treats a number of filenames specially when they are | |
6452 | used in redirection operators (@pxref{Redirections}). | |
ccc6cda3 | 6453 | |
bb70624e JA |
6454 | @item |
6455 | Bash can open network connections to arbitrary machines and services | |
6456 | with the redirection operators (@pxref{Redirections}). | |
ccc6cda3 | 6457 | |
bb70624e JA |
6458 | @item |
6459 | The @code{noclobber} option is available to avoid overwriting existing | |
6460 | files with output redirection (@pxref{The Set Builtin}). | |
6461 | The @samp{>|} redirection operator may be used to override @code{noclobber}. | |
d166f048 | 6462 | |
bb70624e JA |
6463 | @item |
6464 | The Bash @code{cd} and @code{pwd} builtins (@pxref{Bourne Shell Builtins}) | |
28ef6c31 | 6465 | each take @option{-L} and @option{-P} options to switch between logical and |
bb70624e | 6466 | physical modes. |
d166f048 | 6467 | |
bb70624e JA |
6468 | @item |
6469 | Bash allows a function to override a builtin with the same name, and provides | |
6470 | access to that builtin's functionality within the function via the | |
6471 | @code{builtin} and @code{command} builtins (@pxref{Bash Builtins}). | |
d166f048 | 6472 | |
bb70624e JA |
6473 | @item |
6474 | The @code{command} builtin allows selective disabling of functions | |
6475 | when command lookup is performed (@pxref{Bash Builtins}). | |
ccc6cda3 | 6476 | |
bb70624e JA |
6477 | @item |
6478 | Individual builtins may be enabled or disabled using the @code{enable} | |
6479 | builtin (@pxref{Bash Builtins}). | |
b72432fd | 6480 | |
bb70624e JA |
6481 | @item |
6482 | The Bash @code{exec} builtin takes additional options that allow users | |
6483 | to control the contents of the environment passed to the executed | |
6484 | command, and what the zeroth argument to the command is to be | |
6485 | (@pxref{Bourne Shell Builtins}). | |
ccc6cda3 | 6486 | |
bb70624e JA |
6487 | @item |
6488 | Shell functions may be exported to children via the environment | |
6489 | using @code{export -f} (@pxref{Shell Functions}). | |
ccc6cda3 | 6490 | |
bb70624e JA |
6491 | @item |
6492 | The Bash @code{export}, @code{readonly}, and @code{declare} builtins can | |
28ef6c31 | 6493 | take a @option{-f} option to act on shell functions, a @option{-p} option to |
bb70624e | 6494 | display variables with various attributes set in a format that can be |
28ef6c31 | 6495 | used as shell input, a @option{-n} option to remove various variable |
bb70624e JA |
6496 | attributes, and @samp{name=value} arguments to set variable attributes |
6497 | and values simultaneously. | |
cce855bc | 6498 | |
bb70624e JA |
6499 | @item |
6500 | The Bash @code{hash} builtin allows a name to be associated with | |
6501 | an arbitrary filename, even when that filename cannot be found by | |
28ef6c31 | 6502 | searching the @env{$PATH}, using @samp{hash -p} |
bb70624e | 6503 | (@pxref{Bourne Shell Builtins}). |
cce855bc | 6504 | |
bb70624e JA |
6505 | @item |
6506 | Bash includes a @code{help} builtin for quick reference to shell | |
6507 | facilities (@pxref{Bash Builtins}). | |
cce855bc | 6508 | |
bb70624e JA |
6509 | @item |
6510 | The @code{printf} builtin is available to display formatted output | |
6511 | (@pxref{Bash Builtins}). | |
ccc6cda3 | 6512 | |
bb70624e JA |
6513 | @item |
6514 | The Bash @code{read} builtin (@pxref{Bash Builtins}) | |
6515 | will read a line ending in @samp{\} with | |
28ef6c31 | 6516 | the @option{-r} option, and will use the @env{REPLY} variable as a |
bb70624e JA |
6517 | default if no non-option arguments are supplied. |
6518 | The Bash @code{read} builtin | |
28ef6c31 JA |
6519 | also accepts a prompt string with the @option{-p} option and will use |
6520 | Readline to obtain the line when given the @option{-e} option. | |
bb70624e | 6521 | The @code{read} builtin also has additional options to control input: |
28ef6c31 JA |
6522 | the @option{-s} option will turn off echoing of input characters as |
6523 | they are read, the @option{-t} option will allow @code{read} to time out | |
bb70624e | 6524 | if input does not arrive within a specified number of seconds, the |
28ef6c31 JA |
6525 | @option{-n} option will allow reading only a specified number of |
6526 | characters rather than a full line, and the @option{-d} option will read | |
bb70624e | 6527 | until a particular character rather than newline. |
ccc6cda3 | 6528 | |
bb70624e JA |
6529 | @item |
6530 | The @code{return} builtin may be used to abort execution of scripts | |
6531 | executed with the @code{.} or @code{source} builtins | |
6532 | (@pxref{Bourne Shell Builtins}). | |
ccc6cda3 | 6533 | |
bb70624e JA |
6534 | @item |
6535 | Bash includes the @code{shopt} builtin, for finer control of shell | |
6536 | optional capabilities (@pxref{Bash Builtins}). | |
ccc6cda3 | 6537 | |
bb70624e JA |
6538 | @item |
6539 | Bash has much more optional behavior controllable with the @code{set} | |
6540 | builtin (@pxref{The Set Builtin}). | |
ccc6cda3 | 6541 | |
bb70624e JA |
6542 | @item |
6543 | The @code{test} builtin (@pxref{Bourne Shell Builtins}) | |
6544 | is slightly different, as it implements the @sc{posix} algorithm, | |
6545 | which specifies the behavior based on the number of arguments. | |
d166f048 | 6546 | |
bb70624e JA |
6547 | @item |
6548 | The @code{trap} builtin (@pxref{Bourne Shell Builtins}) | |
6549 | allows a @code{DEBUG} pseudo-signal specification, | |
6550 | similar to @code{EXIT}. Commands specified with a @code{DEBUG} trap are | |
6551 | executed after every simple command. The @code{DEBUG} trap is not | |
6552 | inherited by shell functions. | |
d166f048 | 6553 | |
bb70624e JA |
6554 | @item |
6555 | The Bash @code{type} builtin is more extensive and gives more information | |
6556 | about the names it finds (@pxref{Bash Builtins}). | |
cce855bc | 6557 | |
bb70624e | 6558 | @item |
28ef6c31 | 6559 | The Bash @code{umask} builtin permits a @option{-p} option to cause |
bb70624e JA |
6560 | the output to be displayed in the form of a @code{umask} command |
6561 | that may be reused as input (@pxref{Bourne Shell Builtins}). | |
ccc6cda3 | 6562 | |
bb70624e JA |
6563 | @item |
6564 | Bash implements a @code{csh}-like directory stack, and provides the | |
6565 | @code{pushd}, @code{popd}, and @code{dirs} builtins to manipulate it | |
6566 | (@pxref{The Directory Stack}). | |
6567 | Bash also makes the directory stack visible as the value of the | |
28ef6c31 | 6568 | @env{DIRSTACK} shell variable. |
d166f048 | 6569 | |
bb70624e JA |
6570 | @item |
6571 | Bash interprets special backslash-escaped characters in the prompt | |
6572 | strings when interactive (@pxref{Printing a Prompt}). | |
cce855bc | 6573 | |
bb70624e JA |
6574 | @item |
6575 | The Bash restricted mode is more useful (@pxref{The Restricted Shell}); | |
6576 | the SVR4.2 shell restricted mode is too limited. | |
d166f048 | 6577 | |
bb70624e JA |
6578 | @item |
6579 | The @code{disown} builtin can remove a job from the internal shell | |
6580 | job table (@pxref{Job Control Builtins}) or suppress the sending | |
6581 | of @code{SIGHUP} to a job when the shell exits as the result of a | |
6582 | @code{SIGHUP}. | |
d166f048 | 6583 | |
bb70624e JA |
6584 | @item |
6585 | The SVR4.2 shell has two privilege-related builtins | |
6586 | (@code{mldmode} and @code{priv}) not present in Bash. | |
d166f048 | 6587 | |
bb70624e JA |
6588 | @item |
6589 | Bash does not have the @code{stop} or @code{newgrp} builtins. | |
ccc6cda3 | 6590 | |
bb70624e | 6591 | @item |
28ef6c31 | 6592 | Bash does not use the @env{SHACCT} variable or perform shell accounting. |
ccc6cda3 | 6593 | |
bb70624e | 6594 | @item |
28ef6c31 JA |
6595 | The SVR4.2 @code{sh} uses a @env{TIMEOUT} variable like Bash uses |
6596 | @env{TMOUT}. | |
ccc6cda3 | 6597 | |
bb70624e | 6598 | @end itemize |
d166f048 | 6599 | |
bb70624e JA |
6600 | @noindent |
6601 | More features unique to Bash may be found in @ref{Bash Features}. | |
d166f048 | 6602 | |
ccc6cda3 | 6603 | |
bb70624e | 6604 | @appendixsec Implementation Differences From The SVR4.2 Shell |
ccc6cda3 | 6605 | |
bb70624e JA |
6606 | Since Bash is a completely new implementation, it does not suffer from |
6607 | many of the limitations of the SVR4.2 shell. For instance: | |
ccc6cda3 | 6608 | |
bb70624e | 6609 | @itemize @bullet |
ccc6cda3 | 6610 | |
bb70624e JA |
6611 | @item |
6612 | Bash does not fork a subshell when redirecting into or out of | |
6613 | a shell control structure such as an @code{if} or @code{while} | |
6614 | statement. | |
ccc6cda3 | 6615 | |
bb70624e JA |
6616 | @item |
6617 | Bash does not allow unbalanced quotes. The SVR4.2 shell will silently | |
6618 | insert a needed closing quote at @code{EOF} under certain circumstances. | |
6619 | This can be the cause of some hard-to-find errors. | |
ccc6cda3 | 6620 | |
bb70624e JA |
6621 | @item |
6622 | The SVR4.2 shell uses a baroque memory management scheme based on | |
6623 | trapping @code{SIGSEGV}. If the shell is started from a process with | |
6624 | @code{SIGSEGV} blocked (e.g., by using the @code{system()} C library | |
6625 | function call), it misbehaves badly. | |
ccc6cda3 | 6626 | |
ccc6cda3 | 6627 | @item |
bb70624e | 6628 | In a questionable attempt at security, the SVR4.2 shell, |
28ef6c31 | 6629 | when invoked without the @option{-p} option, will alter its real |
bb70624e JA |
6630 | and effective @sc{uid} and @sc{gid} if they are less than some |
6631 | magic threshold value, commonly 100. | |
6632 | This can lead to unexpected results. | |
6633 | ||
ccc6cda3 | 6634 | @item |
bb70624e JA |
6635 | The SVR4.2 shell does not allow users to trap @code{SIGSEGV}, |
6636 | @code{SIGALRM}, or @code{SIGCHLD}. | |
6637 | ||
ccc6cda3 | 6638 | @item |
28ef6c31 JA |
6639 | The SVR4.2 shell does not allow the @env{IFS}, @env{MAILCHECK}, |
6640 | @env{PATH}, @env{PS1}, or @env{PS2} variables to be unset. | |
bb70624e | 6641 | |
ccc6cda3 | 6642 | @item |
bb70624e JA |
6643 | The SVR4.2 shell treats @samp{^} as the undocumented equivalent of |
6644 | @samp{|}. | |
6645 | ||
ccc6cda3 | 6646 | @item |
bb70624e JA |
6647 | Bash allows multiple option arguments when it is invoked (@code{-x -v}); |
6648 | the SVR4.2 shell allows only one option argument (@code{-xv}). In | |
6649 | fact, some versions of the shell dump core if the second argument begins | |
6650 | with a @samp{-}. | |
ccc6cda3 | 6651 | |
bb70624e JA |
6652 | @item |
6653 | The SVR4.2 shell exits a script if any builtin fails; Bash exits | |
6654 | a script only if one of the @sc{posix} 1003.2 special builtins fails, and | |
6655 | only for certain failures, as enumerated in the @sc{posix} 1003.2 standard. | |
ccc6cda3 | 6656 | |
bb70624e JA |
6657 | @item |
6658 | The SVR4.2 shell behaves differently when invoked as @code{jsh} | |
6659 | (it turns on job control). | |
6660 | @end itemize | |
ccc6cda3 JA |
6661 | |
6662 | @node Builtin Index | |
bb70624e | 6663 | @unnumbered Index of Shell Builtin Commands |
ccc6cda3 JA |
6664 | @printindex bt |
6665 | ||
6666 | @node Reserved Word Index | |
bb70624e | 6667 | @unnumbered Index of Shell Reserved Words |
ccc6cda3 JA |
6668 | @printindex rw |
6669 | ||
6670 | @node Variable Index | |
bb70624e | 6671 | @unnumbered Parameter and Variable Index |
ccc6cda3 JA |
6672 | @printindex vr |
6673 | ||
6674 | @node Function Index | |
bb70624e | 6675 | @unnumbered Function Index |
ccc6cda3 JA |
6676 | @printindex fn |
6677 | ||
6678 | @node Concept Index | |
bb70624e | 6679 | @unnumbered Concept Index |
ccc6cda3 JA |
6680 | @printindex cp |
6681 | ||
6682 | @contents | |
6683 | @bye |