EFTA00315849.pdf

Bash Reference Manual Reference Documentation for Bash Edition 3.1-betal, for Bash Version 3.1-betal. September 2005 Chet Ramey, Case Western Reserve University Brian Fox, Free Software Foundation EFTA00315849 This text is a brief description of the features that are present in the Bash shell (version 3.1-betal, 5 September 2005). This is Edition 3.1-betal, last updated 5 September 2005, of The GNU Bash Reference Manual, for Bash, Version 3.1-betal. Copyright © 1988-2005 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being "A GNU Manual," and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled "GNU Free Documentation License." (a) The FSF's Back-Cover Text is: "You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development." Published by the Free Software Foundation 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA EFTA00315850 Table of Contents 1 Introduction 1 1.1 What is Bash? 1 1.2 What is a shell? 1 2 Definitions 3 3 Basic Shell Features 5 3.1 Shell Syntax 5 3.1.1 Shell Operation 5 3.1.2 Quoting 5 3.1.2.1 Escape Character 6 3.1.2.2 Single Quotes 6 3.1.2.3 Double Quotes 6 3.1.2.4 ANSI-C Quoting 6 3.1.2.5 Locale-Specific Translation 7 3.1.3 Comments 7 3.2 Shell Commands 7 3.2.1 Simple Commands 8 3.2.2 Pipelines 8 3.2.3 Lists of Commands 8 3.2.4 Compound Commands 9 3.2.4.1 Looping Constructs 9 3.2.4.2 Conditional Constructs 10 3.2.4.3 Grouping Commands 13 3.3 Shell Functions 13 3.4 Shell Parameters 15 3.4.1 Positional Parameters 15 3.4.2 Special Parameters 16 3.5 Shell Expansions 17 3.5.1 Brace Expansion 17 3.5.2 Tilde Expansion 18 3.5.3 Shell Parameter Expansion 19 3.5.4 Command Substitution 21 3.5.5 Arithmetic Expansion 22 3.5.6 Process Substitution 22 3.5.7 Word Splitting 22 3.5.8 Filename Expansion 23 3.5.8.1 Pattern Matching 23 3.5.9 Quote Removal 24 3.6 Redirections 24 3.6.1 Redirecting Input 25 3.6.2 Redirecting Output 26 EFTA00315851 ii Bash Reference Manual 3.6.3 Appending Redirected Output 26 3.6.4 Redirecting Standard Output and Standard Error 26 3.6.5 Here Documents 26 3.6.6 Here Strings 27 3.6.7 Duplicating File Descriptors 27 3.6.8 Moving File Descriptors 27 3.6.9 Opening File Descriptors for Reading and Writing 28 3.7 Executing Commands 28 3.7.1 Simple Command Expansion 28 3.7.2 Command Search and Execution 29 3.7.3 Command Execution Environment 29 3.7.4 Environment 30 3.7.5 Exit Status 31 3.7.6 Signals 31 3.8 Shell Scripts 32 4 Shell Builtin Commands 33 4.1 Bourne Shell Builtins 33 4.2 Bash Builtin Commands 39 4.3 The Set Builtin 50 4.4 Special Builtins 54 5 Shell Variables 55 5.1 Bourne Shell Variables 55 5.2 Bash Variables 55 6 Bash Features 65 6.1 Invoking Bash 65 6.2 Bash Startup Files 67 6.3 Interactive Shells 69 6.3.1 What is an Interactive Shell? 69 6.3.2 Is this Shell Interactive 69 6.3.3 Interactive Shell Behavior 69 6.4 Bash Conditional Expressions 70 6.5 Shell Arithmetic 72 6.6 Aliases 73 6.7 Arrays 74 6.8 The Directory Stack 75 6.8.1 Directory Stack Builtins 75 6.9 Controlling the Prompt 76 6.10 The Restricted Shell 78 6.11 Bash POSIX Mode 78 EFTA00315852  iii 7 Job Control 83 7.1 Job Control Basics 83 7.2 Job Control Builtins 84 7.3 Job Control Variables 85 8 Command Line Editing 87 8.1 Introduction to Line Editing 87 8.2 Readline Interaction 87 8.2.1 Readline Bare Essentials 87 8.2.2 Readline Movement Commands 88 8.2.3 Readline Killing Commands 88 8.2.4 Readline Arguments 89 8.2.5 Searching for Commands in the History 89 8.3 Readline Init File 90 8.3.1 Readline Init File Syntax 90 8.3.2 Conditional Init Constructs 95 8.3.3 Sample Init File 96 8.4 Bindable Readline Commands 99 8.4.1 Commands For Moving 99 8.4.2 Commands For Manipulating The History 99 8.4.3 Commands For Changing Text 101 8.4.4 Killing And Yanking 102 8.4.5 Specifying Numeric Arguments 103 8.4.6 Letting Readline Type For You 103 8.4.7 Keyboard Macros 104 8.4.8 Some Miscellaneous Commands 105 8.5 Readline vi Mode 107 8.6 Programmable Completion 107 8.7 Programmable Completion Builtins 109 9 Using History Interactively 113 9.1 Bash History Facilities 113 9.2 Bash History Builtins 113 9.3 History Expansion 115 9.3.1 Event Designators 115 9.3.2 Word Designators 116 9.3.3 Modifiers 117 10 Installing Bash 119 10.1 Basic Installation 119 10.2 Compilers and Options 119 10.3 Compiling For Multiple Architectures 120 10.4 Installation Names 120 10.5 Specifying the System Type 120 10.6 Sharing Defaults 121 10.7 Operation Controls 121 10.8 Optional Features 121 EFTA00315853 iv Bash Reference Manual Appendix A Reporting Bugs 127 Appendix B Major Differences From The Bourne Shell 129 B.1 Implementation Differences From The SVR4.2 Shell 133 Appendix C Copying This Manual 135 C.1 GNU Free Documentation License 135 C.1.1 ADDENDUM: How to use this License for your documents 141 Index of Shell Builtin Commands 143 Index of Shell Reserved Words 145 Parameter and Variable Index 147 Function Index 149 Concept Index 151 EFTA00315854 Chapter 1: Introduction 1 1 Introduction 1.1 What is Bash? Bash is the shell, or command language interpreter, for the GNU operating system. The name is an acronym for the `Bourne-Again Shell', a pun on Stephen Bourne, the author of the direct ancestor of the current Unix shell ah, which appeared in the Seventh Edition Bell Labs Research version of Unix. Bash is largely compatible with ah and incorporates useful features from the Korn shell kah and the C shell csh. It is intended to be a conformant implementation of the IEEE POSIX Shell and Tools specification (IEEE Working Group 1003.2). It offers functional improvements over sh for both interactive and programming use. While the GNU operating system provides other shells, including a version of esh, Bash is the default shell. Like other GNU software, Bash is quite portable. It currently runs on nearly every version of Unix and a few other operating systems — independently-supported ports exist for MS-DOS, OS/2, and Windows platforms. 1.2 What is a shell? At its base, a shell is simply a macro processor that executes commands. The term macro processor means functionality where text and symbols are expanded to create larger expressions. A Unix shell is both a conunand interpreter and a programming language. As a com- mand interpreter, the shell provides the user interface to the rich set of GNU utilities. The programming language features allow these utilitites to be combined. Files containing com- mands can be created, and become commands themselves. These new commands have the same status as system commands in directories such as 4/ bin', allowing users or groups to establish custom environments to automate their common tasks. Shells may be used interactively or non-interactively. In interactive mode, they accept input typed front the keyboard. When executing non-interactively, shells execute commands read from a file. A shell allows execution of GNU commands, both synchronously and asynchronously. The shell waits for synchronous commands to complete before accepting more input; asyn- chronous commands continue to execute in parallel with the shell while it reads and executes additional commands. The redirection constructs permit fine-grained control of the input and output of those commands. Moreover, the shell allows control over the contents of commands' environments. Shells also provide a small set of built-in commands (builtins) implementing function- ality impossible or inconvenient to obtain via separate utilities. For example, cd, break, continue, and exec) cannot be implemented outside of the shell because they directly manipulate the shell itself. The history, getopts, kill, or pwd builtins, among others, could be implemented in separate utilities, but they are more convenient to use as builtin commands. All of the shell builtins are described in subsequent sections. EFTA00315855 2 Bash Reference Manual While executing commands is essential, most of the power (and complexity) of shells is due to their embedded programming languages. Like any high-level language, the shell provides variables, flow control constructs, quoting, and functions. Shells offer features geared specifically for interactive use rather than to augment the pro- gramming language. These interactive features include job control, command line editing, command history and aliases. Each of these features is described in this manual. EFTA00315856 Chapter 2: Definitions 3 2 Definitions These definitions are used throughout the remainder of this manual. POSIX A family of open system standards based on Unix. Bash is concerned with POSIX 1003.2, the Shell and Tools Standard. blank A space or tab character. built in A command that is implemented internally by the shell itself, rather than by an executable program somewhere in the file system. control operator A word that performs a control function. It is a newline or one of the following: I 11, le , le, `;', C; ; C, or T. exit status The value returned by a command to its caller. The value is restricted to eight bits, so the maximum value is 255. field A unit of text that is the result of one of the shell expansions. After expansion, when executing a command, the resulting fields are used as the command name and arguments. filename A string of characters used to identify a file. j ob A set of processes comprising a pipeline, and any processes descended from it, that are all in the same process group. job control A mechanism by which users can selectively stop (suspend) and restart (resume) execution of processes. metacharacter A character that, when unquoted, separates words. A metacharacter is a blank or one of the following characters: ' I ', `;', C, `<', or `>'. name A word consisting solely of letters, numbers, and underscores, and beginning with a letter or underscore. Names are used as shell variable and function names. Also referred to as an identifier. operator A control operator or a redirection operator. See Section 3.6 [B,edirec- tions], page 25, for a list of redirection operators. process group A collection of related processes each having the same process group ID. process group ID A unique identifer that represents a process group during its lifetime. reserved word A word that has a special meaning to the shell. Most reserved words introduce shell flow control constructs, such as for and while. return status A synonym for exit status. EFTA00315857 4 Bash Reference Manual signal A mechanism by which a process may be notified by the kernel of an event occurring in the system. special builtin A shell builtin command that has been classified as special by the POSIX 1003.2 standard. token A sequence of characters considered a single unit by the shell. It is either a word or an operator. word A token that is not an operator. EFTA00315858 Chapter 3: Basic Shell Features 5 3 Basic Shell Features Bash is an acronym for 'Bourne-Again SHell'. The Bourne shell is the traditional Unix shell originally written by Stephen Bourne. All of the Bourne shell builtin commands are available in Bash, The rules for evaluation and quoting are taken from the POSIX specifica- tion for the `standard' Unix shell. This chapter briefly summarizes the shell's 'building blocks': commands, control struc- tures, shell functions, shell parameters, shell expansions, redirections, which are a way to direct input and output from and to named files, and how the shell executes commands. 3.1 Shell Syntax When the shell reads input, it proceeds through a sequence of operations. If the input indicates the beginning of a continent, the shell ignores the continent symbol (`ir), and the rest of that line. Otherwise, roughly speaking, the shell reads its input and divides the input into words and operators, employing the quoting rules to select which meanings to assign various words and characters. The shell then parses these tokens into commands and other constructs, removes the special meaning of certain words or characters, expands others, redirects input and output as needed, executes the specified command, waits for the command's exit status, and makes that exit status available for further inspection or processing. 3.1.1 Shell Operation The following is a brief description of the shell's operation when it reads and executes a command. Basically, the shell does the following: 1. Reads its input from a file (see Section 3.8 [Shell Scripts], page 32), from a string supplied as an argument to the `-c' invocation option (see Section 6.1 [Invoking Bash], page 65), or from the user's terminal. 2. Breaks the input into words and operators, obeying the quoting rules described in Section 3.1.2 [Quoting], page 6. These tokens are separated by metacharacters. Alias expansion is performed by this step (see Section 6.6 [Aliases], page 73). 3. Parses the tokens into simple and compound commands (see Section 3.2 [Shell Com- mands], page 8). 4. Performs the various shell expansions (see Section 3.5 [Shell Expansions], page 17), breaking the expanded tokens into lists of filenames (see Section 3.5.8 [Filename Ex- pansion], page 23) and conunands and arguments. 5. Performs any necessary redirections (see Section 3.6 [Redirection], page 25) and re- moves the redirection operators and their operands from the argument list. 6. Executes the command (see Section 3.7 [Executing Commands], page 28). 7. Optionally waits for the command to complete and collects its exit status (see Sec- tion 3.7.5 [Exit Status], page 31). EFTA00315859 6 Bash Reference Manual 3.1.2 Quoting Quoting is used to remove the special meaning of certain characters or words to the shell. Quoting can be used to disable special treatment for special characters, to prevent reserved words from being recognized as such, and to prevent parameter expansion. Each of the shell metacharacters (see Chapter 2 [Definitions], page 3) has special meaning to the shell and must be quoted if it is to represent itself. When the command history expansion facilities are being used (see Section 9.3 [History Interaction], page 115), the history expansion character, usually '!', must be quoted to prevent history expansion. See Section 9.1 [Bash History Facilities], page 113, for more details concerning history expansion. There are three quoting mechanisms: the escape character, single quotes, and double quotes. 3.1.2.1 Escape Character A non-quoted backslash `\' is the Bash escape character. It preserves the literal value of the next character that follows, with the exception of newline. If a \newline pair appears, and the backslash itself is not quoted, the \newline is treated as a line continuation (that is, it is removed from the input stream and effectively ignored). 3.1.2.2 Single Quotes Enclosing characters in single quotes (" ') preserves the literal value of each character within the quotes. A single quote may not occur between single quotes, even when preceded by a backslash. 3.1.2.3 Double Quotes Enclosing characters in double quotes Cul preserves the literal value of all characters within the quotes, with the exception of '$', " '\', and, when history expansion is enabled, '!'. The characters '5' and "' retain their special meaning within double quotes (see Sec- tion 3.5 [Shell Expansions], page 17). The backslash retains its special meaning only when followed by one of the following characters: `5', "', "", '\', or newline. Within double quotes, backslashes that are followed by one of these characters are removed. Backslashes preceding characters without a special meaning are left unmodified. A double quote may be quoted within double quotes by preceding it with a backslash. If enabled, history expansion will be performed unless an ! ' appearing in double quotes is escaped using a backslash. The backslash preceding the '!' is not removed. The special parameters '*' and have special meaning when in double quotes (see Section 3.5.3 [Shell Parameter Expansion], page 19). 3.1.2.4 ANSI-C Quoting Words of the form $ ' string are treated specially. The word expands to string, with backslash-escaped characters replaced as specified by the ANSI C standard. Backslash escape sequences, if present, are decoded as follows: EFTA00315860 Chapter 3: Basic Shell Features 7 \a alert (bell) \b backspace \e an escape character (not ANSI C) \f form feed \n newline \r carriage return \t horizontal tab \v vertical tab \\ backslash single quote \nnn the eight-bit character whose value is the octal value nnn (one to three digits) \ xHH the eight-bit character whose value is the hexadecimal value HH (one or two hex digits) \ cx a control-x character The expanded result is single-quoted, as if the dollar sign had not been present. 3.1.2.5 Locale-Specific Translation A double-quoted string preceded by a dollar sign (I') will cause the string to be trans- lated according to the current locale. If the current locale is C or POSIX, the dollar sign is ignored. If the string is translated and replaced, the replacement is double-quoted. Some systems use the message catalog selected by the LC_MESSAGES shell variable. Others create the name of the message catalog from the value of the TEXTDOMAIN shell variable, possibly adding a suffix of ' .mo'. If you use the TEXTDOMAIN variable, you may need to set the TEXTDOMAINDIR variable to the location of the message catalog files. Still others use both variables in this fashion: TEXTDOMAINDIR/LC_MESSAGES/LC_IvIESSAGES/TEXTDOMAIN.mo. 3.1.3 Comments In a non-interactive shell, or an interactive shell in which the interactive_comments option to the shopt builtin is enabled (see Section 4.2 [Bash Builtins], page 39), a word beginning with causes that word and all remaining characters on that line to be ignored. An interactive shell without the interactive_comments option enabled does not allow comments. The interactive_comments option is on by default in interactive shells. See Section 6.3 [Interactive Shells], page 69, for a description of what makes a shell interactive. EFTA00315861 8 Bash Reference Manual 3.2 Shell Commands A simple shell command such as echo a b e consists of the command itself followed by arguments, separated by spaces. More complex shell commands are composed of simple commands arranged together in a variety of ways: in a pipeline in which the output of one command becomes the input of a second, in a loop or conditional construct, or in some other grouping. 3.2.1 Simple Commands A simple command is the kind of command encountered most often. It's just a sequence of words separated by blanks, terminated by one of the shell's control operators (see Chap- ter 2 ['Definitions], page 3). The first word generally specifies a command to be executed, with the rest of the words being that command's arguments. The return status (see Section 3.7.5 [Exit Status], page 31) of a simple command is its exit status as provided by the POSIX 1003.1 waitpid function, or 128+n if the command was terminated by signal n. 3.2.2 Pipelines A pipeline is a sequence of simple commands separated by ' '. The format for a pipeline is [time [-p]] 1!) command.' CI command2 .. .] The output of each command in the pipeline is connected via a pipe to the input of the next command. That is, each command reads the previous command's output. The reserved word time causes timing statistics to be printed for the pipeline once it finishes. The statistics currently consist of elapsed (wall-clock) time and user and system time consumed by the command's execution. The `-p' option changes the output format to that specified by POSIX. The TIMEFORMAT variable may be set to a format string that specifies how the timing information should be displayed. See Section 5.2 [Bash Variables], page 55, for a description of the available formats. The use of time as a reserved word per- mits the timing of shell builtins, shell functions, and pipelines. An external time command cannot time these easily. If the pipeline is not executed asynchronously (see Section 3.2.3 [Lists], page 9), the shell waits for all commands in the pipeline to complete. Each command in a pipeline is executed in its own subshell (see Section 3.7.3 [Command Execution Environment], page 29). The exit status of a pipeline is the exit status of the last command in the pipeline, unless the pipefail option is enabled (see Section 4.3 (The Set Builtin], page 51). If pipefail is enabled, the pipeline's return status is the value of the last (rightmost) command to exit with a non-zero status, or zero if all commands exit successfully. If the reserved word `!' precedes the pipeline, the exit status is the logical negation of the exit status as described above. The shell waits for all commands in the pipeline to terminate before returning a value. EFTA00315862 Chapter 3: Basic Shell Features 9 3.2.3 Lists of Commands A list is a sequence of one or more pipelines separated by one of the operators '; le, or ' I I', and optionally terminated by one of ';', 1', or a newline. Of these list operators, '&&' and'I I' have equal precedence, followed by 4; ' and which have equal precedence. A sequence of one or more newlines may appear in a list to delimit commands, equiv- alent to a semicolon. If a command is terminated by the control operator the shell executes the command asynchronously in a subshell. This is known as executing the command in the background. The shell does not wait for the command to finish, and the return status is 0 (true). When job control is not active (see Chapter 7 [Job Control], page 83), the standard input for asynchronous commands, in the absence of any explicit redirections, is redirected from /dev/null. Commands separated by a '; ' are executed sequentially; the shell waits for each conunand to terminate in turn. The return status is the exit status of the last command executed. The control operators Ite and ' I I' denote AND lists and OR lists, respectively. An AND list has the form commandl && command2 command2 is executed if, and only if, command! returns an exit status of zero. An OR list has the form commandl I I command2 command2 is executed if, and only if, commandl returns a non-zero exit status. The return status of AND and OR lists is the exit status of the last command executed in the list. 3.2.4 Compound Commands Compound conunands are the shell programming constructs. Each construct begins with a reserved word or control operator and is terminated by a corresponding reserved word or operator. Any redirections (see Section 3.6 [Redirection], page 25) associated with a compound command apply to all commands within that compound command unless explicitly overridden. Bash provides looping constructs, conditional conunands, and mechanisms to group commands and execute them as a unit. 3.2.4.1 Looping Constructs Bash supports the following looping constructs. Note that wherever a '; ' appears in the description of a command's syntax, it may be replaced with one or more newlines. until The syntax of the until command is: EFTA00315863 10 Bash Reference Manual until test-commands; do consequent-commands; done Execute consequent-commands as long as test-commands has an exit status which is not zero. The return status is the exit status of the last command executed in consequent-commands, or zero if none was executed. while The syntax of the while command is: while test-commands; do consequent-commands; done Execute consequent-commands as long as test-commands has an exit status of zero. The return status is the exit status of the last command executed in consequent-commands, or zero if none was executed. for The syntax of the for command is: for name [in words . .] ; do commands; done Expand words, and execute commands once for each member in the resultant list, with name bound to the current member. If 'in words' is not present, the for command executes the commands once for each positional parameter that is set, as if `in "VP' had been specified (see Section 3.4.2 [Special Parameters], page 16). The return status is the exit status of the last command that executes. If there are no items in the expansion of words, no commands are executed, and the return status is zero. An alternate form of the for command is also supported: for (( exprl ; expr2 ; expr3 )) ; do commands ; done First, the arithmetic expression exprl is evaluated according to the rules de- scribed below (see Section 6.5 [Shell Arithmetic], page 72). The arithmetic expression expr2 is then evaluated repeatedly until it evaluates to zero. Each time expr2 evaluates to a non-zero value, commands are executed and the arith- metic expression expr3 is evaluated. If any expression is omitted, it behaves as if it evaluates to 1. The return value is the exit status of the last command in list that is executed, or false if any of the expressions is invalid. The break and continue builtins (see Section 4.1 [Bourne Shell Builtins], page 33) may be used to control loop execution. 3.2.4.2 Conditional Constructs if The syntax of the if command is: if test-commands; then consequent-commands; [elif more-test-commands; then more-consequents ;) [else alternate-consequents ;] fi The test-commands list is executed, and if its return status is zero, the consequent-commands list is executed. If test-commands returns a non-zero status, each elif list is executed in turn, and if its exit status is zero, the corresponding more-consequents is executed and the command completes. If EFTA00315864 Chapter 3: Basic Shell Features 11 'else alternate -consequents' is present, and the final command in the final if or elif clause has a non-zero exit status, then alternate-consequents is executed. The return status is the exit status of the last command executed, or zero if no condition tested true. Case The syntax of the case command is: case word in [0 pattern [I pattern] . ..) command-list ; ;] esac case will selectively execute the command-list corresponding to the first pat- tern that matches word. If the shell option nocasematch (see the description of shopt in Section 4.2 [Bash Builtins], page 39) is enabled, the match is per- formed without regard to the case of alphabetic characters. The ' I ' is used to separate multiple patterns, and the ')' operator terminates a pattern list. A list of patterns and an associated command-list is known as a clause. Each clause must be terminated with '; ;'. The word undergoes tilde expansion, parameter expansion, command substitution, arithmetic expansion, and quote removal be- fore matching is attempted. Each pattern undergoes tilde expansion, parameter expansion, command substitution, and arithmetic expansion. There may be an arbitrary number of case clauses, each terminated by a '; ; The first pattern that matches determines the command-list that is executed. Here is an example using case in a script that could be used to describe one interesting feature of an animal: echo -n "Enter the name of an animal: read ANIMAL echo -n "The $ANIMAL has " case $ANIMAL in horse I dog I cat) echo -n "four";; man I kangaroo ) echo -n "two";; *) echo -n "an unknown number of";; esac echo " legs." The return status is zero if no pattern is matched. Otherwise, the return status is the exit status of the command-list executed. select The select construct allows the easy generation of menus. It has almost the same syntax as the for command: select name [in words .] ; do commands; done The list of words following in is expanded, generating a list of items. The set of expanded words is printed on the standard error output stream, each preceded by a munber. If the 'in words' is omitted, the positional parameters are printed, as if 'in "$($"' had been specifed. The PS3 prompt is then displayed and a line is read from the standard input. If the line consists of a number corresponding to one of the displayed words, then the value of name is set to that word. If the line is empty, the words and prompt are displayed again. If EOF is read, the select command completes. Any other value read causes name to be set to null. The line read is saved in the variable REPLY. EFTA00315865 12 Bash Reference Manual The commands are executed after each selection until a break command is executed, at which point the select command completes. Here is an example that allows the user to pick a filename from the current directory, and displays the name and index of the file selected. select fname in *; do echo you picked $f name \($REPLY\) break; done (( expression )) The arithmetic expression is evaluated according to the rules described below (see Section 6.5 [Shell Arithmetic], page 72). If the value of the expression is non-zero, the return status is 0; otherwise the return status is 1. This is exactly equivalent to let "expression" See Section 4.2 [Bash Builtins], page 39, for a full description of the let builtin. (C expression ]] Return a status of 0 or 1 depending on the evaluation of the conditional expres- sion expression. Expressions are composed of the primaries described below in Section 6.4 [Bash Conditional Expressions], page 71. Word splitting and file- name expansion are not performed on the words between the ' L' and 1 '; tilde expansion, parameter and variable expansion, arithmetic expansion, command substitution, process substitution, and quote removal are performed. Condi- tional operators such as `-f' must be =quoted to be recognized as primaries. When the `==' and ' = operators are used, the string to the right of the operator is considered a pattern and matched according to the niles described below in Section 3.5.8.1 [Pattern Matching], page 23. If the shell option nocasematch (see the description of shopt in Section 4.2 [Bash Builtins], page 39) is enabled, the match is performed without regard to the case of alphabetic characters. The return value is 0 if the string matches or does not match the pattern, respectively, and 1 otherwise. Any part of the pattern may be quoted to force it to be matched as a string. An additional binary operator, `=', is available, with the same precedence as `==' and `!=. When it is used, the string to the right of the operator is consid- ered an extended regular expression and matched accordingly (as in regex3)). The return value is 0 if the string matches the pattern, and 1 otherwise. If the regular expression is syntactically incorrect, the conditional expression's re- turn value is 2. If the shell option nocasematch (see the description of shopt in Section 4.2 [Bash Builtins], page 39) is enabled, the match is performed without regard to the case of alphabetic characters. Substrings matched by parenthesized subexpressions within the regular expression are saved in the array variable BASH_REMATCH. The element of BASH_REMATCH with index 0 is EFTA00315866 Chapter 3: Basic Shell Features 13 the portion of the string matching the entire regular expression. The element of BASH_REMATCH with index n is the portion of the string matching the nth parenthesized subexpression. Expressions may be combined using the following operators, listed in decreasing order of precedence: ( expression ) Returns the value of expression. This may be used to override the normal precedence of operators. ! expression True if expression is false. expression! tat expression2 'flue if both expression.? and expression2 are true. expression! I I expression2 True if either expression.' or expression2 is true. The a and I I operators do not evaluate expression2 if the value of exprassionl is sufficient to determine the return value of the entire conditional expression. 3.2.4.3 Grouping Commands Bash provides two ways to group a list of commands to be executed as a unit. When com- mands are grouped, redirections may be applied to the entire command list. For example, the output of all the commands in the list may be redirected to a single stream. 0 ( list ) Placing a list of commands between parentheses causes a subshell environment to be created (see Section 3.7.3 (Command Execution Environment], page 29), and each of the commands in list to be executed in that subshell. Since the list is executed in a subshell, variable assignments do not remain in effect after the subshell completes. {} { list; } Placing a list of commands between curly braces causes the list to be executed in the current shell context. No subshell is created. The semicolon (or 'towline) following list is required. In addition to the creation of a subshell, there is a subtle difference between these two constructs due to historical reasons. The braces are reserved words, so they must be separated from the list by blanks. The parentheses are operators, and are recognized as separate tokens by the shell even if they are not separated from the list by whitespace. The exit status of both of these constructs is the exit status of list. EFTA00315867 14 Bash Reference Manual 3.3 Shell Functions Shell functions are a way to group commands for later execution using a single name for the group. They are executed just like a "regular" command. When the name of a shell function is used as a simple command name, the list of commands associated with that function name is executed. Shell functions are executed in the current shell context; no new process is created to interpret them. Functions are declared using this syntax: [ function ] name () compound-command [ redirection ] This defines a shell function named name. The reserved word function is optional. If the function reserved word is supplied, the parentheses are optional. The body of the function is the compound command compound-command (see Section 3.2.4 [Compound Commands], page 9). That command is usually a list enclosed between { and }, but may be any compound conunand listed above. compound-command is executed whenever name is specified as the name of a command. Any redirections (see Section 3.6 [Redirection* page 25) associated with the shell function are performed when the function is executed. The exit status of a function definition is zero unless a syntax error occurs or a readonly function with the same name already exists. When executed, the exit status of a function is the exit status of the last command executed in the body. Note that for historical reasons, in the most common usage the curly braces that surround the body of the function must be separated from the body by blanks or newlines. This is because the braces are reserved words and are only recognized as such when they are separated by whitespace. Also, when using the braces, the list must be terminated by a semicolon, a `✓e, or a newline. When a function is executed, the arguments to the function become the positional pa- rameters during its execution (see Section 3.4.1 [Positional Parameters], page 15). The special parameter It' that expands to the number of positional parameters is updated to reflect the change. Special parameter 0 is unchanged. The first element of the FUNCNAME variable is set to the name of the function while the function is executing. All other aspects of the shell execution environment are identical between a function and its caller with the exception that the DEBUG and RETURN traps are not inherited unless the function has been given the trace attribute using the declare builtin or the -o functrace option has been enabled with the set builtin, (in which case all functions inherit the DEBUG and RETURN traps). See Section 4.1 [Bourne Shell Builtins], page 33, for the description of the trap builtin. If the builtin command return is executed in a function, the function completes and execution resumes with the next command after the function call. Any command associated with the RETURN trap is executed before execution resumes. When a function completes, the values of the positional parameters and the special parameter `tt' are restored to the values they had prior to the function's execution. If a numeric argument is given to return, that is the function's return status; otherwise the function's return status is the exit status of the last command executed before the return. Variables local to the function may be declared with the local builtin. These variables are visible only to the function and the commands it invokes. EFTA00315868 Chapter 3: Basic Shell Features 15 Function names and definitions may be listed with the `-f' option to the declare or typeset builtin commands (see Section 4.2 [Bash Builtins], page 39). The `-F' option to declare or typeset will list the function names only (and optionally the source file and line number, if the extdebug shell option is enabled). Functions may be exported so that subshells automatically have them defined with the `-f' option to the export builtin (see Section 4.1 [Bourne Shell Builtins], page 33). Note that shell functions and variables with the same name may result in multiple identically-named entries in the environment passed to the shell's children. Care should be taken in cases where this may cause a problem. Functions may be recursive. No limit is placed on the number of recursive calls. 3.4 Shell Parameters A parameter is an entity that stores values. It can be a name, a number, or one of the special characters listed below. A variable is a parameter denoted by a name. A variable has a value and zero or more attributes. Attributes are assigned using the declare builtin command (see the description of the declare builtin in Section 4.2 [Bash Builtins], page 39). A parameter is set if it has been assigned a value. The null string is a valid value. Once a variable is set, it may be unset only by using the unset builtin command. A variable may be assigned to by a statement of the form name=(value] If value is not given, the variable is assigned the null string. All values undergo tilde ex- pansion, parameter and variable expansion, command substitution, arithmetic expansion, and quote removal (detailed below). If the variable has its integer attribute set, then value is evaluated as an arithmetic expression even if the $ ((...)) expansion is not used (see Section 3.5.5 [Arithmetic Expansion], page 22). Word splitting is not performed, with the exception of "$C" as explained below. Filename expansion is not performed. Assign- ment statements may also appear as arguments to the alias, declare, typeset, export, readonly, and local builtin commands. In the context where an assignment statement is assigning a value to a shell variable or array index (see Section 6.7 [Arrays], page 74), the `+=' operator can be used to append to or add to the variable's previous value. When `+=' is applied to a variable for which the integer attribute has been set, value is evaluated as an arithmetic expression and added to the variable's current value, which is also evaluated. When 'I.& is applied to an array variable using compound assignment (see Section 6.7 [Arrays], page 74), the variable's value is not unset (as it is when using ='), and new values are a